minnimemory 1.0.0-beta.1

package/dist/recallDir.js

@@ -0,0 +1,187 @@
+/**
+ * Manifest-less recall over a memory folder (Layout B): an index file (one of
+ * discover.ts's `LIST_FILE_NAMES`) plus topic `.md` files, or a Claude Code auto-memory folder.
+ * No `.minnimemory/` compile step, no manifest - the same rankUnits/selectUnits pipeline
+ * recall() in recall.ts runs against a compiled workspace's manifest, built straight off files on
+ * disk instead. This is the "memory-dir" launch mode (detectPhase() in discover.ts), a new
+ * surface, not a change to the existing compiled or setup surfaces.
+ *
+ * Lexical only, offline, deterministic - same posture as recall()/router.ts: BM25 over stemmed
+ * terms, no embeddings, no model call, no network. The index file's hook lines
+ * ("- [Title](file.md) - hook text") are parsed into per-file triggers the same way
+ * Research/Pipeline/replay_ranker.mjs already does for its own offline replay.
+ *
+ * Never follows a `@path` import: this module simply does not implement that resolution, so a
+ * topic file naming one outside the directory has nothing to follow it with. Every file read
+ * passes paths.ts's containment check first, so a symlinked topic file cannot point recall()
+ * outside the directory it was asked to serve.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { LIST_FILE_NAMES } from "./discover.js";
+import { containedIn } from "./paths.js";
+import { buildSearchIndex, RECALL_MAX_TOKENS, rankUnits, selectUnits, unitsOf } from "./router.js";
+export class RecallDirError extends Error {
+}
+/** Some hook lines use Unicode code point U+2014 (a long dash) as the separator instead of a
+ * plain hyphen. Built from a character code, not a literal character pasted into source (house
+ * style: no such characters in anything written here). */
+const LONG_DASH = String.fromCharCode(0x2014);
+/** A hook line in an index file: "- [Title](file.md) - hook text", with either separator above. */
+const RE_HOOK_LINE = new RegExp(`^-\\s*\\[([^\\]]+)\\]\\(([^)]+)\\)\\s*[${LONG_DASH}-]\\s*(.+)$`);
+function stripMdExt(name) {
+    return name.replace(/\.md$/i, "");
+}
+/** The index file present in `dir`, by LIST_FILE_NAMES priority (stat only). */
+function findIndexFile(dir) {
+    for (const name of LIST_FILE_NAMES) {
+        const abs = path.join(dir, name);
+        try {
+            if (fs.statSync(abs).isFile())
+                return name;
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * Every top-level `.md` file in `dir`, the index file and `README.md` excluded, name-sorted.
+ * Non-recursive on purpose - `archive/` and any other subdirectory is never descended into, the
+ * same rule discover.ts's readAutoMemoryFiles applies to an auto-memory folder's topic files.
+ */
+function topicFiles(dir, indexName) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".md"))
+        .filter((e) => e.name !== indexName && e.name.toLowerCase() !== "readme.md")
+        .map((e) => ({ name: stripMdExt(e.name), file: e.name, abs: path.join(dir, e.name) }))
+        .sort((a, b) => a.file.localeCompare(b.file));
+}
+/** Parse an index file's hook lines into `[title, hook]` pairs keyed by topic file name
+ * (extension stripped). A line that does not match the hook shape is not an error - prose above
+ * or below the list is common - it is simply not a trigger source. */
+function parseTriggers(dir, indexName) {
+    const triggers = new Map();
+    let content;
+    try {
+        content = fs.readFileSync(path.join(dir, indexName), "utf8");
+    }
+    catch {
+        return triggers;
+    }
+    for (const raw of content.split(/\r?\n/)) {
+        const m = RE_HOOK_LINE.exec(raw.trim());
+        if (!m)
+            continue;
+        const title = m[1] ?? "";
+        const target = stripMdExt(path.basename((m[2] ?? "").trim()));
+        const hook = (m[3] ?? "").trim();
+        triggers.set(target, [title, hook]);
+    }
+    return triggers;
+}
+/**
+ * One cache entry per directory, the same idea as recall.ts's unitIndexCache: rebuilding means
+ * re-reading and re-splitting every topic file, real work a per-turn recall() call should not
+ * redo against an unchanged directory within one server session.
+ */
+const dirIndexCache = new Map();
+function fileSignature(abs) {
+    try {
+        const st = fs.statSync(abs);
+        return `${abs}:${st.mtimeMs}:${st.size}`;
+    }
+    catch {
+        return `${abs}:(missing)`;
+    }
+}
+function dirSignature(dir, indexName, files) {
+    const parts = files.map((f) => fileSignature(f.abs));
+    if (indexName)
+        parts.push(fileSignature(path.join(dir, indexName)));
+    return parts.join("|");
+}
+/**
+ * The section-level unit index for a memory directory, rebuilt only when a topic file's or the
+ * index file's mtime/size has changed since the last call for this directory.
+ */
+export function getDirIndex(dir) {
+    const abs = path.resolve(dir);
+    const indexName = findIndexFile(abs);
+    const files = topicFiles(abs, indexName);
+    const signature = dirSignature(abs, indexName, files);
+    const cached = dirIndexCache.get(abs);
+    if (cached && cached.signature === signature)
+        return cached.index;
+    const triggers = indexName ? parseTriggers(abs, indexName) : new Map();
+    const units = [];
+    for (const f of files) {
+        // Defensive: a symlinked topic file that resolves outside the directory is skipped, not
+        // followed. Every real file in the directory already passes this trivially.
+        if (!containedIn(abs, f.abs))
+            continue;
+        let content;
+        try {
+            content = fs.readFileSync(f.abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        units.push(...unitsOf({ name: f.name, file: f.file }, content));
+    }
+    const index = buildSearchIndex(units, triggers);
+    dirIndexCache.set(abs, { signature, index });
+    return index;
+}
+/** Test-only: forget every cached directory index, so a test that edits files on disk between
+ * calls does not also need to fake mtime/size to bust the cache. */
+export function clearDirIndexCache() {
+    dirIndexCache.clear();
+}
+export function listDirFiles(dir) {
+    const abs = path.resolve(dir);
+    const indexName = findIndexFile(abs);
+    const files = topicFiles(abs, indexName);
+    const triggers = indexName ? parseTriggers(abs, indexName) : new Map();
+    return files.map((f) => ({ name: f.name, file: f.file, triggers: triggers.get(f.name) ?? [] }));
+}
+/**
+ * The best section-level units for a query over a memory directory with no manifest, same shape
+ * as recall.ts's recall(). `drifted` is always empty here: drift (MM010) is a manifest concept, and
+ * a manifest-less directory has none to drift from.
+ */
+export function recallDir(dir, query, options = {}) {
+    const abs = path.resolve(dir);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+        throw new RecallDirError(`not a directory: ${abs}`);
+    }
+    const index = getDirIndex(abs);
+    const maxTokens = options.maxTokens ?? RECALL_MAX_TOKENS;
+    let ranked = rankUnits(index, query);
+    if (options.file !== undefined) {
+        const wanted = options.file;
+        ranked = ranked.filter((r) => r.unit.onDemandFile === wanted);
+    }
+    const picked = selectUnits(ranked, maxTokens);
+    const matches = picked.map(({ unit, score }) => ({
+        onDemandFile: unit.onDemandFile,
+        file: unit.file,
+        heading: unit.heading,
+        path: unit.path,
+        kind: unit.kind,
+        startLine: unit.startLine,
+        endLine: unit.endLine,
+        tokens: unit.tokens,
+        score,
+        content: unit.content,
+    }));
+    return { query, unit: "section", maxTokens, matches, drifted: [] };
+}

package/dist/reorganize.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Applies an agent-proposed reorganize plan to a memory directory.
+ *
+ * This is the write half of "AI-scanned reorganization" (project_minnimemory memory,
+ * 2026-09-03). It does no scanning and no judgment - scan.ts and the calling agent do that -
+ * it only executes a small, explicit set of file operations, gated on the one hard requirement
+ * already locked in for this feature: every `.md` file under the target directory (the only
+ * shape a plan's ops can touch - see isMemoryShaped below) is backed up verbatim, inside the
+ * directory itself, before a single byte of the plan is applied.
+ */
+export declare class ReorganizeError extends Error {
+}
+export type ReorganizeOp = {
+    op: "write_file";
+    path: string;
+    content: string;
+} | {
+    op: "delete_file";
+    path: string;
+} | {
+    op: "rename_file";
+    from: string;
+    to: string;
+};
+export interface ReorganizePlan {
+    /** absolute or relative path to the memory directory these ops apply to */
+    root: string;
+    ops: ReorganizeOp[];
+}
+export interface AppliedOp {
+    op: ReorganizeOp["op"];
+    path: string;
+}
+export interface ReorganizeResult {
+    root: string;
+    backupDir: string;
+    applied: AppliedOp[];
+}
+/** Name of the backup directory reorganize creates inside the memory directory it operates on.
+ * Exported so every place that spells out the backup path (a tool description, a doc) says the
+ * same thing the code actually does. */
+export declare const BACKUP_DIRNAME = ".minnimemory-backup";
+/**
+ * Ceiling on a single write_file's content, checked before any op runs. `reorganize` is a memory
+ * tool, not a general file writer; a plan this large is almost certainly a mistake, and refusing
+ * it before the backup and the rest of the plan run keeps the failure cheap and obvious.
+ */
+export declare const MAX_WRITE_CHARS = 1000000;
+/**
+ * How many timestamped backups to keep. Every apply copies the whole directory again, so
+ * without a ceiling a handful of reorganizes quietly multiplies a memory folder on disk, and
+ * pointing this at something larger than a memory folder multiplies that instead.
+ */
+export declare const BACKUP_KEEP = 10;
+/**
+ * Apply every op in `plan.ops`, in order, after backing up `plan.root` verbatim. All-or-nothing
+ * in intent: every op's path is validated against `root` before any op runs, so a bad path fails
+ * before touching disk rather than mid-way through a partially-applied plan. A later op is still
+ * free to fail on its own (disk full, permissions) - the backup exists either way, so a partial
+ * apply is always recoverable by hand from `.minnimemory-backup/<timestamp>/`.
+ */
+export declare function applyPlan(plan: ReorganizePlan): ReorganizeResult;

package/dist/reorganize.js

@@ -0,0 +1,216 @@
+/**
+ * Applies an agent-proposed reorganize plan to a memory directory.
+ *
+ * This is the write half of "AI-scanned reorganization" (project_minnimemory memory,
+ * 2026-09-03). It does no scanning and no judgment - scan.ts and the calling agent do that -
+ * it only executes a small, explicit set of file operations, gated on the one hard requirement
+ * already locked in for this feature: every `.md` file under the target directory (the only
+ * shape a plan's ops can touch - see isMemoryShaped below) is backed up verbatim, inside the
+ * directory itself, before a single byte of the plan is applied.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { SKIP_DIRS } from "./discover.js";
+import { containedIn, hasSegment, isEscapingRelative } from "./paths.js";
+export class ReorganizeError extends Error {
+}
+/** Name of the backup directory reorganize creates inside the memory directory it operates on.
+ * Exported so every place that spells out the backup path (a tool description, a doc) says the
+ * same thing the code actually does. */
+export const BACKUP_DIRNAME = ".minnimemory-backup";
+function timestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+/**
+ * Is `rel` shaped like a memory file this tool understands: a `.md` leaf? A reorganize op only
+ * ever needs to touch the markdown files a memory directory is made of - containment alone still
+ * lets a write land on an extensionless executable like `.git/hooks/pre-commit` inside the
+ * confined root, which is a filesystem location, not a memory file. Confirmed live in the
+ * 2026-09-10 audit: with `--allow-write`, `write_file` happily created a working git hook. The
+ * `.md` requirement alone closes it - git hooks are matched by exact filename, so no `.md`-named
+ * file is ever run as one. Deliberately not also banning dot-segments in general: an existing
+ * test (backup directory guard) allows a directory that merely starts with the backup dirname.
+ */
+function isMemoryShaped(rel) {
+    return rel.toLowerCase().endsWith(".md");
+}
+/**
+ * Confine a plan-supplied relative path to `root`: no absolute paths, no `..` segments, must be
+ * memory-shaped (see isMemoryShaped), and the resolved real path (symlinks followed) must land
+ * inside `root`'s real path. Mirrors the same containment check recall.ts's loadOnDemandContent
+ * already applies to manifest-supplied module paths.
+ */
+function resolveInRoot(root, rel, label) {
+    if (isEscapingRelative(rel)) {
+        throw new ReorganizeError(`refusing ${label} outside the memory directory: ${rel}`);
+    }
+    // A path segment, not a string prefix: `sub/.minnimemory-backup/x` used to slip past this
+    // while the innocent `.minnimemory-backupX/x` was refused.
+    if (hasSegment(rel, BACKUP_DIRNAME)) {
+        throw new ReorganizeError(`refusing to touch the backup directory itself: ${rel}`);
+    }
+    if (!isMemoryShaped(rel)) {
+        throw new ReorganizeError(`refusing ${label} outside the memory file shape (must end in .md): ${rel}`);
+    }
+    const abs = path.join(root, rel);
+    if (!containedIn(root, abs)) {
+        throw new ReorganizeError(`refusing ${label} that resolves outside the memory directory: ${rel}`);
+    }
+    return abs;
+}
+/**
+ * Ceiling on a single write_file's content, checked before any op runs. `reorganize` is a memory
+ * tool, not a general file writer; a plan this large is almost certainly a mistake, and refusing
+ * it before the backup and the rest of the plan run keeps the failure cheap and obvious.
+ */
+export const MAX_WRITE_CHARS = 1_000_000;
+/**
+ * How many timestamped backups to keep. Every apply copies the whole directory again, so
+ * without a ceiling a handful of reorganizes quietly multiplies a memory folder on disk, and
+ * pointing this at something larger than a memory folder multiplies that instead.
+ */
+export const BACKUP_KEEP = 10;
+/** Drop all but the newest BACKUP_KEEP backups. Names are ISO timestamps, so sort order is age. */
+function pruneBackups(backupRoot) {
+    let entries;
+    try {
+        entries = fs
+            .readdirSync(backupRoot, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return;
+    }
+    for (const old of entries.slice(0, Math.max(0, entries.length - BACKUP_KEEP))) {
+        fs.rmSync(path.join(backupRoot, old), { recursive: true, force: true });
+    }
+}
+/**
+ * Every `.md` file under `root`, recursively, copied to the same relative path inside the backup
+ * directory. This is the only shape `reorganize`'s ops can touch (see isMemoryShaped and
+ * resolveInRoot above), so it is the only shape worth backing up.
+ *
+ * Before this, the whole directory was copied verbatim. The MCP root is wherever `mcp` was
+ * launched - the plugin launches at the project root - so one `reorganize` call in a real repo
+ * copied `.git`, `node_modules`, `dist`, everything, into `.minnimemory-backup/<ts>/`, up to
+ * BACKUP_KEEP times over (2026-09-13 audit, B1). `SKIP_DIRS` (the same list discover.ts uses to
+ * avoid descending into build output and dependency trees) and symlinks are skipped; a symlinked
+ * `.md` is not copied because following it could read a file outside `root` into the backup.
+ */
+function collectMarkdownFiles(root, dir, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name === BACKUP_DIRNAME)
+            continue;
+        const abs = path.join(dir, entry.name);
+        let stat;
+        try {
+            stat = fs.lstatSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            collectMarkdownFiles(root, abs, out);
+        }
+        else if (stat.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            out.push(abs);
+        }
+    }
+}
+/** Every `.md` file under `root`, `.minnimemory-backup/`, `node_modules`, `.git`, `dist` and
+ * `build` skipped, copied verbatim to the same relative path. The only files a plan can touch. */
+function backupVerbatim(root) {
+    const backupRoot = path.join(root, BACKUP_DIRNAME);
+    const dir = path.join(backupRoot, timestamp());
+    fs.mkdirSync(dir, { recursive: true });
+    const files = [];
+    collectMarkdownFiles(root, root, files);
+    for (const abs of files) {
+        const rel = path.relative(root, abs);
+        const dest = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.cpSync(abs, dest);
+    }
+    const gitignore = path.join(backupRoot, ".gitignore");
+    if (!fs.existsSync(gitignore))
+        fs.writeFileSync(gitignore, "*\n");
+    pruneBackups(backupRoot);
+    return dir;
+}
+/**
+ * Apply every op in `plan.ops`, in order, after backing up `plan.root` verbatim. All-or-nothing
+ * in intent: every op's path is validated against `root` before any op runs, so a bad path fails
+ * before touching disk rather than mid-way through a partially-applied plan. A later op is still
+ * free to fail on its own (disk full, permissions) - the backup exists either way, so a partial
+ * apply is always recoverable by hand from `.minnimemory-backup/<timestamp>/`.
+ */
+export function applyPlan(plan) {
+    const root = path.resolve(plan.root);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        throw new ReorganizeError(`not a directory: ${root}`);
+    }
+    if (plan.ops.length === 0) {
+        throw new ReorganizeError("empty plan - nothing to apply");
+    }
+    // Validate every path before touching disk.
+    for (const op of plan.ops) {
+        if (op.op === "rename_file") {
+            const from = resolveInRoot(root, op.from, "rename source");
+            const to = resolveInRoot(root, op.to, "rename destination");
+            if (!fs.existsSync(from) || !fs.statSync(from).isFile()) {
+                throw new ReorganizeError(`rename source does not exist: ${op.from}`);
+            }
+            if (fs.existsSync(to)) {
+                throw new ReorganizeError(`rename destination already exists: ${op.to}; delete_file it first`);
+            }
+        }
+        else {
+            const abs = resolveInRoot(root, op.path, `${op.op} path`);
+            // Caught here, not left for fs.rmSync to throw EISDIR mid-apply: every other bad path
+            // fails before any op runs, and this one should too.
+            if (op.op === "delete_file" && fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+                throw new ReorganizeError(`refusing delete_file on a directory: ${op.path}`);
+            }
+            if (op.op === "write_file" && op.content.length > MAX_WRITE_CHARS) {
+                throw new ReorganizeError(`write_file content is ${op.content.length} characters, over the ${MAX_WRITE_CHARS} limit: ${op.path}`);
+            }
+        }
+    }
+    const backupDir = backupVerbatim(root);
+    const applied = [];
+    for (const op of plan.ops) {
+        if (op.op === "write_file") {
+            const abs = resolveInRoot(root, op.path, "write_file path");
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, op.content);
+            applied.push({ op: op.op, path: op.path });
+        }
+        else if (op.op === "delete_file") {
+            const abs = resolveInRoot(root, op.path, "delete_file path");
+            if (fs.existsSync(abs))
+                fs.rmSync(abs);
+            applied.push({ op: op.op, path: op.path });
+        }
+        else {
+            const from = resolveInRoot(root, op.from, "rename source");
+            const to = resolveInRoot(root, op.to, "rename destination");
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.renameSync(from, to);
+            applied.push({ op: op.op, path: `${op.from} -> ${op.to}` });
+        }
+    }
+    return { root, backupDir, applied };
+}

package/dist/report.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Rendering for doctor results. Human output first, JSON for tooling.
+ * No dependencies: colour is a handful of ANSI codes, disabled unless asked for.
+ */
+import { type DoctorConfig, type DoctorResult, type Finding, type Severity } from "./types.js";
+export interface RenderOptions {
+    color: boolean;
+    /** terse output suitable for a build log */
+    ci: boolean;
+}
+/** Findings shown per rule before the human view collapses the rest into one marker line. */
+export declare const DISPLAY_LIMIT = 10;
+export declare function renderHuman(result: DoctorResult, config: DoctorConfig, opts: RenderOptions): string;
+export declare function renderJson(result: DoctorResult, config: DoctorConfig): string;
+/** 0 clean, 1 findings at or above the threshold. */
+export declare function exitCodeFor(findings: Finding[], failOn: Severity): 0 | 1;

package/dist/report.js

@@ -0,0 +1,204 @@
+/**
+ * Rendering for doctor results. Human output first, JSON for tooling.
+ * No dependencies: colour is a handful of ANSI codes, disabled unless asked for.
+ */
+import { formatTokens, TOKENIZER_ID } from "./tokenizer.js";
+import { SEVERITY_ORDER } from "./types.js";
+const MSG_WIDTH = 58;
+const GUTTER = "         ";
+const ANSI = {
+    reset: "\u001b[0m",
+    dim: "\u001b[2m",
+    red: "\u001b[31m",
+    yellow: "\u001b[33m",
+    blue: "\u001b[34m",
+    bold: "\u001b[1m",
+};
+function paint(text, code, color) {
+    return color ? `${code}${text}${ANSI.reset}` : text;
+}
+function severityColor(s) {
+    if (s === "high")
+        return ANSI.red;
+    if (s === "med")
+        return ANSI.yellow;
+    return ANSI.blue;
+}
+/** Greedy word wrap. Long unbreakable tokens are allowed to overflow rather than be cut. */
+function wrap(text, width) {
+    const words = text.split(/\s+/).filter(Boolean);
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (line === "") {
+            line = word;
+        }
+        else if (line.length + 1 + word.length <= width) {
+            line += ` ${word}`;
+        }
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line)
+        lines.push(line);
+    return lines.length ? lines : [""];
+}
+function location(f) {
+    if (f.startLine === undefined)
+        return undefined;
+    const range = f.endLine !== undefined && f.endLine !== f.startLine ? `${f.startLine}-${f.endLine}` : `${f.startLine}`;
+    return `${f.file}:${range}`;
+}
+function renderFinding(f, color) {
+    const out = [];
+    const body = wrap(f.message, MSG_WIDTH);
+    const head = body[0] ?? "";
+    out.push(`  ${paint(f.rule.padEnd(7), ANSI.bold, color)}${head.padEnd(MSG_WIDTH)} ${paint(f.severity, severityColor(f.severity), color)}`);
+    for (const extra of body.slice(1)) {
+        out.push(`${GUTTER}${extra}`);
+    }
+    const loc = location(f);
+    if (loc)
+        out.push(`${GUTTER}${paint(`at ${loc}`, ANSI.dim, color)}`);
+    if (f.hint) {
+        for (const hintLine of wrap(`-> ${f.hint}`, MSG_WIDTH + 8)) {
+            out.push(`${GUTTER}${paint(hintLine, ANSI.dim, color)}`);
+        }
+    }
+    return out;
+}
+function counts(findings) {
+    const c = { high: 0, med: 0, low: 0 };
+    for (const f of findings)
+        c[f.severity]++;
+    return c;
+}
+/** Findings shown per rule before the human view collapses the rest into one marker line. */
+export const DISPLAY_LIMIT = 10;
+/**
+ * Truncate for the terminal only, one group per rule, in the order the findings arrive.
+ * Everything else in the pipeline (JSON, exit code, the summary count) sees the full list:
+ * the cap used to live in the rules themselves, which hid findings from every output mode
+ * while the marker line advised re-running with --json to see them.
+ */
+function forDisplay(findings, limit = DISPLAY_LIMIT) {
+    const perRule = new Map();
+    const out = [];
+    const hidden = new Map();
+    for (const f of findings) {
+        const n = perRule.get(f.rule) ?? 0;
+        perRule.set(f.rule, n + 1);
+        if (n < limit) {
+            out.push(f);
+        }
+        else {
+            const rest = hidden.get(f.rule) ?? [];
+            rest.push(f);
+            hidden.set(f.rule, rest);
+        }
+    }
+    for (const [rule, rest] of hidden) {
+        const last = out.filter((f) => f.rule === rule).pop();
+        if (!last)
+            continue;
+        out.splice(out.lastIndexOf(last) + 1, 0, {
+            rule,
+            severity: last.severity,
+            file: last.file,
+            message: `and ${rest.length} more ${rule} finding${rest.length === 1 ? "" : "s"} not shown`,
+            hint: "re-run with --json for the full list",
+            overflow: true,
+        });
+    }
+    return out;
+}
+export function renderHuman(result, config, opts) {
+    const { findings } = result;
+    const shown = forDisplay(findings);
+    const lines = [];
+    const color = opts.color;
+    lines.push("");
+    if (findings.length === 0) {
+        lines.push(`  ${paint("no findings", ANSI.blue, color)}`);
+    }
+    else {
+        for (const f of shown) {
+            lines.push(...renderFinding(f, color));
+            if (!opts.ci)
+                lines.push("");
+        }
+    }
+    if (!opts.ci && findings.length === 0)
+        lines.push("");
+    const c = counts(findings);
+    const breakdown = [
+        c.high ? `${c.high} high` : "",
+        c.med ? `${c.med} med` : "",
+        c.low ? `${c.low} low` : "",
+    ]
+        .filter(Boolean)
+        .join(", ");
+    // The count is of everything found, not of what fit on screen; say so when they differ, so a
+    // truncated run never reads as though the hidden findings do not exist.
+    const displayed = shown.filter((f) => !f.overflow).length;
+    const truncated = displayed < findings.length ? `, showing ${displayed}` : "";
+    const summary = findings.length === 0
+        ? "  0 findings"
+        : `  ${findings.length} finding${findings.length === 1 ? "" : "s"}${breakdown ? ` (${breakdown})` : ""}${truncated}`;
+    lines.push(summary);
+    const over = result.alwaysLoadedTokens > config.budget;
+    const budgetNote = `budget ${formatTokens(config.budget)}${over ? ", over" : ", within"}`;
+    lines.push(`  always-loaded prefix: ${formatTokens(result.alwaysLoadedTokens)} tokens across ` +
+        `${result.alwaysLoadedFiles} file${result.alwaysLoadedFiles === 1 ? "" : "s"} (${budgetNote})`);
+    lines.push(paint(`  tokenizer: ${result.tokenizer}, an offline estimate`, ANSI.dim, color));
+    // An unfollowed import means the always-loaded total above is short by whatever it points at.
+    // Say so: a number that is quietly incomplete is worse than one that admits it.
+    const skipped = result.workspace.skippedImports ?? [];
+    if (skipped.length > 0) {
+        lines.push("");
+        lines.push(`  ${skipped.length} import${skipped.length === 1 ? "" : "s"} outside this directory not followed, so the total above excludes them:`);
+        for (const raw of skipped.slice(0, 5))
+            lines.push(`    ${raw}`);
+        if (skipped.length > 5)
+            lines.push(`    and ${skipped.length - 5} more`);
+        lines.push("  pass --follow-external-imports to include them, if this memory file is yours to trust");
+    }
+    // The re-apply case: a workspace optimised earlier. Say what state it is in and what the
+    // one command to bring it current is, so doctor is the whole front door for coming back.
+    if (result.workspace.shape === "compiled") {
+        const onDemandFiles = result.workspace.files.filter((f) => f.kind === "onDemand").length;
+        const drift = findings.filter((f) => f.rule === "MM010").length;
+        lines.push("");
+        lines.push(`  compiled workspace: ${onDemandFiles} OnDemandMemory file${onDemandFiles === 1 ? "" : "s"} in .minnimemory/`);
+        if (!result.workspace.manifest) {
+            lines.push("  manifest.json unreadable, so drift cannot be checked; re-apply with: minnimemory init --update");
+        }
+        else if (drift === 0) {
+            lines.push("  no drift since init: the stub and every compiled file match the manifest. Nothing to re-apply.");
+        }
+        else {
+            lines.push(`  drift: ${drift} file${drift === 1 ? "" : "s"} changed since init (MM010). Re-apply with: minnimemory init --update`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function renderJson(result, config) {
+    return JSON.stringify({
+        tokenizer: TOKENIZER_ID,
+        root: result.workspace.root,
+        shape: result.workspace.shape,
+        budget: config.budget,
+        alwaysLoadedTokens: result.alwaysLoadedTokens,
+        alwaysLoadedFiles: result.alwaysLoadedFiles,
+        counts: counts(result.findings),
+        findings: result.findings,
+    }, null, 2);
+}
+/** 0 clean, 1 findings at or above the threshold. */
+export function exitCodeFor(findings, failOn) {
+    const threshold = SEVERITY_ORDER[failOn];
+    return findings.some((f) => SEVERITY_ORDER[f.severity] >= threshold) ? 1 : 0;
+}