create-evda 0.1.8 → 0.1.9

package/hooks/evda-day-writer-guard.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook: on a machine with EVDA_DAY_WRITER set, refuse a direct write to the
+// record's daily file and send the agent to evda_write on the machine that writes it (HQ-2165). The
+// logic is lib/day-writer.mjs; this file is only the entry point a user-level settings.json names.
+import { runHook } from "../lib/day-writer.mjs";
+
+runHook().then((code) => process.exit(code), () => process.exit(0));

package/lib/acknowledge.mjs

@@ -0,0 +1,187 @@
+// Acknowledging what the owner put in the record (HQ-2060): the first reader to reach a weighty
+// entry says it back to them once, and every other reader can see that it did.
+//
+// THE PROBLEM. An owner learns how much something weighed from how it was received. Today every
+// agent over one record writes its own record and reads only its own: a live conversation, an
+// always-on agent, a scheduled run. So a correction the owner filed on Monday gets reacted to three
+// times, once by each, or zero times, because each assumes another already did. Mike, 2026-10-01:
+// "whoever sees it first acts on it whetehr its phroneiss or plan pass or a next session".
+//
+// WHERE THE MARK LIVES, AND WHY NOT ON THE ENTRY.
+//   - A record file is append only, and `evda_write` takes no path on purpose. The one tool that
+//     edits a file is `evda_release_note`, which edits one frontmatter line and only on the owner's
+//     explicit yes. A mark written into the entry would make every reader a writer of the owner's
+//     words.
+//   - The unit of weight is a section, not a file: one conversation is one `## HH:MM` inside a day
+//     file that holds several. Frontmatter cannot address a section.
+//   - Their words stay their words. A line the agent appends inside the day file is the agent's text
+//     in the owner's file, and a later reader can quote it back as something they said.
+// So the mark is a sidecar the readers share, in the shape `messages/.seen.json` already uses for
+// "what this agent has seen" (lib/messages.mjs): a dotfile of bookkeeping, keyed by what it tracks,
+// beside the thing it tracks. It is at the record root rather than under `.evda/`, because `.evda/`
+// is derived and rebuildable and an acknowledgement is derivable from nothing.
+//
+// The format, one file per record:
+//
+//   .acknowledged.json
+//     {
+//       "record/daily/2026-10-01.md#14:03": {
+//         "by": "Hestia",
+//         "at": "2026-10-01T06:12:00-04:00",
+//         "note": "said back to him that the Greek trade is settled and I will not reopen it"
+//       }
+//     }
+//
+// The key is the entry: its path relative to the record, and the exact heading of the section when
+// the weight is in one section. A heading never changes once written, so the key is stable.
+//
+// Append only, in the same sense as the record: a key that is present is never written over. The
+// second reader of an entry gets { first: false, already } and nothing is written, which is the
+// whole mechanism. "Weighty" is never decided here; weight is the reader's judgment and this file
+// only remembers that one of them acted.
+//
+// EVDA_ACK_FALSIFY=<mode,...>, for the tests. Each breaks exactly one rule:
+//   overwrite     a second acknowledgement of the same entry overwrites the first and reports first
+//   any-section   a section that is not a heading in that file is accepted
+//   strict-read   an .acknowledged.json that does not parse throws instead of reading as empty
+//   no-secrets    the secret check is skipped
+//   hide          acknowledgementsFor returns nothing, so a later reader cannot see the mark
+
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { agentName } from "./messages.mjs";
+import { secretShape } from "./references.mjs";
+import { isoLocal } from "./messages.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const ACK_FILE = ".acknowledged.json";
+export const NOTE_MAX = 400;
+export const BY_MAX = 60;
+export const SECTION_MAX = 200;
+
+export const ACK_FALSIFY_MODES = ["overwrite", "any-section", "strict-read", "no-secrets", "hide"];
+const falsified = (mode) => (process.env.EVDA_ACK_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+const refuse = (message, code) => new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+
+// The entry a mark is about: a path, and the section heading inside it when there is one.
+export function entryKey(path, section = null) {
+  const p = String(path).replace(/\\/g, "/").replace(/^\.\//, "");
+  return section ? `${p}#${section}` : p;
+}
+
+// A section as it is keyed: the heading's text, with its leading #s and surrounding space gone, so
+// "## 14:03", "##14:03" and "14:03" are one section.
+export function normalizeSection(section) {
+  return String(section).replace(/^\s*#+\s*/, "").trim();
+}
+
+function ackPath(evda) {
+  return join(evda.dir, ACK_FILE);
+}
+
+// Every mark this record holds, as { key: { by, at, note } }. Missing, unreadable, or not a JSON
+// object: empty, so a reader with no file acts like the first reader rather than throwing.
+export function readAcknowledged(evda) {
+  const p = ackPath(evda);
+  if (!existsSync(p)) return {};
+  let v;
+  try { v = JSON.parse(readFileSync(p, "utf8")); } catch (e) { if (falsified("strict-read")) throw e; return {}; }
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return {};
+  const out = {};
+  for (const [k, m] of Object.entries(v)) {
+    if (m === null || typeof m !== "object" || Array.isArray(m)) continue;
+    if (typeof m.at !== "string" || typeof m.note !== "string") continue;
+    out[k] = { by: typeof m.by === "string" ? m.by : null, at: m.at, note: m.note };
+  }
+  return out;
+}
+
+function writeAcknowledged(evda, all) {
+  const p = ackPath(evda);
+  const keys = Object.keys(all).sort();
+  const ordered = Object.fromEntries(keys.map((k) => [k, all[k]]));
+  const t = `${p}.tmp-${process.pid}`;
+  writeFileSync(t, JSON.stringify(ordered, null, 2) + "\n");
+  renameSync(t, p);
+}
+
+// What is already acknowledged in one file, newest-written last: [{ section, by, at, note }]. A mark
+// on the file as a whole comes back with section null.
+export function acknowledgementsFor(path, all) {
+  if (falsified("hide")) return [];
+  const p = String(path).replace(/\\/g, "/");
+  const out = [];
+  for (const [key, m] of Object.entries(all)) {
+    const hash = key.indexOf("#");
+    const keyPath = hash === -1 ? key : key.slice(0, hash);
+    if (keyPath !== p) continue;
+    out.push({ section: hash === -1 ? null : key.slice(hash + 1), by: m.by, at: m.at, note: m.note });
+  }
+  out.sort((a, b) => String(a.section ?? "").localeCompare(String(b.section ?? "")));
+  return out;
+}
+
+// Is this entry already acknowledged? The read every other reader does before it says anything.
+export function isAcknowledged(evda, { path, section = null } = {}, all = null) {
+  const marks = all ?? readAcknowledged(evda);
+  const key = entryKey(path, section === null || section === undefined ? null : normalizeSection(section));
+  return marks[key] ?? null;
+}
+
+function oneLine(value, name, max) {
+  if (typeof value !== "string" || value.trim() === "") throw refuse(`evda_acknowledge needs "${name}".`, "EMPTY");
+  const v = value.trim();
+  if (/[\r\n]/.test(v)) throw refuse(`evda_acknowledge "${name}" is one line.`, "LINES");
+  if (v.length > max) throw refuse(`evda_acknowledge "${name}" is ${v.length} characters; at most ${max}.`, "TOO_LONG");
+  return v;
+}
+
+function refuseSecrets(value, name) {
+  if (falsified("no-secrets")) return;
+  const shape = secretShape(value);
+  if (shape) throw refuse(`evda_acknowledge "${name}" holds ${shape}. A password, key or token is never written into the record.`, "SECRET");
+}
+
+// Does `section` exist as a markdown heading in `text`?
+export function hasHeading(text, section) {
+  const want = normalizeSection(section);
+  return text.split("\n").some((line) => /^#{1,6}\s+/.test(line) && normalizeSection(line) === want);
+}
+
+// Record that this reader acted on one weighty entry. Returns
+// { key, path, section, first, by, at, note, already }.
+//
+// first true  : nothing was marked before, this reader is the one that acts, and the mark is written.
+// first false : another reader already did. Nothing is written, `already` says who, when and what
+//               they did, and this reader says nothing about the entry.
+export function acknowledge(evda, args = {}, { now = new Date() } = {}) {
+  if (typeof args.path !== "string" || args.path.trim() === "") throw refuse('evda_acknowledge needs "path", the entry in the record you acted on.', "NO_PATH");
+  const abs = resolve(evda.dir, args.path.trim());
+  if (abs !== evda.dir && !abs.startsWith(evda.dir + sep)) throw refuse(`${args.path} is outside the record.`, "OUTSIDE");
+  if (!existsSync(abs) || !statSync(abs).isFile()) throw refuse(`nothing is at ${args.path} in the record, so there is no entry to acknowledge.`, "MISSING");
+  const path = relative(evda.dir, abs).split(sep).join("/");
+
+  let section = null;
+  if (args.section !== undefined && args.section !== null && String(args.section).trim() !== "") {
+    section = normalizeSection(oneLine(String(args.section), "section", SECTION_MAX));
+    if (!falsified("any-section") && !hasHeading(readFileSync(abs, "utf8"), section)) {
+      throw refuse(`${path} has no heading "${section}". Acknowledge the heading as it is written in the file, or leave section out to acknowledge the whole entry.`, "NO_SECTION");
+    }
+  }
+
+  const key = entryKey(path, section);
+  const all = readAcknowledged(evda);
+  if (all[key] && !falsified("overwrite")) {
+    return { key, path, section, first: false, by: all[key].by, at: all[key].at, note: all[key].note, already: all[key] };
+  }
+
+  const note = oneLine(args.note, "note", NOTE_MAX);
+  refuseSecrets(note, "note");
+  const by = args.by === undefined || args.by === null ? agentName(evda) : oneLine(String(args.by), "by", BY_MAX);
+  refuseSecrets(by, "by");
+  const at = isoLocal(now);
+  all[key] = { by, at, note };
+  writeAcknowledged(evda, all);
+  return { key, path, section, first: true, by, at, note, already: null };
+}

package/lib/browse.mjs

@@ -0,0 +1,354 @@
+// The whole record as a folder tree, for the owner's own app (HQ-2038).
+//
+// The EVÐA Mac app shows every folder of the record, not only the record roles, one folder at a
+// time so a record of tens of thousands of files opens fast. Three rules decide what it lists, and
+// each is the rule another reader already uses, never a copy of it:
+//
+//   what the scan reads   sync-rules `scanSkip` with the plan's excludes and the sub-record
+//                         boundaries, the same predicate the shadow scan and doctor walk with, so
+//                         the app and the sync agree on what is in the record. Dot-named entries
+//                         (.obsidian, .claude) are left out of the view on top of that.
+//   which circle          circles `homesOf` through readers `readersFor`, the resolver doctor and
+//                         the MCP server use: a file shows the circle that homes it.
+//   what stays closed     `noted: true` and `sealed: true` entries (readers `isNotedFile`,
+//                         `isSealedFile`), and a part whose read_by says no AI reads it (`none`)
+//                         or does not parse: the app hosts the owner's AI connection, so it keeps
+//                         those closed as the phone keeps a noted entry closed.
+//
+// `openEntry` opens exactly what `browse` lists as text: it walks the same rules down the path, so
+// a path the listing would not show is refused however it is spelled.
+//
+// Listing never reads a file iCloud holds only in the cloud (a dataless file): reading it would
+// download it. Such a file is listed with `cloud: true` and its frontmatter unread; opening it reads
+// it, and a noted or sealed entry is refused then.
+
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { scanSkip, datalessAmong, isTextPath } from "./sync-rules.mjs";
+import { planBeside } from "./circle-plan.mjs";
+import { boundaries } from "./records.mjs";
+import { resolveRole } from "./roles.mjs";
+import { readContext, readersFor, isNotedFile, isSealedFile, aiView } from "./readers.mjs";
+import { EvdaError } from "./errors.mjs";
+import { FENCE_OPEN } from "./agents.mjs";
+import { write as writeToday, todayPath } from "./tools.mjs";
+
+// The default preset: the roles pinned above the tree, in this order, when the mapping gives each a
+// folder. The journal first. `work` is a live source (harlequin:), not a folder, so it is never pinned.
+export const DEFAULT_PINS = ["record/daily", "record/captures", "record/people", "collections", "collections/areas", "knowledge"];
+
+// The record roles keep the names the phone gives them; any other pin is named by its folder.
+const ROLE_TITLES = { "record/daily": "Journal", "record/captures": "Captures", "record/people": "People" };
+
+// The largest file the app opens as text. Bigger text is listed and stays closed.
+export const MAX_OPEN_BYTES = 4 * 1024 * 1024;
+
+const DATED = /^\d{4}-\d{2}-\d{2}/;
+
+// Tooling the view leaves out, by kind (HQ-2038, round 2): a package manifest or lockfile, a shell
+// script, a license, a backup copy, an empty file. It stays in the record and in the sync; the app
+// does not list or open it, and each folder says how many it left out. Dot-named entries are left
+// out the same way.
+const LOCKFILE = /(^package(-lock)?\.json$)|(-lock\.json$)|(^pnpm-lock\.yaml$)|(^yarn\.lock$)/i;
+export function isTooling(name, size) {
+  if (name.startsWith(".")) return true;
+  if (size === 0) return true;
+  if (LOCKFILE.test(name)) return true;
+  if (/\.(sh|zsh|bash)$/i.test(name)) return true;
+  if (/^(LICENSE|LICENCE|COPYING)(\.(md|txt))?$/i.test(name)) return true;
+  if (/\.bak($|[.-])|~$/i.test(name)) return true;
+  return false;
+}
+
+// The files that say how the record and its agent work: the manifest, the operating layer the
+// mapping names, the agent pointer files create-evda writes, and any root file carrying the
+// generated core fence (his IRIS.md). Only at the record's root. The app groups them under one
+// entry instead of mixing them with notes.
+const AGENT_FILES = ["evda.json", "AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+function isOperating(bctx, name) {
+  if (AGENT_FILES.includes(name)) return true;
+  const agents = bctx.evda.manifest?.mapping?.agents;
+  if (typeof agents === "string" && agents.replace(/^\.\//, "") === name) return true;
+  if (!/\.md$/i.test(name)) return false;
+  if (datalessAmong(bctx.evda.dir, [name]).size) return false;
+  try {
+    return readFileSync(join(bctx.evda.dir, name), "utf8").includes(FENCE_OPEN);
+  } catch {
+    return false;
+  }
+}
+
+// "01_Projects" -> "Projects", "03_Resources/Wiki" -> "Wiki".
+export function folderTitle(rel) {
+  const last = rel.split("/").pop() ?? rel;
+  const t = last.replace(/^\d+[\s_.-]+/, "").replace(/[_-]+/g, " ").trim();
+  return t ? t[0].toUpperCase() + t.slice(1) : last;
+}
+
+// Everything one listing needs, read once: the scan's skip rule, the circles and the readers.
+export function browseContext(evda) {
+  let extra = [];
+  try { extra = planBeside(evda)?.plan?.exclude ?? []; } catch { extra = []; }
+  const skip = scanSkip([...extra, ...boundaries(evda)]);
+  return { evda, skip, readers: readContext(evda) };
+}
+
+// Why the app keeps a file closed, or null when it opens. `cloud` skips the frontmatter read.
+export function closedBecause(bctx, abs, { cloud = false } = {}) {
+  if (!cloud && isSealedFile(abs)) return "sealed";
+  if (!cloud && isNotedFile(abs)) return "noted";
+  const r = readersFor(bctx.readers, abs);
+  if (r.broken) return "reader";
+  if (Array.isArray(r.readers) && r.readers.length > 0 && r.readers.every((x) => x.kind === "none")) return "reader";
+  return null;
+}
+
+const circleOf = (bctx, abs) => readersFor(bctx.readers, abs).circle;
+
+const shown = (name) => !name.startsWith(".");
+
+// A relative folder or file path, refused unless every segment is a plain, visible name.
+function cleanRel(rel, what) {
+  const r = String(rel ?? "").replace(/^\/+|\/+$/g, "");
+  if (r === "") return "";
+  const parts = r.split("/");
+  if (parts.some((p) => p === "" || p === "." || p === ".." || !shown(p))) throw new EvdaError(`${rel} is not ${what} in your record.`, { code: "OUTSIDE", exit: 2 });
+  return parts.join("/");
+}
+
+// Walk the rules down `rel` from the root: every segment visible, not skipped by the scan, and no
+// symlink on the way. Returns the lstat of the last segment, or null when the path is not one the
+// listing shows (missing included).
+function reachable(bctx, rel) {
+  const parts = rel.split("/");
+  let st = null;
+  for (let i = 0; i < parts.length; i++) {
+    const sub = parts.slice(0, i + 1).join("/");
+    try { st = lstatSync(join(bctx.evda.dir, sub)); } catch { return null; }
+    if (st.isSymbolicLink() || bctx.skip(sub, st)) return null;
+    if (i < parts.length - 1 && !st.isDirectory()) return null;
+  }
+  return st;
+}
+
+// The pinned folders: each DEFAULT_PINS role the mapping gives a folder, with whether it is there.
+// A role the mapping leaves out is not pinned, except the record roles, which read from
+// `record/<x>` as everywhere else.
+export function pins(evda, { bctx = browseContext(evda) } = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const role of DEFAULT_PINS) {
+    let r;
+    try { r = resolveRole(evda, role); } catch { continue; }
+    if (r.kind === "source") continue;
+    if (!r.mapped && !role.startsWith("record/")) continue;
+    let folder;
+    try { folder = cleanRel(r.mapped ? String(r.rel).replace(/^(\.\/)+/, "") : role, "a folder"); } catch { continue; }
+    if (folder === "" || seen.has(folder)) continue;
+    seen.add(folder);
+    const st = reachable(bctx, folder);
+    out.push({ role, title: ROLE_TITLES[role] ?? folderTitle(folder), folder, exists: Boolean(st?.isDirectory()) });
+  }
+  return out;
+}
+
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+
+// Dated names newest first, ahead of the rest; the rest by name.
+function fileOrder(a, b) {
+  const da = DATED.test(a.name), db = DATED.test(b.name);
+  if (da && db) return -byName(a, b);
+  if (da !== db) return da ? -1 : 1;
+  return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" });
+}
+
+// One folder's children: its folders and its files, each file with the circle that homes it.
+// `hidden` counts the files kept closed (noted, sealed, a part no AI reads), never their names.
+// `noted` gives each noted entry by its date alone (HQ-2049), newest first: the date its name
+// starts with, else the day it was last written. Never a name, a title or a word of it.
+// `tooling` counts what the view leaves out by kind (isTooling). At the root, the files that say
+// how the record works are left to `operating` instead.
+export function browse(evda, folder = "", { bctx = browseContext(evda) } = {}) {
+  const rel = cleanRel(folder, "a folder");
+  if (rel !== "") {
+    const st = reachable(bctx, rel);
+    if (!st || !st.isDirectory()) throw new EvdaError(`${rel} is not a folder in your record.`, { code: "NOT_FOUND", exit: 2 });
+  }
+  const abs = rel === "" ? evda.dir : join(evda.dir, rel);
+  const dirs = [];
+  const files = [];
+  let hidden = 0;
+  let tooling = 0;
+  const noted = [];
+  const candidates = [];
+  for (const name of readdirSync(abs)) {
+    const child = rel === "" ? name : `${rel}/${name}`;
+    let st;
+    try { st = lstatSync(join(evda.dir, child)); } catch { continue; }
+    if (st.isSymbolicLink() || bctx.skip(child, st)) continue;
+    if (!shown(name)) { tooling++; continue; }
+    if (st.isDirectory()) dirs.push({ path: child, name });
+    else if (!st.isFile()) continue;
+    else if (rel === "" && isOperating(bctx, name)) continue;
+    else if (isTooling(name, st.size)) tooling++;
+    else candidates.push({ child, name, size: st.size, mtime: st.mtimeMs });
+  }
+  // Every file, not only notes: a PDF or an image iCloud holds only in the cloud is listed as such,
+  // so the app says so and fetches it on a click instead of downloading it by opening (HQ-2071).
+  const cloud = datalessAmong(evda.dir, candidates.map((c) => c.child));
+  for (const c of candidates) {
+    const fabs = join(evda.dir, c.child);
+    const inCloud = cloud.has(c.child);
+    const why = closedBecause(bctx, fabs, { cloud: inCloud });
+    if (why) {
+      hidden++;
+      if (why === "noted") noted.push(notedDate(c.name, c.mtime));
+      continue;
+    }
+    files.push({ path: c.child, name: c.name, size: c.size, circle: circleOf(bctx, fabs), text: isTextPath(c.child) && c.size <= MAX_OPEN_BYTES, cloud: inCloud });
+  }
+  dirs.sort(byName);
+  files.sort(fileOrder);
+  noted.sort().reverse();
+  return { folder: rel, dirs, files, hidden, noted, tooling };
+}
+
+// A noted entry's date and nothing else: the YYYY-MM-DD its name starts with, else the local day
+// it was last written.
+export function notedDate(name, mtimeMs) {
+  const m = DATED.exec(name);
+  if (m) return m[0];
+  const d = new Date(mtimeMs);
+  const two = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+}
+
+// The files that say how the record and its agent work, from the root (isOperating), each with its
+// circle, by name. Closed ones are left out as anywhere else.
+export function operating(evda, { bctx = browseContext(evda) } = {}) {
+  const out = [];
+  for (const name of readdirSync(evda.dir).sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }))) {
+    let st;
+    try { st = lstatSync(join(evda.dir, name)); } catch { continue; }
+    if (!st.isFile() || st.isSymbolicLink() || bctx.skip(name, st) || !shown(name) || !isOperating(bctx, name)) continue;
+    const abs = join(evda.dir, name);
+    if (closedBecause(bctx, abs)) continue;
+    out.push({ path: name, name, size: st.size, circle: circleOf(bctx, abs), text: isTextPath(name) && st.size <= MAX_OPEN_BYTES, cloud: false });
+  }
+  return out;
+}
+
+// Append the owner's words to today's daily note, verbatim, under a new timestamped section: the
+// same write evda_write makes (lib/tools.mjs write, lib/day-file.mjs appendToDay), so nothing is
+// ever replaced. Returns { path, bytes, section }.
+export const CAPTURE_CONTEXT = "Typed into the capture box in the EVÐA app.";
+export function capture(evda, words, { now = new Date() } = {}) {
+  return writeToday(evda, { words, context: CAPTURE_CONTEXT }, { now });
+}
+
+// The circle a file at the record's root would land in: the record's default home. The app tags a
+// file with its circle only when it is not this one, so the usual circle is not on every row.
+export function defaultCircle(evda, { bctx = browseContext(evda) } = {}) {
+  return circleOf(bctx, join(evda.dir, "evda-default-home.md"));
+}
+
+// Today's Journal (HQ-2038): today's daily note, always there for the app even before it is
+// written. `exists` false means an empty page; the first capture creates it through `write`.
+// `path` is null only when the record maps no daily role.
+export function today(evda, { now = new Date(), bctx = browseContext(evda) } = {}) {
+  const home = defaultCircle(evda, { bctx });
+  let path;
+  try { path = todayPath(evda, { now }); } catch { return { path: null, exists: false, text: "", circle: home, home }; }
+  const st = reachable(bctx, path);
+  if (!st?.isFile()) return { path, exists: false, text: "", circle: home, home };
+  const opened = openEntry(evda, path, { bctx });
+  return { path, exists: true, text: opened.text, circle: opened.circle, home };
+}
+
+// Every text file the listing shows, the whole record walked one `browse` at a time, plus the
+// operating files at the root (HQ-2049): the app's quick open and its link resolution read this,
+// so a name the tree would not show (noted, sealed, a part no AI reads, tooling, excluded) is never
+// offered or resolved. Paths only, in walk order; nothing of any file's words.
+export function index(evda, { bctx = browseContext(evda) } = {}) {
+  const out = operating(evda, { bctx }).filter((f) => f.text).map((f) => f.path);
+  const walk = (folder) => {
+    const f = browse(evda, folder, { bctx });
+    for (const file of f.files) if (file.text) out.push(file.path);
+    for (const d of f.dirs) walk(d.path);
+  };
+  walk("");
+  return out;
+}
+
+// One listed text file, opened: its words with any sealed section replaced by one line, and its
+// circle. Anything `browse` would not list as text is refused, with nothing of it returned.
+export function openEntry(evda, path, { bctx = browseContext(evda) } = {}) {
+  const rel = cleanRel(path, "a file");
+  const refused = () => new EvdaError(`${path} is not in your record.`, { code: "OUTSIDE", exit: 2 });
+  if (rel === "") throw refused();
+  const st = reachable(bctx, rel);
+  if (!st) throw refused();
+  if (!st.isFile()) throw refused();
+  const name = rel.split("/").pop();
+  if (isTooling(name, st.size) && !(rel === name && isOperating(bctx, name))) throw refused();
+  const abs = join(evda.dir, rel);
+  // A hard path check after the walk: the resolved file is inside the resolved record.
+  const root = realpathSync(evda.dir);
+  if (!realpathSync(abs).startsWith(root + "/")) throw refused();
+  if (!isTextPath(rel)) throw new EvdaError(`${rel} is not text, so it opens in Finder, not here.`, { code: "NOT_TEXT", exit: 2 });
+  if (st.size > MAX_OPEN_BYTES) throw new EvdaError(`${rel} is too large to open here.`, { code: "TOO_LARGE", exit: 2 });
+  if (closedBecause(bctx, abs)) throw refused();
+  const text = readFileSync(abs, "utf8");
+  return { path: rel, text: aiView(text).text, circle: circleOf(bctx, abs) };
+}
+
+// ─── Attachments: PDFs, images and every other file the tree lists (HQ-2071) ───────────────────
+//
+// The app shows a PDF or an image itself and hands any other attachment to the Mac's default app.
+// What it may show is what `browse` lists and `openEntry` would not open as text: the same walk,
+// the same closed rules, decided from names and stat alone, so asking never downloads a file iCloud
+// holds only in the cloud. The app serves the bytes itself, only for a path this answered.
+
+const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "heic", "heif", "gif", "webp"]);
+
+// "pdf", "image", or "other", by the name alone.
+export function attachmentKind(rel) {
+  const name = String(rel ?? "").split("/").pop() ?? "";
+  const dot = name.lastIndexOf(".");
+  const ext = dot <= 0 ? "" : name.slice(dot + 1).toLowerCase();
+  if (ext === "pdf") return "pdf";
+  if (IMAGE_EXTENSIONS.has(ext)) return "image";
+  return "other";
+}
+
+// One listed file that is not text: its kind, size, circle, and whether its bytes are only in
+// iCloud. Refused, with nothing of it returned, whenever `browse` would not list it.
+export function attachEntry(evda, path, { bctx = browseContext(evda) } = {}) {
+  const rel = cleanRel(path, "a file");
+  const refused = () => new EvdaError(`${path} is not in your record.`, { code: "OUTSIDE", exit: 2 });
+  if (rel === "") throw refused();
+  const st = reachable(bctx, rel);
+  if (!st || !st.isFile()) throw refused();
+  const name = rel.split("/").pop();
+  if (isTooling(name, st.size)) throw refused();
+  const abs = join(evda.dir, rel);
+  const root = realpathSync(evda.dir);
+  if (!realpathSync(abs).startsWith(root + "/")) throw refused();
+  if (isTextPath(rel)) throw new EvdaError(`${rel} is text, so it opens as a note.`, { code: "TEXT", exit: 2 });
+  const cloud = datalessAmong(evda.dir, [rel]).has(rel);
+  if (closedBecause(bctx, abs, { cloud })) throw refused();
+  return { path: rel, kind: attachmentKind(rel), size: st.size, circle: circleOf(bctx, abs), cloud };
+}
+
+// Every listed file that is not text, by path, the whole tree walked as `index` walks it: what a
+// link or an embed to a PDF or an image resolves against. Paths only.
+export function attachments(evda, { bctx = browseContext(evda) } = {}) {
+  const out = [];
+  const walk = (folder) => {
+    const f = browse(evda, folder, { bctx });
+    for (const file of f.files) if (!file.text && !isTextPath(file.path)) out.push(file.path);
+    for (const d of f.dirs) walk(d.path);
+  };
+  walk("");
+  return out;
+}

package/lib/circles.mjs

@@ -552,7 +552,11 @@ export function markdownFiles(root) {
     for (const name of readdirSync(abs).sort()) {
       if (name.startsWith(".") || name === "node_modules") continue;
       const p = join(abs, name);
-      const st = statSync(p);
+      // A dangling symlink (target lives only on another machine, e.g. raw media kept
+      // outside the synced vault) has nothing to stat. It is not markdown content either
+      // way, so skip it rather than let the whole walk crash on one broken pointer.
+      let st;
+      try { st = statSync(p); } catch { continue; }
       if (st.isDirectory()) walk(p);
       else if (st.isFile() && /\.md$/i.test(name)) out.push(p);
     }

package/lib/clients.mjs

@@ -1,13 +1,16 @@
 // How each AI client adds the EVDA MCP server, given the command that starts it. No node: imports,
 // so the EVDA app's webview renders the same text `evda connect` prints (lib/connect.mjs).
 
+import { everyChatLine, CHAT_APPS, GENERIC_WHERE } from "./every-chat.mjs";
+
 export const SERVER_NAME = "evda";
 
 const shellQuote = (s) => (/^[A-Za-z0-9_./:@=+-]+$/.test(s) ? s : `'${String(s).replace(/'/g, "'\\''")}'`);
 const tomlString = (s) => JSON.stringify(s);
 
-// `desktopConfig` is where claude_desktop_config.json lives on this machine, when known.
-export function clientsFor(command, args, { desktopConfig = null } = {}) {
+// `desktopConfig` is where claude_desktop_config.json lives on this machine, when known. `filing` is
+// the owner's answer in evda.json, which picks the form of the every-chat line (HQ-2205).
+export function clientsFor(command, args, { desktopConfig = null, filing = null } = {}) {
   const argv = [command, ...args].map(shellQuote).join(" ");
   return [
     {
@@ -44,5 +47,18 @@ export function clientsFor(command, args, { desktopConfig = null } = {}) {
       text: JSON.stringify({ mcpServers: { [SERVER_NAME]: { type: "stdio", command, args } } }, null, 2),
       file: ".mcp.json",
     },
+    {
+      // Not a way to add the server: the one line a chat app needs in its every-chat setting, because
+      // a chat that never calls an evda tool is reached by nothing else (lib/every-chat.mjs).
+      key: "every-chat",
+      label: "Every chat app (so each chat starts as your agent)",
+      steps: [
+        "Add this line to your chat app's every-chat instructions:",
+        ...Object.values(CHAT_APPS).map((a) => `${a.label}: ${a.where}`),
+        `Any other app: ${GENERIC_WHERE}`,
+      ],
+      text: everyChatLine(filing),
+      file: null,
+    },
   ];
 }

package/lib/connect.mjs

@@ -14,6 +14,7 @@ import { delimiter, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { clientsFor, SERVER_NAME } from "./clients.mjs";
+import { filingOf } from "./day-file.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = resolve(HERE, "..");
@@ -101,7 +102,13 @@ export function desktopConfigPath(platform = process.platform, env = process.env
 // Every client's setup for one record, as data. `text` fields are what a person copies.
 export function clients(recordDir, opts = {}) {
   const { command, args } = serverCommand(recordDir, opts);
-  return clientsFor(command, args, { desktopConfig: desktopConfigPath() });
+  return clientsFor(command, args, { desktopConfig: desktopConfigPath(), filing: opts.filing ?? filingIn(recordDir) });
+}
+
+// The owner's filing answer, for the form of the every-chat line. A record that cannot be read yet
+// (connect run before create-evda finished) gets the "everything" form, the default setup offers.
+function filingIn(recordDir) {
+  try { return filingOf(JSON.parse(readFileSync(join(resolve(recordDir), "evda.json"), "utf8"))); } catch { return null; }
 }
 
 export function connectText(recordDir, opts = {}) {