create-evda 0.1.9 → 0.1.11

package/lib/adopt.mjs

@@ -0,0 +1,516 @@
+// evda adopt (HQ-2797): an existing folder of notes becomes an EVDA where it is.
+//
+// `evda gather` moves a pile into create-evda's layout. Someone who already lives in their own
+// folders (an old Iris Vault, an Obsidian vault) needs the opposite: the folders stay, and evda.json
+// names where each role already is. Spec 05, "The layout is declared, not imposed."
+//
+//   - The Iris Vault layout (00_Inbox through 06_Metadata) is recognized and mapped without asking.
+//     Any other folder is placed by its name when the name says what it holds; a folder whose name
+//     does not is never guessed at: it is named back, and the owner answers with `--map`.
+//   - What is written: evda.json, AGENTS.md (the one create-evda ships), the GEMINI.md loader when
+//     absent, the `@AGENTS.md` line appended to the owner's CLAUDE.md (or the loader when there is
+//     none), folder manifests in the record folders, .evda/, the Claude Code hooks in
+//     .claude/settings.json, and the README.md sections AGENTS.md sends the agent to (training off,
+//     what each AI company says, a local model: HQ-2812), as one marked block after the owner's
+//     README, or the whole README create-evda writes when there is none. Every other file that was
+//     there stays byte for byte.
+//   - Every write is listed in a reversal manifest outside the folder. `revertAdopt` restores the
+//     folder byte for byte, folder times included, and refuses when a file the adopt wrote or changed
+//     was edited since, unless forced. Edits that never block it: the owner's own edits to CLAUDE.md
+//     or README.md (only the added line, or the added block, is taken out), `evda upgrade` replacing
+//     AGENTS.md's generated block, and `evda upgrade` refreshing the README block.
+//
+// EVDA_ADOPT_FALSIFY=<mode,...>, for the tests: guess-unplaced places an unknown folder in
+// knowledge instead of asking; claude-rewrite writes CLAUDE.md as the loader instead of appending;
+// revert-ignores-edits reverts over edited files without --force; revert-not-exact skips restoring
+// the files the adopt changed.
+
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, unlinkSync, utimesSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { EvdaError } from "./errors.mjs";
+import { SCHEMA_VERSION, writeVersion, openEvda } from "./manifest.mjs";
+import { ROLES, fourRoleOf } from "./roles.mjs";
+import { FOLDER_MANIFEST } from "./folders.mjs";
+import { FILING_MODES } from "./day-file.mjs";
+import { fillOwnerSection, filingKey, DEFAULT_AGENT_NAME } from "./setup.mjs";
+import { splitFence } from "./agents.mjs";
+import { installHook, installPromptHook } from "./hooks.mjs";
+import { installGuard, clients } from "./connect.mjs";
+import { reindex } from "./index.mjs";
+import { readPointer, setPointer, pointerPath } from "./locate.mjs";
+import { stampInstalledVersion } from "./update-check.mjs";
+import { doctor } from "./doctor.mjs";
+import { everyChatSetupLines } from "./every-chat.mjs";
+import { outsideRecord } from "./record-walk.mjs";
+import { ensureReadme, withoutBlock, README_REL } from "./readme.mjs";
+
+export const ADOPT_VERSION = 1;
+export const ADOPT_FALSIFY_MODES = ["guess-unplaced", "claude-rewrite", "revert-ignores-edits", "revert-not-exact"];
+const falsified = (mode) => (process.env.EVDA_ADOPT_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(HERE, "..", "templates");
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+const posix = (p) => p.split(sep).join("/");
+const refuse = (msg, code) => new EvdaError(`REFUSED: ${msg}`, { code, exit: 2 });
+
+// The line added to the owner's CLAUDE.md. Doctor reads exactly this shape as the import.
+export const CLAUDE_LINE = "@AGENTS.md";
+// The starter kit's seven folders. Five or more of them at the top is an Iris Vault.
+export const IRIS_VAULT_DIRS = ["00_Inbox", "01_Projects", "02_Areas", "03_Resources", "04_Archive", "05_Attachments", "06_Metadata"];
+// Folders no one keeps notes in: tooling, never asked about.
+const IGNORED = new Set(["dist", "build"]); // plus outsideRecord: node_modules, any *.nosync
+// What the adopt writes under these is derived state, rebuilt by the tooling, so an edit there never
+// blocks a revert.
+const DERIVED = [".evda/"];
+// The files whose bytes are kept before the adopt runs, because the adopt (or an installer it calls)
+// may change them. Anything else that changes is a bug, and the adopt says so.
+const MAY_CHANGE = ["CLAUDE.md", "GEMINI.md", "AGENTS.md", "evda.json", ".claude/settings.json", README_REL];
+
+// The Iris Vault mapping, as the reference instance (the starter kit's author's own vault) keeps it.
+// `make: true` is a folder the role needs that the starter kit does not ship.
+const IRIS_VAULT_MAP = [
+  { key: "record/daily", path: "06_Metadata/Daily Journal", make: true },
+  { key: "record/captures", path: "00_Inbox" },
+  { key: "record/people", path: "02_Areas/Relationships/People", make: true },
+  { key: "collections", path: "01_Projects" },
+  { key: "collections/areas", path: "02_Areas" },
+  { key: "collections/archive", path: "04_Archive" },
+  { key: "collections/attachments", path: "05_Attachments" },
+  { key: "knowledge", path: "03_Resources" },
+  { key: "knowledge/self", path: "02_Areas/Self-Knowledge" },
+  { key: "knowledge/reference", path: "06_Metadata/Reference" },
+  { key: "knowledge/templates", path: "06_Metadata/Templates" },
+];
+
+// A folder's name, read for what it holds: "02_Daily Notes" -> "daily notes".
+const bare = (name) => name.replace(/^\d+[\s._-]*/, "").trim().toLowerCase();
+const NAME_ROLES = [
+  [/^(daily|daily notes|dailies|journal|journals|diary|days|daily journal)$/, "record/daily"],
+  [/^(inbox|captures|capture)$/, "record/captures"],
+  [/^(people|persons|contacts)$/, "record/people"],
+  [/^(projects?)$/, "collections"],
+  [/^(areas?)$/, "collections/areas"],
+  [/^(archives?)$/, "collections/archive"],
+  [/^(attachments|assets|media|files)$/, "collections/attachments"],
+  [/^(resources|notes|wiki|knowledge|references?)$/, "knowledge"],
+  [/^(templates)$/, "knowledge/templates"],
+];
+const roleFromName = (name) => NAME_ROLES.find(([re]) => re.test(bare(name)))?.[1] ?? null;
+const facetSlug = (name) => bare(name).replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "folder";
+
+// Which keys an owner may map a folder to: the record facets and any four-role key.
+export function adoptableKey(key) {
+  if (["record/daily", "record/captures", "record/people"].includes(key)) return true;
+  if (ROLES[key] && !ROLES[key].four) return false;
+  return fourRoleOf(key) !== null && /^[a-z]+(\/[a-z0-9][a-z0-9-]*)?$/.test(key);
+}
+
+// Parse `--map` answers: "<folder>=<key>" or "<folder>=none".
+export function parseMapArgs(values) {
+  const map = {};
+  for (const v of values) {
+    const i = v.lastIndexOf("=");
+    if (i <= 0) throw refuse(`--map takes <folder>=<role>, got ${JSON.stringify(v)}.`, "BAD_MAP");
+    map[v.slice(0, i).replace(/\/+$/, "")] = v.slice(i + 1).trim();
+  }
+  return map;
+}
+
+// The mapping this folder would get, without writing anything:
+// { dir, layout: "iris-vault" | "folder", entries: [{ key, path, make, why }], unplaced, ignored, problems }.
+export function proposeAdoption(dirIn, { map = {} } = {}) {
+  const dir = resolve(dirIn);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw refuse(`${dir} is not a folder.`, "NOT_A_FOLDER");
+  const top = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".") && !IGNORED.has(d.name) && !outsideRecord(d.name)).map((d) => d.name).sort();
+  const iris = IRIS_VAULT_DIRS.filter((d) => top.includes(d)).length >= 5;
+  const entries = [];
+  const problems = [];
+  const has = (rel) => existsSync(join(dir, rel)) && statSync(join(dir, rel)).isDirectory();
+  const answered = new Set(Object.keys(map));
+  for (const [folder, key] of Object.entries(map)) {
+    if (key === "none") continue;
+    if (!adoptableKey(key)) { problems.push(`--map ${folder}=${key}: "${key}" is not a role a folder can fill. Use record/daily, record/captures, record/people, or journal, work, collections, knowledge (each with an optional /facet), or none.`); continue; }
+    if (resolve(dir, folder) === dir || !resolve(dir, folder).startsWith(dir + sep)) { problems.push(`--map ${folder}: the folder must be inside ${dir}.`); continue; }
+    entries.push({ key, path: posix(folder), make: !has(folder), why: "your answer" });
+  }
+  const taken = () => new Set(entries.map((e) => e.key));
+  const add = (e) => {
+    if (answered.has(e.path) || entries.some((x) => x.path === e.path)) return true;
+    if (taken().has(e.key)) return false;
+    entries.push(e);
+    return true;
+  };
+  const unplaced = [];
+  if (iris) {
+    for (const m of IRIS_VAULT_MAP) if (m.make || has(m.path)) add({ key: m.key, path: m.path, make: !has(m.path), why: "Iris Vault layout" });
+  }
+  for (const name of top) {
+    if (answered.has(name) || entries.some((e) => e.path === name)) continue;
+    if (iris && IRIS_VAULT_DIRS.includes(name)) continue;
+    let key = roleFromName(name);
+    if (key && taken().has(key)) {
+      const role = fourRoleOf(key);
+      key = key.startsWith("record/") ? null : `${role}/${facetSlug(name)}`;
+      if (key && taken().has(key)) key = null;
+    }
+    if (!key && falsified("guess-unplaced")) key = `knowledge/${facetSlug(name)}`;
+    if (key) add({ key, path: name, make: false, why: `its name, "${name}"` });
+    else unplaced.push(name);
+  }
+  const keys = entries.map((e) => e.key);
+  for (const k of new Set(keys)) if (keys.filter((x) => x === k).length > 1) problems.push(`"${k}" is answered for ${entries.filter((e) => e.key === k).map((e) => e.path).join(" and ")}; one folder fills one key. Give the others a facet, such as ${fourRoleOf(k) ?? "knowledge"}/<name>.`);
+  const paths = entries.map((e) => e.path);
+  for (const p of new Set(paths)) if (paths.filter((x) => x === p).length > 1) problems.push(`${p} is mapped twice; a folder fills one role.`);
+  if (!keys.includes("record/daily")) problems.push('no folder holds the daily notes, which is where the owner\'s words are filed. Name one with --map "<folder>=record/daily" (it is made if it is not there).');
+  return { dir, layout: iris ? "iris-vault" : "folder", entries, unplaced, ignored: Object.entries(map).filter(([, k]) => k === "none").map(([f]) => f), problems };
+}
+
+// The questions a proposal still needs answered, in plain words, one per folder.
+export function adoptQuestions(p) {
+  const out = p.unplaced.map((f) => `${f}/: what does this folder hold? Answer with --map "${f}=<role>": journal (dated writing), collections (things kept together), knowledge (what you learn from), work (efforts with an end), or none to leave it out of the record.`);
+  return [...out, ...p.problems];
+}
+
+export function proposalLines(p) {
+  const out = [`${p.dir}: ${p.layout === "iris-vault" ? "an Iris Vault. Its folders map without asking." : "a folder of notes."}`];
+  for (const e of p.entries) out.push(`  ${e.key.padEnd(24)} ${e.path}${e.make ? "  (made, empty)" : ""}  [${e.why}]`);
+  for (const f of p.ignored) out.push(`  ${"(left out)".padEnd(24)} ${f}  [your answer]`);
+  return out;
+}
+
+// ---- snapshot: what the folder holds before, so the adopt can say what it changed ----
+
+function walk(root, { files, dirs }, rel = "") {
+  for (const d of readdirSync(join(root, rel), { withFileTypes: true })) {
+    const r = rel ? `${rel}/${d.name}` : d.name;
+    if (d.name === ".git" || outsideRecord(d.name)) continue;
+    const abs = join(root, r);
+    const st = lstatSync(abs);
+    if (st.isDirectory()) { dirs.set(r, { atimeMs: st.atimeMs, mtimeMs: st.mtimeMs }); walk(root, { files, dirs }, r); }
+    else files.set(r, { size: st.size, mtimeMs: st.mtimeMs, mode: st.mode & 0o7777, atimeMs: st.atimeMs });
+  }
+  return { files, dirs };
+}
+
+function snapshot(root) {
+  const s = walk(root, { files: new Map(), dirs: new Map() });
+  const rootSt = statSync(root);
+  s.dirs.set("", { atimeMs: rootSt.atimeMs, mtimeMs: rootSt.mtimeMs });
+  const kept = new Map();
+  const keep = (rel) => { if (s.files.has(rel)) kept.set(rel, readFileSync(join(root, rel))); };
+  for (const rel of MAY_CHANGE) keep(rel);
+  for (const rel of s.files.keys()) if (rel.startsWith(".claude/hooks/") || rel.startsWith(".evda/")) keep(rel);
+  s.kept = kept;
+  return s;
+}
+
+// ---- adopt ----
+
+function render(name) {
+  return readFileSync(join(TEMPLATES, name), "utf8");
+}
+
+function localDate(d = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+const slug = (name) => String(name).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "record";
+
+export function adoptDir(env = process.env) {
+  return env.EVDA_ADOPT_DIR ?? join(env.HOME ?? homedir(), ".evda", "adopt");
+}
+
+// A person folder fails doctor for every note without person-profile frontmatter, so its manifest is
+// written only when the folder holds no note yet.
+function noNotes(abs) {
+  return !existsSync(abs) || readdirSync(abs).every((n) => n.startsWith(".") || n === "README.md" || !/\.md$/i.test(n));
+}
+
+const FOLDER_TYPES = { "record/daily": "record", "record/captures": "capture", "record/people": "person" };
+
+export function adopt(dirIn, { map = {}, filing = null, owner = "", agentName = null, dry = false, hooks = true, manifestOut = null, pointer = true, now = new Date(), env = process.env, version = null } = {}) {
+  const dir = resolve(dirIn);
+  if (filing !== null && !FILING_MODES.includes(filing)) throw refuse(`filing is ${FILING_MODES.join(" or ")}, got ${JSON.stringify(filing)}.`, "BAD_FILING");
+  if (existsSync(join(dir, "evda.json"))) throw refuse(`${dir} already holds evda.json, so it is already an EVDA. Nothing was written. \`evda update\` keeps it current.`, "ALREADY_ADOPTED");
+  const p = proposeAdoption(dir, { map });
+  const questions = adoptQuestions(p);
+  const agentsText = fillOwnerSection(render("AGENTS.md"), { agentName, owner, purpose: "", voice: "", ai: "" });
+  const result = { dir, dry, proposal: p, questions, lines: proposalLines(p) };
+  if (dry) {
+    const rd = ensureReadme(dir, { agents: agentsText, dry: true });
+    return { ...result, readme: rd, lines: [...result.lines, `  ${dryReadmeLine(rd)}`] };
+  }
+  if (questions.length) throw new EvdaError(["REFUSED: some folders need your answer before anything is written. Nothing was written.", ...questions.map((q) => `  ${q}`)].join("\n"), { code: "NEEDS_ANSWERS", exit: 2 });
+  for (const f of ["AGENTS.md"]) if (existsSync(join(dir, f))) throw refuse(`${f} is already in ${dir}, and the adopt writes its own; it never overwrites a file of yours. Rename it, or map it by hand in evda.json. Nothing was written.`, "AGENTS_EXISTS");
+
+  const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\..*$/, "");
+  const manifestAbs = resolve(manifestOut ?? join(adoptDir(env), `${slug(dir.split(sep).pop())}-${stamp}.json`));
+  if (manifestAbs === dir || manifestAbs.startsWith(dir + sep)) throw refuse("the reversal manifest goes outside the folder it reverses. Name another with --manifest.", "MANIFEST_INSIDE");
+  if (existsSync(manifestAbs)) throw refuse(`a reversal manifest is already at ${manifestAbs}. Name another with --manifest.`, "MANIFEST_EXISTS");
+
+  const before = snapshot(dir);
+  const today = localDate(now);
+  const name = dir.split(sep).pop();
+  const madeDirs = [];
+  const mkdirp = (rel) => {
+    const segs = rel.split("/");
+    for (let i = 1; i <= segs.length; i++) {
+      const sub = segs.slice(0, i).join("/");
+      if (existsSync(join(dir, sub))) continue;
+      mkdirSync(join(dir, sub));
+      madeDirs.push(sub);
+    }
+  };
+  const writeNew = (rel, text) => { mkdirp(posix(dirname(rel)) === "." ? "" : posix(dirname(rel))); writeFileSync(join(dir, rel), text, { flag: "wx" }); };
+
+  // 1. Folders a role needs that are not there.
+  for (const e of p.entries) if (e.make) mkdirp(e.path);
+  // 2. The manifest.
+  const mapping = { agents: "AGENTS.md" };
+  for (const e of p.entries) mapping[e.key] = e.path;
+  const manifest = { evda: SCHEMA_VERSION, id: `${slug(name)}.atlas`, name, owner: { name: owner ?? "", kind: "person" }, created: today, layers: ["record"], mapping, subrecords: "bounded", adopted: { from: p.layout, date: today } };
+  if (filing) manifest.filing = filing;
+  writeNew("evda.json", JSON.stringify(manifest, null, 2) + "\n");
+  // 3. The operating layer, the one create-evda ships, with the owner section filled from the answers.
+  writeNew("AGENTS.md", agentsText);
+  // 3b. The README sections AGENTS.md cites (HQ-2812): appended as one marked block, or the whole
+  // README when there is none. The owner's text is never touched.
+  const readme = ensureReadme(dir, { agents: agentsText });
+  // 4. Loaders. The owner's CLAUDE.md is theirs: one line is added at its end and nothing else changes.
+  const claude = join(dir, "CLAUDE.md");
+  let claudeAdded = null;
+  if (existsSync(claude) && !falsified("claude-rewrite")) {
+    const text = readFileSync(claude, "utf8");
+    if (!new RegExp(`^${CLAUDE_LINE.replace(/[.]/g, "\\.")}\\s*$`, "m").test(text)) {
+      claudeAdded = `${text === "" || text.endsWith("\n") ? "" : "\n"}\n${CLAUDE_LINE}\n`;
+      writeFileSync(claude, text + claudeAdded);
+    }
+  } else {
+    writeFileSync(claude, render("CLAUDE.md").replaceAll("{{agents}}", "AGENTS.md"));
+  }
+  if (!existsSync(join(dir, "GEMINI.md"))) writeNew("GEMINI.md", render("GEMINI.md").replaceAll("{{agents}}", "AGENTS.md"));
+  // 5. What each record folder holds.
+  for (const [key, type] of Object.entries(FOLDER_TYPES)) {
+    const rel = mapping[key];
+    if (!rel || existsSync(join(dir, rel, FOLDER_MANIFEST))) continue;
+    if (type === "person" && !noNotes(join(dir, rel))) continue;
+    writeNew(`${rel}/${FOLDER_MANIFEST}`, JSON.stringify({ type, connectors: [], views: [] }, null, 2) + "\n");
+  }
+  // 6. .evda/, then the hooks `evda hook install` adds, then the index.
+  writeVersion(dir, SCHEMA_VERSION);
+  if (version) stampInstalledVersion(dir, version);
+  const hookLines = [];
+  if (hooks) {
+    const h = installHook(dir);
+    hookLines.push(`Claude Code Stop hook: ${h.action} (${h.settings} runs ${h.hook}, in this folder only)`);
+    const g = installGuard(dir);
+    hookLines.push(`read guard: ${g.action} ${posix(relative(dir, g.path))}`);
+    if (filing === "everything") { const ph = installPromptHook(dir); hookLines.push(`prompt hook: ${ph.action} (${ph.settings} runs ${ph.hook}, which files each message you send)`); }
+  }
+  reindex(openEvda(dir));
+
+  // 7. What changed, read back from the folder rather than trusted from the steps above.
+  const after = walk(dir, { files: new Map(), dirs: new Map() });
+  const created = [];
+  const modified = [];
+  const unexpected = [];
+  for (const [rel, st] of after.files) {
+    const was = before.files.get(rel);
+    const buf = readFileSync(join(dir, rel));
+    if (!was) { created.push({ path: rel, sha256: sha256(buf), ...(rel === "AGENTS.md" ? { outside: sha256(Buffer.from(outsideFence(buf.toString("utf8")))) } : {}) }); continue; }
+    const kept = before.kept.get(rel);
+    if (kept ? kept.equals(buf) : was.size === st.size && was.mtimeMs === st.mtimeMs) continue;
+    if (!kept) { unexpected.push(rel); continue; }
+    modified.push({ path: rel, before: kept.toString("base64"), mode: was.mode, atimeMs: was.atimeMs, mtimeMs: was.mtimeMs, sha256: sha256(buf), ...(rel === "CLAUDE.md" && claudeAdded ? { added: claudeAdded } : {}), ...(rel === README_REL && readme.added ? { added: readme.added, block: true } : {}) });
+  }
+  const dirs = [...after.dirs.keys()].filter((d) => !before.dirs.has(d));
+  const dirTimes = [...before.dirs].filter(([d]) => existsSync(join(dir, d))).map(([d, t]) => ({ path: d, ...t }));
+
+  let pointerAction = "left alone";
+  let wrotePointer = false;
+  if (pointer) {
+    const existing = readPointer(env);
+    if (existing === null) { setPointer(dir, env); pointerAction = "written"; wrotePointer = true; }
+    else pointerAction = `already points at ${existing}; run \`evda use ${dir}\` to switch`;
+  }
+
+  const record = { evdaAdopt: ADOPT_VERSION, target: dir, adopted: now.toISOString(), layout: p.layout, mapping, created, modified, dirs, dirTimes, unexpected, pointer: wrotePointer ? { path: pointerPath(env), target: dir } : null };
+  mkdirSync(dirname(manifestAbs), { recursive: true });
+  writeFileSync(manifestAbs, JSON.stringify(record, null, 2) + "\n", { flag: "wx" });
+
+  // Doctor, after the manifest, so a failing doctor still leaves the way back.
+  const doctorLines = [];
+  const report = doctor(dir, { out: (l) => doctorLines.push(l), via: "evda adopt" });
+  const lines = [
+    `adopted ${dir} in place. Nothing moved.`,
+    ...proposalLines(p).slice(1),
+    `  wrote    ${created.length} new file(s): ${created.map((c) => c.path).join(", ")}`,
+    `  changed  ${modified.length} file(s) of yours: ${modified.map((m) => m.path + (m.block ? ` (EVÐA's block added at the end: ${readme.citations.map((c) => `"${c}"`).join(", ")})` : m.added ? " (one line added at the end)" : "")).join(", ") || "none"}`,
+    ...(dirs.length ? [`  made     ${dirs.length} folder(s): ${dirs.join(", ")}`] : []),
+    ...hookLines.map((l) => `  ${l}`),
+    `  filing:  ${filing === "everything" ? "everything you say is filed automatically" : filing === "asked" ? "only when you ask" : "not answered yet; your agent asks the first time you connect"}`,
+    `  locator ${pointerPath(env)}: ${pointerAction}`,
+    `CHECKED ${before.files.size} file(s) that were here  ${before.files.size - modified.length - unexpected.length} unchanged, ${modified.length} changed by the adopt and kept in the manifest, ${unexpected.length} changed unexpectedly`,
+    ...(unexpected.length ? [`FAIL  adopt  changed ${unexpected.join(", ")}, which it does not keep the bytes of. That is a bug in evda adopt.`] : []),
+    `Reversal manifest: ${manifestAbs}  (evda adopt --revert ${manifestAbs})`,
+    "",
+    ...doctorLines,
+  ];
+  return { ...result, manifest: manifestAbs, record, doctor: report, lines, exit: report.exit === 0 && !unexpected.length ? 0 : 1 };
+}
+
+// What the owner pastes into the Claude desktop app (and Cowork) to reach the record, and the
+// every-chat line, from the sources create-evda prints them from.
+export function connectLines(dir, filing) {
+  const out = ["Connect your AI to it through the evda MCP server. No key and no model call in EVÐA:"];
+  for (const c of clients(dir)) if (c.key !== "project" && c.key !== "every-chat") { out.push(`  ${c.label}:`); for (const l of c.text.split("\n")) out.push(`    ${l}`); }
+  out.push("", ...everyChatSetupLines(filing ?? null));
+  return out;
+}
+
+// What a dry run says about README.md, naming the sections it would add.
+function dryReadmeLine(r) {
+  const names = r.citations.map((c) => `"${c}"`).join(", ");
+  if (r.action === "written") return `${README_REL}: would be written, with ${names}`;
+  if (r.action === "appended") return `${README_REL}: EVÐA's block would be added at the end, with ${names}; your text above it stays as it is`;
+  return `${README_REL}: already has ${names}; left alone`;
+}
+
+// ---- revert ----
+
+export function loadAdoptManifest(path) {
+  const abs = resolve(path);
+  if (!existsSync(abs)) throw refuse(`no adopt manifest at ${abs}.`, "NO_MANIFEST");
+  let m;
+  try { m = JSON.parse(readFileSync(abs, "utf8")); } catch (e) { throw refuse(`${abs} is not valid JSON (${e.message}).`, "BAD_MANIFEST"); }
+  if (m?.evdaAdopt !== ADOPT_VERSION || !Array.isArray(m.created) || !Array.isArray(m.modified)) throw refuse(`${abs} is not an adopt reversal manifest.`, "BAD_MANIFEST");
+  return { m, abs };
+}
+
+const countFiles = (abs) => readdirSync(abs, { withFileTypes: true }).reduce((n, d) => n + (d.isDirectory() ? countFiles(join(abs, d.name)) : 1), 0);
+const hashOf = (abs) => (existsSync(abs) && lstatSync(abs).isFile() ? sha256(readFileSync(abs)) : null);
+
+// AGENTS.md as the owner edits it: everything outside the generated block, which `evda upgrade` owns.
+const outsideFence = (text) => { try { const p = splitFence(text); return p ? p.before + p.after : text; } catch { return text; } };
+
+// CLAUDE.md with the adopt's one line taken back out, or null when that line is not there to take.
+function withoutLine(text, added) {
+  if (text.endsWith(added)) return text.slice(0, -added.length);
+  const lines = text.split("\n");
+  const at = lines.map((l, i) => (l.trim() === CLAUDE_LINE ? i : -1)).filter((i) => i >= 0);
+  if (at.length !== 1) return null;
+  const i = at[0];
+  const drop = i > 0 && lines[i - 1] === "" ? [i - 1, i] : [i];
+  return lines.filter((_, j) => !drop.includes(j)).join("\n");
+}
+
+export function revertAdopt(path, { force = false, now = new Date(), env = process.env } = {}) {
+  const { m, abs } = loadAdoptManifest(path);
+  if (m.reverted) throw refuse(`${abs} was already reverted at ${m.reverted}. Nothing was changed.`, "ALREADY_REVERTED");
+  const root = m.target;
+  const edited = [];
+  const gone = [];
+  for (const f of m.created) {
+    const a = join(root, f.path);
+    const h = hashOf(a);
+    if (h === null) { gone.push(f.path); continue; }
+    if (h === f.sha256 || DERIVED.some((d) => f.path.startsWith(d))) continue;
+    if (f.outside && sha256(Buffer.from(outsideFence(readFileSync(a, "utf8")))) === f.outside) continue;
+    edited.push(f.path);
+  }
+  const ownerEdits = [];
+  for (const f of m.modified) {
+    const a = join(root, f.path);
+    if (hashOf(a) === f.sha256) continue;
+    if (f.block && existsSync(a)) {
+      // The README block: refreshed by `evda upgrade` and nothing else, the bytes before come back
+      // whole; edited around by the owner, their edits stay and only the block goes.
+      const rest = withoutBlock(readFileSync(a, "utf8"), f.added);
+      if (rest !== null && Buffer.from(rest).equals(Buffer.from(f.before, "base64"))) continue;
+      if (rest !== null) { ownerEdits.push(f.path); continue; }
+    }
+    if (f.added && !f.block && existsSync(a) && withoutLine(readFileSync(a, "utf8"), f.added) !== null) { ownerEdits.push(f.path); continue; }
+    edited.push(f.path);
+  }
+  if (edited.length && !force && !falsified("revert-ignores-edits")) {
+    throw refuse(`${edited.length} file(s) the adopt wrote or changed were edited since: ${edited.join(", ")}. Reverting would lose those edits. Pass --force to revert anyway. Nothing was changed.`, "EDITED_SINCE_ADOPT");
+  }
+  let removed = 0;
+  for (const f of m.created) { const a = join(root, f.path); if (existsSync(a)) { unlinkSync(a); removed += 1; } }
+  let restored = 0;
+  if (!falsified("revert-not-exact")) {
+    for (const f of m.modified) {
+      const a = join(root, f.path);
+      const st = existsSync(a) ? statSync(a) : null;
+      if (ownerEdits.includes(f.path) && !force) {
+        // Their edits stay: only the line the adopt added is taken out.
+        writeFileSync(a, f.block ? withoutBlock(readFileSync(a, "utf8"), f.added) : withoutLine(readFileSync(a, "utf8"), f.added));
+        if (st) utimesSync(a, st.atimeMs / 1000, st.mtimeMs / 1000);
+      } else {
+        mkdirSync(dirname(a), { recursive: true });
+        writeFileSync(a, Buffer.from(f.before, "base64"));
+        chmodSync(a, f.mode);
+        utimesSync(a, f.atimeMs / 1000, f.mtimeMs / 1000);
+      }
+      restored += 1;
+    }
+  }
+  // A derived folder the adopt made (.evda/) goes whole: what the tooling wrote into it since (the
+  // update check's throttle, a rebuilt index) is state it rebuilds, never the owner's.
+  let derived = 0;
+  for (const d of m.dirs) if (DERIVED.includes(`${d}/`) && existsSync(join(root, d))) { derived += countFiles(join(root, d)); rmSync(join(root, d), { recursive: true }); }
+  const kept = [];
+  for (const d of [...m.dirs].sort((a, b) => b.split("/").length - a.split("/").length || b.localeCompare(a))) {
+    const a = join(root, d);
+    if (!existsSync(a)) continue;
+    if (readdirSync(a).length) { kept.push(d); continue; }
+    rmdirSync(a);
+  }
+  let times = 0;
+  for (const d of [...m.dirTimes].sort((a, b) => b.path.split("/").length - a.path.split("/").length)) {
+    const a = join(root, d.path);
+    if (!existsSync(a) || !statSync(a).isDirectory()) continue;
+    utimesSync(a, d.atimeMs / 1000, d.mtimeMs / 1000);
+    times += 1;
+  }
+  let pointer = "left alone";
+  if (m.pointer && readPointer({ ...env, EVDA_CURRENT_FILE: m.pointer.path }) === m.pointer.target) { unlinkSync(m.pointer.path); pointer = `removed ${m.pointer.path}, which the adopt wrote`; }
+  m.reverted = now.toISOString();
+  writeFileSync(abs, JSON.stringify(m, null, 2) + "\n");
+  return { manifest: abs, target: root, removed, restored, derived, kept, gone, edited, ownerEdits: force ? [] : ownerEdits, forced: force && edited.length > 0, times, pointer };
+}
+
+export function revertLines(r) {
+  const out = [`Reverted the adopt of ${r.target}.`, `  removed  ${r.removed} file(s) the adopt wrote`, `  restored ${r.restored} file(s) of yours to their bytes before it`];
+  if (r.derived) out.push(`  removed  .evda/, which the adopt made, with ${r.derived} file(s) the tooling wrote into it since`);
+  for (const f of r.ownerEdits) out.push(`  kept     your edits to ${f}; only the ${f === README_REL ? "EVÐA block" : `${CLAUDE_LINE} line`} the adopt added was taken out`);
+  if (r.forced) out.push(`  forced   ${r.edited.length} file(s) edited since the adopt were reverted anyway: ${r.edited.join(", ")}`);
+  for (const d of r.kept) out.push(`  kept     ${d}/, which holds files the adopt did not write`);
+  if (r.gone.length) out.push(`  gone     ${r.gone.length} file(s) were already removed`);
+  out.push(`  locator: ${r.pointer}`);
+  out.push(`CHECKED ${r.removed + r.restored} file(s) reverted  ${r.times} folder time(s) restored, ${r.kept.length} folder(s) kept`);
+  return out;
+}
+
+// ---- the terminal question, and the MCP tool ----
+
+export const FILING_QUESTION = (agent) => `Should ${agent || DEFAULT_AGENT_NAME} file everything you say automatically, or only when you ask? (everything)`;
+export { filingKey };
+
+export function adoptTool(args = {}, { env = process.env, version = null } = {}) {
+  const allowed = ["dir", "map", "filing", "owner", "dry", "confirmed"];
+  const extra = Object.keys(args).filter((k) => !allowed.includes(k));
+  if (extra.length) throw refuse(`evda_adopt does not take ${extra.join(", ")}. It takes ${allowed.join(", ")}.`, "BAD_ARGS");
+  if (typeof args.dir !== "string" || !args.dir.trim()) throw refuse('evda_adopt needs "dir", the folder of notes to adopt where it is.', "NO_DIR");
+  if (args.map !== undefined && (args.map === null || typeof args.map !== "object" || Array.isArray(args.map) || Object.values(args.map).some((v) => typeof v !== "string"))) throw refuse('evda_adopt "map" is an object of folder -> role, from the owner\'s answers.', "BAD_MAP");
+  if (args.filing !== undefined && !FILING_MODES.includes(args.filing)) throw refuse(`evda_adopt "filing" is ${FILING_MODES.join(" or ")}, the owner's answer.`, "BAD_FILING");
+  const opts = { map: args.map ?? {}, filing: args.filing ?? null, owner: typeof args.owner === "string" ? args.owner : "", env, version };
+  if (args.dry === true) return adopt(args.dir, { ...opts, dry: true });
+  if (args.confirmed !== true) throw refuse('evda_adopt needs "confirmed": true, and that is true only when the owner said yes to adopting this folder in this conversation. Call it with dry: true first, show them the mapping, ask about each folder it names, and wait.', "NOT_CONFIRMED");
+  return adopt(args.dir, opts);
+}

package/lib/agents.mjs

@@ -16,7 +16,7 @@ import { EvdaError } from "./errors.mjs";
 
 export const FENCE_OPEN = "<!-- evda:generated -->";
 export const FENCE_CLOSE = "<!-- /evda:generated -->";
-export const DIGEST_BUDGET = 4096;
+export const DIGEST_BUDGET = 6144;
 export const TEMPLATE_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "AGENTS.md");
 
 // {before, generated, after} where generated INCLUDES both fence lines, or null if no fence.