minnimemory 1.0.0-beta.1

package/dist/init.js

@@ -0,0 +1,475 @@
+/**
+ * `init`: compile a memory file into .minnimemory/ and rewrite the host file as a stub.
+ * `init --update`: recompile an already-compiled workspace from its current pieces.
+ *
+ * Dry-run by default. Nothing is written unless `write` is set, and the original is copied
+ * verbatim into .minnimemory/original/ before any host file is touched.
+ *
+ * Safety (security audit 2026-09-02): the source and every path written are checked with
+ * `lstat` and refused when they are symlinks, because a cloned repo can ship a link that
+ * points at a private file; and a source holding a credential-shaped string is refused unless
+ * the user explicitly allows copying it into the compiled tree.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { buildManifest, compile, DEFAULT_BUDGET, isStub, STUB_MARKER, COMPILED_DIR_NAME, ALWAYS_ON_FILE_NAME, ON_DEMAND_DIR_NAME } from "./compile.js";
+import { discover, HOST_FILES, isPlainFile } from "./discover.js";
+import { episodicJsonToMarkdown } from "./episodic.js";
+import { containedIn } from "./paths.js";
+import { loadManifest, McpTargetError } from "./recall.js";
+import { WRITE_PROTOCOL_FILE_NAME } from "./writeProtocol.js";
+import { RULES, secretFindings } from "./rules.js";
+import { bounds } from "./bounds.js";
+import { generatedRegion, LIST_END, LIST_START, INSTRUCTIONS_END, INSTRUCTIONS_START, keywords, sections, splitFrontmatter, } from "./text.js";
+import { estimateTokens, formatTokens, TOKENIZER_ID } from "./tokenizer.js";
+import { DEFAULT_CONFIG } from "./types.js";
+export const COMPILED_DIR = COMPILED_DIR_NAME;
+export class InitError extends Error {
+}
+function resolveProfile(choice, sourceTokens, budget) {
+    if (choice !== "auto")
+        return { name: choice };
+    if (sourceTokens < budget) {
+        return {
+            name: "none",
+            note: `auto: source is under the ${formatTokens(budget)} token budget, so no discipline block is embedded`,
+        };
+    }
+    return { name: "routing", note: `auto: source is over the ${formatTokens(budget)} token budget` };
+}
+/**
+ * Find the memory file to compile: an explicit file, or the host file in a repo.
+ *
+ * `includeAutoMemory` defaults true (the CLI's existing two-location behavior); the MCP `plan`/
+ * `apply` tools pass false unless launched with `--follow-external-imports`, so a directory
+ * target never triggers a read of the operator's OS-level auto-memory folder just to locate the
+ * host file - the auto-memory files are never selected here anyway (tagged `onDemandList`/`loose`,
+ * never `host`), but reading them at all violates "confined to this server's root" (2026-09-10 audit,
+ * second pass: the first fix left this path unaudited on the mistaken belief it only ever saw a
+ * single file).
+ */
+function locateSource(target, includeAutoMemory = true) {
+    const resolved = path.resolve(target);
+    if (fs.existsSync(resolved) && fs.lstatSync(resolved).isFile()) {
+        return { root: path.dirname(resolved), abs: resolved, rel: path.basename(resolved) };
+    }
+    if (fs.existsSync(resolved) && fs.lstatSync(resolved).isSymbolicLink()) {
+        throw new InitError(`${resolved} is a symlink; init only compiles regular files`);
+    }
+    const ws = discover(resolved, { includeAutoMemory });
+    const host = ws.files.find((f) => f.kind === "host");
+    if (host && ws.pointerTarget) {
+        const abs = path.join(ws.root, ws.pointerTarget);
+        if (!isPlainFile(abs))
+            throw new InitError(`${ws.pointerTarget} is not a regular file`);
+        return { root: ws.root, abs, rel: ws.pointerTarget, pointerFrom: host.rel };
+    }
+    if (host)
+        return { root: ws.root, abs: host.abs, rel: host.rel };
+    throw new InitError(`nothing to compile in ${resolved}\n` +
+        `  init needs a host memory file (${HOST_FILES.join(", ")}) or an explicit file path`);
+}
+const RE_LIST_LINE = /^\s*[-*+]\s*\[[^\]]+\]\(([^)\s]+\.md)\)/i;
+/**
+ * Refuse to compile a memory OnDemandMemory list. `init` compiles one host file into
+ * AlwaysOnMemory and OnDemandMemory files; a list (Claude Code's `MEMORY.md`, or any file that
+ * is mostly links to sibling topic files) routes to files that already exist. Compiling one
+ * re-files its hook lines as content and orphans every topic file: found live on 2026-09-03
+ * against a real auto-memory folder, where `init --write` mangled the list and the only guard
+ * was a note in the maintainer's memory. There is no override flag on purpose. A memory
+ * directory is `doctor`'s and the reorganizer's job (`mcp --allow-write`, scan then reorganize,
+ * backup first).
+ */
+function refuseList(abs, rel, source) {
+    const dir = path.dirname(abs);
+    const named = path.basename(abs).toLowerCase() === "memory.md";
+    const lines = source.split(/\r?\n/).filter((l) => l.trim() !== "" && !/^\s*#/.test(l));
+    let links = 0;
+    for (const l of lines) {
+        const m = RE_LIST_LINE.exec(l);
+        if (m && fs.existsSync(path.join(dir, m[1])))
+            links++;
+    }
+    const mostlyLinks = links >= 3 && links * 2 >= lines.length;
+    if (!named && !mostlyLinks)
+        return;
+    const relDir = path.relative(process.cwd(), dir);
+    const shown = relDir === "" ? "." : relDir.startsWith("..") ? dir : relDir;
+    throw new InitError(`${rel} is a memory OnDemandMemory list, not a memory file\n` +
+        `  init compiles one host file into AlwaysOnMemory and OnDemandMemory files; a list routes\n` +
+        `  to topic files that already exist beside it. Compiling it would re-file its hook lines\n` +
+        `  as content and orphan every topic file, so init refuses. For a memory directory:\n` +
+        `    minnimemory doctor "${shown}"                 audit it, change nothing\n` +
+        `    minnimemory mcp "${shown}" --allow-write     scan, then reorganize (agent-driven, backup first)`);
+}
+function secretsIn(rel, source) {
+    return secretFindings({
+        abs: rel,
+        rel,
+        content: source,
+        lines: source.split(/\r?\n/),
+        tokens: 0,
+        alwaysLoaded: true,
+        kind: "host",
+    });
+}
+function refuseSymlink(abs, what) {
+    try {
+        if (fs.lstatSync(abs).isSymbolicLink()) {
+            throw new InitError(`${what} is a symlink (${abs}); refusing to read or write through it`);
+        }
+    }
+    catch (err) {
+        if (err instanceof InitError)
+            throw err;
+        // does not exist yet: fine
+    }
+}
+/** The gitignore dropped into original/: the backup is local safety, not repo content. */
+const ORIGINAL_GITIGNORE = "# minnimemory keeps a verbatim copy of the pre-compile file here. Local only.\n*\n!.gitignore\n";
+export function planInit(target, options) {
+    if (options.update)
+        return planUpdate(target, options);
+    const { root, abs, rel, pointerFrom } = locateSource(target, options.includeAutoMemory !== false);
+    refuseSymlink(abs, rel);
+    const source = fs.readFileSync(abs, "utf8");
+    refuseList(abs, rel, source);
+    if (isStub(source)) {
+        throw new InitError(`${rel} is already a minnimemory stub\n` +
+            `  to recompile a compiled workspace run: minnimemory init --update`);
+    }
+    const compiledDir = path.join(root, COMPILED_DIR);
+    refuseSymlink(compiledDir, COMPILED_DIR);
+    const existing = fs.existsSync(compiledDir);
+    if (existing && !options.force) {
+        throw new InitError(`${COMPILED_DIR}/ already exists in ${root}\n` + `  pass --force to overwrite it, or --update to recompile it`);
+    }
+    const budget = options.budget ?? DEFAULT_BUDGET;
+    const { name: profile, note: profileNote } = resolveProfile(options.profile ?? "auto", estimateTokens(source), budget);
+    const compiled = compile(source, { sourceName: rel, profileName: profile, budget, episodicJson: options.episodicJson });
+    const manifest = buildManifest(compiled, TOKENIZER_ID);
+    const secrets = secretsIn(rel, source);
+    const files = [
+        { rel: `${COMPILED_DIR}/original/${rel}.bak`, contents: source, action: "backup" },
+        { rel: `${COMPILED_DIR}/original/.gitignore`, contents: ORIGINAL_GITIGNORE, action: existing ? "overwrite" : "create" },
+        { rel: `${COMPILED_DIR}/${ALWAYS_ON_FILE_NAME}`, contents: compiled.alwaysOn, action: existing ? "overwrite" : "create" },
+        {
+            rel: `${COMPILED_DIR}/manifest.json`,
+            contents: `${JSON.stringify(manifest, null, 2)}\n`,
+            action: existing ? "overwrite" : "create",
+        },
+    ];
+    for (const m of compiled.onDemandFiles) {
+        files.push({
+            rel: `${COMPILED_DIR}/${m.file}`,
+            contents: `${m.content.trimEnd()}\n`,
+            action: existing ? "overwrite" : "create",
+        });
+    }
+    files.push({ rel, contents: compiled.stub, action: "overwrite" });
+    const sessionBounds = bounds(manifest, VERDICT_TURNS);
+    const verdict = compiled.after < compiled.before ? "compile" : "leave";
+    const advice = adviceOn(abs);
+    return {
+        root,
+        sourceRel: rel,
+        compiled,
+        files,
+        existing,
+        profile,
+        profileNote,
+        pointerFrom,
+        secrets,
+        bounds: sessionBounds,
+        verdict,
+        advice,
+    };
+}
+/** Session length the plan's bounds are quoted over; the same default bench uses. */
+const VERDICT_TURNS = 50;
+/** Rules whose findings init cannot resolve, because resolving them would delete content. */
+const ADVICE_RULES = new Set(["MM002", "MM005"]);
+function adviceOn(abs) {
+    const workspace = discover(abs);
+    const ctx = { workspace, config: DEFAULT_CONFIG };
+    return RULES.filter((r) => ADVICE_RULES.has(r.id)).flatMap((r) => r.run(ctx));
+}
+/**
+ * `init --update`. After the first compile the source of truth is no longer the original file:
+ * it is the stub's own AlwaysOnMemory text plus the OnDemandMemory files on disk, both of which
+ * the user (and the agent) edit directly. So an update does not need a three-way merge against
+ * the original. It reads the stub, strips the generated regions, recompiles what is left
+ * (anything the user appended to the stub gets routed like a fresh section), keeps every
+ * OnDemandMemory file verbatim, recomputes triggers and hashes, and rewrites the OnDemandMemory
+ * list, manifest, and stub.
+ */
+export function planUpdate(target, options) {
+    const resolved = path.resolve(target);
+    const root = fs.existsSync(resolved) && fs.lstatSync(resolved).isFile() ? path.dirname(resolved) : resolved;
+    const compiledDir = path.join(root, COMPILED_DIR);
+    refuseSymlink(compiledDir, COMPILED_DIR);
+    if (!fs.existsSync(path.join(compiledDir, "manifest.json"))) {
+        throw new InitError(`no compiled workspace at ${root}\n  --update needs ${COMPILED_DIR}/manifest.json; run init first`);
+    }
+    let manifest;
+    try {
+        manifest = loadManifest(root);
+    }
+    catch (err) {
+        if (err instanceof McpTargetError)
+            throw new InitError(err.message);
+        throw err;
+    }
+    const rel = manifest.generatedFrom;
+    const hostAbs = path.join(root, rel);
+    refuseSymlink(hostAbs, rel);
+    if (!fs.existsSync(hostAbs))
+        throw new InitError(`${rel} named in the manifest is missing`);
+    const stub = fs.readFileSync(hostAbs, "utf8");
+    if (!isStub(stub)) {
+        throw new InitError(`${rel} is not a minnimemory stub; run init (with --force) to compile it from scratch`);
+    }
+    // Strip the generated parts. What remains is the user's AlwaysOnMemory text plus anything appended.
+    const lines = stub.split(/\r?\n/);
+    const { bodyStartLine } = splitFrontmatter(lines);
+    const drop = new Set();
+    drop.add(bodyStartLine - 1);
+    if ((lines[bodyStartLine] ?? "").trim().startsWith("<!-- generated by minnimemory"))
+        drop.add(bodyStartLine);
+    for (const [s, e] of [
+        [INSTRUCTIONS_START, INSTRUCTIONS_END],
+        [LIST_START, LIST_END],
+    ]) {
+        const r = generatedRegion(lines, s, e);
+        if (r)
+            for (let i = r.from; i <= r.to; i++)
+                drop.add(i);
+    }
+    const userSource = lines.filter((_, i) => !drop.has(i)).join("\n");
+    const budget = options.budget ?? DEFAULT_BUDGET;
+    const { name: profile, note: profileNote } = resolveProfile(options.profile ?? "auto", estimateTokens(userSource), budget);
+    const fresh = compile(userSource, { sourceName: rel, profileName: profile, budget, episodicJson: options.episodicJson });
+    // OnDemandMemory files on disk are kept verbatim. Manifest order first, new files after, then
+    // any OnDemandMemory files the recompile produced from content appended to the stub.
+    const onDemandDir = path.join(compiledDir, ON_DEMAND_DIR_NAME);
+    const onDisk = fs.existsSync(onDemandDir)
+        ? fs
+            .readdirSync(onDemandDir, { withFileTypes: true })
+            .filter((e) => e.isFile() && /\.(md|json)$/.test(e.name))
+            .map((e) => e.name)
+            .filter((f) => f.replace(/\.(md|json)$/, "") !== WRITE_PROTOCOL_FILE_NAME)
+        : [];
+    const stem = (f) => f.replace(/\.(md|json)$/, "");
+    const byName = new Map(manifest.onDemandFiles.map((m) => [m.name, m]));
+    const fileOf = new Map(onDisk.map((f) => [stem(f), f]));
+    const ordered = [
+        ...manifest.order.filter((n) => fileOf.has(n)),
+        ...onDisk.map(stem).filter((n) => !manifest.order.includes(n)).sort(),
+    ];
+    const kept = ordered.map((name) => {
+        const file = fileOf.get(name);
+        const content = fs.readFileSync(path.join(onDemandDir, file), "utf8").trimEnd();
+        const isJson = file.endsWith(".json");
+        // A JSON (episodic, O3) OnDemandMemory file is kept as the bytes on disk; its heading and
+        // triggers come from the markdown it stands for.
+        const markdown = isJson ? episodicJsonToMarkdown(content) : content;
+        const heading = sections(markdown.split("\n")).find((s) => s.level > 0)?.heading ?? name.replace(/_/g, " ");
+        const prev = byName.get(name);
+        return {
+            name,
+            file: `${ON_DEMAND_DIR_NAME}/${file}`,
+            heading,
+            content,
+            tokens: estimateTokens(content),
+            triggers: keywords(heading, markdown),
+            sourceStartLine: prev?.sourceLines[0] ?? 0,
+            sourceEndLine: prev?.sourceLines[1] ?? 0,
+            reason: prev?.reason ?? "task-specific",
+            kind: isJson ? "episodic" : prev?.kind,
+        };
+    });
+    const added = fresh.onDemandFiles.filter((m) => !ordered.includes(m.name));
+    const onDemandFiles = [...kept, ...added];
+    // Re-render with the merged OnDemandMemory file list. compile() already rendered the
+    // AlwaysOnMemory body; only the OnDemandMemory list and stub depend on the file set, and
+    // buildManifest reads the file list.
+    const merged = { ...fresh, onDemandFiles };
+    const rerendered = compile(userSource, {
+        sourceName: rel,
+        profileName: profile,
+        budget,
+        episodicJson: options.episodicJson,
+        onDemandFilesOverride: onDemandFiles,
+    });
+    merged.onDemandList = rerendered.onDemandList;
+    merged.alwaysOn = rerendered.alwaysOn;
+    merged.stub = rerendered.stub;
+    merged.after = rerendered.after;
+    // "before" is what the agent pays today: the current stub, not the stripped source.
+    merged.before = estimateTokens(stub);
+    const newManifest = buildManifest(merged, TOKENIZER_ID);
+    const secrets = secretsIn(rel, userSource);
+    const files = [
+        { rel: `${COMPILED_DIR}/previous/${rel}.bak`, contents: stub, action: "backup" },
+        { rel: `${COMPILED_DIR}/${ALWAYS_ON_FILE_NAME}`, contents: merged.alwaysOn, action: "overwrite" },
+        { rel: `${COMPILED_DIR}/manifest.json`, contents: `${JSON.stringify(newManifest, null, 2)}\n`, action: "overwrite" },
+    ];
+    for (const m of added) {
+        const exists = fs.existsSync(path.join(compiledDir, m.file));
+        files.push({ rel: `${COMPILED_DIR}/${m.file}`, contents: `${m.content.trimEnd()}\n`, action: exists ? "overwrite" : "create" });
+    }
+    files.push({ rel, contents: merged.stub, action: "overwrite" });
+    return {
+        root,
+        sourceRel: rel,
+        compiled: merged,
+        files,
+        existing: true,
+        profile,
+        profileNote,
+        secrets,
+        // The generated protocol OnDemandMemory file is re-emitted on every update; it is not something the user added.
+        updated: { kept: kept.length, added: added.filter((m) => !m.generated).length },
+    };
+}
+export function applyPlan(plan, options = {}) {
+    if (plan.secrets.length > 0 && !options.allowSecrets) {
+        throw new InitError(`${plan.sourceRel} holds ${plan.secrets.length} credential-shaped string(s); refusing to copy them into ${COMPILED_DIR}/\n` +
+            `  rotate and remove them, or pass --allow-secrets to proceed anyway`);
+    }
+    for (const file of plan.files) {
+        const abs = path.join(plan.root, file.rel);
+        // Symlink first: a linked write target is refused by name, which says more than the
+        // containment error it would otherwise trip on the way out of the workspace.
+        refuseSymlink(abs, file.rel);
+        if (!containedIn(plan.root, abs)) {
+            throw new InitError(`refusing to write outside the workspace: ${file.rel}`);
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, file.contents, "utf8");
+    }
+}
+/** A compact, machine-readable shape of a plan (the MCP `plan`/`doctor` tools' `format: "json"`),
+ * built from the same InitPlan renderPlan renders as text - no separate code path to drift. */
+export function planSummary(plan) {
+    return {
+        source: plan.sourceRel,
+        before: plan.compiled.before,
+        after: plan.compiled.after,
+        verdict: plan.verdict,
+        profile: plan.profile,
+        ...(plan.bounds
+            ? {
+                bounds: {
+                    turns: plan.bounds.turns,
+                    baselineTotal: plan.bounds.baselineTotal,
+                    bestCaseTotal: plan.bounds.bestCaseTotal,
+                    breakEvenCarriedTokens: plan.bounds.breakEvenCarriedTokens,
+                },
+            }
+            : {}),
+        onDemandFiles: plan.compiled.onDemandFiles.map((m) => ({ name: m.name, file: m.file, tokens: m.tokens, triggers: m.triggers })),
+        demoted: plan.compiled.demoted,
+        adviceCount: plan.advice?.length ?? 0,
+        secretsCount: plan.secrets.length,
+        files: plan.files.map((f) => ({ action: f.action, rel: f.rel })),
+    };
+}
+/** Human-readable summary of what a plan would do. */
+export function renderPlan(plan, options) {
+    const { compiled } = plan;
+    const lines = [""];
+    if (plan.pointerFrom) {
+        lines.push(`  ${plan.pointerFrom} is a pointer to ${plan.sourceRel}; compiling ${plan.sourceRel}`);
+    }
+    if (plan.updated) {
+        lines.push(`  update: ${plan.updated.kept} OnDemandMemory file(s) kept from disk, ${plan.updated.added} new from the stub`);
+    }
+    lines.push(`  source: ${plan.sourceRel} (${formatTokens(compiled.before)} tokens)`);
+    lines.push("");
+    const onDemandTokens = compiled.onDemandFiles.reduce((n, m) => n + m.tokens, 0);
+    lines.push(`  ${ALWAYS_ON_FILE_NAME.padEnd(34)}${formatTokens(compiled.after).padStart(8)} tokens  always loaded`);
+    lines.push(`  ${`${ON_DEMAND_DIR_NAME}/`.padEnd(34)}${formatTokens(onDemandTokens).padStart(8)} tokens  on demand`);
+    lines.push("");
+    for (const m of compiled.onDemandFiles) {
+        const trig = m.triggers.slice(0, 4).join(", ");
+        lines.push(`    ${m.file.padEnd(32)}${formatTokens(m.tokens).padStart(8)}  ${trig}`);
+    }
+    if (compiled.onDemandFiles.length)
+        lines.push("");
+    if (compiled.demoted.length > 0) {
+        lines.push(`  kept out of AlwaysOnMemory to fit the ${formatTokens(compiled.budget)} token budget (raise with --budget):`);
+        for (const d of compiled.demoted)
+            lines.push(`    "${d.heading}" (${formatTokens(d.tokens)} tokens)`);
+        lines.push("");
+    }
+    const saved = compiled.before - compiled.after;
+    const pct = compiled.before > 0 ? ((Math.abs(saved) / compiled.before) * 100).toFixed(1) : "0.0";
+    const direction = saved >= 0 ? `-${pct}%` : `+${pct}%`;
+    lines.push(`  always-loaded prefix: ${formatTokens(compiled.before)} -> ${formatTokens(compiled.after)} tokens (${direction})`);
+    lines.push(`  of which ${formatTokens(compiled.instructionTokens)} tokens are the added token-discipline block (--profile ${plan.profile})`);
+    if (plan.profileNote)
+        lines.push(`  ${plan.profileNote}`);
+    lines.push(`  tokenizer: ${TOKENIZER_ID}, an offline estimate`);
+    lines.push("");
+    if (plan.bounds) {
+        const b = plan.bounds;
+        const pctBest = b.baselineTotal > 0 ? ((b.bestCaseSaving / b.baselineTotal) * 100).toFixed(1) : "0.0";
+        lines.push(`  over a ${formatTokens(b.turns)}-turn session, exact bounds, no workload assumed:`);
+        lines.push(`    best case (no OnDemandMemory file opened)   ${formatTokens(b.baselineTotal)} -> ${formatTokens(b.bestCaseTotal)}, ` +
+            `${b.bestCaseSaving >= 0 ? `saves ${formatTokens(b.bestCaseSaving)} (${pctBest}%)` : `costs ${formatTokens(-b.bestCaseSaving)} more`}`);
+        lines.push(`    break-even                     ${formatTokens(Math.max(0, b.breakEvenCarriedTokens))} tokens of OnDemandMemory can stay open all session`);
+        lines.push("");
+    }
+    // Only a fresh compile gets a verdict. An update recompiles a workspace that already exists,
+    // so there is no compile-or-not decision to report and no refusal to warn about: printing one
+    // told the user "--write refuses unless you pass --force" directly above the list of files it
+    // had just written.
+    if (plan.updated) {
+        // an update has no compile-or-not decision to report
+    }
+    else if (plan.verdict === "leave" || saved <= 0) {
+        lines.push("  verdict: leave this file as it is.", "  The compile does not shrink the always-loaded prefix: the source is small enough that", "  the routing overhead costs more than routing saves. --write refuses unless you pass", "  --force, for when you want the routing discipline and accept the token cost.", "");
+    }
+    else if (plan.verdict === "compile") {
+        lines.push("  verdict: compile. The prefix shrinks on every turn; OnDemandMemory files cost only when opened.", "");
+    }
+    if (plan.advice && plan.advice.length > 0) {
+        lines.push("  doctor findings init does not apply (init moves content, never deletes it):");
+        for (const a of plan.advice) {
+            const where = a.startLine ? `lines ${a.startLine}-${a.endLine ?? a.startLine}` : "";
+            lines.push(`    ${a.rule}  ${a.message}${where ? ` (${where})` : ""}`);
+            if (a.hint)
+                lines.push(`           -> ${a.hint}`);
+        }
+        lines.push("");
+    }
+    if (plan.secrets.length > 0) {
+        lines.push(`  warning: ${plan.secrets.length} credential-shaped string(s) in the source:`);
+        for (const s of plan.secrets)
+            lines.push(`    line ${s.startLine}: ${s.message}`);
+        lines.push("  --write will refuse unless you rotate and remove them, or pass --allow-secrets.", "");
+    }
+    lines.push("  files:");
+    for (const f of plan.files) {
+        lines.push(`    ${f.action.padEnd(10)}${f.rel}`);
+    }
+    lines.push("");
+    if (!options.write) {
+        lines.push("  dry run, nothing written. Pass --write to apply.");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function init(target, options) {
+    const plan = planInit(target, options);
+    if (options.write && plan.verdict === "leave" && !options.force) {
+        throw new InitError(`${plan.sourceRel} would not get cheaper: always-loaded ${formatTokens(plan.compiled.before)} -> ${formatTokens(plan.compiled.after)} tokens\n` +
+            `  init refuses to write a compile that costs more on every turn than the file it replaces.\n` +
+            `  Pass --force to compile anyway (you want the routing discipline and accept the cost).`);
+    }
+    if (options.write)
+        applyPlan(plan, options);
+    return plan;
+}
+export { STUB_MARKER };

package/dist/instructions.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The token-reduction instruction set.
+ *
+ * Ported from the MinniMemory v1.0 research file. These are the behavioural half of the
+ * product: restructuring a memory file into AlwaysOnMemory plus OnDemandMemory only pays off
+ * if the agent is actually told to route rather than read everything, so candidates 15-25 in
+ * particular are what make the emitted structure do anything at all.
+ *
+ * IMPORTANT, and it must stay in the generated output: this set is reasoned and audited but
+ * NOT measured. The source research states plainly that no live measurement pass has run, and
+ * that candidates 5 and 15-25 cannot be measured by the current single-turn harness at all.
+ * Nothing here may be presented to a user as a proven saving.
+ */
+export type InstructionCategory = 
+/** shapes how the model writes its answer; targets output tokens */
+"output"
+/** shapes what gets loaded, kept, and re-sent; targets input and context growth */
+ | "context";
+export interface Instruction {
+    /** stable id, numbered to match the source research candidates */
+    id: string;
+    title: string;
+    /** the instruction text, written to be dropped into a memory file verbatim */
+    text: string;
+    category: InstructionCategory;
+    /** in the default profile */
+    defaultOn: boolean;
+    /** why it is off by default, or what it replaces */
+    note?: string;
+}
+/**
+ * The default profile resolves the redundancies the source research documents rather than
+ * emitting all 25 and letting them contradict each other:
+ *
+ * - #1 subsumes #6, #7, #10 and #12, so those four are off by default.
+ * - #3 and #11 directly conflict, so both are off and MERGED-3-11 replaces them.
+ * - #13 is off by default because it trades a clarifying question for an assumption, which is
+ *   a judgement call a tool should not make for someone silently.
+ */
+export declare const INSTRUCTIONS: Instruction[];
+/**
+ * Which instructions to embed.
+ *
+ * The CLI default is `auto`, resolved in `init`: `none` when the source is under the budget,
+ * `routing` at or over it. `routing` is the library fallback (`defaultProfile()`), and the reason
+ * is a measured one: the full block costs roughly 660 tokens (approx-v2) of always-loaded prefix,
+ * which is larger than many real memory files. Embedding all of it by default would make `init`
+ * a net loss on an ordinary repo, so the fallback is the minimum set that makes the emitted
+ * structure actually function. The rest is a deliberate opt-in.
+ */
+export type ProfileName = "none" | "routing" | "full";
+export declare function profile(name: ProfileName): Instruction[];
+export declare function isProfileName(value: string): value is ProfileName;
+export declare function defaultProfile(): Instruction[];
+export declare function instructionById(id: string): Instruction | undefined;
+/**
+ * Render the selected instructions as the block that goes into an emitted AlwaysOnMemory file.
+ * Context rules come first because they govern what gets loaded at all.
+ */
+export declare function renderInstructions(selected: Instruction[]): string;