prehello 0.1.0 → 1.0.0

package/dist/calibrate.js

@@ -0,0 +1,265 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextParseError = void 0;
+exports.parseNumber = parseNumber;
+exports.parseContext = parseContext;
+exports.compare = compare;
+exports.renderCalibration = renderCalibration;
+exports.calibrationJson = calibrationJson;
+/**
+ * `prehello calibrate`: compare prehello's estimate with a Claude Code `/context` reading the user pasted. Offline: the text is
+ * parsed locally and nothing is sent anywhere. A file is written only with --save.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const families_1 = require("./tokens/families");
+const fmt_1 = require("./util/fmt");
+class ContextParseError extends Error {
+}
+exports.ContextParseError = ContextParseError;
+const NUM = String.raw `(\d[\d,]*(?:\.\d+)?)\s*([kKmM]?)`;
+function parseNumber(num, suffix) {
+    const n = parseFloat(num.replace(/,/g, ""));
+    const mult = suffix.toLowerCase() === "k" ? 1000 : suffix.toLowerCase() === "m" ? 1_000_000 : 1;
+    const decimals = num.includes(".") ? num.split(".")[1].length : 0;
+    const pm = (mult === 1 && decimals === 0 ? 0.5 : 0.5 * Math.pow(10, -decimals)) * mult;
+    return { value: Math.round(n * mult), pm: mult === 1 && decimals === 0 ? 0.5 : pm, raw: `${num}${suffix}` };
+}
+const KNOWN = ["system prompt", "system tools", "system tools (deferred)", "mcp tools", "mcp tools (deferred)", "custom agents", "memory files", "skills", "messages", "free space", "autocompact buffer"];
+const SECTIONS = [
+    [/^mcp tools\b/i, "mcp tools"],
+    [/^custom agents\b/i, "custom agents"],
+    [/^memory files\b/i, "memory files"],
+    [/^skills\b/i, "skills"],
+    [/^system tools\b/i, "system tools"],
+    [/^plugins?\b/i, "plugins"],
+];
+/** Parse the text of Claude Code's `/context` (any of the layouts seen 2025-2026). Unknown lines are ignored and counted. */
+function parseContext(text) {
+    // eslint-disable-next-line no-control-regex
+    const clean = text.replace(/\u001b\[[0-9;?]*[ -\/]*[@-~]/g, "").replace(/\r\n?/g, "\n");
+    const r = { categories: new Map(), details: new Map(), mcpOnDemand: false, recognised: 0, ignored: 0 };
+    let section;
+    const header = new RegExp(String.raw `([\w.\-\[\]]+)\s+·\s+${NUM}\s*/\s*${NUM}\s+tokens\s*\(`, "i");
+    const usedOnly = new RegExp(String.raw `^\s*${NUM}\s*/\s*${NUM}\s+tokens\s*\(`, "i");
+    const cat = new RegExp(String.raw `([A-Za-z][A-Za-z ]*?(?:\s*\((?:deferred)\))?):\s+${NUM}\s*(?:tokens)?\s*\(\s*\d+(?:\.\d+)?%\s*\)`, "g");
+    const row = new RegExp(String.raw `^\s*[└├│]?[─\s]*└?\s*(.+?):\s+${NUM}\s+tokens\s*$`);
+    const summary = new RegExp(String.raw `^\s*└\s+\d[\d,]*\s+\w+\s+·\s+${NUM}\s+tokens`);
+    for (const line0 of clean.split("\n")) {
+        const line = line0.replace(/[⛁⛀⛶⛝⛃]/g, " ").replace(/^\s*(?:❯|>)?\s*(?:⎿)?\s*/, "");
+        if (!line.trim())
+            continue;
+        const h = header.exec(line);
+        if (h) {
+            r.model = h[1];
+            r.used = parseNumber(h[2], h[3]);
+            r.total = parseNumber(h[4], h[5]);
+            r.recognised++;
+            continue;
+        }
+        const u = usedOnly.exec(line);
+        if (u) {
+            r.used = parseNumber(u[1], u[2]);
+            r.total = parseNumber(u[3], u[4]);
+            r.recognised++;
+            continue;
+        }
+        if (/^\s*claude-[\w.\-\[\]]+\s*$/i.test(line)) {
+            r.model = line.trim();
+            r.recognised++;
+            continue;
+        }
+        let anyCat = false;
+        for (const m of line.matchAll(cat)) {
+            const name = m[1].trim().toLowerCase().replace(/\s+/g, " ");
+            if (!KNOWN.includes(name) && !/^[a-z ]+( \(deferred\))?$/.test(name))
+                continue;
+            r.categories.set(name, parseNumber(m[2], m[3]));
+            anyCat = true;
+        }
+        if (anyCat) {
+            r.recognised++;
+            section = undefined;
+            continue;
+        }
+        const sec = line.trim();
+        const sm = SECTIONS.find(([re]) => re.test(sec) && /·|\/\w/.test(sec));
+        if (sm) {
+            section = sm[1];
+            if (section === "mcp tools" && /on-demand|deferred/i.test(sec))
+                r.mcpOnDemand = true;
+            if (!r.details.has(section))
+                r.details.set(section, []);
+            r.recognised++;
+            continue;
+        }
+        if (section && summary.test(line)) {
+            r.recognised++;
+            continue;
+        }
+        const rw = section ? row.exec(line) : null;
+        if (rw && section) {
+            const label = rw[1].replace(/^[└├│─\s]+/, "").trim();
+            const pm = /\(([^()]*[\/\\][^()]*)\)\s*$/.exec(label);
+            const p = pm ? pm[1] : /[\/\\]/.test(label) ? label : undefined;
+            r.details.get(section).push({ label, tokens: parseNumber(rw[2], rw[3]), ...(p ? { path: p } : {}) });
+            r.recognised++;
+            continue;
+        }
+        if (section && /^\s*(User|Project|Local|Managed|Plugin|Built-in|Enterprise)\b[^:]*$/i.test(line)) {
+            r.recognised++;
+            continue;
+        }
+        r.ignored++;
+    }
+    if (!r.categories.size) {
+        throw new ContextParseError("no /context category rows found (expected lines like 'Memory files: 3.2k tokens (1.6%)'). Paste the whole output of /context (or /context all) from Claude Code");
+    }
+    return r;
+}
+const COMPARED = [
+    { cat: "memory files", kinds: ["instructions", "rule", "memory"] },
+    { cat: "skills", kinds: ["skills-listing"] },
+    { cat: "custom agents", kinds: ["subagents"] },
+    { cat: "mcp tools", kinds: ["mcp-server"] },
+];
+function mk(category, actual, est, unmeasured, note) {
+    const a = actual?.value ?? null;
+    const err = a !== null && a > 0 && est ? ((est.est - a) / a) * 100 : null;
+    const inBand = a !== null && est ? est.low <= a + (actual?.pm ?? 0) && est.high >= a - (actual?.pm ?? 0) : null;
+    return { category, actual: a, actualPm: actual?.pm ?? 0, est: est?.est ?? null, low: est?.low ?? null, high: est?.high ?? null, errorPct: err, inBand, unmeasuredItems: unmeasured, ...(note ? { note } : {}) };
+}
+function sumItems(items) {
+    const m = items.filter((i) => i.tokens);
+    if (!m.length)
+        return null;
+    return m.reduce((s, i) => ({ est: s.est + i.tokens.est, low: s.low + i.tokens.low, high: s.high + i.tokens.high }), { est: 0, low: 0, high: 0 });
+}
+const norm = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+function compare(reading, a, home) {
+    const always = a.items.filter((i) => i.loadMode === "always");
+    const rows = [];
+    const used = { est: 0, low: 0, high: 0, actual: 0, pm: 0, any: false };
+    for (const c of COMPARED) {
+        let items = always.filter((i) => c.kinds.includes(i.kind));
+        let actual = reading.categories.get(c.cat);
+        let note;
+        if (c.cat === "mcp tools") {
+            if (reading.mcpOnDemand || (!actual && reading.categories.has("mcp tools (deferred)")))
+                note = "Claude Code loads these tool schemas on demand (tool search); only the always-on part is compared";
+            if (!actual && items.length === 0)
+                continue;
+        }
+        if (!actual && !items.length)
+            continue;
+        const est = sumItems(items);
+        const unmeasured = items.filter((i) => !i.tokens).length;
+        if (unmeasured)
+            note = `${unmeasured} item(s) unmeasured by prehello: its number is a lower bound`;
+        if (!actual)
+            actual = { value: 0, pm: 0, raw: "absent" };
+        const row = mk(c.cat, actual, est ?? { est: 0, low: 0, high: 0 }, unmeasured, note ?? (reading.categories.has(c.cat) ? undefined : "/context shows no such row (treated as 0)"));
+        rows.push(row);
+        if (est) {
+            used.est += est.est;
+            used.low += est.low;
+            used.high += est.high;
+        }
+        used.actual += actual.value;
+        used.pm += actual.pm;
+        used.any = true;
+        items = [];
+    }
+    const total = mk("compared total", used.any ? { value: used.actual, pm: used.pm, raw: "" } : undefined, used.any ? used : null, rows.reduce((s, r) => s + r.unmeasuredItems, 0));
+    // per memory file, matched by path
+    const files = [];
+    const memItems = always.filter((i) => ["instructions", "rule", "memory"].includes(i.kind) && i.tokens);
+    for (const fr of reading.details.get("memory files") ?? []) {
+        if (!fr.path)
+            continue;
+        const p = norm(fr.path.startsWith("~") ? node_path_1.default.join(home, fr.path.slice(1)) : fr.path);
+        const hit = memItems.find((i) => norm(i.path) === p) ?? memItems.find((i) => p.endsWith("/" + norm(node_path_1.default.basename(i.path))) && norm(i.path).endsWith(p.split("/").slice(-2).join("/")));
+        if (hit)
+            files.push(mk(fr.path, fr.tokens, hit.tokens, 0));
+        else
+            files.push(mk(fr.path, fr.tokens, null, 0, "prehello did not find this file"));
+    }
+    const notEstimated = [];
+    for (const k of ["system prompt", "system tools", "messages"]) {
+        const v = reading.categories.get(k);
+        if (v)
+            notEstimated.push({ category: k, actual: v.value });
+    }
+    // implied ratio on markdown-like content: actual / raw o200k, where raw = est / factor
+    const f = (0, families_1.claudeCalibration)().byKind.markdown.factor * (a.profile.id === "claude-legacy" ? (0, families_1.claudeCalibration)().legacyRatio.value : 1);
+    const md = rows.filter((r) => r.category !== "mcp tools" && r.est && r.actual && r.unmeasuredItems === 0);
+    const mdEst = md.reduce((s, r) => s + (r.est ?? 0), 0);
+    const mdAct = md.reduce((s, r) => s + (r.actual ?? 0), 0);
+    const impliedMarkdownRatio = mdEst > 0 && mdAct > 0 ? Math.round(((mdAct * f) / mdEst) * 1000) / 1000 : null;
+    return { model: reading.model, rows, files, total, notEstimated, impliedMarkdownRatio, ignoredLines: reading.ignored };
+}
+const pctStr = (x) => (x === null ? "n/a" : `${x >= 0 ? "+" : ""}${x.toFixed(1)}%`);
+const cell = (n) => (n === null ? "-" : (0, fmt_1.fmtTok)(n));
+/** A memory-file label the reader can recognise: relative to the scanned folder when inside it, and never cut at the file name. */
+function fileLabel(p, cwd) {
+    const variants = (x) => [x, x.replace(/^\/private(?=\/)/, ""), `/private${x}`];
+    for (const base of variants(cwd)) {
+        for (const cand of variants(p)) {
+            const rel = node_path_1.default.relative(base, cand);
+            if (rel && !rel.startsWith("..") && !node_path_1.default.isAbsolute(rel))
+                return (0, fmt_1.shortenLabel)((0, fmt_1.sanitize)(rel, 1000), 70);
+        }
+    }
+    return (0, fmt_1.shortenLabel)((0, fmt_1.sanitize)(p, 1000), 70);
+}
+function renderCalibration(c, r) {
+    const out = [];
+    out.push(`prehello ${r.tool.version} calibrate · Claude Code${c.model ? ` · /context model ${(0, fmt_1.sanitize)(c.model, 60)}` : ""}`);
+    out.push("Compares prehello's always-on estimate with your /context reading (offline; nothing is sent anywhere).", "");
+    const head = ["category", "/context", "prehello (low-high)", "error", "in band"];
+    const lines = [...c.rows, c.total].map((x) => [x.category, cell(x.actual), x.est === null ? "-" : `${(0, fmt_1.fmtTok)(x.est)} (${(0, fmt_1.fmtTok)(x.low)}-${(0, fmt_1.fmtTok)(x.high)})`, pctStr(x.errorPct), x.inBand === null ? "-" : x.inBand ? "yes" : "NO"]);
+    const w = head.map((h, i) => Math.max(h.length, ...lines.map((l) => l[i].length)));
+    const fmtRow = (l) => "  " + l.map((s, i) => (i === 0 ? s.padEnd(w[i]) : s.padStart(w[i]))).join("  ");
+    out.push(fmtRow(head));
+    for (const l of lines)
+        out.push(fmtRow(l));
+    for (const x of c.rows)
+        if (x.note)
+            out.push(`  note (${x.category}): ${x.note}`);
+    if (c.files.length) {
+        out.push("", "Memory files, one by one:");
+        for (const f of c.files)
+            out.push(`  ${fileLabel(f.category, r.scan.cwd)}: /context ${cell(f.actual)}, prehello ${cell(f.est)}, error ${pctStr(f.errorPct)}${f.note ? ` (${f.note})` : ""}`);
+    }
+    if (c.notEstimated.length)
+        out.push("", `Not estimated by prehello (built into Claude Code): ${c.notEstimated.map((n) => `${n.category} ${(0, fmt_1.fmtTok)(n.actual)}`).join(", ")}.`);
+    if (c.total.errorPct !== null && Math.abs(c.total.errorPct) > 50)
+        out.push("", "The numbers are far apart. Run /context in a fresh Claude Code session started in the folder prehello scans (pass that folder as [path]), and paste its whole output.");
+    if (c.impliedMarkdownRatio !== null && c.impliedMarkdownRatio > 0.5 && c.impliedMarkdownRatio < 3)
+        out.push(`Implied Claude/o200k ratio for text here: ${c.impliedMarkdownRatio} (prehello uses ${(0, families_1.claudeCalibration)().byKind.markdown.factor}; includes listing wrappers).`);
+    out.push("/context rounds its numbers (2.8k = 2,750-2,849); 'in band' allows for that.");
+    if (c.ignoredLines)
+        out.push(`${c.ignoredLines} line(s) of the pasted text were not recognised and ignored.`);
+    out.push("Share it: prehello calibrate --file ctx.txt --save calibration.json, then attach the file to an issue (no paths or names in it).");
+    return out.join("\n") + "\n";
+}
+/** Redacted record: no paths, no names. */
+function calibrationJson(c, r, a, redact) {
+    return {
+        tool: { name: "prehello", version: r.tool.version },
+        kind: "calibration",
+        generatedAt: r.generatedAt,
+        agent: a.id,
+        profile: a.profile.id,
+        model: c.model ?? null,
+        calibration: { measuredAt: (0, families_1.claudeCalibration)().measuredAt, markdownFactor: (0, families_1.claudeCalibration)().byKind.markdown.factor, jsonFactor: (0, families_1.claudeCalibration)().byKind.json.factor },
+        rows: c.rows,
+        total: c.total,
+        files: redact ? c.files.map(({ category: _c, ...rest }, i) => ({ category: `memory file ${i + 1}`, ...rest })) : c.files,
+        notEstimated: c.notEstimated,
+        impliedMarkdownRatio: c.impliedMarkdownRatio,
+        ignoredLines: c.ignoredLines,
+    };
+}

package/dist/cli.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const diff_1 = require("./diff");
+const calibrate_1 = require("./calibrate");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -27,16 +29,24 @@ Local-only, read-only scan. No network, no telemetry, no API key. Token counts a
 Usage:
   prehello [path] [options]
   prehello explain grade        print the Context Grade rubric
+  prehello calibrate [path] --file <ctx.txt|->
+                                compare prehello with Claude Code's /context output
+                                (--json for JSON, --save <file> writes a redacted record)
+  prehello diff <base.json> <head.json> [--markdown[=file]] [--json] [--fail-above <n>]
+                                token change between two snapshots (exit 2 over the limit)
 
 Options:
-  --agent <list>        comma list of: claude-code, cursor, codex (forces them "in use")
+  --agent <list>        comma list of agents to force "in use":
+                        ${model_1.ALL_AGENTS.join(", ")}
   --window <n|200k|1m>  context window for percentages (default 200k)
   --json                print the report as JSON to stdout (versioned schema)
   --json=<file>         also write the JSON to <file>
+  --save <file>         save a snapshot (the JSON report) for prehello diff
+  --badge <file>        write a shields.io endpoint badge JSON (see docs/github-action.md)
   --redact              strict JSON: no paths or names (share-safe)
   --card[=<file>]       write a share card (no paths or file contents). The file extension picks the format:
                         .svg (default name prehello-card.svg) or .png (prehello-card.png)
-                        write the file name with "=": --card=card.png (a space, "--card card.png", is not accepted)
+                        name the file with "=" or a space: --card=card.png or --card card.png
   --markdown[=<file>]   a shareable Markdown report (title, headline, tables, what to cut, measured vs not measured) for a
                         GitHub issue / PR / README / Slack. Without a file it is printed to stdout INSTEAD of the terminal
                         report (pipe it: prehello --markdown | pbcopy); with a file (.md or .markdown) it is written there
@@ -93,7 +103,7 @@ re-encodes redirected output as UTF-16). Works the same on Linux, macOS and Wind
 Exit codes: 0 ok · 1 error (incl. PNG engine missing) · 2 --max-tokens exceeded · 3 partial (some sources unreadable/skipped/budget hit; report still printed)
   (2 wins over 3 when both apply)
 `;
-const VALUE_FLAGS = new Set(["agent", "window", "tokenizer", "claude-profile", "card-theme", "card-size", "card-agent", "cwd", "mcp-catalog", "ceiling", "managed-dir", "system-root", "paste-user-rules", "card-headline", "card-format", "card-scale", "png-engine", "max-tokens", "scan-budget-mb", "scan-budget-ms"]);
+const VALUE_FLAGS = new Set(["agent", "window", "tokenizer", "claude-profile", "card-theme", "card-size", "card-agent", "cwd", "mcp-catalog", "ceiling", "managed-dir", "system-root", "paste-user-rules", "card-headline", "card-format", "card-scale", "png-engine", "max-tokens", "scan-budget-mb", "scan-budget-ms", "file", "context-file", "save", "fail-above", "badge"]);
 const BOOL_FLAGS = new Set(["json", "card", "redact", "fix", "no-grade", "no-color", "quiet", "verbose", "about-specs", "version", "help", "no-redact", "no-bundled-catalog", "force", "card-anonymize", "anonymize", "markdown", "markdown-compact", "sarif", "ascii", "include-fixtures"]);
 function parseArgs(argv) {
     const flags = new Map();
@@ -134,6 +144,11 @@ function parseArgs(argv) {
                 return `option --${name} does not take a value`;
             if (inline === "" && name === "json")
                 return "--json= needs a file name (for stdout, write --json with no =)";
+            // --card card.png: take the next argument as the file name when it ends in .svg/.png and is not an existing directory
+            if (name === "card" && inline === undefined && i + 1 < argv.length && /\.(svg|png)$/i.test(argv[i + 1]) && !argv[i + 1].startsWith("-") && !(0, fs_safe_1.isDir)(node_path_1.default.resolve(argv[i + 1]))) {
+                flags.set(name, argv[++i]);
+                continue;
+            }
             flags.set(name, inline ?? true);
         }
         else
@@ -167,8 +182,37 @@ async function main() {
             return void process.stdout.write((0, terminal_1.renderRubric)());
         return fail("usage: prehello explain grade");
     }
-    if (positional[0] === "ci" || positional[0] === "diff" || positional[0] === "calibrate")
-        return fail(`'${positional[0]}' is not part of 0.1 (planned for 0.2)`);
+    const calibrating = positional[0] === "calibrate";
+    if (calibrating)
+        positional.shift();
+    let contextText;
+    if (calibrating) {
+        const dash = positional.indexOf("-");
+        if (dash >= 0)
+            positional.splice(dash, 1);
+        const src = (flags.get("file") ?? flags.get("context-file") ?? (dash >= 0 ? "-" : undefined));
+        if (src === undefined || src === "-") {
+            if (src === undefined && process.stdin.isTTY)
+                return fail("usage: prehello calibrate --file ctx.txt (paste the output of /context from Claude Code into ctx.txt), or pipe it: pbpaste | prehello calibrate -");
+            contextText = (0, platform_1.decodeUserText)(node_fs_1.default.readFileSync(0));
+        }
+        else {
+            try {
+                contextText = (0, platform_1.decodeUserText)(node_fs_1.default.readFileSync(src));
+            }
+            catch {
+                return fail(`cannot read /context text from ${src}`);
+            }
+        }
+    }
+    else if (flags.has("file") || flags.has("context-file"))
+        return fail("--file and --context-file belong to 'prehello calibrate'");
+    if (positional[0] === "diff")
+        return runDiff(positional.slice(1), flags);
+    if (flags.has("fail-above"))
+        return fail("--fail-above belongs to 'prehello diff'");
+    if (positional[0] === "ci")
+        return fail("there is no 'ci' command: use the GitHub Action (docs/github-action.md), or prehello --save + prehello diff");
     if (positional.length > 1)
         return fail("at most one path argument is supported");
     const env = process.env;
@@ -176,7 +220,7 @@ async function main() {
     const cwdAbs = node_path_1.default.resolve(target);
     if (!(0, fs_safe_1.isDir)(cwdAbs)) {
         if (flags.get("card") === true && positional[0] && /\.(svg|png)$/i.test(positional[0]))
-            return fail(`not a directory: ${target}. To name the card file write --card=${positional[0]} (with "=", no space)`);
+            return fail(`not a directory: ${target}. To name the card file write --card=${positional[0]}`);
         return fail(`not a directory: ${target}`);
     }
     const cwd = (0, fs_safe_1.realpathOrSelf)(cwdAbs);
@@ -204,9 +248,14 @@ async function main() {
             return fail("--agent needs at least one of: " + model_1.ALL_AGENTS.join(", "));
         const bad = list.filter((x) => !model_1.ALL_AGENTS.includes(x));
         if (bad.length)
-            return fail(`unknown agent '${bad[0]}' (supported in 0.1: ${model_1.ALL_AGENTS.join(", ")})`);
+            return fail(`unknown agent '${bad[0]}' (supported: ${model_1.ALL_AGENTS.join(", ")})`);
         agents = list;
     }
+    if (calibrating) {
+        if (agents && (agents.length !== 1 || agents[0] !== "claude-code"))
+            return fail("calibrate reads Claude Code's /context; Codex and Cursor have no per-category reading to compare against (yet)");
+        agents = ["claude-code"];
+    }
     const cardTheme = String(flags.get("card-theme") ?? "dark");
     const cardSize = String(flags.get("card-size") ?? "og");
     if (!["dark", "light"].includes(cardTheme))
@@ -354,6 +403,32 @@ async function main() {
             return fail(`could not write ${what} to ${file}: ${(0, safe_write_1.describeWriteError)(e.code)}`);
         }
     };
+    if (calibrating) {
+        let reading;
+        try {
+            reading = (0, calibrate_1.parseContext)(contextText ?? "");
+        }
+        catch (e) {
+            if (e instanceof calibrate_1.ContextParseError)
+                return fail(e.message);
+            throw e;
+        }
+        const a = report.agents.find((x) => x.id === "claude-code");
+        if (!a)
+            return fail("no Claude Code report to compare against");
+        const cal = (0, calibrate_1.compare)(reading, a, home);
+        if (flags.has("save"))
+            write(String(flags.get("save")), JSON.stringify((0, calibrate_1.calibrationJson)(cal, report, a, true), null, 2) + "\n", "calibration", "json");
+        if (process.exitCode)
+            return;
+        if (flags.get("json") === true)
+            process.stdout.write(JSON.stringify((0, calibrate_1.calibrationJson)(cal, report, a, flags.has("redact")), null, 2) + "\n");
+        else
+            process.stdout.write((0, calibrate_1.renderCalibration)(cal, report));
+        if (flags.has("save"))
+            process.stderr.write(`Calibration written to ${flags.get("save")} (no paths or names).\n`);
+        return;
+    }
     const strict = flags.has("redact");
     const jsonFlag = flags.get("json");
     const color = !flags.has("no-color") && !env.NO_COLOR && env.TERM !== "dumb" && !!process.stdout.isTTY;
@@ -363,6 +438,13 @@ async function main() {
     const jsonText = jsonFlag !== undefined ? JSON.stringify((0, json_1.toJson)(report, { cwd, home }, strict), null, 2) + "\n" : "";
     if (typeof jsonFlag === "string")
         write(jsonFlag, jsonText, "JSON", "json");
+    if (flags.has("save"))
+        write(String(flags.get("save")), JSON.stringify((0, json_1.toJson)(report, { cwd, home }, strict), null, 2) + "\n", "snapshot", "json");
+    if (flags.has("badge")) {
+        // a CI runner has no agent installed: fall back to the agent with the most always-on context in the repository
+        const ba = (0, card_1.pickCardAgent)(report, flags.get("card-agent")) ?? [...report.agents].filter((a) => a.items.length).sort((x, y) => y.totals.always.est - x.totals.always.est)[0] ?? null;
+        write(String(flags.get("badge")), JSON.stringify(ba ? (0, diff_1.badgeJson)(ba.name, ba.totals.always.measuredItems || !ba.totals.always.unmeasuredItems ? ba.totals.always.est : null, ba.lowerBound) : (0, diff_1.badgeJson)("no agent", null, false)) + "\n", "badge", "badge");
+    }
     let cardMsg = "";
     let cardFailed = false;
     const anonymizeNames = flags.has("card-anonymize") || flags.has("anonymize") || strict;
@@ -452,3 +534,58 @@ main().catch((e) => {
     process.stderr.write(`prehello: internal error: ${e.message}\n`);
     process.exitCode = 1;
 });
+function parseTokenCount(v) {
+    const m = /^(\d+(?:\.\d+)?)([kKmM]?)$/.exec(v.trim());
+    if (!m)
+        return undefined;
+    return Math.round(parseFloat(m[1]) * (m[2].toLowerCase() === "k" ? 1000 : m[2].toLowerCase() === "m" ? 1_000_000 : 1));
+}
+/** `prehello diff base.json head.json [--markdown[=file]] [--json] [--fail-above N]`. Reads two saved reports; no scan, no git. */
+function runDiff(files, flags) {
+    if (files.length !== 2)
+        return fail("usage: prehello diff <base.json> <head.json> [--markdown] [--json] [--fail-above <tokens>]  (make each file with: prehello --save <file>)");
+    let threshold;
+    if (flags.has("fail-above")) {
+        threshold = parseTokenCount(String(flags.get("fail-above")));
+        if (threshold === undefined)
+            return fail("--fail-above needs a token count, e.g. 2000 or 2k");
+    }
+    const snaps = [];
+    for (const f of files) {
+        let text;
+        try {
+            text = node_fs_1.default.readFileSync(f === "-" ? 0 : f, "utf8");
+        }
+        catch {
+            return fail(`cannot read ${f}`);
+        }
+        try {
+            snaps.push((0, diff_1.parseSnapshot)(text, f));
+        }
+        catch (e) {
+            if (e instanceof diff_1.DiffInputError)
+                return fail(e.message);
+            throw e;
+        }
+    }
+    const d = (0, diff_1.diffSnapshots)(snaps[0], snaps[1]);
+    const md = flags.get("markdown");
+    if (typeof md === "string") {
+        try {
+            (0, safe_write_1.safeWrite)(node_path_1.default.resolve(md), (0, diff_1.renderDiffMarkdown)(d, { threshold }), { kind: "md", force: flags.has("force") });
+        }
+        catch (e) {
+            return fail(`diff Markdown not written to ${md}: ${e.message}`);
+        }
+    }
+    if (flags.get("json") === true)
+        process.stdout.write(JSON.stringify((0, diff_1.diffJson)(d, threshold), null, 2) + "\n");
+    else if (md === true)
+        process.stdout.write((0, diff_1.renderDiffMarkdown)(d, { threshold }));
+    else
+        process.stdout.write((0, diff_1.renderDiffTerminal)(d));
+    const over = threshold !== undefined ? (0, diff_1.overThreshold)(d, threshold) : [];
+    for (const a of over)
+        process.stderr.write(`prehello: ${a.name} always-on context grew by ${(0, fmt_1.fmtTok)(a.delta)} tokens (estimate), above --fail-above ${(0, fmt_1.fmtTok)(threshold)}\n`);
+    process.exitCode = over.length ? 2 : 0;
+}

package/dist/context.js

@@ -9,6 +9,7 @@ exports.lineCount = lineCount;
 exports.shingles = shingles;
 exports.jaccard = jaccard;
 const node_path_1 = __importDefault(require("node:path"));
+const agents_1 = require("./agents");
 const families_1 = require("./tokens/families");
 const fs_safe_1 = require("./fs-safe");
 const redact_1 = require("./redact");
@@ -31,7 +32,7 @@ function readFailWhy(reason, verb) {
 }
 /** Names (files) and "dir/" entries looked for in every directory of the bounded project walk. */
 exports.WALK_CANDIDATES = [
-    "CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md", "AGENTS.md", "AGENTS.override.md",
+    "CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md", "AGENTS.md", "AGENTS.override.md", "GEMINI.md",
     ".cursor/rules/", ".cursor/skills/", ".agents/skills/", ".claude/skills/",
 ];
 class Ctx {
@@ -81,10 +82,7 @@ class Ctx {
             return false;
         if (this.gitRoot && this.gitRoot !== this.home)
             return true;
-        const top = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", ".cursorrules", ".mcp.json"];
-        if (top.some((f) => (0, fs_safe_1.isFile)(node_path_1.default.join(this.cwd, f))))
-            return true;
-        return [".claude", ".cursor", ".codex", ".agents"].some((d) => (0, fs_safe_1.isDir)(node_path_1.default.join(this.cwd, d)));
+        return agents_1.AGENTS.flatMap((a) => a.projectMarkers).some((m) => m.endsWith("/") ? (0, fs_safe_1.isDir)(node_path_1.default.join(this.cwd, m.slice(0, -1))) : (0, fs_safe_1.isFile)(node_path_1.default.join(this.cwd, m)));
     }
     get cwd() {
         return this.opts.cwd;
@@ -243,7 +241,7 @@ class Ctx {
             kind: a.kind,
             scope: a.scope,
             loadMode: a.loadMode,
-            tokens: a.raw === null ? null : prof.apply(a.raw),
+            tokens: a.raw === null ? null : prof.apply(a.raw, a.kind === "mcp-server" ? "json" : "markdown"),
             ...(a.raw === null ? { unmeasuredReason: a.unmeasuredReason ?? "not measurable" } : {}),
             chars: a.chars ?? 0,
             lines: a.lines ?? 0,