create-evda 0.1.8 → 0.1.10

package/lib/plugin.mjs

@@ -0,0 +1,208 @@
+// `evda plugin <dir>`: a Claude plugin for one record, so Claude Cowork reaches it (HQ-2802).
+//
+// Cowork does not start the local servers in claude_desktop_config.json (support.claude.com
+// article 11175166: they "aren't available in Cowork or claude.ai"), and its docs never say it
+// reads a folder's CLAUDE.md, AGENTS.md or .claude/settings.json. It does load a plugin's skills,
+// hooks/hooks.json and a local MCP server the app starts, when the task runs on the owner's
+// computer (claude.com/docs/plugins/platform-support, read 2026-10-21). So a record reaches Cowork
+// only through a plugin, built here for one record with its path baked in:
+//
+//   .claude-plugin/plugin.json   the manifest (claude.com/docs/plugins/build)
+//   .mcp.json                    the record's server: `evda mcp <record>`, by connect.mjs's rule
+//   hooks/hooks.json             Stop, UserPromptSubmit and PreToolUse, each through
+//                                scripts/evda-hook.mjs to the hooks `evda hook install` installs
+//   scripts/evda-hook.mjs        lib/plugin-hook.mjs, copied (the plugin is a zip with no packages)
+//   skills/evda/SKILL.md         the shipped evda skill, its description saying to load the
+//                                operating layer first in every conversation, because Cowork may
+//                                never read AGENTS.md
+//
+// Two rules from the same page shape it. Cowork ignores a server whose `${user_config.*}` has no
+// default, because it does not prompt, so nothing here asks for configuration: the path is baked
+// in. And claude.ai and Cowork refuse a plugin with a top-level bin/, so there is none.
+//
+// The owner uploads the zip in Customize, then Plugins, then Add, then Upload plugin. Exported for
+// `evda adopt` (HQ-2797): buildPlugin(dir, { out }) and uploadLines(result).
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
+import { PACKAGE_ROOT, serverCommand, stableNode, installGuard, SKILL_SOURCE } from "./connect.mjs";
+import { installHook, installPromptHook } from "./hooks.mjs";
+import { filingOf } from "./day-file.mjs";
+import { readManifest } from "./manifest.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const PLUGIN_SERVER = "evda";
+export const LAUNCHER_SOURCE = join(PACKAGE_ROOT, "lib", "plugin-hook.mjs");
+export const LAUNCHER_REL = "scripts/evda-hook.mjs";
+export const UPLOAD_STEP = "In the Claude app, open Customize, then Plugins, then Add, then Upload plugin, and choose";
+
+const packageVersion = () => JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
+
+// A plugin name is lowercase words joined by hyphens, and permanent: one per record folder.
+export function pluginName(dir) {
+  const slug = basename(resolve(dir)).normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+  return slug ? `evda-${slug}` : "evda-record";
+}
+
+// One shell word, whatever the path holds: spaces, quotes, $ and backticks included.
+export const shq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+
+// The server command for a plugin. connect.mjs's rule (absolute node and bin when installed
+// somewhere stable), except that the npx form is pinned to this version and names npx by its
+// absolute path with a PATH that finds node: the desktop app starts servers with a minimal PATH,
+// and `@latest` would let an uploaded plugin change under the owner.
+export function pluginServerCommand(dir, { execPath = process.execPath, bin, env = process.env, version = packageVersion() } = {}) {
+  const rec = resolve(dir);
+  const c = serverCommand(rec, { execPath, env, ...(bin ? { bin } : {}) });
+  if (c.command !== "npx") return { command: c.command, args: c.args };
+  const node = stableNode(execPath, env);
+  const npx = join(dirname(node), process.platform === "win32" ? "npx.cmd" : "npx");
+  const sep = process.platform === "win32" ? ";" : ":";
+  const path = [dirname(node), ...(process.platform === "win32" ? [] : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"])].join(sep);
+  return { command: existsSync(npx) ? npx : "npx", args: ["-y", "-p", `create-evda@${version}`, "evda", "mcp", rec], env: { PATH: path } };
+}
+
+// A hook command in shell form, the form every Claude Code version runs. The node this was built
+// with when it is there, else whatever `node` the hook's PATH has (a Cowork VM, another machine).
+export function hookCommand(mode, dir, { execPath = process.execPath, env = process.env } = {}) {
+  const node = stableNode(execPath, env);
+  return `n=${shq(node)}; [ -x "$n" ] || n=node; "$n" "\${CLAUDE_PLUGIN_ROOT}/${LAUNCHER_REL}" ${mode} ${shq(resolve(dir))}`;
+}
+
+function skillText() {
+  const shipped = readFileSync(SKILL_SOURCE, "utf8");
+  const body = shipped.replace(/^---\n[\s\S]*?\n---\n/, "");
+  const description = "Use at the start of every conversation and every task, before your first reply: call evda_operating_layer from this plugin's evda server and follow it for the whole session, because it says who you are for the owner and how their EVÐA record is kept. Also use whenever they talk about their day, a person, what is on their mind, or say evda, Iris, my record, journal this or log this. Files their words verbatim through the evda_* tools and never quizzes.";
+  return `---\nname: evda\ndescription: ${description}\n---\n${body}`;
+}
+
+// The plugin's files, as { relative path: string }.
+export function pluginFiles(dir, opts = {}) {
+  const rec = resolve(dir);
+  const manifest = readManifest(rec);
+  const filing = filingOf(manifest);
+  const name = pluginName(rec);
+  const version = opts.version ?? packageVersion();
+  const server = pluginServerCommand(rec, { ...opts, version });
+  const hook = (mode, timeout, matcher) => ({ ...(matcher ? { matcher } : {}), hooks: [{ type: "command", command: hookCommand(mode, rec, opts), timeout }] });
+  const hooks = {
+    Stop: [hook("keep", 30)],
+    PreToolUse: [hook("guard", 30, "Read|Grep|Bash|NotebookRead")],
+    // The prompt hook files every message, so only an owner who chose "everything" gets it (HQ-1385).
+    ...(filing === "everything" ? { UserPromptSubmit: [hook("prompt", 15)] } : {}),
+  };
+  const owner = typeof manifest.owner === "string" ? manifest.owner : manifest.owner?.name;
+  return {
+    ".claude-plugin/plugin.json": JSON.stringify({
+      name,
+      displayName: `EVÐA: ${basename(rec)}`,
+      version,
+      description: `Reach the EVÐA record at ${rec} from Cowork: its evda tools, the hooks that keep it, and the skill that loads its operating layer first.`,
+      author: { name: owner || "EVÐA" },
+    }, null, 2) + "\n",
+    ".mcp.json": JSON.stringify({ mcpServers: { [PLUGIN_SERVER]: { type: "stdio", ...server } } }, null, 2) + "\n",
+    "hooks/hooks.json": JSON.stringify({ hooks }, null, 2) + "\n",
+    [LAUNCHER_REL]: readFileSync(LAUNCHER_SOURCE, "utf8"),
+    "skills/evda/SKILL.md": skillText(),
+    "README.md": `# ${name}\n\nThis plugin connects Claude Cowork to one EVÐA record, the folder at \`${rec}\` on this computer. It starts that record's evda MCP server, so Claude can read the record and file the owner's words into it verbatim, and it runs the record's own hooks in Cowork tasks: the one that asks before a task ends with nothing filed${filing === "everything" ? ", the one that files each message as it is sent" : ""}, and the read guard. Nothing leaves this computer through it. Rebuild it with \`evda plugin\` if the folder moves.\n`,
+  };
+}
+
+// CRC-32 (IEEE), for the zip.
+const CRC = (() => { const t = new Uint32Array(256); for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0; } return t; })();
+function crc32(buf) { let c = 0xffffffff; for (const b of buf) c = CRC[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; }
+
+// A zip of { path: string|Buffer }, deflated, paths at the archive root.
+export function zip(files) {
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+  for (const [path, content] of Object.entries(files)) {
+    const data = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+    const comp = deflateRawSync(data);
+    const name = Buffer.from(path, "utf8");
+    const crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0); local.writeUInt16LE(20, 4); local.writeUInt16LE(0x0800, 6); local.writeUInt16LE(8, 8);
+    local.writeUInt16LE(0, 10); local.writeUInt16LE(0x21, 12); local.writeUInt32LE(crc, 14); local.writeUInt32LE(comp.length, 18);
+    local.writeUInt32LE(data.length, 22); local.writeUInt16LE(name.length, 26); local.writeUInt16LE(0, 28);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0); central.writeUInt16LE(0x0314, 4); central.writeUInt16LE(20, 6); central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(8, 10); central.writeUInt16LE(0, 12); central.writeUInt16LE(0x21, 14); central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(comp.length, 20); central.writeUInt32LE(data.length, 24); central.writeUInt16LE(name.length, 28);
+    central.writeUInt32LE(((0o100644) << 16) >>> 0, 38); central.writeUInt32LE(offset, 42);
+    locals.push(local, name, comp);
+    centrals.push(central, name);
+    offset += 30 + name.length + comp.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  const count = Object.keys(files).length;
+  end.writeUInt32LE(0x06054b50, 0); end.writeUInt16LE(count, 8); end.writeUInt16LE(count, 10);
+  end.writeUInt32LE(cd.length, 12); end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+// The entries of a zip this module wrote, as { path: Buffer }. For tests and doctor-style checks.
+export function unzip(buf) {
+  const out = {};
+  const endAt = buf.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+  if (endAt < 0) throw new Error("not a zip");
+  let p = buf.readUInt32LE(endAt + 16);
+  const count = buf.readUInt16LE(endAt + 10);
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(p) !== 0x02014b50) throw new Error("bad central directory");
+    const method = buf.readUInt16LE(p + 10), csize = buf.readUInt32LE(p + 20), nlen = buf.readUInt16LE(p + 28);
+    const xlen = buf.readUInt16LE(p + 30), clen = buf.readUInt16LE(p + 32), at = buf.readUInt32LE(p + 42);
+    const name = buf.subarray(p + 46, p + 46 + nlen).toString("utf8");
+    const dataAt = at + 30 + buf.readUInt16LE(at + 26) + buf.readUInt16LE(at + 28);
+    const raw = buf.subarray(dataAt, dataAt + csize);
+    out[name] = method === 8 ? inflateRawSync(raw) : Buffer.from(raw);
+    p += 46 + nlen + xlen + clen;
+  }
+  return out;
+}
+
+const isOurs = (folder) => {
+  try { return JSON.parse(readFileSync(join(folder, ".claude-plugin", "plugin.json"), "utf8")).name?.startsWith("evda-"); } catch { return false; }
+};
+
+// Build the plugin folder and its zip. `out` is the zip's path (default
+// <record>/.evda/plugin/<name>.zip, which no device sync carries); the folder sits beside it.
+// Installs or refreshes the record's hooks first, so what the plugin points at is current.
+export function buildPlugin(dir, { out = null, ...opts } = {}) {
+  const rec = resolve(dir);
+  if (!existsSync(join(rec, "evda.json"))) throw new EvdaError(`REFUSED: ${rec} has no evda.json, so it is not an EVÐA record. Nothing was written.`, { code: "NOT_A_RECORD", exit: 2 });
+  const name = pluginName(rec);
+  const zipPath = resolve(out ?? join(rec, ".evda", "plugin", `${name}.zip`));
+  if (!zipPath.endsWith(".zip")) throw new EvdaError(`REFUSED: --out names the zip to write, so it ends in .zip (got ${zipPath}). Nothing was written.`, { code: "BAD_OUT", exit: 2 });
+  const folder = zipPath.slice(0, -4);
+  if (existsSync(folder) && readdirSync(folder).length && !isOurs(folder)) throw new EvdaError(`REFUSED: ${folder} already holds something that is not an EVÐA plugin. Nothing was written.`, { code: "OUT_TAKEN", exit: 2 });
+
+  const installed = [installHook(rec).action];
+  installGuard(rec);
+  if (filingOf(readManifest(rec)) === "everything") installed.push(installPromptHook(rec).action);
+
+  const files = pluginFiles(rec, opts);
+  rmSync(folder, { recursive: true, force: true });
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(folder, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  }
+  mkdirSync(dirname(zipPath), { recursive: true });
+  writeFileSync(zipPath, zip(files));
+  return { name, record: rec, folder, zip: zipPath, files: Object.keys(files), bytes: statSync(zipPath).size, hooks: installed };
+}
+
+// What to tell the owner once it is built: the one step left is theirs.
+export function uploadLines(r) {
+  return [
+    `Built the Cowork plugin ${r.name} for ${r.record}:`,
+    `  ${r.zip}`,
+    `${UPLOAD_STEP} that zip. Cowork then reaches this record in tasks that run on this computer, through its evda tools and hooks.`,
+    `It also loads in Claude Code sessions signed in to the same account. Its hooks stay quiet there, because the record's own hooks already run in it; its evda server shows up as a second one, and \`claude plugin disable ${r.name}@synced\` turns the plugin off in Claude Code only. If the folder moves, run \`evda plugin\` again and upload the new zip.`,
+  ];
+}
+

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,7 @@ 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";
 
 export const PRESETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "presets");
 export const PRESET_FILE = "preset.json";
@@ -223,6 +227,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 +236,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 +268,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 +314,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 +337,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 +364,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/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;
 }