create-evda 0.1.4 → 0.1.6

package/lib/gather.mjs

@@ -0,0 +1,808 @@
+// `evda gather`: point EVDA at a pile the owner already has (a Documents folder, a Notes or
+// Obsidian export, a contacts export) and get back a proposal for the EVDA it would become.
+// Spec 07, "Gathering a pile".
+//
+// Three steps, each its own function, and none of them writes into a source or into a record:
+//
+//   scan      walk each source, type every file with a person-layer kind, and record the facts a
+//             placement needs: its subject, the project it sits in, the people it mentions, whether
+//             it reads like therapy notes. App state (.obsidian/, .DS_Store) is skipped and said so.
+//   place     derive the preset, the folders, and one placement per item from those facts and the
+//             owner's answers. Pure: the same facts and answers give the same placements.
+//   questions derive what to ask: only a question whose answers give different placements is kept,
+//             so the owner is never asked something that changes nothing.
+//
+// The proposal is one JSON file outside every source and every record: `--out`, or
+// $EVDA_GATHER_DIR, or ~/.evda/gather/. Anything an app holds (a Contacts card, a bookmark, a list
+// of links) becomes a reference (Spec 07 section 4), and the proposal never carries its payload:
+// a card's phone number and email are read to be discarded. A file holding something shaped like a
+// secret is refused and quoted nowhere. The proposal quotes at most a heading or the one word that
+// typed an item, never a sentence from a note.
+//
+// EVDA holds no key and calls no model. `--with-ai` hands the items it could not place to the
+// owner's own `claude -p`, the same way `evda organize --with-ai` does, and records the answer.
+//
+// With `--into <record>` the gather also reads the record it would grow: an item whose bytes the
+// record already holds (by hash, or by the record's own list of what it gathered) is marked present
+// and placed nowhere, and a person who already has a page there is not asked about. So a second
+// gather asks only about what is new. Applying the proposal is lib/gather-apply.mjs.
+//
+// A placed `.txt` note is named `.md` on the way in, its bytes unchanged: plain text is already
+// markdown, and every reader in EVDA (the occurrence index, doctor, search) reads `.md`. Nothing
+// else is renamed; an `.html` export keeps its name, because making it markdown would change it.
+//
+// A chat export (HQ-1385: Claude.ai's or ChatGPT's conversations.json) is not a file to place. It is
+// the backstop for what an agent did not file while the conversation happened: the owner's own
+// messages the record does not already hold are added to their day at apply, under the
+// conversation's date and time (lib/chat-export.mjs). The proposal carries only counts.
+//
+// EVDA_GATHER_FALSIFY=<mode,...> breaks one guarantee on purpose, so the tests can show each check
+// fails when its guarantee is gone. The gather's modes are FALSIFY_MODES below and the apply's are
+// APPLY_FALSIFY_MODES in lib/gather-apply.mjs; nothing reads it otherwise.
+
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, appendFileSync } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { loadPreset, listPresets } from "./presets.mjs";
+import { fourRoleOf } from "./roles.mjs";
+import { secretShape } from "./references.mjs";
+import { findRoot, openEvda } from "./manifest.mjs";
+import { folderManifests } from "./folders.mjs";
+import { askOwnersAi } from "./organize.mjs";
+import { onlyKeys, refuse, dayFile } from "./tools.mjs";
+import { readChatExport, conversations, filedSections, backfillPlan, CHAT_FORMATS } from "./chat-export.mjs";
+import { EvdaError } from "./errors.mjs";
+import { frontmatterOf, heldBy, withoutSealed, carries, NOTED } from "./circles.mjs";
+
+export const GATHER_VERSION = 1;
+// The person-layer kinds an item is typed with, and the folder type each lives under.
+export const GATHER_KINDS = ["note", "person", "project", "event", "log", "source", "piece", "blob", "capture"];
+export const FOLDER_TYPE_FOR = { note: "record", person: "person", project: "project", event: "event", log: "log", source: "source", piece: "piece", blob: "blob", capture: "capture" };
+export const FALSIFY_MODES = ["touch-source", "copy-contacts", "ask-everything", "answer-no-replace", "keep-secrets", "examine-nothing", "no-role"];
+// The role each kind fills when the preset has no folder for it (Spec 07 section 2, HQ-1371):
+// what happened, dated, is journal; one folder per thing is collections; what is known is knowledge.
+export const ROLE_FOR_KIND = { note: "journal", capture: "journal", log: "journal", person: "collections", project: "collections", event: "collections", piece: "collections", blob: "collections", course: "collections", source: "knowledge", areas: "collections" };
+// A person is asked about once this many files mention them and no page for them exists.
+export const PEOPLE_MIN_FILES = 3;
+
+const falsified = (mode) => (process.env.EVDA_GATHER_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+const posix = (p) => p.split(sep).join("/");
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+const SKIP_NAMES = new Set([".DS_Store", "Thumbs.db", "desktop.ini", "node_modules", ".git", ".obsidian", ".trash", ".Trash", "__MACOSX"]);
+const APP_DIRS = { ".obsidian": "obsidian" };
+const ARCHIVE_EXT = new Set([".zip", ".tar", ".gz", ".tgz", ".7z", ".rar"]);
+const BINARY_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".heic", ".webp", ".pdf", ".mov", ".mp4", ".m4a", ".mp3", ".wav", ".xlsx", ".xls", ".docx", ".doc", ".pptx", ".key", ".pages", ".numbers", ".sqlite", ".db"]);
+const TEXT_MAX = 2 * 1024 * 1024;
+// Folder names that hold things without saying what they are about, so they are not a subject.
+const CONTAINERS = new Set(["documents", "desktop", "downloads", "notes", "daily", "inbox", "captures", "vault", "obsidian vault", "misc", "stuff", "untitled folder", "new folder", "export", "icloud drive"]);
+const COURSE = /\b[A-Z]{2,4}\s?\d{3}[A-Z]?\b/;
+const COURSE_WORD = /\b(syllabus|lecture|homework|problem set|midterm)\b/i;
+const THERAPY = /\b(therapy|therapist|counsell?or|counselling|counseling|psychiatrist|psychologist|CBT|EMDR)\b/i;
+const FINISHED = /\b(shipped|finished|wrapped up|completed|retro|retrospective|post-?mortem|archived|done;|done\.)/i;
+const MEETING = /\b(meeting|sync|standup|stand-up|1-1|1:1|one on one|design review|call with|interview)\b/i;
+const ATTENDEES = /^(?:attendees|participants|with|present)\s*:\s*(.+)$/im;
+const URL_LINE = /^https?:\/\/\S+$/;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const LEADING_DAY = /^(\d{4}-\d{2}-\d{2})\b/;
+
+function isBinary(buf) {
+  const n = Math.min(buf.length, 8192);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+function frontmatter(text) {
+  if (!text.startsWith("---\n")) return { fm: {}, body: text };
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return { fm: {}, body: text };
+  const fm = {};
+  for (const line of text.slice(4, end).split("\n")) {
+    const m = /^([A-Za-z_][\w-]*):\s*(.*?)\s*$/.exec(line);
+    if (m) fm[m[1].toLowerCase()] = m[2].replace(/^["']|["']$/g, "");
+  }
+  return { fm, body: text.slice(text.indexOf("\n", end + 1) + 1) };
+}
+
+const stripHtml = (t) => t.replace(/<(script|style)[\s\S]*?<\/\1>/gi, "").replace(/<br\s*\/?>/gi, "\n").replace(/<\/h\d>/gi, "\n\n").replace(/<\/(p|div|li)>/gi, "\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&");
+
+function headingOf(body) {
+  const h = /^#{1,6} (.+)$/m.exec(body);
+  if (h) return h[1].trim();
+  // A plain text export's title is its first line, when a blank line and more words follow it.
+  const lines = body.split("\n");
+  const at = lines.findIndex((l) => l.trim() !== "");
+  if (at === -1 || lines[at].length > 80 || (lines[at + 1] ?? "x").trim() !== "") return null;
+  return lines.slice(at + 2).some((l) => l.trim() !== "") ? lines[at].trim() : null;
+}
+
+// Parse a vCard file into { uid, name } per card. Every other property is read past and dropped.
+function vcards(text) {
+  const out = [];
+  let card = null;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (/^BEGIN:VCARD$/i.test(line)) card = { uid: null, name: null, payload: [] };
+    else if (/^END:VCARD$/i.test(line)) { if (card?.name) out.push(card); card = null; }
+    else if (card) {
+      const m = /^([A-Z-]+)(?:;[^:]*)?:(.*)$/i.exec(line);
+      if (!m) continue;
+      const key = m[1].toUpperCase();
+      if (key === "UID") card.uid = m[2].trim();
+      else if (key === "FN") card.name = m[2].trim();
+      else if (key === "TEL" || key === "EMAIL" || key === "ADR") card.payload.push(`${key}:${m[2].trim()}`);
+    }
+  }
+  return out;
+}
+
+function weblocUrl(text) {
+  const m = /<string>(https?:\/\/[^<]+)<\/string>/.exec(text) ?? /^URL=(https?:\/\/\S+)$/m.exec(text);
+  return m ? m[1] : null;
+}
+
+const slugId = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+// ---- what a record already holds ----
+
+// Where a record keeps its list of what it gathered: one JSON line per file an apply wrote, with
+// the hash of the source bytes it came from. A file an apply changed on the way in (a reference
+// added to its frontmatter, a finished status) no longer hashes like its source; this is how a
+// second gather still knows it.
+export const GATHERED = ".evda/gathered.jsonl";
+const WALK_SKIP = new Set([".git", "node_modules", ".evda", ".obsidian", ".trash", ".DS_Store"]);
+
+// Every file in the record by the hash of its bytes, and the source hashes it has gathered.
+// Returns { byHash: Map<sha256, rel>, gathered: Map<sha256, rel> }.
+export function presentIndex(dir) {
+  const byHash = new Map();
+  const gathered = new Map();
+  if (falsified("reapply-resorts")) return { byHash, gathered };
+  const go = (d) => {
+    for (const name of readdirSync(d).sort()) {
+      if (WALK_SKIP.has(name)) continue;
+      const abs = join(d, name);
+      const st = lstatSync(abs);
+      if (st.isDirectory()) go(abs);
+      else if (st.isFile()) {
+        const h = sha256(readFileSync(abs));
+        if (!byHash.has(h)) byHash.set(h, posix(relative(dir, abs)));
+      }
+    }
+  };
+  go(dir);
+  const g = join(dir, GATHERED);
+  if (existsSync(g)) {
+    for (const line of readFileSync(g, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try { const r = JSON.parse(line); if (r.source && r.to) gathered.set(r.source, r.to); } catch { /* a line an older tool wrote; skipped */ }
+    }
+  }
+  return { byHash, gathered };
+}
+
+// Where a record already holds an item, or null.
+export const presentAt = (index, sha) => index.byHash.get(sha) ?? index.gathered.get(sha) ?? null;
+
+// The record's person pages, by name: every markdown file in a folder whose manifest says person.
+export function personPages(evda) {
+  const out = new Map();
+  for (const m of folderManifests(evda)) {
+    if (m.type !== "person") continue;
+    for (const n of readdirSync(m.dir)) if (/\.md$/i.test(n)) out.set(basename(n, extname(n)), posix(relative(evda.dir, join(m.dir, n))));
+  }
+  return out;
+}
+
+// ---- scan ----
+
+// Walk one source. Returns { files: [{ rel, abs, size }], skipped: [{ rel, why }], apps: [] }.
+function walk(root) {
+  const files = [];
+  const skipped = [];
+  const apps = new Set();
+  const st = lstatSync(root);
+  if (st.isFile()) return { files: [{ rel: basename(root), abs: root, size: st.size }], skipped, apps: [] };
+  const go = (dir) => {
+    for (const name of readdirSync(dir).sort()) {
+      const abs = join(dir, name);
+      const rel = posix(relative(root, abs));
+      if (APP_DIRS[name]) apps.add(APP_DIRS[name]);
+      if (SKIP_NAMES.has(name)) { skipped.push({ rel, why: APP_DIRS[name] ? `${APP_DIRS[name]}'s own settings, not the owner's notes` : "app or system state" }); continue; }
+      const s = lstatSync(abs);
+      if (s.isSymbolicLink()) { skipped.push({ rel, why: "a symlink; not followed" }); continue; }
+      if (s.isDirectory()) { go(abs); continue; }
+      if (!s.isFile()) { skipped.push({ rel, why: "not a regular file" }); continue; }
+      if (name.startsWith(".")) { skipped.push({ rel, why: "a hidden file" }); continue; }
+      files.push({ rel, abs, size: s.size });
+    }
+  };
+  go(root);
+  return { files, skipped, apps: [...apps] };
+}
+
+// The folders an item sits in, below the source root, without the containers.
+function subjectOf(rel, projectRoot) {
+  if (projectRoot) return null;
+  const parts = rel.split("/").slice(0, -1);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const p = parts[i];
+    if (CONTAINERS.has(p.toLowerCase())) continue;
+    if (/^(people|contacts|meetings|projects|drafts|writing|essays|clippings|reading|articles|bookmarks|logs|calendar|photos|attachments)$/i.test(p)) continue;
+    return p;
+  }
+  return null;
+}
+
+// A project is a folder directly under a folder named Projects, or any folder holding a README
+// beside at least one other file. Returns the project's folder (relative) for a file, or null.
+function projectRootFor(rel, readmeDirs) {
+  const parts = rel.split("/");
+  for (let i = 1; i < parts.length; i++) {
+    const dir = parts.slice(0, i).join("/");
+    if (i >= 2 && /^projects?$/i.test(parts[i - 2]) ) return dir;
+    if (readmeDirs.has(dir)) return dir;
+  }
+  return null;
+}
+
+// Type one file. Returns the item's facts. `text` is null for a binary.
+function typeItem({ rel, buf, ext, projectRoot }) {
+  const name = basename(rel, extname(rel));
+  const folders = rel.split("/").slice(0, -1);
+  const inFolder = (re) => folders.some((f) => re.test(f));
+  const item = { kind: null, why: [], mode: "move", confidence: "high" };
+  if (ARCHIVE_EXT.has(ext)) return { ...item, kind: "blob", archive: true, why: ["an archive file"] };
+  if (BINARY_EXT.has(ext) || isBinary(buf) || buf.length > TEXT_MAX) return { ...item, kind: "blob", why: [BINARY_EXT.has(ext) ? `a ${ext.slice(1)} file` : "binary bytes"] };
+  const raw = buf.toString("utf8");
+  const secret = raw.split("\n").map(secretShape).find(Boolean);
+  if (secret && !falsified("keep-secrets")) return { ...item, kind: "note", refused: `holds ${secret}`, why: [`holds ${secret}`] };
+  if (ext === ".vcf") {
+    const cards = vcards(raw);
+    return { ...item, kind: "person", mode: "reference", why: [`a Contacts export of ${cards.length} card(s)`], cards: cards.map((c) => ({ name: c.name, ref: `contacts:${c.uid ?? slugId(c.name)}`, ...(falsified("copy-contacts") ? { payload: c.payload } : {}) })) };
+  }
+  if (ext === ".webloc" || ext === ".url") {
+    const url = weblocUrl(raw);
+    return url ? { ...item, kind: "source", mode: "reference", refs: [`url:${url}`], why: ["a bookmark"] } : { ...item, kind: "blob", why: ["a bookmark file with no URL in it"] };
+  }
+  if (ext === ".ics") return { ...item, kind: "event", why: ["a calendar export"] };
+  if (ext === ".csv" || ext === ".tsv") {
+    const [head, first] = raw.split(/\r?\n/);
+    if (/\bdate\b/i.test(head ?? "") || LEADING_DAY.test(first ?? "")) return { ...item, kind: "log", why: ["rows of fields with a date column"] };
+    return { ...item, kind: "source", why: ["a table"] };
+  }
+  const text = ext === ".html" || ext === ".htm" ? stripHtml(raw) : raw;
+  const { fm, body } = frontmatter(text);
+  const heading = headingOf(body);
+  const lines = body.split("\n").map((l) => l.trim()).filter(Boolean);
+  const facts = { heading, dated: LEADING_DAY.exec(name)?.[1] ?? (DAY.test(fm.date ?? "") ? fm.date : null), daily: DAY.test(name) };
+  if (THERAPY.test(body)) facts.sensitive = { kind: "therapy", word: THERAPY.exec(body)[1] };
+  const att = ATTENDEES.exec(body);
+  if (att) facts.attendees = att[1].split(/,|\band\b/).map((s) => s.trim()).filter((s) => /^[A-Z][\p{L}'-]+(?: [A-Z][\p{L}'-]+)+$/u.test(s));
+  const declared = (fm.kind ?? fm.type ?? "").toLowerCase();
+  const typed = (kind, why, extra = {}) => ({ ...item, ...facts, kind, why: [why], ...extra });
+  if (GATHER_KINDS.includes(declared)) return typed(declared, `frontmatter says ${fm.kind ? "kind" : "type"}: ${declared}`);
+  if (projectRoot) {
+    const fin = FINISHED.exec(body);
+    return typed("project", `in the project folder ${projectRoot}`, fin ? { finishedWord: fin[1].replace(/[;.]$/, "") } : {});
+  }
+  if (lines.length && lines.every((l) => URL_LINE.test(l))) return typed("source", "a list of links and nothing else", { mode: "reference", refs: lines.map((l) => `url:${l}`) });
+  if (inFolder(/^(people|contacts)$/i)) return typed("person", `in the folder ${folders.find((f) => /^(people|contacts)$/i.test(f))}`);
+  if (att || MEETING.test(name)) return typed("event", att ? `names its ${att[0].split(":")[0].toLowerCase()}` : `named "${MEETING.exec(name)[1]}"`);
+  if (/^(draft|published|final)$/i.test(fm.status ?? "")) return typed("piece", `frontmatter says status: ${fm.status}`);
+  if (inFolder(/^(drafts|writing|essays)$/i)) return typed("piece", `in the folder ${folders.find((f) => /^(drafts|writing|essays)$/i.test(f))}`);
+  const src = /^source:\s*(https?:\/\/\S+)/im.exec(body);
+  if (src) return typed("source", "names its source", { refs: [`url:${src[1]}`] });
+  if (inFolder(/^(clippings|reading|articles)$/i)) return typed("source", `in the folder ${folders.find((f) => /^(clippings|reading|articles)$/i.test(f))}`);
+  if (facts.daily) return typed("note", "named for its day");
+  if (inFolder(/^(inbox|captures)$/i)) return typed("capture", `in the folder ${folders.find((f) => /^(inbox|captures)$/i.test(f))}`);
+  if (!heading && lines.length <= 2 && body.trim().length < 280) return typed("capture", "a line or two with no title");
+  return typed("note", facts.dated ? "dated words" : "words with no other shape", { confidence: facts.dated || heading ? "high" : "low" });
+}
+
+// Scan every source. Reads bytes; writes nothing anywhere.
+export function scan(sources, { now = new Date() } = {}) {
+  if (!Array.isArray(sources) || sources.length === 0) throw new EvdaError("REFUSED: gather needs at least one source: a folder or an export file.", { code: "NO_SOURCE", exit: 2 });
+  const out = { sources: [], items: [], skipped: [], chats: [] };
+  sources.forEach((src, si) => {
+    const root = resolve(src);
+    if (!existsSync(root)) throw new EvdaError(`REFUSED: the source ${root} does not exist. Nothing was written.`, { code: "NO_SOURCE", exit: 2 });
+    const w = falsified("examine-nothing") ? { files: [], skipped: [], apps: [] } : walk(root);
+    const readmeDirs = new Set(w.files.filter((f) => /^readme\.(md|txt)$/i.test(basename(f.rel)) && f.rel.includes("/")).map((f) => dirname(f.rel)).filter((d) => w.files.filter((f) => dirname(f.rel) === d).length >= 2));
+    out.sources.push({ id: `s${si}`, path: root, files: w.files.length, skipped: w.skipped.length, apps: w.apps });
+    for (const s of w.skipped) out.skipped.push({ source: `s${si}`, ...s });
+    for (const f of w.files) {
+      const buf = readFileSync(f.abs);
+      const ext = extname(f.rel).toLowerCase();
+      const chat = ext === ".json" ? readChatExport(buf) : null;
+      if (chat) {
+        const convs = conversations(chat);
+        out.chats.push({ source: `s${si}`, path: f.rel, sha256: sha256(buf), format: chat.format, conversations: convs.length, messages: convs.reduce((n, c) => n + c.messages.length, 0) });
+        continue;
+      }
+      const projectRoot = projectRootFor(f.rel, readmeDirs);
+      // Sealed (HQ-1220) and just noted (HQ-1414): such a file is typed from its path and frontmatter
+      // alone, so no heading, name or word of it reaches the proposal or the owner's AI; a sealed
+      // section is cut before any file is read for its heading, people or words. Its bytes and hash
+      // are unchanged, so apply copies it with its flag.
+      const seal = sealedOf(ext, buf);
+      const facts = typeItem({ rel: f.rel, buf: seal.buf, ext, projectRoot });
+      if (seal.sealed) facts.sealed = true;
+      if (seal.noted) facts.noted = true;
+      const item = { id: `s${si}:${f.rel}`, source: `s${si}`, path: f.rel, size: f.size, sha256: sha256(buf), ...facts };
+      if (projectRoot) item.project = projectRoot;
+      item.subject = subjectOf(f.rel, projectRoot);
+      if (!item.refused && !item.sealed && !item.noted && item.kind !== "blob" && item.mode !== "reference") item.text = seal.buf.toString("utf8");
+      out.items.push(item);
+    }
+  });
+  if (falsified("touch-source")) {
+    const t = out.items.find((i) => i.text !== undefined);
+    if (t) appendFileSync(join(out.sources.find((s) => s.id === t.source).path, t.path), " ");
+  }
+  return out;
+}
+
+// What a pile file may be read as: a sealed or just-noted markdown or text file is its frontmatter
+// only, and any other text file is itself with every sealed section cut. { sealed, noted, buf }.
+function sealedOf(ext, buf) {
+  if (![".md", ".markdown", ".txt"].includes(ext)) return { sealed: false, noted: false, buf };
+  const raw = buf.toString("utf8");
+  const held = heldBy(frontmatterOf(raw), "gather");
+  if (held) {
+    const lines = raw.split("\n");
+    const end = lines.indexOf("---", 1);
+    return { sealed: held !== NOTED, noted: held === NOTED, buf: Buffer.from(`${lines.slice(0, end + 1).join("\n")}\n`, "utf8") };
+  }
+  if (!carries("gather", "sealed")) return { sealed: false, noted: false, buf };
+  const cut = withoutSealed(raw);
+  return { sealed: false, noted: false, buf: cut.sections ? Buffer.from(cut.text, "utf8") : buf };
+}
+
+// People: names from Contacts cards, attendee lines and existing People pages, and which files
+// mention each. Only a name a source itself names is a person; nothing is guessed from capitals.
+function findPeople(items) {
+  const byName = new Map();
+  const add = (name, fact) => {
+    const p = byName.get(name) ?? { name, cards: [], pages: [], files: new Set() };
+    Object.entries(fact).forEach(([k, v]) => p[k].push(v));
+    byName.set(name, p);
+  };
+  for (const i of items) {
+    for (const c of i.cards ?? []) add(c.name, { cards: c.ref });
+    for (const a of i.attendees ?? []) add(a, {});
+    if (i.kind === "person" && i.mode !== "reference") add(i.heading ?? basename(i.path, extname(i.path)), { pages: i.id });
+  }
+  const firsts = new Map();
+  for (const n of byName.keys()) firsts.set(n.split(" ")[0], (firsts.get(n.split(" ")[0]) ?? 0) + 1);
+  const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  for (const p of byName.values()) {
+    const first = p.name.split(" ")[0];
+    const re = new RegExp(`(^|[^\\p{L}])(${escape(p.name)}${firsts.get(first) === 1 && first.length >= 3 ? `|${escape(first)}` : ""})($|[^\\p{L}])`, "u");
+    for (const i of items) {
+      if (i.text === undefined || p.pages.includes(i.id)) continue;
+      if (re.test(i.text) || re.test(i.path)) p.files.add(i.id);
+    }
+  }
+  return [...byName.values()].map((p) => ({ name: p.name, ref: p.cards[0] ?? null, page: p.pages[0] ?? null, files: [...p.files].sort() })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function findProjects(items) {
+  const roots = new Map();
+  for (const i of items) {
+    if (!i.project) continue;
+    const r = roots.get(`${i.source}:${i.project}`) ?? { id: `${i.source}:${i.project}`, source: i.source, root: i.project, name: basename(i.project), files: [], finished: null };
+    r.files.push(i.id);
+    if (i.finishedWord && !r.finished) r.finished = { file: i.id, word: i.finishedWord };
+    roots.set(r.id, r);
+  }
+  return [...roots.values()];
+}
+
+// Which preset the pile fits, and why, from counts alone.
+export function choosePreset(items, projects) {
+  const courses = new Set(items.flatMap((i) => i.path.split("/").slice(0, -1).filter((f) => COURSE.test(f) || COURSE_WORD.test(f))));
+  const subjects = new Set(items.map((i) => i.subject).filter(Boolean));
+  // A course is a collection (Spec 07 section 2), so courses make Projects and areas, whose
+  // Academics folder holds one folder per course.
+  if (courses.size >= 2) return { id: "projects-and-areas", why: [`${courses.size} folders look like courses (${[...courses].slice(0, 3).join(", ")}), and a course is a collection`] };
+  if (projects.length >= 1 || subjects.size >= 3) return { id: "projects-and-areas", why: [`${projects.length} project folder(s) and ${subjects.size} subjects (${[...subjects].slice(0, 4).join(", ")})`] };
+  return { id: "journal", why: [`mostly dated notes and people, ${subjects.size} subject(s) and no project folder`] };
+}
+
+// ---- place ----
+
+// Where a kind lives under a preset: the preset's own folder when it has one, else a folder the
+// pile needs and the preset does not have, named here and marked as such.
+const NEEDED = { note: "Notes", capture: "Captures", person: "People", project: "Projects", event: "Events", log: "Logs", source: "Sources", piece: "Writing", blob: "Attachments", areas: "Notes" };
+
+// The role a path under the preset fills: the longest mapping path at or above it.
+export function presetRole(preset, rel) {
+  if (falsified("no-role")) return null;
+  let best = null;
+  for (const [key, path] of Object.entries(preset.mapping ?? {})) {
+    if ((rel === path || rel.startsWith(`${path}/`)) && (!best || path.length > best.path.length)) best = { key, path, role: fourRoleOf(key) };
+  }
+  return best?.role ?? null;
+}
+
+// Where each kind lives under a preset, by type and by the role the kind fills: of the preset's
+// folders of that type, one in the kind's role first.
+function homes(preset) {
+  const typed = (t, role = null) => {
+    const all = preset.folders.filter((f) => f.type === t);
+    return (all.find((f) => role && presetRole(preset, f.path) === role) ?? all[0])?.path ?? null;
+  };
+  const named = (re) => preset.folders.find((f) => re.test(basename(f.path)))?.path ?? null;
+  return {
+    type: typed,
+    areas: named(/^\d*_?Areas$/) ?? preset.folders.find((f) => f.type === "concept" && /^Notes$/.test(basename(f.path)))?.path ?? null,
+    attachments: named(/^\d*_?Attachments$/),
+    captures: typed("capture", "journal"),
+    courses: typed("course", "collections"),
+  };
+}
+
+// A placed text item's name: `.txt` becomes `.md`, bytes unchanged. Every other name is kept.
+const asMarkdown = (i, name) => (i.kind !== "blob" && /\.txt$/i.test(name) ? name.replace(/\.txt$/i, ".md") : name);
+
+// The placement of every item, given the facts and the answers. Pure.
+export function place(p) {
+  const preset = loadPreset(p.preset.id);
+  const h = homes(preset);
+  const ans = Object.fromEntries((p.answers ?? []).map((a) => [a.question, a.value]));
+  const needed = new Map();
+  const folderFor = (key, type) => {
+    const own = key === "areas" ? h.areas : key === "blob" ? (h.attachments ?? h.type("blob", "collections")) : h.type(FOLDER_TYPE_FOR[key] ?? key, ROLE_FOR_KIND[key]);
+    if (own) return own;
+    // A folder the preset lacks is named for the kind and fills the kind's role, declared as a
+    // facet of that role in the proposal's mapping, so no gathered folder fills no role.
+    needed.set(NEEDED[key], { path: NEEDED[key], type: type ?? null, role: ROLE_FOR_KIND[key] ?? "collections" });
+    return NEEDED[key];
+  };
+  const therapyOwn = ans["circle:therapy"] === "yes";
+  const placements = [];
+  const taken = new Map();
+  // The role a destination fills: the preset's mapping, else the needed folder's own role.
+  const roleOf = (to) => presetRole(preset, to) ?? (falsified("no-role") ? null : undefined) ?? [...needed.values()].find((n) => to === n.path || to.startsWith(`${n.path}/`))?.role ?? null;
+  const claim = (to, id) => {
+    let t = to;
+    for (let n = 2; taken.has(t) && taken.get(t) !== id; n++) t = to.replace(/(\.[^./]+)?$/, (e) => ` (${n})${e ?? ""}`);
+    taken.set(t, id);
+    return t;
+  };
+  for (const i of p.items) {
+    const file = asMarkdown(i, basename(i.path));
+    let pl;
+    if (i.refused) pl = { status: "refused", to: null, why: `${i.refused}; left where it is and quoted nowhere. Keep the secret in a password manager.` };
+    else if (i.present) pl = { status: "present", to: null, at: i.present, why: `already in the record at ${i.present}; left where it is` };
+    else if (i.archive) pl = { status: "unplaced", to: null, why: "an archive file; unpack it and gather the folder" };
+    else if (i.cards) pl = { status: "reference", to: null, why: "held by Contacts; a person page keeps a contacts: reference, never the card" };
+    else if (i.kind === "project") {
+      // Status is a field, never a move: a finished project stays in its collection and says so.
+      const proj = p.projects.find((x) => x.id === `${i.source}:${i.project}`);
+      const finished = ans[`finished:${proj.id}`] === "finished";
+      pl = { status: "placed", to: `${folderFor("project", "project")}/${proj.name}/${asMarkdown(i, posix(relative(i.project, i.path)))}`, ...(finished ? { fields: { status: "finished" } } : {}) };
+    } else if (i.sensitive?.kind === "therapy" && therapyOwn) {
+      pl = { status: "placed", to: `${h.areas ? `${h.areas}/Therapy` : "Therapy"}/${file}`, circle: "therapy" };
+      if (!h.areas) needed.set("Therapy", { path: "Therapy", type: "record" });
+    } else if (i.kind === "note" && i.daily) pl = { status: "placed", to: `${folderFor("note", "record")}/${file}` };
+    else if (i.kind === "note") {
+      const course = h.courses && i.subject && COURSE.test(i.subject);
+      if (course) pl = { status: "placed", to: `${h.courses}/${i.subject}/${file}` };
+      else if (i.subject) pl = { status: "placed", to: `${folderFor("areas", "record")}/${i.subject}/${file}` };
+      else pl = { status: "unplaced", to: null, why: `no subject: it sits in no folder that says what it is about${h.captures ? `; ${h.captures}/ holds it until someone says` : ""}` };
+    } else if (i.mode === "reference") pl = { status: "reference", to: `${folderFor(i.kind, FOLDER_TYPE_FOR[i.kind])}/${basename(i.path, extname(i.path))}.md`, refs: i.refs, why: "a new entry holding the reference; the file stays where it is" };
+    else pl = { status: "placed", to: `${folderFor(i.kind, FOLDER_TYPE_FOR[i.kind])}/${file}` };
+    if (pl.to) pl.to = claim(pl.to, i.id);
+    if (pl.to) pl.role = roleOf(pl.to);
+    if (i.refs && pl.status === "placed") pl.refs = i.refs;
+    if (i.kind === "person" && !i.cards) {
+      const who = p.people.find((x) => x.page === i.id);
+      if (who?.ref) pl.refs = [who.ref];
+    }
+    placements.push({ item: i.id, ...pl });
+  }
+  // Person pages the owner said yes to, made new, holding a Contacts reference when a card names them.
+  for (const who of p.people) {
+    if (ans[`person:${slugId(who.name)}`] !== "yes" || who.page) continue;
+    const to = claim(`${folderFor("person", "person")}/${who.name}.md`, `new:person:${who.name}`);
+    placements.push({ item: `new:person:${who.name}`, status: "create", to, role: roleOf(to), refs: who.ref ? [who.ref] : [], mentions: who.files.length });
+  }
+  const circles = therapyOwn ? [{ name: "therapy", covers: h.areas ? `${h.areas}/Therapy` : "Therapy", status: "proposed only: a proposal file at apply, never a circle" }] : [];
+  const used = new Map();
+  for (const pl of placements) {
+    if (!pl.to) continue;
+    const top = preset.folders.map((f) => f.path).filter((fp) => pl.to.startsWith(`${fp}/`)).sort((a, b) => b.length - a.length)[0] ?? pl.to.split("/")[0];
+    used.set(top, (used.get(top) ?? 0) + 1);
+  }
+  const folders = [...used.entries()].map(([path, n]) => {
+    const f = preset.folders.find((x) => x.path === path);
+    return f ? { path, type: f.type ?? null, role: presetRole(preset, path), from: "preset", items: n } : { path, type: needed.get(path)?.type ?? null, role: needed.get(path)?.role ?? null, from: "needed: the preset has no folder for these", items: n };
+  }).sort((a, b) => a.path.localeCompare(b.path));
+  // The roles applying this proposal would declare: the preset's, and a facet for every needed
+  // folder, so each placed item lands in a folder that fills one of the four roles.
+  const mapping = { ...(preset.mapping ?? {}) };
+  for (const f of folders.filter((x) => x.from !== "preset" && x.role)) mapping[`${f.role}/${f.path.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`] = f.path;
+  return { placements, folders, circles, mapping };
+}
+
+// ---- questions ----
+
+// Every question the facts could raise, before the filter.
+function candidates(p) {
+  const out = [];
+  for (const who of p.people) {
+    if (who.page) continue;
+    if (who.files.length < PEOPLE_MIN_FILES && !falsified("ask-everything")) continue;
+    out.push({ id: `person:${slugId(who.name)}`, kind: "person", options: ["yes", "no"], text: `${who.files.length} file(s) mention ${who.name}. Keep a page for ${who.name}?`, about: who.name });
+  }
+  for (const proj of p.projects) {
+    if (!proj.finished && !falsified("ask-everything")) continue;
+    out.push({ id: `finished:${proj.id}`, kind: "finished", options: ["finished", "live"], text: `${proj.name} looks finished (${basename(proj.files.find((f) => f === proj.finished?.file) ?? proj.root)} says "${proj.finished?.word ?? "nothing"}"). Is it finished, or live? It stays where it is; finished is its status.`, about: proj.name });
+  }
+  const therapy = p.items.filter((i) => i.sensitive?.kind === "therapy");
+  if (therapy.length) out.push({ id: "circle:therapy", kind: "circle", options: ["yes", "no"], text: `${therapy.length} file(s) read like therapy notes. Give them their own circle, so only who you choose reads them?`, about: "therapy" });
+  return out;
+}
+
+const placementMap = (p) => Object.fromEntries(place(p).placements.map((x) => [x.item, placedAs(x)]));
+// A placement in one string: where it goes, and the fields it is given there.
+const placedAs = (x) => `${x.status}:${x.to}${x.fields ? ` ${JSON.stringify(x.fields)}` : ""}`;
+
+// The questions worth asking: those whose answers place at least one item differently. Each
+// carries the items it moves.
+export function questions(p) {
+  const base = p.answers ?? [];
+  const out = [];
+  for (const q of candidates(p)) {
+    const outcomes = q.options.map((o) => placementMap({ ...p, answers: [...base.filter((a) => a.question !== q.id), { question: q.id, value: o }] }));
+    const ids = new Set(outcomes.flatMap((m) => Object.keys(m)));
+    const affects = [...ids].filter((id) => new Set(outcomes.map((m) => m[id])).size > 1).sort();
+    if (!affects.length && !falsified("ask-everything")) continue;
+    const answered = base.find((a) => a.question === q.id);
+    out.push({ ...q, affects, ...(answered ? { answer: answered.value } : {}) });
+  }
+  return out;
+}
+
+// ---- the proposal ----
+
+function counts(p) {
+  const c = { items: p.items.length, placed: 0, reference: 0, create: 0, unplaced: 0, refused: 0, present: 0, skipped: p.skipped.length };
+  for (const pl of p.placements) c[pl.status] += 1;
+  c.chats = (p.chats ?? []).length;
+  c.chatMessages = (p.chats ?? []).reduce((n, x) => n + x.messages, 0);
+  c.questions = p.questions.length;
+  c.open = p.questions.filter((q) => q.answer === undefined).length;
+  return c;
+}
+
+function refresh(p) {
+  const r = place(p);
+  p.placements = r.placements;
+  p.folders = r.folders;
+  p.circles = r.circles;
+  p.mapping = r.mapping;
+  p.questions = questions(p);
+  p.counts = counts(p);
+  return p;
+}
+
+export function gather(sources, { now = new Date(), into = null } = {}) {
+  const s = scan(sources, { now });
+  // The record this pile would grow, when named: what it already holds is present, and a person
+  // with a page there has one.
+  let record = null;
+  if (into !== null) {
+    const abs = resolve(into);
+    if (!existsSync(join(abs, "evda.json"))) throw new EvdaError(`REFUSED: --into ${abs} is not an EVDA (no evda.json). Name the record this pile would grow, or leave --into off for a new one. Nothing was written.`, { code: "NOT_A_RECORD", exit: 2 });
+    record = openEvda(abs);
+    const index = presentIndex(record.dir);
+    for (const i of s.items) { const at = presentAt(index, i.sha256); if (at) i.present = at; }
+    // What each chat export would add to this record: the owner's messages it does not hold yet.
+    for (const c of s.chats) c.add = chatPlan(record, s.sources.find((x) => x.id === c.source), c).counts.add;
+  }
+  const projects = findProjects(s.items);
+  const people = findPeople(s.items);
+  if (record && !falsified("reapply-resorts")) {
+    const pages = personPages(record);
+    for (const who of people) if (!who.page && pages.has(who.name)) who.page = `record:${pages.get(who.name)}`;
+  }
+  const preset = choosePreset(s.items, projects);
+  const p = {
+    evdaGather: GATHER_VERSION,
+    id: `${now.toISOString().slice(0, 10)}-${sha256(Buffer.from(s.sources.map((x) => x.path).join("\n"))).slice(0, 8)}`,
+    created: now.toISOString(),
+    note: "A proposal only. Nothing in any source was changed, and nothing was written into a record.",
+    sources: s.sources,
+    ...(record ? { into: record.dir } : {}),
+    preset: { ...preset, title: loadPreset(preset.id).title },
+    projects,
+    people,
+    items: s.items.map(({ text, finishedWord, ...rest }) => rest),
+    skipped: s.skipped,
+    chats: s.chats,
+    answers: [],
+    ai: null,
+  };
+  // The people and project facts were read from the text; the text itself is not kept.
+  return refresh(p);
+}
+
+// Record one answer and re-place. Returns { proposal, moved: [{ item, from, to }] }.
+export function answer(p, questionId, value, { now = new Date() } = {}) {
+  const q = questions(p).find((x) => x.id === questionId);
+  if (!q) throw refuse(`no open question "${questionId}" on this proposal. Its questions: ${questions(p).map((x) => x.id).join(", ") || "none"}.`, "NO_QUESTION");
+  if (!q.options.includes(value)) throw refuse(`"${questionId}" takes ${q.options.map((o) => JSON.stringify(o)).join(" or ")}, not ${JSON.stringify(value)}.`, "BAD_ANSWER");
+  const said = (x) => (x.to ? `${x.to}${x.fields?.status ? ` (status ${x.fields.status})` : ""}` : null);
+  const before = Object.fromEntries(p.placements.map((x) => [x.item, said(x)]));
+  p.answers = [...p.answers.filter((a) => a.question !== questionId), { question: questionId, value, at: now.toISOString() }];
+  if (falsified("answer-no-replace")) { p.questions = questions(p); return { proposal: p, moved: [] }; }
+  refresh(p);
+  const after = Object.fromEntries(p.placements.map((x) => [x.item, said(x)]));
+  const moved = [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((id) => before[id] !== after[id]).sort().map((id) => ({ item: id, from: before[id] ?? null, to: after[id] ?? null }));
+  p.answers[p.answers.length - 1].moved = moved.length;
+  return { proposal: p, moved };
+}
+
+// ---- the owner's AI ----
+
+// Items it could not place, or typed only by elimination, handed to the owner's claude -p.
+export function withOwnersAi(p, { model = null, env = process.env } = {}) {
+  const unsure = p.items.filter((i) => !i.refused && !i.sealed && !i.noted && !i.present && (i.confidence === "low" || p.placements.find((x) => x.item === i.id)?.status === "unplaced") && !i.archive);
+  if (!unsure.length) { p.ai = { status: "SKIPPED", why: "nothing was unsure" }; return { ok: true, p }; }
+  const kinds = GATHER_KINDS.join(", ");
+  const lines = unsure.map((i) => `- ${i.id} (typed ${i.kind}${i.heading ? `, titled "${i.heading}"` : ""})`);
+  const prompt = [
+    "These files are from a pile the owner is turning into an EVDA. The gatherer could not place them.",
+    `For each, answer on one line: <id> | <kind> | <subject>, where kind is one of ${kinds} and subject is the area it is about in one or two words, or - for none.`,
+    "Only the lines in that shape are read. Write nothing else to disk.",
+    "",
+    ...lines,
+  ].join("\n");
+  const ai = askOwnersAi(null, prompt, { model, env });
+  if (!ai.ok) { p.ai = { status: "SKIPPED", why: ai.why }; return { ok: false, p }; }
+  if (ai.text.split("\n").some(secretShape)) { p.ai = { status: "NOT_KEPT", why: "the answer held a secret-shaped line" }; return { ok: false, p }; }
+  let applied = 0;
+  let ignored = 0;
+  for (const line of ai.text.split("\n")) {
+    const m = /^\s*-?\s*(\S.*?)\s*\|\s*([a-z]+)\s*\|\s*(.+?)\s*$/.exec(line);
+    const item = m && unsure.find((i) => i.id === m[1]);
+    if (!item || !GATHER_KINDS.includes(m[2]) || /[/\\]|\.\./.test(m[3])) { if (line.trim()) ignored += 1; continue; }
+    item.kind = m[2];
+    item.subject = m[3] === "-" ? null : m[3];
+    item.confidence = "owner's AI";
+    item.why = [...item.why, `the owner's AI typed it ${m[2]}${m[3] === "-" ? "" : `, about ${m[3]}`}`];
+    applied += 1;
+  }
+  p.ai = { status: "ASKED", asked: unsure.length, applied, ignored };
+  refresh(p);
+  return { ok: true, p };
+}
+
+// ---- files ----
+
+export function gatherDir(env = process.env) {
+  return resolve(env.EVDA_GATHER_DIR || join(homedir(), ".evda", "gather"));
+}
+
+// Refuse an output path inside a source or inside a record: the gather writes into neither.
+export function checkOut(out, p) {
+  const abs = resolve(out);
+  for (const s of p.sources) {
+    if (abs === s.path || abs.startsWith(s.path + sep)) throw new EvdaError(`REFUSED: the proposal would be written inside the source ${s.path}. A gather writes nothing into a source; pass --out somewhere else, or set EVDA_GATHER_DIR. Nothing was written.`, { code: "OUT_IN_SOURCE", exit: 2 });
+  }
+  const rec = findRoot(dirname(abs));
+  if (rec) throw new EvdaError(`REFUSED: the proposal would be written inside the EVDA at ${rec}. A gather writes nothing into a record until the owner says yes to applying it. Nothing was written.`, { code: "OUT_IN_RECORD", exit: 2 });
+  return abs;
+}
+
+export function saveProposal(p, out) {
+  const abs = checkOut(out, p);
+  mkdirSync(dirname(abs), { recursive: true });
+  const tmp = `${abs}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(p, null, 2) + "\n");
+  renameSync(tmp, abs);
+  return abs;
+}
+
+export function proposalPath(ref, env = process.env) {
+  if (typeof ref !== "string" || ref.trim() === "") throw refuse("a proposal is named by its id or its path.", "NO_PROPOSAL");
+  if (/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9a-f]{8}$/.test(ref)) return join(gatherDir(env), `${ref}.json`);
+  return resolve(ref);
+}
+
+export function loadProposal(ref, env = process.env) {
+  const abs = proposalPath(ref, env);
+  if (!existsSync(abs)) throw refuse(`no gather proposal at ${abs}.`, "NO_PROPOSAL");
+  let p;
+  try { p = JSON.parse(readFileSync(abs, "utf8")); } catch (e) { throw refuse(`${abs} is not valid JSON (${e.message}).`, "BAD_PROPOSAL"); }
+  if (p?.evdaGather !== GATHER_VERSION || !Array.isArray(p.items)) throw refuse(`${abs} is not a gather proposal.`, "BAD_PROPOSAL");
+  return { p, abs };
+}
+
+// ---- words ----
+
+export function checkedLines(p) {
+  const c = p.counts;
+  const chats = p.chats ?? [];
+  return [
+    ...(chats.length ? [`CHECKED ${c.chatMessages} message(s) of the owner's in ${chats.reduce((n, x) => n + x.conversations, 0)} conversation(s) from ${chats.length} chat export(s)${p.into ? `  ${chats.reduce((n, x) => n + (x.add ?? 0), 0)} not yet in the record` : ""}`] : []),
+    `CHECKED ${c.items} items in ${p.sources.length} source(s)  ${c.placed} placed, ${c.reference} by reference, ${c.create} to create, ${c.unplaced} left for a person, ${c.refused} refused, ${c.skipped} skipped${p.into ? `, ${c.present} already in the record` : ""}`,
+    c.questions ? `CHECKED ${c.questions} question(s)  each changes where at least one item goes; ${c.open} open` : "SKIPPED questions: nothing in this pile needs the owner to decide a placement",
+  ];
+}
+
+export function summaryText(p, { detail = false } = {}) {
+  const lines = [`A proposal for ${p.into ? `growing the EVDA at ${p.into} from` : "turning"} ${p.sources.map((s) => s.path).join(", ")}${p.into ? "" : " into an EVDA"}. Nothing was moved, copied or changed.`, ""];
+  lines.push(`Preset: ${p.preset.title} (${p.preset.id}), because ${p.preset.why.join("; ")}.`, "", "Folders:");
+  for (const f of p.folders) lines.push(`- ${f.path}/${f.type ? ` (${f.type})` : ""}${f.role ? `, ${f.role}` : ""}: ${f.items} item(s)${f.from === "preset" ? "" : ", a folder the preset does not have"}`);
+  const byStatus = (s) => p.placements.filter((x) => x.status === s);
+  if (byStatus("reference").length) { lines.push("", "Kept as references, never copied:"); for (const x of byStatus("reference")) lines.push(`- ${x.item}${x.to ? ` -> ${x.to}` : ""}: ${x.why}`); }
+  if (byStatus("create").length) { lines.push("", "New pages:"); for (const x of byStatus("create")) lines.push(`- ${x.to}${x.refs.length ? ` (${x.refs.join(", ")})` : ""}`); }
+  if (byStatus("unplaced").length) { lines.push("", "Left for a person:"); for (const x of byStatus("unplaced")) lines.push(`- ${x.item}: ${x.why}`); }
+  if (byStatus("refused").length) { lines.push("", "Refused:"); for (const x of byStatus("refused")) lines.push(`- ${x.item}: ${x.why}`); }
+  if (byStatus("present").length) lines.push("", `Already in the record, left where they are: ${byStatus("present").length} item(s).`);
+  for (const c of p.chats ?? []) lines.push("", `A ${CHAT_FORMATS[c.format]} export (${c.path}): ${c.messages} message(s) of the owner's in ${c.conversations} conversation(s)${c.add !== undefined ? `, ${c.add} of them not in the record yet, to be added under each conversation's date and time` : ", each added to its day unless the record already holds it"}. Only their messages; the model's replies are never written.`);
+  if (p.circles.length) { lines.push("", "Circles:"); for (const c of p.circles) lines.push(`- ${c.name} over ${c.covers}/, ${c.status}`); }
+  if (detail) { lines.push("", "Every placement:"); for (const x of byStatus("placed")) lines.push(`- ${x.item} -> ${x.to}`); }
+  const open = p.questions.filter((q) => q.answer === undefined);
+  lines.push("", open.length ? `${open.length} question(s) for the owner:` : "No open questions.");
+  for (const q of open) lines.push(`- [${q.id}] ${q.text} (${q.options.join(" / ")})`);
+  return lines.join("\n");
+}
+
+// ---- chat exports ----
+
+// The day folder of a record, or null when it maps no day role.
+export function dayDirOf(evda) {
+  try { return dayFile(evda, "0000-00-00").dir; } catch { return null; }
+}
+
+// What one chat export adds to a record now: lib/chat-export.mjs backfillPlan over the record's day
+// files. `source` is the proposal's source entry, `c` its chat entry. Throws when the export changed
+// since the gather.
+export function chatPlan(evda, source, c) {
+  const abs = existsSync(source.path) && lstatSync(source.path).isFile() ? source.path : join(source.path, c.path);
+  const buf = readFileSync(abs);
+  if (sha256(buf) !== c.sha256) throw refuse(`the chat export ${abs} changed since the gather; gather it again.`, "CHANGED");
+  const chat = readChatExport(buf);
+  const plan = backfillPlan(conversations(chat), filedSections(dayDirOf(evda)), { format: chat.format });
+  return { ...plan, abs };
+}
+
+// ---- MCP tools ----
+
+export function gatherTool(evda, args = {}, { now = new Date(), env = process.env } = {}) {
+  onlyKeys("evda_gather", args, ["sources", "into"], "It only proposes. It moves, copies and writes nothing in the sources or the record.");
+  if (!Array.isArray(args.sources) || !args.sources.length || !args.sources.every((s) => typeof s === "string" && s.trim() !== "")) throw refuse('evda_gather needs "sources": the folders or export files to gather, as paths on this machine.', "NO_SOURCE");
+  if (args.into !== undefined && (typeof args.into !== "string" || args.into.trim() === "")) throw refuse('evda_gather "into" is the path of the record this pile would grow.', "BAD_INTO");
+  const p = gather(args.sources, { now, into: args.into ?? null });
+  if (p.counts.items === 0 && !p.counts.chats) throw refuse(`evda_gather found nothing to gather in ${args.sources.join(", ")}: CHECKED 0 items.`, "EMPTY_SOURCE");
+  const path = saveProposal(p, join(gatherDir(env), `${p.id}.json`));
+  return { p, path };
+}
+
+export function gatherQuestionsTool(evda, args = {}, { env = process.env } = {}) {
+  onlyKeys("evda_gather_questions", args, ["proposal"]);
+  const { p } = loadProposal(args.proposal, env);
+  return { p, open: p.questions.filter((q) => q.answer === undefined) };
+}
+
+export function gatherAnswerTool(evda, args = {}, { now = new Date(), env = process.env } = {}) {
+  onlyKeys("evda_gather_answer", args, ["proposal", "question", "answer"], "It records the owner's answer on the proposal and re-places what it changes; it moves no file.");
+  const { p, abs } = loadProposal(args.proposal, env);
+  const r = answer(p, args.question, args.answer, { now });
+  saveProposal(r.proposal, abs);
+  return { ...r, path: abs };
+}
+
+export function answerLines(r) {
+  return r.moved.length ? r.moved.map((m) => `  ${m.item}: ${m.from ?? "(nothing)"} -> ${m.to ?? "(nothing)"}`) : ["  nothing moved"];
+}
+
+// A preset the gather knows. Exported for tests that check every shipped preset has a home for
+// every kind, or names the folder it needs.
+export const presetsKnown = () => listPresets().map((x) => x.id);