create-evda 0.1.9 → 0.1.11

package/lib/presets.mjs

@@ -28,7 +28,10 @@
 // that are missing, and reports the rest: a manifest that already says the same thing is skipped,
 // one that says something else is a conflict and is left exactly as it is, and a preset path that
 // already exists as a file is a conflict. Nothing is moved, renamed or deleted, so applying twice
-// writes nothing the second time. A shipped preset that does not validate fails
+// writes nothing the second time. A folder typed person also brings its layout (HQ-2024): a sibling
+// Processing/ for processing docs, and a README inside the folder stating the one-file-per-person
+// rule doctor checks, each only when missing and only when the folder's manifest is the preset's.
+// A shipped preset that does not validate fails
 // test/presets.test.mjs, so the person running it never meets one.
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
@@ -40,6 +43,8 @@ import { validateFolderManifest, FOLDER_MANIFEST, FOLDER_TYPES } from "./folders
 import { ROUTINE_KEYS } from "./routines.mjs";
 import { onlyKeys, proposeCircle, refuse, PROPOSALS } from "./tools.mjs";
 import { EvdaError } from "./errors.mjs";
+import { PERSON_FOLDER_README, PROCESSING_DIR, README_NAME } from "./person-folders.mjs";
+import { outsideRecord } from "./record-walk.mjs";
 
 export const PRESETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "presets");
 export const PRESET_FILE = "preset.json";
@@ -62,7 +67,7 @@ function pathProblem(p) {
   if (p.startsWith("/")) return "is absolute; paths are relative to the record root";
   for (const seg of p.split("/")) {
     if (seg === "" || seg === "." || seg === "..") return `has an empty, . or .. segment`;
-    if (seg.startsWith(".") || seg === "node_modules") return `has the segment "${seg}", which doctor does not read`;
+    if (seg.startsWith(".") || outsideRecord(seg)) return `has the segment "${seg}", which doctor does not read`;
   }
   return null;
 }
@@ -223,6 +228,7 @@ const viewHeader = (v) => ["---", `view: ${v.view}`, `of: ${v.of}`, `in: ${v.in}
 //   create     directories that do not exist yet
 //   write      manifests that do not exist yet ({ path, folder, manifest })
 //   views      view files a manifest declares that do not exist yet
+//   files      files a person folder brings that do not exist yet ({ path, text }): its README
 //   matched    manifests that exist and already say what the preset says (skipped)
 //   conflicts  manifests that exist and say something else, and preset paths that are files
 //              ({ path, why }); reported, never overwritten
@@ -231,7 +237,7 @@ const viewHeader = (v) => ["---", `view: ${v.view}`, `of: ${v.of}`, `in: ${v.in}
 export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRESETS_DIR } = {}) {
   const evda = openEvda(resolve(root));
   const preset = loadPreset(id, { dir });
-  const plan = { id: preset.id, title: preset.title, root: evda.dir, dry, create: [], write: [], views: [], matched: [], conflicts: [], circles: [], proposed: [], routines: preset.routines ?? [], folders: preset.folders.length, roles: [] };
+  const plan = { id: preset.id, title: preset.title, root: evda.dir, dry, create: [], write: [], files: [], views: [], matched: [], conflicts: [], circles: [], proposed: [], routines: preset.routines ?? [], folders: preset.folders.length, roles: [] };
   // The four roles the record does not declare yet. A key it has with another path is a conflict,
   // left as it is; a path it already maps under a key of the same role is already there.
   const has = evda.manifest.mapping;
@@ -263,15 +269,29 @@ export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRE
     const want = manifestFor(f);
     const mpath = `${f.path}/${FOLDER_MANIFEST}`;
     const mabs = join(abs, FOLDER_MANIFEST);
+    let ours = true;
     if (!existsSync(mabs)) plan.write.push({ path: mpath, folder: f, manifest: want });
-    else if (!lstatSync(mabs).isFile()) plan.conflicts.push({ path: mpath, why: "exists and is not a file" });
+    else if (!lstatSync(mabs).isFile()) { plan.conflicts.push({ path: mpath, why: "exists and is not a file" }); ours = false; }
     else {
       let existing;
       try { existing = JSON.parse(readFileSync(mabs, "utf8")); } catch { plan.conflicts.push({ path: mpath, why: "exists and is not valid JSON" }); continue; }
       const diff = differences(existing, want);
-      if (diff.length) plan.conflicts.push({ path: mpath, why: `exists and differs: ${diff.join("; ")}` });
+      if (diff.length) { plan.conflicts.push({ path: mpath, why: `exists and differs: ${diff.join("; ")}` }); ours = false; }
       else plan.matched.push({ path: mpath });
     }
+    if (f.type === "person" && ours) {
+      const readme = `${f.path}/${README_NAME}`;
+      const rabs = join(abs, README_NAME);
+      if (!existsSync(rabs)) plan.files.push({ path: readme, text: PERSON_FOLDER_README });
+      else if (!lstatSync(rabs).isFile()) plan.conflicts.push({ path: readme, why: "exists and is not a file" });
+      const parent = f.path.includes("/") ? f.path.slice(0, f.path.lastIndexOf("/")) : "";
+      const processing = parent ? `${parent}/${PROCESSING_DIR}` : PROCESSING_DIR;
+      const pfile = blockedBy(evda.dir, processing);
+      if (pfile) {
+        if (!blocked.has(pfile)) plan.conflicts.push({ path: pfile, why: `exists as a file, so ${processing}/ for processing docs beside ${f.path} cannot be made there` });
+        blocked.add(pfile);
+      } else if (!existsSync(join(evda.dir, processing)) && !plan.create.includes(processing)) plan.create.push(processing);
+    }
     for (const v of want.views) {
       if (!existsSync(resolve(evda.dir, v.path))) plan.views.push({ path: v.path, view: v });
     }
@@ -295,6 +315,7 @@ export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRE
   }
   for (const rel of plan.create) mkdirSync(join(evda.dir, rel), { recursive: true });
   for (const w of plan.write) writeFileSync(join(evda.dir, w.path), JSON.stringify(w.manifest, null, 2) + "\n", { flag: "wx" });
+  for (const w of plan.files) writeFileSync(join(evda.dir, w.path), w.text, { flag: "wx" });
   for (const v of plan.views) {
     mkdirSync(dirname(resolve(evda.dir, v.path)), { recursive: true });
     writeFileSync(resolve(evda.dir, v.path), viewHeader(v.view), { flag: "wx" });
@@ -317,7 +338,7 @@ export function diffPreset(root, id, opts = {}) {
   return applyPreset(root, id, { ...opts, dry: true });
 }
 
-export const planIsEmpty = (plan) => !plan.create.length && !plan.write.length && !plan.views.length && !plan.circles.length && !plan.conflicts.length && !(plan.roles ?? []).length;
+export const planIsEmpty = (plan) => !plan.create.length && !plan.write.length && !(plan.files ?? []).length && !plan.views.length && !plan.circles.length && !plan.conflicts.length && !(plan.roles ?? []).length;
 
 // The plan in plain words, for the owner to say yes or no to. Names each folder by its note.
 export function summary(plan, preset = loadPreset(plan.id)) {
@@ -344,6 +365,7 @@ export function planLines(plan, { diff = false } = {}) {
   const verb = plan.dry || diff ? "would" : "did";
   for (const p of plan.create) out.push(`  ${verb === "did" ? "created " : "create  "} ${p}/`);
   for (const w of plan.write) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${w.path}  type ${w.manifest.type}${w.manifest.connectors.length ? `, connectors ${w.manifest.connectors.join(", ")}` : ""}`);
+  for (const w of plan.files ?? []) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${w.path}  the person folder's rule`);
   for (const r of plan.roles ?? []) out.push(`  ${verb === "did" ? "declared" : "declare "} ${r.key} -> ${r.rel}  in evda.json`);
   for (const v of plan.views) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${v.path}  view ${v.view.view} (header only)`);
   if (!diff) for (const m of plan.matched) out.push(`  skipped  ${m.path}  already says the same`);

package/lib/prompt-hook.mjs

@@ -23,10 +23,30 @@
 //
 // EVDA_CHAT_FALSIFY=ignore-filing files even when evda.json does not say "everything", for the test
 // that shows the hook reads the owner's answer.
+//
+// ON A MACHINE THAT DOES NOT WRITE THE DAY (HQ-2817). EVDA_DAY_WRITER set means another machine
+// writes the daily file, and a local append is the iCloud race HQ-2165 exists to stop (lib/
+// day-writer.mjs). There the hook never touches the day file. It hands the words to the command in
+// EVDA_DAY_WRITER_SEND, which receives evda_write's arguments as JSON on stdin and exits 0 once the
+// writer filed them (Mike's: ssh to Hestia and its evda-tool.mjs evda_write). Each message is first
+// saved as one JSON file in this machine's own outbox, outside the record and outside any synced
+// folder (EVDA_PROMPT_OUTBOX, default ~/.evda/outbox), then the outbox is sent oldest first and a
+// file is deleted only after its send exits 0. So a message said while the writer is unreachable
+// waits there and goes on the next message that reaches it, filed once:
+//   - one drainer: only this machine's hook reads its outbox, so no other machine can file it too;
+//   - one sender per file: a send first renames the file to `.sending`, an atomic claim, so two
+//     sessions submitting at once never send the same file; a claim older than SENDING_STALE_MS
+//     (a hook that was killed mid-send) is put back for the next run.
+// The whole send is bounded by EVDA_DAY_WRITER_SEND_MS (default 6000) because Claude Code holds the
+// owner's message until this hook returns. One case can still file twice: a send that reached the
+// writer and timed out before it answered. A connect timeout on the sender's side keeps that rare.
+// With EVDA_DAY_WRITER set and no EVDA_DAY_WRITER_SEND, nothing on this machine can reach the
+// writer, so nothing is queued and the hook tells the model to file the message with evda_write.
 
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
-import { tmpdir } from "node:os";
+import { homedir, hostname, tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dayRole, findRecord, filingOf, appendToDay, localDate } from "./day-file.mjs";
 import { secretShape } from "./secret-shape.mjs";
@@ -35,14 +55,100 @@ export const PROMPT_HOOK_NAME = "evda-file-prompt.mjs";
 
 const falsified = (mode) => (process.env.EVDA_CHAT_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
 
+export const DAY_WRITER_SEND_ENV = "EVDA_DAY_WRITER_SEND";
+export const PROMPT_OUTBOX_ENV = "EVDA_PROMPT_OUTBOX";
+export const SEND_BUDGET_MS = 6000;
+export const SENDING_STALE_MS = 2 * 60 * 1000;
+
+export function promptOutboxDir(env = process.env) {
+  return env[PROMPT_OUTBOX_ENV] || join(homedir(), ".evda", "outbox");
+}
+
+const realOr = (p) => { try { return realpathSync(p); } catch { return p; } };
+
+// Save one message for the writer: a new file per message, never rewritten, in this machine's outbox.
+export function queuePrompt(root, { words, context, now = new Date(), env = process.env }) {
+  const dir = promptOutboxDir(env);
+  mkdirSync(dir, { recursive: true });
+  const at = now.toISOString();
+  const stamp = at.replace(/[-:.]/g, "");
+  let file = join(dir, `${stamp}-${process.pid}.json`);
+  for (let n = 2; existsSync(file); n++) file = join(dir, `${stamp}-${process.pid}-${n}.json`);
+  writeFileSync(file, JSON.stringify({ tool: "evda_write", record: realOr(root), words, context, at, host: hostname().split(".")[0] || "host" }, null, 1) + "\n", { flag: "wx" });
+  return file;
+}
+
+// Send this record's queued messages to the writer, oldest first, within `budgetMs`. Returns
+// { sent: [file...], left, error }. Stops at the first failure, so the order of the day is kept.
+// A claim's age is measured against the file system's own clock (the mtime of a file touched now),
+// never Date.now(): a claim's mtime is stamped by the file system, and the two clocks can disagree.
+export function drainPromptOutbox(root, { env = process.env, budgetMs = Number(env.EVDA_DAY_WRITER_SEND_MS) || SEND_BUDGET_MS, nowMs = null } = {}) {
+  const cmd = (env[DAY_WRITER_SEND_ENV] ?? "").trim();
+  const dir = promptOutboxDir(env);
+  const out = { sent: [], left: 0, error: null };
+  if (!cmd || !existsSync(dir)) return out;
+  if (nowMs === null) { const probe = join(dir, ".now"); writeFileSync(probe, ""); nowMs = statSync(probe).mtimeMs; }
+  const rec = realOr(root);
+  for (const f of readdirSync(dir).filter((n) => n.endsWith(".json.sending"))) {
+    const abs = join(dir, f);
+    try { if (nowMs - statSync(abs).mtimeMs > SENDING_STALE_MS) renameSync(abs, abs.replace(/\.sending$/, "")); } catch { /* another run took it back */ }
+  }
+  const mine = readdirSync(dir).filter((n) => n.endsWith(".json")).sort().filter((n) => {
+    try { return JSON.parse(readFileSync(join(dir, n), "utf8")).record === rec; } catch { return false; }
+  });
+  const deadline = Date.now() + budgetMs;
+  for (let i = 0; i < mine.length; i++) {
+    const abs = join(dir, mine[i]);
+    const claim = `${abs}.sending`;
+    try { renameSync(abs, claim); } catch { continue; } // another session claimed it
+    let entry;
+    try { entry = JSON.parse(readFileSync(claim, "utf8")); } catch { renameSync(claim, abs); continue; }
+    const left = deadline - Date.now();
+    const args = { words: entry.words, ...(entry.context ? { context: entry.context } : {}) };
+    const r = left > 200 ? spawnSync(cmd, { shell: true, input: JSON.stringify(args), encoding: "utf8", timeout: left, env }) : { status: null, error: { code: "ETIMEDOUT" } };
+    if (r.status === 0) { unlinkSync(claim); out.sent.push(abs); continue; }
+    try { renameSync(claim, abs); } catch { /* kept as a claim; the stale rule puts it back */ }
+    out.error = r.error ? (r.error.code === "ETIMEDOUT" ? `no answer in ${budgetMs}ms` : r.error.code ?? r.error.message) : `exited ${r.status ?? r.signal}: ${String(r.stderr ?? "").trim().split("\n").pop() ?? ""}`.trim();
+    out.left = mine.length - i;
+    break;
+  }
+  return out;
+}
+
+const timeOf = (d) => `${localDate(d)} ${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+
+// The non-writer path: queue, send, and say what happened. Never touches the day file.
+function viaWriter(root, prompt, now, env) {
+  const writer = env.EVDA_DAY_WRITER.trim();
+  if (!(env[DAY_WRITER_SEND_ENV] ?? "").trim()) {
+    return `evda: this machine does not write the daily file (EVDA_DAY_WRITER is ${writer}) and has no ${DAY_WRITER_SEND_ENV} to reach it, so the owner's message above is NOT filed yet. File it verbatim with evda_write this turn.`;
+  }
+  const file = queuePrompt(root, { words: prompt, context: `Claude Code on ${hostname().split(".")[0]}, said ${timeOf(now)}`, now, env });
+  const r = drainPromptOutbox(root, { env });
+  if (r.sent.includes(file)) {
+    const more = r.sent.length > 1 ? ` (with ${r.sent.length - 1} message(s) queued earlier)` : "";
+    return `evda: the owner's message above is already filed verbatim through the day writer (${writer})${more}. Do not file it again with evda_write.`;
+  }
+  return `evda: the day writer (${writer}) could not be reached (${r.error ?? "not sent"}), so the owner's message above is queued in ${dirname(file)} on this machine and goes to the writer with their next message. Do not file it again with evda_write; if you tell them, say it is queued, not filed.`;
+}
+
 function stateFile(sid) {
   const dir = process.env.EVDA_PROMPT_STATE_DIR || join(tmpdir(), "evda-file-prompt");
   mkdirSync(dir, { recursive: true });
   return join(dir, `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
 }
 
+// The keep hook reads this (HQ-2817): on a machine that does not write the day, the day file does
+// not change here when a message is filed, so the time it was handed over is the evidence.
+function markFiled(sid, now) {
+  const sf = stateFile(sid ?? "unknown");
+  let session = {};
+  try { session = JSON.parse(readFileSync(sf, "utf8")); } catch { /* none yet */ }
+  writeFileSync(sf, JSON.stringify({ ...session, filedAt: now.toISOString() }) + "\n");
+}
+
 // One UserPromptSubmit event in, the hook's stdout out ("" for nothing to say). Never throws.
-export function run(payload, { now = new Date() } = {}) {
+export function run(payload, { now = new Date(), env = process.env } = {}) {
   try {
     const prompt = typeof payload?.prompt === "string" ? payload.prompt : "";
     if (!prompt.trim() || /^\s*\//.test(prompt)) return "";
@@ -55,6 +161,11 @@ export function run(payload, { now = new Date() } = {}) {
     if (!role) return "";
     const shape = prompt.split("\n").map(secretShape).find(Boolean);
     if (shape) return `evda: this message was not filed, because it holds ${shape}. Keep that in a password manager; file the rest of what they said with evda_write if it is worth keeping.`;
+    if ((env.EVDA_DAY_WRITER ?? "").trim()) {
+      const said = viaWriter(root, prompt, now, env);
+      if ((env[DAY_WRITER_SEND_ENV] ?? "").trim()) markFiled(payload.session_id, now); // sent or queued to send
+      return said;
+    }
     const dayAbs = join(root, manifest.mapping[role].replace(/\/+$/, ""));
     mkdirSync(dayAbs, { recursive: true });
     const abs = join(dayAbs, `${localDate(now)}.md`);
@@ -62,7 +173,7 @@ export function run(payload, { now = new Date() } = {}) {
     let session = {};
     try { session = JSON.parse(readFileSync(sf, "utf8")); } catch { /* the first prompt of the session */ }
     appendToDay(abs, { now, words: prompt, session });
-    writeFileSync(sf, JSON.stringify(session) + "\n");
+    writeFileSync(sf, JSON.stringify({ ...session, filedAt: now.toISOString() }) + "\n");
     const rel = relative(root, abs).split("\\").join("/");
     return `evda: the owner's message above is already filed verbatim in ${rel}. Do not file it again with evda_write.`;
   } catch {

package/lib/publish.mjs

@@ -29,7 +29,9 @@
 //      written, and a hit refuses. A label is its opaque id, its namespace, its own directory, a
 //      member path, or its name between slashes. The exported files' own paths are the released
 //      set (doctor prints them every run) and are left out of that search, since a marked file
-//      necessarily lives under a keyed circle's member path.
+//      necessarily lives under a keyed circle's member path. A markdown file's `sources:`
+//      frontmatter field is cut from its exported bytes before this search (HQ-2698): it is
+//      provenance, the record's own paths, and is never published.
 //
 // The fourth check in the spec (the site holds no credential to anything else) is a property of
 // where the export is served, not of this code.
@@ -70,6 +72,41 @@ function filesUnder(abs) {
 const posix = (rel) => rel.split(sep).join("/");
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
+// Provenance (HQ-2698). A top-level `sources:` field in a markdown file's frontmatter lists the
+// record paths the file was written from: a blog Companion names the private draft and the journal
+// days behind it. That is the record's own bookkeeping, never part of what a stranger reads, so it
+// is cut from every exported markdown file, whatever folder or rule released it, the way a sealed
+// section is. Only the frontmatter field is cut: a private path anywhere in the body still reaches
+// the stranger check and refuses. The value runs to the next top-level key, so a block list,
+// indented or not, a flow list on one or more lines and a bare string all go with the key.
+const PROVENANCE_KEY = /^(["']?)sources\1[ \t]*:/;
+const isFence = (line) => line.replace(/\r$/, "") === "---";
+const continues = (line) => /^[ \t]/.test(line) || /^-([ \t]|\r?$)/.test(line);
+const blank = (line) => line.replace(/\r$/, "").trim() === "";
+export function withoutProvenance(text) {
+  const lines = String(text).split("\n");
+  if (!isFence(lines[0])) return { text, cut: 0 };
+  let end = 1;
+  while (end < lines.length && !isFence(lines[end])) end++;
+  if (end >= lines.length) return { text, cut: 0 };
+  const kept = [lines[0]];
+  let cut = 0;
+  for (let i = 1; i < end; i++) {
+    if (!PROVENANCE_KEY.test(lines[i])) { kept.push(lines[i]); continue; }
+    cut++;
+    let j = i + 1;
+    for (;;) {
+      let k = j;
+      while (k < end && blank(lines[k])) k++;
+      if (k < end && continues(lines[k])) j = k + 1;
+      else break;
+    }
+    i = j - 1;
+  }
+  if (!cut) return { text, cut: 0 };
+  return { text: [...kept, ...lines.slice(end)].join("\n"), cut };
+}
+
 // Build the export in memory and run the checks. Writes nothing.
 export function buildPublicExport(evda, { circleName = null, publishedAt = new Date() } = {}) {
   const circle = publicCircle(evda, circleName);
@@ -114,14 +151,21 @@ export function buildPublicExport(evda, { circleName = null, publishedAt = new D
   // A sealed section (HQ-1220) is cut out of every markdown file on the way out; the rest of the
   // file is exported, and nothing marks where the section was. A sealed FILE never gets here:
   // released() refuses it, and a refusal refuses the publish above.
+  // A file's `sources:` provenance is cut the same way (withoutProvenance above, HQ-2698).
   let sealedCut = 0;
+  let provenanceCut = 0;
   const exportBytes = (abs) => {
     const bytes = readFileSync(abs);
-    if (!/\.md$/i.test(abs) || !carries("publish", "sealed")) return bytes;
-    const cut = withoutSealed(bytes.toString("utf8"));
-    if (!cut.sections) return bytes;
-    sealedCut += cut.sections;
-    return Buffer.from(cut.text, "utf8");
+    if (!/\.md$/i.test(abs)) return bytes;
+    let text = bytes.toString("utf8");
+    let changed = false;
+    if (carries("publish", "sealed")) {
+      const cut = withoutSealed(text);
+      if (cut.sections) { sealedCut += cut.sections; text = cut.text; changed = true; }
+    }
+    const prov = withoutProvenance(text);
+    if (prov.cut) { provenanceCut += 1; text = prov.text; changed = true; }
+    return changed ? Buffer.from(text, "utf8") : bytes;
   };
   const loaded = files.filter((f) => !consumed.has(f.path)).map((f) => ({ path: f.path, bytes: exportBytes(f.abs), by: f.by }));
   for (const v of rendered.views) loaded.push({ path: v.path, bytes: v.bytes, by: "view", view: v.view, sources: v.entries.map((e) => ({ path: e.path, sha256: e.sha256 })) });
@@ -157,9 +201,9 @@ export function buildPublicExport(evda, { circleName = null, publishedAt = new D
       // What identifies a private circle to a stranger is a LABEL: a path segment, the circle's own
       // directory, or the opaque id that travels on a Change and in an export manifest. A name
       // matched as a word anywhere in the bytes is not that test, and on a real record it refuses
-      // every publish there is: his private circles are core, health, money, people, school,
-      // therapy, wellness and workshop, and his public fact sheet says "10 core mechanics" and
-      // "help other people understand me" (2026-09-21, HQ-1199). So the name is matched only
+      // every publish there is: private circles are named with ordinary words (a circle called
+      // "core" or "people"), and a public fact sheet uses those words in plain prose ("10 core
+      // mechanics", "help other people understand me") (2026-09-21, HQ-1199). So the name is matched only
       // between slashes, and the id and namespace, which the word match never looked at, are
       // matched literally. The gap this leaves, stated so the next reader does not rediscover it:
       // a distinctive circle name written as bare prose passes.
@@ -188,7 +232,7 @@ export function buildPublicExport(evda, { circleName = null, publishedAt = new D
     }
   }
 
-  return { manifest, files: loaded, sealedCut };
+  return { manifest, files: loaded, sealedCut, provenanceCut };
 }
 
 export function canonicalManifest(manifest) {
@@ -259,6 +303,7 @@ export async function publishCommand(dir, circleName, { out, key }) {
   console.log(`published ${built.files.length} file(s) from the public circle to ${at} (${built.files.length - marked - views.length} by path, ${marked} by mark${views.length ? `, ${views.length} rendered from ${drawn} entries` : ""})`);
   for (const f of views) console.log(`  view  ${f.path}  rendered from ${f.sources.length} entries (${f.view})`);
   if (built.sealedCut) console.log(`  ${built.sealedCut} sealed section(s) left out of the files they sit in`);
+  if (built.provenanceCut) console.log(`  ${built.provenanceCut} file(s) exported without their sources: provenance`);
   console.log(`CHECKED ${built.files.length} public members, signed by ${signed.publicKey}`);
   return 0;
 }

package/lib/readme.mjs

@@ -0,0 +1,145 @@
+// README.md, the owner-facing half of the operating layer (HQ-2812).
+//
+// AGENTS.md sends the agent to sections of README.md for the facts it must never give from memory:
+// the steps for turning training off, what each AI company says, and running a model locally. A
+// record create-evda makes has them, because it writes README.md from templates/README.md. A record
+// `evda adopt` makes keeps the owner's own README.md, which has none of them, so the privacy step
+// pointed at nothing. This module renders the README once, for both, and keeps those sections in an
+// adopted README as one marked block the owner's text never shares:
+//
+//   <the owner's README, byte for byte>
+//   <!-- evda:readme -->
+//   _lead line_
+//   ## Turning training off ... ## Running a model on your own computer ...
+//   <!-- /evda:readme -->
+//
+// `ensureReadme` writes the file when it is absent, appends the block when a cited section is
+// missing, and refreshes the block's content when it is there (`evda upgrade`). A README that already
+// holds every cited heading outside a block (create-evda's own) is left alone.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { trainingSection, termsSection, INTRO } from "./setup.mjs";
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const README_REL = "README.md";
+export const README_OPEN = "<!-- evda:readme -->";
+export const README_CLOSE = "<!-- /evda:readme -->";
+export const README_LEAD = "_EVÐA wrote this block and `evda upgrade` keeps it current. Everything above it is yours, and EVÐA never changes it._";
+// The first and the last heading of templates/README.md the block carries, in that file's order.
+const FIRST = "## Turning training off";
+const AFTER = "## Getting started";
+
+// The local-model doc as a README section: its title dropped and its headings one level down.
+export function localModelSection() {
+  const text = readFileSync(join(PKG, "docs", "local-model.md"), "utf8");
+  return text.split("\n").slice(1).join("\n").replace(/^## /gm, "### ").trim();
+}
+
+// The README create-evda writes into a new record.
+export function renderReadme() {
+  let text = readFileSync(join(PKG, "templates", "README.md"), "utf8");
+  const vars = { training: trainingSection(), terms: termsSection(), intro: INTRO, localModel: localModelSection() };
+  for (const [k, v] of Object.entries(vars)) text = text.replaceAll(`{{${k}}}`, v);
+  return text;
+}
+
+// The sections AGENTS.md cites, cut from the rendered README rather than written a second time.
+export function readmeSections() {
+  const text = renderReadme();
+  const from = text.indexOf(FIRST);
+  const to = text.indexOf(AFTER);
+  if (from === -1 || to === -1 || to < from) throw new Error(`templates/README.md no longer has "${FIRST}" before "${AFTER}", so the adopted README block cannot be cut from it.`);
+  return text.slice(from, to).trimEnd();
+}
+
+export function readmeBlock() {
+  return `${README_OPEN}\n${README_LEAD}\n\n${readmeSections()}\n${README_CLOSE}\n`;
+}
+
+// Every README.md section an operating layer sends the agent to: a quoted heading followed by
+// `section of` or `in`, then `README.md`, line breaks inside the quote allowed.
+export function readmeCitations(agentsText) {
+  const flat = String(agentsText).replace(/\s+/g, " ");
+  const out = [];
+  for (const m of flat.matchAll(/"([^"]{2,120})"(?: section)? (?:of|in) `?README\.md`?/g)) if (!out.includes(m[1])) out.push(m[1]);
+  return out;
+}
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export const hasHeading = (text, heading) => new RegExp(`^#{1,6}[ \\t]+${escape(heading)}[ \\t]*#*[ \\t]*$`, "m").test(text);
+
+// The cited headings README text lacks.
+export function missingHeadings(readmeText, citations) {
+  return citations.filter((h) => !hasHeading(readmeText ?? "", h));
+}
+
+// The block's place in README text: { start, end } around the markers (end past the closing line
+// break), or null when there is none. Two blocks, or an open with no close, is a problem, not a block.
+export function findBlock(text) {
+  const open = text.indexOf(README_OPEN);
+  const close = text.indexOf(README_CLOSE);
+  if (open === -1 && close === -1) return null;
+  if (open === -1 || close === -1 || close < open || text.indexOf(README_OPEN, open + 1) !== -1 || text.indexOf(README_CLOSE, close + 1) !== -1) {
+    throw new Error(`${README_REL} has a broken ${README_OPEN} block (one marker without the other, or two of them). Fix the markers by hand; nothing was changed.`);
+  }
+  let end = close + README_CLOSE.length;
+  if (text[end] === "\n") end += 1;
+  return { start: open, end };
+}
+
+// What the README should become. Returns { action, text, added }:
+//   "written"    absent: the whole README create-evda writes
+//   "appended"   a cited section was missing and there was no block: the block is added at the end
+//   "refreshed"  the block was there with other content: its content is replaced
+//   "current"    the block is there and matches
+//   "present"    no block, and every cited heading is already in the owner's text
+// `added` is exactly what "appended" put after the owner's bytes, so a revert can take it back out.
+export function planReadme(text, citations) {
+  if (text === null) return { action: "written", text: renderReadme(), added: null };
+  const block = readmeBlock();
+  const at = findBlock(text);
+  if (at) {
+    const next = text.slice(0, at.start) + block + text.slice(at.end);
+    return next === text ? { action: "current", text, added: null } : { action: "refreshed", text: next, added: null };
+  }
+  if (!missingHeadings(text, citations).length) return { action: "present", text, added: null };
+  const added = `${text === "" || text.endsWith("\n") ? "" : "\n"}\n${block}`;
+  return { action: "appended", text: text + added, added };
+}
+
+// Apply planReadme to <dir>/README.md. `citations` defaults to the record's AGENTS.md, or the shipped
+// template's when there is none.
+export function ensureReadme(dir, { citations = null, dry = false, agents = null } = {}) {
+  const abs = join(dir, README_REL);
+  const cites = citations ?? readmeCitations(agents ?? readFileSync(join(PKG, "templates", "AGENTS.md"), "utf8"));
+  const before = existsSync(abs) ? readFileSync(abs, "utf8") : null;
+  const plan = planReadme(before, cites);
+  if (!dry && plan.text !== before) writeFileSync(abs, plan.text);
+  return { ...plan, abs, rel: README_REL, citations: cites };
+}
+
+// README text with the block taken back out: exactly what was there before an "appended", when the
+// owner did not edit around the block. Null when there is no block to take.
+export function withoutBlock(text, added) {
+  if (added && text.endsWith(added)) return text.slice(0, -added.length);
+  let at;
+  try { at = findBlock(text); } catch { return null; }
+  if (!at) return null;
+  // The line breaks the adopt put in front of the block go with it.
+  const lead = added ? added.slice(0, added.indexOf(README_OPEN)) : "";
+  const start = lead && text.slice(at.start - lead.length, at.start) === lead ? at.start - lead.length : at.start;
+  return text.slice(0, start) + text.slice(at.end);
+}
+
+export function readmeLine(r) {
+  const names = r.citations.map((c) => `"${c}"`).join(", ");
+  switch (r.action) {
+    case "written": return `README.md: written, with ${names}`;
+    case "appended": return `README.md: EVÐA's block added at the end, with ${names}; your text above it is unchanged`;
+    case "refreshed": return "README.md: EVÐA's block refreshed to what this tool ships; your text around it is unchanged";
+    case "current": return "README.md: EVÐA's block already matches what this tool ships";
+    default: return `README.md: already has ${names}; left alone`;
+  }
+}

package/lib/record-walk.mjs

@@ -0,0 +1,9 @@
+// The one rule every walker over the record uses for what is outside it (HQ-2811): a folder named
+// node_modules (packages, not notes), and any name ending in .nosync, the iCloud convention for
+// "do not sync this". A .nosync folder is one the owner chose to keep out of sync, which is the same
+// as keeping it out of the record; Mike's vault keeps its packages in node_modules.nosync, and the
+// bears-on notice once named a vendored eslint doc in it as an existing entry. Dot-names and app
+// folders stay each walker's own choice, since they differ by what the walk is for.
+export function outsideRecord(name) {
+  return name === "node_modules" || name.endsWith(".nosync");
+}

package/lib/record.mjs

@@ -98,3 +98,57 @@ export function moment(evda, { from, to = from } = {}) {
   out.entries.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : a.date.localeCompare(b.date)));
   return out;
 }
+
+// What a reader needs from each section of a file to know what it was about without opening it
+// (HQ-2324): its heading, its context line (the one line the filing agent wrote above the owner's
+// words, `Context, not their words:` or `*Context (Iris, ...): ...*`), and the opening of the
+// owner's words, cut at a word. A day file's headings are mostly times (`## 20:13`), so a heading
+// alone told a chat app nothing about his last days. Text before the first heading is a section
+// with no heading. Frontmatter, fences and the one-line marker a sealed part leaves are skipped.
+export const OPENING_MAX = 280;
+const CONTEXT_MAX = 240;
+const CONTEXT_LINE = /^\*{0,2}_?\s*Context\b[^:]*:/i;
+
+function cutAt(text, max) {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const at = cut.lastIndexOf(" ");
+  return `${at > max / 2 ? cut.slice(0, at) : cut}...`;
+}
+
+export function sectionDigest(text, { openingMax = OPENING_MAX } = {}) {
+  let body = text;
+  if (body.startsWith("---")) {
+    const end = body.indexOf("\n---", 3);
+    if (end !== -1) body = body.slice(end + 4);
+  }
+  const out = [];
+  let cur = { heading: null, lines: [] };
+  let fence = false;
+  const flush = () => {
+    const lines = cur.lines.map((l) => l.trim()).filter((l) => l && !/^\[sealed[:\]]/i.test(l));
+    const ctxAt = lines.findIndex((l) => CONTEXT_LINE.test(l));
+    const context = ctxAt === -1 ? null : cutAt(lines[ctxAt].replace(/^[*_\s]+|[*_\s]+$/g, ""), CONTEXT_MAX);
+    const words = lines.filter((_, i) => i !== ctxAt)
+      .map((l) => l.replace(/^>\s?/, "").replace(/^>\s?/, "").trim())
+      .filter(Boolean)
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (cur.heading !== null || context || words) out.push({ heading: cur.heading, context, opening: words ? cutAt(words, openingMax) : null });
+  };
+  for (const line of body.split("\n")) {
+    if (/^\s*(`{3,}|~{3,})/.test(line)) { fence = !fence; continue; }
+    if (fence) continue;
+    const h = /^#{1,6} (.*)$/.exec(line);
+    if (h) { flush(); cur = { heading: h[1].trim(), lines: [] }; continue; }
+    cur.lines.push(line);
+  }
+  flush();
+  return out;
+}
+
+// The date a heading names (`## 2026-10-02, morning: ...`, `## October 4 (added 2026-10-04)`), or null.
+export function headingDate(heading) {
+  return /\b(\d{4}-\d{2}-\d{2})\b/.exec(heading ?? "")?.[1] ?? null;
+}

package/lib/routines.mjs

@@ -243,7 +243,17 @@ export function uninstallLaunchd(key, dir, { env = process.env, home = env.HOME
 // What setup does with the routines it was given (HQ-1246). On a Mac each is installed as a launchd
 // job; elsewhere nothing can be scheduled from here, so it prints the Claude desktop steps and says
 // so. Returns the lines to print.
-export function installAtSetup(keys, dir, { env = process.env, platform = process.platform } = {}) {
+//
+// `say` prints a line at once, before anything is installed (HQ-1368): a run with --yes asks nothing,
+// so the line that a launchd job is about to be loaded into this Mac is said before launchctl runs,
+// not only in the summary after it. `launchctl` is the tests' stand-in, handed through to
+// installLaunchd with loading on, so a test can watch the order without the real launchctl.
+export function setupNotice(key, dir) {
+  const r = ROUTINES[key];
+  return `Installing a launchd job on this Mac: ${r.title}, ${r.when.toLowerCase()}, runs ${r.command.join(" ")} on ${resolve(dir)} with your own Claude. Not wanted: create-evda --no-routines, or afterwards evda routine ${key} ${resolve(dir)} --uninstall`;
+}
+
+export function installAtSetup(keys, dir, { env = process.env, platform = process.platform, say = null, launchctl = null } = {}) {
   const lines = [];
   for (const key of keys) {
     const r = ROUTINES[key];
@@ -251,7 +261,8 @@ export function installAtSetup(keys, dir, { env = process.env, platform = proces
     if (platform === "darwin") {
       let done;
       try {
-        done = installLaunchd(key, dir, { env });
+        if (say && !falsified(env, "silent-install")) say(setupNotice(key, dir));
+        done = installLaunchd(key, dir, launchctl ? { env, launchctl, load: true } : { env });
       } catch (e) {
         if (e.code !== "TEMP_RECORD") throw e;
         lines.push(e.message);