create-evda 0.1.8 → 0.1.10

package/lib/tools.mjs

@@ -6,7 +6,9 @@
 //
 // Three rules hold for every write, and each has a test in test/tools.test.mjs:
 //   1. Append only. A write adds bytes to the end of a file or creates a new one. No tool takes a
-//      path to write to, and none replaces what is there.
+//      path to write to, and none replaces what is there. The one exception is evda_replace
+//      (HQ-2066), the owner's own edit from their phone: it replaces a note's whole text only when
+//      the note is byte for byte what they read, and is offered to no chat app.
 //   2. Nothing secret-shaped is written. The words are run through the same check that guards a
 //      reference (lib/references.mjs secretShape) and a hit refuses the whole write.
 //   3. Every write says where it landed, as a path relative to the record.
@@ -25,17 +27,28 @@
 // making the circle, and granting anyone anything, stays the owner's explicit yes through
 // `evda grant` or their own hands.
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { hostname } from "node:os";
 import { resolveRole, rolesForLayer, agentsFile } from "./roles.mjs";
-import { mdFiles, fileDate } from "./record.mjs";
-import { readCircles, isSealed } from "./circles.mjs";
+import { mdFiles, fileDate, headings, sectionDigest, headingDate } from "./record.mjs";
+import { splitFence, FENCE_OPEN } from "./agents.mjs";
+import { datalessAmong } from "./sync-rules.mjs";
+import { readCircles, isSealed, frontmatterOf, markdownFiles } from "./circles.mjs";
 import { secretShape } from "./references.mjs";
 import { doctor } from "./doctor.mjs";
-import { readContext, mayRead, heldBack, callerFrom, aiView, note as writeNote, releaseNote, SEALED_WHY } from "./readers.mjs";
+import { readContext, mayRead, heldBack, callerFrom, aiView, note as writeNote, releaseNote, SEALED_WHY, isSealedFile, isNotedFile } from "./readers.mjs";
 import { EvdaError } from "./errors.mjs";
-import { dayRole, appendToDay, CONTEXT_LABEL, localDate, localTime } from "./day-file.mjs";
-import { writeMessage, unseenReplies } from "./messages.mjs";
+import { dayRole, appendToDay, setPointerLine, CONTEXT_LABEL, localDate, localTime } from "./day-file.mjs";
+import { writeMessage, unseenReplies, agentName } from "./messages.mjs";
+import { acknowledge as writeAcknowledgement, readAcknowledged, acknowledgementsFor } from "./acknowledge.mjs";
+import { openEvda, holderOf } from "./manifest.mjs";
+import { toYaml } from "./yaml.mjs";
+import { readEntry } from "./kinds.mjs";
+import { correctionsTarget } from "./corrections.mjs";
+import { slug } from "./migrate-people.mjs";
 
 export { localDate, localTime, CONTEXT_LABEL };
 
@@ -99,12 +112,73 @@ export function operatingLayer(evda, args = {}) {
   const a = agentsFile(evda);
   if (!a) throw new EvdaError('this record maps no "agents" role, so it has no operating layer.', { code: "NO_ROLE" });
   if (isSealed(a.abs)) throw new EvdaError(`REFUSED: ${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, { code: "SEALED", exit: 2 });
-  return { path: a.rel, text: aiView(readFileSync(a.abs, "utf8")).text };
+  const raw = readFileSync(a.abs, "utf8");
+  const found = coreBeside(evda, a, raw);
+  return { path: a.rel, text: aiView(raw).text, core: found.core, coreNote: found.note };
 }
 
-// 2. The last `days` days of the record, newest first, whole files, capped in size. A file is in the
-// window by its date (filename, then a date or created key), the same rule `evda moment` uses.
-export function recent(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
+// The generated core, when the agents file is only the owner layer (HQ-2203). A scaffolded record's
+// AGENTS.md carries the `evda:generated` fence itself, and then there is nothing to add. A record
+// that maps agents to an owner-only file (his: CLAUDE.md) keeps the core in another markdown file
+// in the same folder (his: IRIS.md, built from the vault's template), and Claude Code loads it
+// through its own prompt while a chat app gets only this tool. The rule is the one browse.mjs
+// uses to show operating files: the markdown file beside the agents file that carries the fence.
+// No name is assumed, so an owner who renamed their agent still gets theirs, and the core is read
+// from the record, never from the server's templates. Two candidates are not guessed between:
+// neither is served and the note names them. A sealed or noted file, or one still in the cloud
+// (reading it would start a download), is not a candidate.
+export function coreBeside(evda, agents, agentsText) {
+  try {
+    if (splitFence(agentsText)) return { core: null, note: null };
+  } catch {
+    return { core: null, note: null };
+  }
+  const folder = dirname(agents.abs);
+  let names;
+  try {
+    names = readdirSync(folder).filter((n) => /\.md$/i.test(n) && join(folder, n) !== agents.abs).sort();
+  } catch {
+    return { core: null, note: null };
+  }
+  const cloud = datalessAmong(folder, names);
+  const found = [];
+  for (const n of names) {
+    const abs = join(folder, n);
+    if (cloud.has(n)) continue;
+    let text;
+    try {
+      if (!statSync(abs).isFile()) continue;
+      text = readFileSync(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (!text.includes(FENCE_OPEN) || isSealedFile(abs) || isNotedFile(abs)) continue;
+    let parts;
+    try { parts = splitFence(text); } catch { continue; }
+    if (parts) found.push({ path: rel(evda, abs), text: aiView(parts.generated).text });
+  }
+  if (found.length === 1) return { core: found[0], note: null };
+  if (found.length > 1) return { core: null, note: `${found.map((f) => f.path).join(" and ")} both carry the generated core, so neither was served here. Read the one the owner means with evda_read.` };
+  return { core: null, note: null };
+}
+
+// 2. The last `days` days of the record, newest first, capped in size. A file is in the window by
+// its date (filename, then a date or created key), the same rule `evda moment` uses.
+//
+// Returns each file's headings and, per section, its context line and the opening of the owner's
+// words (HQ-2324), not the whole file (HQ-2163). HQ-2227 had cut it to headings only, after a
+// claude.ai question about deadlines got a relationship capture through a first line; and then a
+// chat started knowing only timestamps (most day-file headings are times), so on 2026-10-07 it
+// missed who a question was about. His call that day: approving the connector with training off
+// settles privacy, so a chat reads the record as the terminal does. Noted and sealed entries still
+// never appear (mayRead and aiView below). The whole text of one file is `evda_read`'s job, by path. `full: true` is
+// not part of the tool's args (onlyKeys refuses it there); it is an internal option for callers in
+// this process, such as the evda://today resource below, that still need one file's whole text.
+//
+// Each file carries what an earlier reader already acknowledged in it (HQ-2060, lib/acknowledge.mjs):
+// this is the one read path every reader uses at session start, so it is where a reader learns that
+// a weighty entry is already handled and it should stay quiet about it.
+export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(), full = false } = {}) {
   onlyKeys("evda_recent", args, ["days"]);
   const days = args.days === undefined ? 3 : Number(args.days);
   if (!Number.isInteger(days) || days < 1 || days > 90) throw new EvdaError("evda_recent days must be a whole number from 1 to 90.", { code: "BAD_ARGUMENT", exit: 2 });
@@ -116,6 +190,7 @@ export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(
   const ctx = readContext(evda);
   const refused = [];
   let sealed = false;
+  const marks = readAcknowledged(evda);
   for (const abs of recordFiles(evda)) {
     const raw = readFileSync(abs, "utf8");
     const date = fileDate(abs, raw);
@@ -124,18 +199,80 @@ export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(
     if (!may.ok) { refused.push(may); continue; }
     const shown = aiView(raw);
     if (shown.sections) sealed = true;
-    files.push({ date, path: rel(evda, abs), text: shown.text });
+    const path = rel(evda, abs);
+    const acknowledged = acknowledgementsFor(path, marks);
+    files.push(full
+      ? { date, path, text: shown.text, acknowledged }
+      : { date, path, headings: headings(shown.text), sections: sectionDigest(shown.text), acknowledged });
   }
   files.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : b.date.localeCompare(a.date)));
   let used = 0;
   const out = [];
   let truncated = 0;
   for (const f of files) {
-    if (used + f.text.length > MAX_READ) { truncated += 1; continue; }
-    used += f.text.length;
+    const weight = full ? f.text.length : f.headings.join("\n").length;
+    if (used + weight > MAX_READ) { truncated += 1; continue; }
+    used += weight;
     out.push(f);
   }
-  return { from, to, files: out, omitted: truncated, refused: refused.filter((r) => r.kind !== "sealed"), heldBack: heldBack(refused, { sealed }) };
+  return {
+    from,
+    to,
+    files: out,
+    omitted: truncated,
+    acknowledged: out.reduce((n, f) => n + f.acknowledged.length, 0),
+    refused: refused.filter((r) => r.kind !== "sealed"),
+    heldBack: heldBack(refused, { sealed }),
+  };
+}
+
+// 2'. The people whose pages gained a dated section in the last `days` days (HQ-2324), newest
+// first: the page's name and path, and those sections with their context and opening. A section is
+// dated by the date its heading names, the way the owner's people pages are kept ("## 2026-10-02,
+// morning: ..."). Pages a reader may not read, and sealed sections, never appear.
+export function recentPeople(evda, { days = 7, now = new Date(), caller = callerFrom(), perPerson = 6 } = {}) {
+  const r = resolveRole(evda, "record/people");
+  if (!r.mapped || !r.exists || !r.isDir) return { from: null, to: null, people: [] };
+  const start = new Date(now);
+  start.setDate(start.getDate() - (days - 1));
+  const from = localDate(start);
+  const to = localDate(now);
+  const ctx = readContext(evda);
+  const people = [];
+  for (const abs of mdFiles(r.abs)) {
+    if (!mayRead(ctx, abs, caller).ok) continue;
+    const shown = aiView(readFileSync(abs, "utf8"));
+    const grew = sectionDigest(shown.text)
+      .map((s) => ({ ...s, date: headingDate(s.heading) }))
+      .filter((s) => s.date && s.date >= from && s.date <= to)
+      .sort((a, b) => b.date.localeCompare(a.date));
+    if (!grew.length) continue;
+    const name = /^name:\s*["']?(.+?)["']?\s*$/m.exec(frontmatterText(shown.text))?.[1] ?? abs.split(sep).pop().replace(/\.md$/, "");
+    people.push({ name, path: rel(evda, abs), latest: grew[0].date, sections: grew.slice(0, perPerson), more: Math.max(0, grew.length - perPerson) });
+  }
+  people.sort((a, b) => (a.latest === b.latest ? a.name.localeCompare(b.name) : b.latest.localeCompare(a.latest)));
+  return { from, to, people };
+}
+
+function frontmatterText(text) {
+  if (!text.startsWith("---")) return "";
+  const end = text.indexOf("\n---", 3);
+  return end === -1 ? "" : text.slice(3, end);
+}
+
+// 2a. Record that this reader acted on one weighty entry, so no other reader acts on it again
+// (HQ-2060). The first reader to reach it writes the mark; a later one gets first: false and nothing
+// is written. Weight is the reader's judgment; this only remembers that one of them already did it.
+export function acknowledgeEntry(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_acknowledge", args, ["path", "section", "note", "by"], "It writes one mark beside the record and nothing else: it never edits the entry, and it never writes over a mark another reader left.");
+  return writeAcknowledgement(evda, args, { now });
+}
+
+// 2b. Every mark the record holds, for a reader that wants them without the files.
+export function acknowledgements(evda, args = {}) {
+  onlyKeys("evda_acknowledgements", args, []);
+  const all = readAcknowledged(evda);
+  return { count: Object.keys(all).length, marks: Object.entries(all).map(([key, m]) => ({ key, ...m })) };
 }
 
 // Every markdown file the record holds: each record-layer role, and the imports folder. Not the
@@ -155,6 +292,12 @@ function recordFiles(evda) {
   return out;
 }
 
+// Today's daily file, relative to the record, whether or not it exists yet: the one `write` appends
+// to. The app's Today's Journal (HQ-2038) shows it, and an empty page when it is not written yet.
+export function todayPath(evda, { now = new Date() } = {}) {
+  return rel(evda, join(dailyDir(evda).abs, `${localDate(now)}.md`));
+}
+
 // 3. Append the owner's words, verbatim, to today's daily file. Creates the file with a date heading
 // when it is the first write of the day. Returns the path.
 // `context` (HQ-1377) is one line on what the conversation was about, in the agent's words, written
@@ -162,25 +305,179 @@ function recordFiles(evda) {
 // `session` (HQ-1385) is the conversation: its first write opens `## HH:MM` with the context line,
 // and later writes append under it (lib/day-file.mjs, the one append path).
 export const CONTEXT_MAX = 240;
-export function write(evda, args = {}, { now = new Date(), session = null } = {}) {
-  onlyKeys("evda_write", args, ["words", "context"], "It appends to today's daily file and nothing else: it takes no path, and it never replaces or edits what is already written.");
-  const words = text(args.words, "words", "evda_write");
-  refuseSecrets(words, "evda_write");
+// `toolName` (HQ-2164) is what an error names itself as: evda_write when called directly, or
+// another tool's own name when it reuses this same append-only logic against a different day
+// file (evda_write_agent_log, against Iris's own sub-record). The behavior is identical either
+// way; only what a refusal calls itself changes.
+export function write(evda, args = {}, { now = new Date(), session = null, toolName = "evda_write" } = {}) {
+  onlyKeys(toolName, args, ["words", "context"], "It appends to today's daily file and nothing else: it takes no path, and it never replaces or edits what is already written.");
+  const words = text(args.words, "words", toolName);
+  refuseSecrets(words, toolName);
   let context = null;
   if (args.context !== undefined) {
-    if (typeof args.context !== "string" || args.context.trim() === "") throw refuse(`evda_write "context" is one line on what the conversation was about; leave it out rather than send it empty.`, "EMPTY");
-    if (/\n/.test(args.context.trim())) throw refuse(`evda_write "context" is one line. Their words go in "words"; the context is a single line on what the conversation was about.`, "CONTEXT_LINES");
-    if (args.context.trim().length > CONTEXT_MAX) throw refuse(`evda_write "context" is ${args.context.trim().length} characters; one line of context is at most ${CONTEXT_MAX}.`, "TOO_LONG");
-    refuseSecrets(args.context, "evda_write");
+    if (typeof args.context !== "string" || args.context.trim() === "") throw refuse(`${toolName} "context" is one line on what the conversation was about; leave it out rather than send it empty.`, "EMPTY");
+    if (/\n/.test(args.context.trim())) throw refuse(`${toolName} "context" is one line. Their words go in "words"; the context is a single line on what the conversation was about.`, "CONTEXT_LINES");
+    if (args.context.trim().length > CONTEXT_MAX) throw refuse(`${toolName} "context" is ${args.context.trim().length} characters; one line of context is at most ${CONTEXT_MAX}.`, "TOO_LONG");
+    refuseSecrets(args.context, toolName);
     context = args.context.trim();
   }
-  const r = dailyDir(evda);
-  mkdirSync(r.abs, { recursive: true });
-  const abs = join(r.abs, `${localDate(now)}.md`);
+  const abs = join(evda.dir, todayPath(evda, { now }));
+  mkdirSync(dirname(abs), { recursive: true });
+  // The owner's day only: evda_write, and the tools that file the owner's message along with them.
+  // The agent log is the agent's own record, which nothing drains from an outbox.
+  if (toolName !== "evda_write_agent_log") {
+    const held = dayWriteHeld(abs);
+    if (held !== null) {
+      const q = queueToOutbox(abs, { now, words, context });
+      return { path: rel(evda, q), bytes: Buffer.byteLength(words), queued: true, held };
+    }
+  }
   const w = appendToDay(abs, { now, words, context, session });
   return { path: rel(evda, abs), bytes: Buffer.byteLength(words), section: w.opened ? "opened" : "continued" };
 }
 
+// EVDA_DAY_WRITE_GATE (HQ-2596): a command the writing machine asks before an evda_write touches
+// the owner's day, run as `<gate> --file <abs>`; exit 0 writes, anything else holds. Hestia sets it
+// to its own check (not within minutes of a boot, iCloud says its copy is current), because on
+// 2026-10-14 it came back from an outage and appended to its pre-outage copy within two minutes,
+// and the sync kept that copy over sections written meanwhile. Unset, every write goes ahead.
+// Returns null to write, or the gate's one-line reason to hold. A gate that cannot run holds:
+// a queued write waits, a write onto a stale copy is lost.
+export const DAY_WRITE_GATE_ENV = "EVDA_DAY_WRITE_GATE";
+function dayWriteHeld(abs) {
+  const gate = (process.env[DAY_WRITE_GATE_ENV] ?? "").trim();
+  if (!gate) return null;
+  const r = spawnSync(gate, ["--file", abs], { encoding: "utf8", timeout: 60_000 });
+  if (r.status === 0) return null;
+  const said = `${r.stdout ?? ""}\n${r.stderr ?? ""}`.trim().split("\n").filter(Boolean).pop();
+  return said || (r.error ? `the gate did not run (${r.error.code ?? r.error.message})` : `the gate exited ${r.status ?? r.signal}`);
+}
+
+// Queue held words where the writer files them later (HQ-2596): one new JSON file per write in the
+// daily folder's .outbox/, {tool, words, context, at, host}, named `<UTC timestamp>-<host>-evda_write.json`
+// (the shape the day-writer guard's refusal names, lib/day-writer.mjs OUTBOX_DIR). One file per write,
+// so no two writers ever share one and no sync can drop either. Returns the file's absolute path.
+function queueToOutbox(abs, { now, words, context }) {
+  const box = join(dirname(abs), ".outbox");
+  mkdirSync(box, { recursive: true });
+  const at = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  const host = hostname().split(".")[0] || "host";
+  const stamp = at.replace(/[-:]/g, "").replace(/^(\d{8})T/, (_, d) => `${d.slice(0, 4)}-${d.slice(4, 6)}-${d.slice(6)}T`);
+  let file = join(box, `${stamp}-${host}-evda_write.json`);
+  for (let n = 2; existsSync(file); n++) file = join(box, `${stamp}-${host}-evda_write-${n}.json`);
+  writeFileSync(file, JSON.stringify({ tool: "evda_write", words: String(words), context: context ?? "", at, host }, null, 1), { flag: "wx" });
+  return file;
+}
+
+// 3b. What `evda mcp`'s evda_write tool actually calls (HQ-2165). `write` above already appended
+// the words; this reads them back after a short real delay and refuses to report success if they
+// are gone, so a caller that overwrote the file in that gap is caught instead of the agent telling
+// the owner "Filed" about words that are no longer there (the night of 2026-10-03: the connector's
+// evda_write reported Filed at 03:40:46Z and the owner's words were gone by the time anyone looked).
+//
+// What this catches: a same-host writer (Hestia's journal-append.mjs doing a read-modify-write of
+// the whole file) that lands in the window between this function's append and its own read-back.
+// What this CANNOT catch: two different machines' local replicas of this file diverging and iCloud
+// picking one wholesale, which can resolve on any timescale and is not bounded by a short delay.
+// That class is why every writer but one host must stop touching this file's local copy at all --
+// see test/single-writer.test.mjs. This is a backstop for the class it can catch, not the fix for
+// the class that caused the incident; HQ-2165's "Done when" is the single-writer change, not this.
+const VERIFY_DELAY_MS = 400;
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+export async function writeVerified(evda, args = {}, { verifyDelayMs = VERIFY_DELAY_MS, ...rest } = {}) {
+  const r = write(evda, args, rest);
+  if (r.queued) return r;  // queued, not written: nothing in the day to read back
+  const abs = join(evda.dir, r.path);
+  if (verifyDelayMs > 0) await sleep(verifyDelayMs);
+  const expect = String(args.words).replace(/\n+$/, "");
+  const after = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+  if (!after.includes(expect)) {
+    throw new EvdaError(
+      `evda_write: ${r.path} was written, then read back after ${verifyDelayMs}ms and the words were gone -- `
+      + "another writer overwrote the file in between. Tell the owner the write FAILED; never say \"Filed\" "
+      + "about this call.",
+      { code: "LOST_WRITE", exit: 1 },
+    );
+  }
+  return r;
+}
+
+// 3a. Append one dated correction to AGENTS.md's "What I have been taught" (HQ-1997). That section
+// is always outside the installer's fence (Spec 05 ruling 2, lib/agents.mjs splitFence), so a write
+// here never touches the generated block and survives `evda upgrade` untouched, the same way any
+// other owner edit below the fence does. Append only: an earlier entry is never edited or removed;
+// a correction that reverses one is a new entry with "supersedes" naming the date of the one it
+// replaces, exactly as the section's own instructions ask.
+const CHANGE_MAX = 400;
+const WORDS_MAX = 400;
+const TITLE_MAX = 160;
+// HQ-2325: when evda.json names a "corrections" file (lib/corrections.mjs), the correction is a
+// dated section at the end of that file instead: `## YYYY-MM-DD: <title>` and one paragraph, the
+// owner's words quoted and then what changes, the shape the owner's own log already uses. The
+// setting wins over the heading, and a setting that does not resolve refuses rather than falling
+// back, so a correction never lands somewhere the owner did not choose. Append only, either way.
+export function recordCorrection(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
+  onlyKeys("evda_record_correction", args, ["words", "change", "supersedes", "title"], "It appends one dated correction where this record keeps them and nothing else: it takes no path, and it never edits or replaces an earlier entry.");
+  if (typeof args.change !== "string" || args.change.trim() === "") throw refuse('evda_record_correction needs "change": what you do differently now, one line.', "NO_CHANGE");
+  const change = args.change.trim();
+  if (/\n/.test(change)) throw refuse('evda_record_correction "change" is one line.', "MULTILINE");
+  if (change.length > CHANGE_MAX) throw refuse(`evda_record_correction "change" is ${change.length} characters; at most ${CHANGE_MAX}.`, "TOO_LONG");
+  refuseSecrets(change, "evda_record_correction");
+  let words = null;
+  if (args.words !== undefined) {
+    if (typeof args.words !== "string" || args.words.trim() === "") throw refuse('evda_record_correction "words" is the owner\'s exact words; leave it out rather than send it empty.', "EMPTY");
+    words = args.words.trim();
+    if (/\n/.test(words)) throw refuse('evda_record_correction "words" is one line.', "MULTILINE");
+    if (words.length > WORDS_MAX) throw refuse(`evda_record_correction "words" is ${words.length} characters; at most ${WORDS_MAX}.`, "TOO_LONG");
+    refuseSecrets(words, "evda_record_correction");
+  }
+  let title = null;
+  if (args.title !== undefined) {
+    if (typeof args.title !== "string" || args.title.trim() === "") throw refuse('evda_record_correction "title" names what went wrong in a few words; leave it out rather than send it empty.', "EMPTY");
+    title = args.title.trim();
+    if (/\n/.test(title)) throw refuse('evda_record_correction "title" is one line.', "MULTILINE");
+    if (title.length > TITLE_MAX) throw refuse(`evda_record_correction "title" is ${title.length} characters; at most ${TITLE_MAX}.`, "TOO_LONG");
+    refuseSecrets(title, "evda_record_correction");
+  }
+  let supersedes = null;
+  if (args.supersedes !== undefined) {
+    if (typeof args.supersedes !== "string" || !DATE.test(args.supersedes.trim())) throw refuse('evda_record_correction "supersedes" must be YYYY-MM-DD, the date of the earlier entry this one reverses.', "BAD_DATE");
+    supersedes = args.supersedes.trim();
+  }
+  const date = localDate(now);
+  const said = words ? `"${words}" -> ` : "";
+  const supersededNote = supersedes ? ` Supersedes ${supersedes}.` : "";
+
+  const target = correctionsTarget(evda);
+  if (target) {
+    if (target.problem) throw refuse(`evda.json ${target.problem.replace(/^"corrections"/, 'sets "corrections", but it')} Ask the owner where corrections go.`, "NO_TARGET");
+    const may = mayRead(readContext(evda), target.abs, caller);
+    if (!may.ok) throw refuse(`${may.why} It is not yours to add to.`, may.kind === "sealed" ? "SEALED" : may.kind === "noted" ? "NOTED" : "NOT_THIS_READER");
+    const raw = readFileSync(target.abs, "utf8");
+    const heading = `## ${date}: ${title ?? change}`;
+    const body = (title ? [words ? `"${words}" → ${change}` : change, supersedes ? `Supersedes ${supersedes}.` : ""] : [words ? `"${words}"` : "", supersedes ? `Supersedes ${supersedes}.` : ""]).filter(Boolean).join(" ");
+    const lead = raw === "" ? "" : raw.endsWith("\n\n") ? "" : raw.endsWith("\n") ? "\n" : "\n\n";
+    appendFileSync(target.abs, `${lead}${heading}\n${body ? `\n${body}\n` : ""}`);
+    return { path: target.rel, date, section: heading.slice(3) };
+  }
+
+  const a = agentsFile(evda);
+  if (!a) throw refuse('this record maps no "agents" role and evda.json sets no "corrections" file, so a correction has nowhere to land.', "NO_ROLE");
+  if (isSealed(a.abs)) throw refuse(`${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, "SEALED");
+  const raw = readFileSync(a.abs, "utf8");
+  const parts = splitFence(raw);
+  const owner = parts ? parts.after : raw;
+  if (!/(^|\n)## What I have been taught(\n|$)/.test(owner)) {
+    throw refuse(`${a.rel} has no "## What I have been taught" section outside the generated block, and evda.json sets no "corrections" file, so a correction has nowhere to land. Add that heading (templates/AGENTS.md has the wording), or name the file the owner keeps corrections in as "corrections" in evda.json; evda doctor names this too.`, "NO_SECTION");
+  }
+  const line = `- ${date}: ${title ? `${title}. ` : ""}${said}${change}${supersededNote}\n`;
+  const lineSep = owner.endsWith("\n") ? "" : "\n";
+  const newOwner = owner + lineSep + line;
+  const newRaw = parts ? parts.before + parts.generated + newOwner : newOwner;
+  writeFileSync(a.abs, newRaw);
+  return { path: a.rel, date, section: "What I have been taught" };
+}
+
 // The day file for a date, as { abs, rel }, for writers that are not evda_write (the chat-export
 // backstop in `evda gather`). Throws when the record maps no day role.
 export function dayFile(evda, date) {
@@ -188,6 +485,661 @@ export function dayFile(evda, date) {
   return { abs: join(r.abs, `${date}.md`), rel: rel(evda, join(r.abs, `${date}.md`)), dir: r.abs };
 }
 
+// 3b. Iris's own day log (HQ-2164): a fixed, named sub-record, exactly like AGENTS.md's "What I
+// have been taught" is a fixed, named section. Not a general path: this is the one place
+// evda_write_agent_log is ever allowed to write, and it is reused unchanged from `write` above
+// against that sub-record's own evda.json, so a section there opens and continues by the same
+// one-conversation rule as the owner's own daily file.
+const AGENT_LOG_REL = "01_Projects/Evda/Iris - Universal Thinking Partner/memory";
+function agentLogRecord(evda) {
+  const abs = join(evda.dir, AGENT_LOG_REL);
+  if (!existsSync(join(abs, "evda.json"))) {
+    throw refuse(`${AGENT_LOG_REL} has no evda.json, so there is no agent log sub-record to write into.`, "NO_ROLE");
+  }
+  return openEvda(abs);
+}
+
+// Whether this record has the agent log sub-record. A chat app is offered evda_write_agent_log only
+// when it does (HQ-2164), so a chat is never handed a tool that can only refuse.
+export function hasAgentLog(evda) {
+  return existsSync(join(evda.dir, AGENT_LOG_REL, "evda.json"));
+}
+
+// HQ-2306: the same call keeps the one pointer line in the owner's day, under `## <Agent>`:
+//   Iris: <one fragment per conversation>. [[<agent log day, no .md>|Iris's log for the day]]
+// the shape Hestia's journal-append.mjs writes for its own agents, so the vault's journal:check
+// reads both the same. Only the writing machine may touch the owner's day (HQ-2165), and this is the
+// tool a laptop session reaches it through. The agent log is already on disk when the pointer is
+// written, so a failed pointer is reported in the result, never thrown: a retry would log twice.
+export function writeAgentLog(evda, args = {}, { now = new Date(), session = null } = {}) {
+  const sub = agentLogRecord(evda);
+  const r = write(sub, args, { now, session, toolName: "evda_write_agent_log" });
+  const path = `${AGENT_LOG_REL}/${r.path}`;
+  return { path, bytes: r.bytes, section: r.section, pointer: writeAgentPointer(evda, path, { now }) };
+}
+
+const POINTER_FRAGMENT_MAX = 100;
+const POINTER_FRAGMENTS_MAX = 6;
+
+// The fragments of the pointer line, built from the whole of the agent's day log every time so the
+// line is a function of the log: refreshing it never drifts or duplicates. One per section (one per
+// conversation): the first sentence of its first line that is not the context line.
+export function agentLogFragments(logText) {
+  const frags = [];
+  for (const section of String(logText).split(/^## .*$/m).slice(1)) {
+    const first = section.split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith(`*${CONTEXT_LABEL}`));
+    if (!first) continue;
+    const sentence = first.split(/(?<=[.!?])\s+/)[0].replace(/\.\s*$/, "").trim();
+    frags.push(sentence.length > POINTER_FRAGMENT_MAX ? `${sentence.slice(0, POINTER_FRAGMENT_MAX - 3).trimEnd()}…` : sentence);
+  }
+  if (frags.length > POINTER_FRAGMENTS_MAX) {
+    const shown = frags.slice(0, POINTER_FRAGMENTS_MAX - 1);
+    return [...shown, `and ${frags.length - shown.length} more`];
+  }
+  return frags.length ? frags : ["see the log"];
+}
+
+function writeAgentPointer(evda, logPath, { now }) {
+  const date = localDate(now);
+  const day = join(evda.dir, todayPath(evda, { now }));
+  const at = rel(evda, day);
+  try {
+    if (existsSync(day) && isSealed(day)) return { path: at, state: "sealed" };
+    const agent = agentName(evda);
+    const link = `[[${logPath.replace(/\.md$/, "")}|${agent}'s log for the day]]`;
+    // Only what any AI reader of the log may see is quoted: a sealed section is cut, and a sealed or
+    // just-noted log gives no fragment at all, so the pointer never carries held words into the day.
+    const logAbs = join(evda.dir, logPath);
+    const held = isSealed(logAbs) || isNotedFile(logAbs);
+    const frags = held ? ["see the log"] : agentLogFragments(aiView(readFileSync(logAbs, "utf8")).text);
+    const line = `${agent}: ${frags.join("; ")}. ${link}`;
+    mkdirSync(dirname(day), { recursive: true });
+    return { path: at, state: setPointerLine(day, { date, heading: `## ${agent}`, prefix: `${agent}: `, line }) };
+  } catch (e) {
+    return { path: at, state: "failed", error: e.message };
+  }
+}
+
+// 3c. Append one dated section to an EXISTING person page (HQ-2164), in the evda_record_correction
+// shape: one named target class (record/people), resolved by name rather than by path, and append
+// only. Never creates a page (CLAUDE.md: "Only docs that already exist. Do not auto-create a new
+// profile mid-conversation; offer it."); refuses a sealed page, and refuses when the name matches
+// more than one page rather than guessing. When the page's frontmatter is `kind: person-profile`,
+// the new section also gets a matching `observations` entry (CLAUDE.md / doctor's HQ-1397 rule:
+// "A People doc with kind: person-profile frontmatter gets an observation for each new dated
+// section"), so this write can never silently leave a profile failing that check. Everything else
+// in the file, including the rest of the frontmatter, is byte for byte what it was.
+const PERSON_CONTEXT_MAX = CONTEXT_MAX;
+function peopleDir(evda) {
+  const r = resolveRole(evda, "record/people");
+  if (!r.mapped) throw refuse('this record maps no "record/people" role, so it has no person pages to write into.', "NO_ROLE");
+  if (!r.exists || !r.isDir) throw refuse(`${r.rel} is mapped as "record/people" but is not a folder.`, "NO_ROLE");
+  return r;
+}
+
+// HQ-2696: the pages that are a person's, wherever they live in the record. A person's page is any
+// page whose frontmatter kind is a person kind, anywhere in the record, plus any page directly in the
+// folder the record/people role maps to (a plain page there predates the frontmatter). Reading only
+// the people folder made a page in a Family/ folder beside it invisible (2026-10-16): the agent was
+// told there was no page, and evda_create would have made a second one. A family member is a person,
+// so no folder is special-cased. Only a file's head is read, so a walk of a large record stays cheap.
+export const PERSON_KINDS = ["person-profile", "person"];
+const PERSON_HEAD = 8192;
+const PERSON_KIND_LINE = new RegExp(`^kind:[ \\t]*["']?(?:${PERSON_KINDS.join("|")})["']?[ \\t]*$`, "m");
+function headOf(abs) {
+  let fd;
+  try {
+    fd = openSync(abs, "r");
+    const buf = Buffer.alloc(PERSON_HEAD);
+    return buf.toString("utf8", 0, readSync(fd, buf, 0, PERSON_HEAD, 0));
+  } catch { return ""; } finally { if (fd !== undefined) closeSync(fd); }
+}
+function frontOfPersonHead(abs) {
+  let text = headOf(abs);
+  if (!text.startsWith("---\n")) return null;
+  const close = text.indexOf("\n---", 3);
+  if (close === -1) { try { text = readFileSync(abs, "utf8"); } catch { return null; } }
+  else if (!PERSON_KIND_LINE.test(text.slice(0, close))) return null;
+  return frontmatterOf(text);
+}
+
+const normName = (s) => String(s).trim().toLowerCase().replace(/\s+/g, " ");
+const withoutParen = (s) => s.replace(/\s*\([^)]*\)\s*$/, "").trim();
+// The names one person page answers to: its filename, its name:, each alias, and each of those
+// without a trailing parenthetical ("John Veson (Dad / JV)" answers to "john veson" too).
+function personNames(abs, front) {
+  const out = new Set();
+  const add = (v) => {
+    if (typeof v !== "string" || !v.trim()) return;
+    const n = normName(v);
+    out.add(n);
+    const bare = withoutParen(n);
+    if (bare) out.add(bare);
+  };
+  add(abs.split(sep).pop().replace(/\.md$/i, ""));
+  if (front) {
+    add(front.name);
+    const al = front.aliases ?? front.alias;
+    for (const a of Array.isArray(al) ? al : [al]) add(a);
+  }
+  return out;
+}
+
+// Every person page in the record: { abs, names }.
+export function personPages(evda) {
+  const people = resolveRole(evda, "record/people");
+  const peopleAbs = people.mapped && people.exists && people.isDir ? people.abs : null;
+  const out = [];
+  for (const abs of markdownFiles(evda.dir)) {
+    const name = abs.split(sep).pop();
+    if (/^readme\.md$/i.test(name)) continue;
+    const inPeople = peopleAbs !== null && dirname(abs) === peopleAbs;
+    const front = frontOfPersonHead(abs);
+    const isPerson = front !== null && PERSON_KINDS.includes(front.kind);
+    if (!inPeople && !isPerson) continue;
+    out.push({ abs, names: personNames(abs, isPerson ? front : null) });
+  }
+  return out;
+}
+
+// The person pages a name points at: every page one of whose names equals it, case-insensitively;
+// only when none does, every page whose filename starts with it (the older shorthand, "Sam" for
+// "Sam Lee"). Returns absolute paths; more than one is ambiguous and the caller says so.
+export function findPersonPages(evda, name) {
+  const want = normName(name);
+  const bare = withoutParen(want);
+  const pages = personPages(evda);
+  const exact = pages.filter((p) => p.names.has(want) || (bare && p.names.has(bare)));
+  if (exact.length) return exact.map((p) => p.abs);
+  return pages.filter((p) => normName(p.abs.split(sep).pop().replace(/\.md$/i, "")).startsWith(want)).map((p) => p.abs);
+}
+
+export function recordPersonNote(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
+  onlyKeys("evda_record_person_note", args, ["person", "context", "words"], "It appends one dated section to an existing person page and nothing else: it takes no path, it never creates a page, and it never edits or removes an earlier section.");
+  if (typeof args.person !== "string" || args.person.trim() === "") throw refuse('evda_record_person_note needs "person": the name on their page.', "NO_PERSON");
+  if (typeof args.context !== "string" || args.context.trim() === "") throw refuse('evda_record_person_note needs "context": one line on what this section is.', "NO_CONTEXT");
+  const context = args.context.trim();
+  if (/\n/.test(context)) throw refuse('evda_record_person_note "context" is one line.', "MULTILINE");
+  if (context.length > PERSON_CONTEXT_MAX) throw refuse(`evda_record_person_note "context" is ${context.length} characters; at most ${PERSON_CONTEXT_MAX}.`, "TOO_LONG");
+  refuseSecrets(context, "evda_record_person_note");
+  const words = text(args.words, "words", "evda_record_person_note");
+  refuseSecrets(words, "evda_record_person_note");
+
+  const matches = findPersonPages(evda, args.person);
+  if (matches.length === 0) throw refuse(`no page for "${args.person.trim()}" anywhere in the record (a person's page is one with kind: person-profile frontmatter, or any page in the people folder). This tool never creates one: offer in one line to start their page, and on their yes make it with evda_create (kind "person").`, "MISSING");
+  if (matches.length > 1) throw refuse(`"${args.person.trim()}" matches more than one page (${matches.map((m) => rel(evda, m)).join(", ")}). Say which one.`, "AMBIGUOUS");
+
+  const abs = matches[0];
+  if (isSealed(abs)) throw refuse(`${rel(evda, abs)} ${SEALED_WHY.replace(/^It /, "is ")}`, "SEALED");
+  const may = mayRead(readContext(evda), abs, caller);
+  if (!may.ok) throw refuse(may.why, may.kind === "noted" ? "NOTED" : "READER");
+
+  const raw = readFileSync(abs, "utf8");
+  const date = localDate(now);
+  const heading = `## ${context} (added ${date})`;
+  const lead = raw.endsWith("\n") ? "" : "\n";
+  const section = `${lead}\n${heading}\n\n${words.trim()}\n`;
+
+  const fm = frontmatterOf(raw);
+  let newRaw = raw + section;
+  let observationId = null;
+  if (fm && fm.kind === "person-profile") {
+    const lines = raw.split("\n");
+    const end = lines.indexOf("---", 1);
+    const body = lines.slice(end + 1).join("\n");
+    const obs = Array.isArray(fm.observations) ? fm.observations : [];
+    const stamp = `${date}-${localTime(now).replace(":", "")}`;
+    const ids = new Set(obs.map((o) => o.id));
+    let id = stamp;
+    for (let n = 2; ids.has(id); n++) id = `${stamp}-${n}`;
+    const observation = { id, since: date, text: context };
+    const nextFm = { ...fm, observations: [...obs, observation] };
+    const owner = holderOf(evda).id ?? holderOf(evda).name;
+    const before = readEntry("person-profile", fm, { owner });
+    const after = readEntry("person-profile", nextFm, { owner });
+    const introduced = after.dto === null ? [after.problems[0]] : after.problems.filter((p) => !before.problems.includes(p));
+    if (introduced.length) throw refuse(`writing this observation into ${rel(evda, abs)} would leave its frontmatter invalid: ${introduced[0]}`, "BAD_PROFILE");
+    const newFrontmatter = `---\n${toYaml(nextFm)}---\n`;
+    newRaw = newFrontmatter + body + section;
+    observationId = id;
+  }
+  writeFileSync(abs, newRaw);
+  return { path: rel(evda, abs), date, observation: observationId };
+}
+
+// 3d. "Entries grow on their own" (HQ-2228): one dated section on an entry that already exists, by
+// its path. In a chat app this is the only way the core's rule can be carried out, since the
+// connector is the only thing that writes. It never creates a file and never touches a byte already
+// there: the section goes at the end, `## YYYY-MM-DD`, and a second append the same day continues
+// that section instead of opening a second heading for the day. Who may write follows who may read
+// (lib/readers.mjs mayRead): a sealed entry, a noted one and a part read by a different AI are each
+// refused, since the core says those are not the agent's to add to. The files other tools own are
+// refused with the tool that does it: the operating layer, the day's file, a person's page, and the
+// record's own machinery (circles, grants, mounts, messages, the ledger, proposals, anything at the
+// root or in a dot-folder, which is where skills live).
+const APPEND_ELSEWHERE = [
+  ["record/daily", "is the day's file: the owner's words go there with evda_write."],
+  ["record/people", "is a person's page: add to it with evda_record_person_note, which also keeps its observations in step."],
+  ["circles", "is part of how the record is shared, which only the owner changes."],
+  ["grants", "is part of how the record is shared, which only the owner changes."],
+  ["mounts", "is part of how the record is shared, which only the owner changes."],
+  ["messages", "is a message file, which evda_message and the phone write."],
+  ["ledger", "is the hypothesis ledger, which has its own format and tools."],
+];
+// Where an entry-shaped write may land, by path: inside the record, a Markdown file, not the
+// operating layer, not one of the record's own files (the root, a dot-folder, proposals/), not a
+// file another tool owns (APPEND_ELSEWHERE), and readable by this caller (sealed, noted and
+// read_by all refuse, since what the agent may not read is not the agent's to add to). `exists`
+// says whether the path must already hold a file (append) or must hold nothing (create).
+function entryPath(evda, tool, path, caller, { exists = true, folder = false } = {}) {
+  if (typeof path !== "string" || path.trim() === "") throw refuse(`${tool} needs "path": the entry, relative to the record, as evda_search or evda_recent gave it.`, "BAD_ARGUMENT");
+  const want = path.trim();
+  refuseSecrets(want, tool);
+  const abs = resolve(evda.dir, want);
+  if (!abs.startsWith(evda.dir + sep)) throw refuse(`${want} is outside the record.`, "OUTSIDE");
+  const where = rel(evda, abs);
+  if (!folder && !/\.md$/i.test(abs)) throw refuse(`${where} is not a Markdown entry; only a .md entry ${exists ? "grows" : "is started"} here.`, "NOT_AN_ENTRY");
+  if (exists && (!existsSync(abs) || !statSync(abs).isFile())) throw refuse(`no entry is at ${where}. This tool never creates one: say in one line that you can start the page, and on their yes make it with evda_create.`, "MISSING");
+  if (!exists && existsSync(abs)) throw refuse(`${where} already exists. evda_create never overwrites; add to an entry with evda_append.`, "EXISTS");
+  const a = agentsFile(evda);
+  if (a && resolve(a.abs) === abs) throw refuse(`${where} is the operating layer: a correction goes in with evda_record_correction, and a setup answer with evda_setup_answer.`, "NOT_AN_ENTRY");
+  const parts = where.split("/");
+  if ((!folder && parts.length < 2) || parts.some((p) => p.startsWith("."))) throw refuse(`${where} is one of the record's own files, not an entry.`, "NOT_AN_ENTRY");
+  if (parts[0] === PROPOSALS) throw refuse(`${where} is one of the record's own files, not an entry.`, "NOT_AN_ENTRY");
+  for (const [role, why] of APPEND_ELSEWHERE) {
+    const r = resolveRole(evda, role);
+    if (role === "record/people" && !exists && !folder) continue;
+    if (r.mapped && r.abs && (abs === r.abs || abs.startsWith(r.abs + sep) || (folder && r.abs.startsWith(abs + sep)))) throw refuse(`${where} ${why}`, "NOT_AN_ENTRY");
+  }
+  const may = mayRead(readContext(evda), abs, caller);
+  if (!may.ok) throw refuse(`${may.why} It is not yours to add to.`, may.kind === "sealed" ? "SEALED" : may.kind === "noted" ? "NOTED" : "NOT_THIS_READER");
+  return { abs, where };
+}
+
+// Markdown headings outside fenced code, as { level, text, start, end } (end: the offset after its
+// line), so a `#` inside a code block is never read as structure.
+function mdHeadings(raw) {
+  const out = [];
+  let fence = null;
+  let at = 0;
+  for (const line of raw.split("\n")) {
+    const start = at;
+    at += line.length + 1;
+    const f = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (f) {
+      if (!fence) fence = f[1];
+      else if (f[1][0] === fence[0] && f[1].length >= fence.length) fence = null;
+      continue;
+    }
+    if (fence) continue;
+    const h = /^ {0,3}(#{1,6})[ \t]+(.*?)[ \t#]*$/.exec(line);
+    if (h) out.push({ level: h[1].length, text: h[2].trim(), start, end: Math.min(at, raw.length) });
+  }
+  return out;
+}
+
+// The section a heading names: from the end of its heading line to the start of the next heading
+// at its level or above, or the end of the file. Refuses a heading that is missing or matches twice.
+function sectionUnder(raw, under, tool, where) {
+  if (typeof under !== "string" || under.trim() === "") throw refuse(`${tool} "under" is the text of a heading in ${where}, without the #s.`, "BAD_ARGUMENT");
+  const want = under.trim().replace(/^#+\s*/, "").toLowerCase();
+  const hs = mdHeadings(raw);
+  const hits = hs.filter((h) => h.text.toLowerCase() === want);
+  if (hits.length === 0) {
+    const names = hs.filter((h) => h.level <= 3).slice(0, 15).map((h) => JSON.stringify(h.text)).join(", ");
+    throw refuse(`${where} has no heading "${under.trim()}".${names ? ` Its headings include ${names}.` : ""}`, "NO_HEADING");
+  }
+  if (hits.length > 1) throw refuse(`${where} has ${hits.length} headings "${under.trim()}", so which section is meant is not clear. Name a heading that appears once.`, "AMBIGUOUS");
+  const h = hits[0];
+  const next = hs.find((x) => x.start > h.start && x.level <= h.level);
+  return { heading: h, start: h.end, end: next ? next.start : raw.length, inside: hs.filter((x) => x.start > h.start && (!next || x.start < next.start)) };
+}
+
+// Insert `block` (whole lines, ending in "\n") at `at`, so one blank line separates it from what is
+// before and from a heading after. Every byte of raw is kept; the result is before + insert + after.
+function insertAt(raw, at, block) {
+  const before = raw.slice(0, at);
+  const after = raw.slice(at);
+  const lead = before === "" || before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
+  const trail = after === "" ? "" : "\n";
+  const insert = `${lead}${block}${trail}`;
+  return { text: before + insert + after, insert };
+}
+
+const TITLE_LINE_MAX = 160;
+function oneLine(value, name, tool, max = TITLE_LINE_MAX) {
+  if (typeof value !== "string" || value.trim() === "") throw refuse(`${tool} "${name}" is one line of text; leave it out rather than send it empty.`, "EMPTY");
+  const v = value.trim();
+  if (/\n/.test(v)) throw refuse(`${tool} "${name}" is one line.`, "MULTILINE");
+  if (v.length > max) throw refuse(`${tool} "${name}" is ${v.length} characters; at most ${max}.`, "TOO_LONG");
+  refuseSecrets(v, tool);
+  return v;
+}
+
+// HQ-2328: `under` places the section at the end of that heading's section instead of the end of
+// the file, with its heading one level below, so an entry goes into the right part of a file whose
+// last section is "Completed" or an archive. `title` names the section: `<title> (added
+// YYYY-MM-DD)`, the dated-heading shape the record's other entries use; without it the heading is
+// the date alone, and a second append the same day continues it.
+export function appendEntry(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
+  onlyKeys("evda_append", args, ["path", "words", "under", "title"], "It adds one dated section to an entry that already exists and nothing else: it never creates a file and never edits what is there.");
+  const words = text(args.words, "words", "evda_append");
+  refuseSecrets(words, "evda_append");
+  const title = args.title === undefined ? null : oneLine(args.title, "title", "evda_append");
+  const { abs, where } = entryPath(evda, "evda_append", args.path, caller);
+  const raw = readFileSync(abs, "utf8");
+  const fm = frontmatterOf(raw);
+  if (fm && fm.kind === "person-profile") throw refuse(`${where} is a person profile, and each new section there needs an observation: add to it with evda_record_person_note.`, "NOT_AN_ENTRY");
+  const date = localDate(now);
+  const label = title ? `${title} (added ${date})` : date;
+
+  if (args.under !== undefined) {
+    const s = sectionUnder(raw, args.under, "evda_append", where);
+    const level = Math.min(s.heading.level + 1, 6);
+    const heading = `${"#".repeat(level)} ${label}`;
+    const last = s.inside.filter((h) => h.level === level).pop();
+    const continued = !title && last && last.text === label && !s.inside.some((h) => h.start > last.start);
+    const block = continued ? `${words.trim()}\n` : `${heading}\n\n${words.trim()}\n`;
+    const { text: next } = insertAt(raw, s.end, block);
+    writeFileSync(abs, next);
+    return { path: where, date, section: continued ? "continued" : "opened", under: s.heading.text };
+  }
+
+  const heading = `## ${label}`;
+  const lastHeading = [...raw.matchAll(/^## .*$/gm)].pop()?.[0]?.trim();
+  const continued = !title && lastHeading === heading;
+  const lead = raw === "" || raw.endsWith("\n") ? "" : "\n";
+  const add = continued ? `${lead}\n${words.trim()}\n` : `${lead}${raw === "" ? "" : "\n"}${heading}\n\n${words.trim()}\n`;
+  appendFileSync(abs, add);
+  return { path: where, date, section: continued ? "continued" : "opened" };
+}
+
+// The markdown tables in a text, outside fenced code: a header row, a delimiter row, then body rows,
+// every line starting with `|`. { start, end, columns, header } with end the offset after the last row.
+function splitRow(line) {
+  let s = line.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|") && !s.endsWith("\\|")) s = s.slice(0, -1);
+  return s.split(/(?<!\\)\|/).map((c) => c.trim());
+}
+function mdTables(raw) {
+  const lines = raw.split("\n");
+  const offs = [];
+  let at = 0;
+  for (const l of lines) { offs.push(at); at += l.length + 1; }
+  const out = [];
+  let fence = null;
+  const isRow = (l) => /^ {0,3}\|/.test(l);
+  for (let i = 0; i < lines.length; i++) {
+    const f = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
+    if (f) {
+      if (!fence) fence = f[1];
+      else if (f[1][0] === fence[0] && f[1].length >= fence.length) fence = null;
+      continue;
+    }
+    if (fence || !isRow(lines[i]) || i + 1 >= lines.length) continue;
+    if (!/^ {0,3}\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)*\|?\s*$/.test(lines[i + 1])) continue;
+    const header = splitRow(lines[i]);
+    let j = i + 2;
+    while (j < lines.length && isRow(lines[j])) j++;
+    const lastLine = j - 1;
+    out.push({ start: offs[i], end: Math.min(offs[lastLine] + lines[lastLine].length + 1, raw.length), lastEndsFile: lastLine === lines.length - 1, columns: header.length, header });
+    i = j - 1;
+  }
+  return out;
+}
+
+const CELL_MAX = 4000;
+// HQ-2328: one row at the end of a markdown table in an existing entry. A log kept as a table (the
+// food log, a spike log, a weekends board) grows by a row, not by a dated section. The row has to
+// fill the table's columns exactly, so a row is never written into the wrong shape; a file with more
+// than one table needs `under`, the heading whose section holds the one meant. Only the new row's
+// bytes are added: everything before and after it is what it was.
+export function appendRow(evda, args = {}, { caller = callerFrom() } = {}) {
+  onlyKeys("evda_append_row", args, ["path", "cells", "under"], "It adds one row to the end of a table in an entry that already exists and nothing else: it never edits a row that is there.");
+  const { abs, where } = entryPath(evda, "evda_append_row", args.path, caller);
+  if (!Array.isArray(args.cells) || args.cells.length === 0) throw refuse('evda_append_row needs "cells": the new row\'s cells, in the table\'s column order, one string each ("" for an empty cell).', "BAD_ARGUMENT");
+  const cells = args.cells.map((c, i) => {
+    if (typeof c !== "string") throw refuse(`evda_append_row cell ${i + 1} is not text; send each cell as a string, "" when empty.`, "BAD_ARGUMENT");
+    if (/[\r\n]/.test(c)) throw refuse(`evda_append_row cell ${i + 1} has a line break; a table cell is one line.`, "MULTILINE");
+    if (c.length > CELL_MAX) throw refuse(`evda_append_row cell ${i + 1} is ${c.length} characters; at most ${CELL_MAX}.`, "TOO_LONG");
+    refuseSecrets(c, "evda_append_row");
+    return c.trim().replace(/(?<!\\)\|/g, "\\|");
+  });
+  const raw = readFileSync(abs, "utf8");
+  let tables = mdTables(raw);
+  let scope = "";
+  if (args.under !== undefined) {
+    const s = sectionUnder(raw, args.under, "evda_append_row", where);
+    tables = tables.filter((t) => t.start >= s.start && t.start < s.end);
+    scope = ` under "${s.heading.text}"`;
+  }
+  if (tables.length === 0) throw refuse(`${where} has no table${scope}. A row goes into a table that is already there.`, "NO_TABLE");
+  if (tables.length > 1) {
+    const where2 = mdHeadings(raw);
+    const named = tables.map((t) => where2.filter((h) => h.start < t.start).pop()?.text).map((h) => (h ? JSON.stringify(h) : "(before any heading)"));
+    throw refuse(`${where} has ${tables.length} tables${scope}, so which one is meant is not clear. Pass "under" with the heading of the one meant: ${named.join(", ")}.`, "AMBIGUOUS");
+  }
+  const t = tables[0];
+  if (cells.length !== t.columns) throw refuse(`the table in ${where}${scope} has ${t.columns} columns (${t.header.map((h) => JSON.stringify(h)).join(", ")}) and this row has ${cells.length} cells. Send one cell per column, "" for an empty one.`, "COLUMNS");
+  const row = `| ${cells.join(" | ")} |`.replace(/\|  \|/g, "| |").replace(/\|  \|/g, "| |");
+  const insert = t.lastEndsFile && !raw.endsWith("\n") ? `\n${row}` : `${row}\n`;
+  writeFileSync(abs, raw.slice(0, t.end) + insert + raw.slice(t.end));
+  return { path: where, row, columns: t.columns };
+}
+
+// HQ-2333: one line at the end of a list in an existing entry. A board kept as a list (his Weekends
+// board is "- **Oct 9 - 11**: Austin (ACL) · `confirmed`", one line a weekend) grows by an item, and on
+// 10/7 a chat with only evda_append and evda_append_row gave a new weekend its own heading and
+// paragraph instead. The item takes the list's own marker (the next number in a numbered list), so it
+// is written in the list's shape; the line is the caller's, in the format the items around it use.
+const ITEM = /^( {0,3})([-*+]|\d{1,9}[.)])[ \t]+\S/;
+function mdLists(raw) {
+  const lines = raw.split("\n");
+  const offs = [];
+  let at = 0;
+  for (const l of lines) { offs.push(at); at += l.length + 1; }
+  const kind = (m) => (/\d/.test(m) ? `n${m.slice(-1)}` : m);
+  const out = [];
+  let fence = null;
+  for (let i = 0; i < lines.length; i++) {
+    const f = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
+    if (f) {
+      if (!fence) fence = f[1];
+      else if (f[1][0] === fence[0] && f[1].length >= fence.length) fence = null;
+      continue;
+    }
+    const m = fence ? null : ITEM.exec(lines[i]);
+    if (!m) continue;
+    const indent = m[1].length;
+    const k = kind(m[2]);
+    let last = i;
+    let lastMarker = m[2];
+    const items = [{ line: i, text: lines[i].trim(), marker: m[2] }];
+    let j = i + 1;
+    while (j < lines.length) {
+      const l = lines[j];
+      if (/^ {0,3}(`{3,}|~{3,})/.test(l)) break;
+      const n = ITEM.exec(l);
+      if (n && n[1].length === indent && kind(n[2]) === k) { items[items.length - 1].lastLine = last; items.push({ line: j, text: l.trim(), marker: n[2] }); last = j; lastMarker = n[2]; j++; continue; }
+      if (l.trim() !== "" && /^\s/.test(l) && l.search(/\S/) > indent) { last = j; j++; continue; }
+      // A line straight after an item, with no blank between, that starts nothing of its own (a
+      // heading, a fence, a table row, a quote, a rule) belongs to that item: markdown reads it as a
+      // continuation, and so does his editor. His Weekends board has two ("**Oct 31:** Houston ...").
+      if (l.trim() !== "" && j === last + 1 && !/^ {0,3}(#{1,6}(\s|$)|\||>|(\*\s*){3,}$|(-\s*){3,}$|(_\s*){3,}$)/.test(l)) { last = j; j++; continue; }
+      if (l.trim() === "") {
+        let k2 = j;
+        while (k2 < lines.length && lines[k2].trim() === "") k2++;
+        const n2 = k2 < lines.length ? ITEM.exec(lines[k2]) : null;
+        if (n2 && n2[1].length === indent && kind(n2[2]) === k) { j = k2; continue; }
+      }
+      break;
+    }
+    items[items.length - 1].lastLine = last;
+    const endOf = (n) => Math.min(offs[n] + lines[n].length + 1, raw.length);
+    out.push({ start: offs[i], end: endOf(last), lastEndsFile: last === lines.length - 1, indent: m[1], marker: lastMarker, first: lines[i].trim(), items: items.map((x) => ({ text: x.text, marker: x.marker, end: endOf(x.lastLine), endsFile: x.lastLine === lines.length - 1 })) });
+    i = j - 1;
+  }
+  return out;
+}
+
+const ITEM_MAX = 2000;
+export function appendItem(evda, args = {}, { caller = callerFrom() } = {}) {
+  onlyKeys("evda_append_item", args, ["path", "line", "under", "after"], "It adds one item to a list in an entry that already exists and nothing else: it never edits an item that is there.");
+  const { abs, where } = entryPath(evda, "evda_append_item", args.path, caller);
+  if (typeof args.line !== "string" || args.line.trim() === "") throw refuse('evda_append_item needs "line": the new item, one line, in the format the list\'s other items use.', "BAD_ARGUMENT");
+  if (/[\r\n]/.test(args.line.trim())) throw refuse("evda_append_item takes one line; a list item here is one line.", "MULTILINE");
+  const body = args.line.trim().replace(/^([-*+]|\d{1,9}[.)])[ \t]+/, "");
+  if (body.length > ITEM_MAX) throw refuse(`evda_append_item line is ${body.length} characters; at most ${ITEM_MAX}.`, "TOO_LONG");
+  refuseSecrets(body, "evda_append_item");
+  const raw = readFileSync(abs, "utf8");
+  let lists = mdLists(raw);
+  let scope = "";
+  if (args.under !== undefined) {
+    const s = sectionUnder(raw, args.under, "evda_append_item", where);
+    lists = lists.filter((l) => l.start >= s.start && l.start < s.end);
+    scope = ` under "${s.heading.text}"`;
+  }
+  if (lists.length === 0) throw refuse(`${where} has no list${scope}. An item goes into a list that is already there; a new section is evda_append.`, "NO_LIST");
+  if (lists.length > 1) {
+    const hs = mdHeadings(raw);
+    const named = [...new Set(lists.map((l) => hs.filter((h) => h.start < l.start).pop()?.text).map((h) => (h ? JSON.stringify(h) : "(before any heading)")))];
+    throw refuse(`${where} has ${lists.length} lists${scope}, so which one is meant is not clear. Pass "under" with the heading of the one meant${named.length ? `: ${named.join(", ")}` : ""}.`, "AMBIGUOUS");
+  }
+  const l = lists[0];
+  // HQ-2333: a list kept in order (his Weekends board is by date) takes a new item beside the one it
+  // belongs next to, so "after" names an item already there by a piece of its text.
+  let at = l.end;
+  let endsFile = l.lastEndsFile;
+  let marker = /\d/.test(l.marker) ? `${Number(l.marker.slice(0, -1)) + 1}${l.marker.slice(-1)}` : l.marker;
+  if (args.after !== undefined) {
+    if (typeof args.after !== "string" || args.after.trim() === "") throw refuse('evda_append_item "after" is a piece of the text of the item the new one goes right after.', "BAD_ARGUMENT");
+    if (/\d/.test(l.marker)) throw refuse(`the list in ${where}${scope} is numbered, so a new item goes at its end; leave out "after".`, "NUMBERED");
+    const want = args.after.trim().toLowerCase();
+    const hits = l.items.filter((x) => x.text.toLowerCase().includes(want));
+    if (hits.length === 0) throw refuse(`no item in the list in ${where}${scope} contains "${args.after.trim()}". Name a piece of one item's text as it is written there.`, "NO_ITEM");
+    if (hits.length > 1) throw refuse(`${hits.length} items in the list in ${where}${scope} contain "${args.after.trim()}": ${hits.slice(0, 5).map((x) => JSON.stringify(x.text.slice(0, 60))).join(", ")}. Name a piece of text only one of them has.`, "AMBIGUOUS");
+    at = hits[0].end;
+    endsFile = hits[0].endsFile;
+    marker = hits[0].marker;
+  }
+  const item = `${l.indent}${marker} ${body}`;
+  const insert = endsFile && !raw.endsWith("\n") ? `\n${item}` : `${item}\n`;
+  writeFileSync(abs, raw.slice(0, at) + insert + raw.slice(at));
+  return { path: where, item };
+}
+
+// HQ-2331: start a new entry or folder, on the owner's yes. In a chat app the connector is the only
+// thing that writes, so without this an offer to "start a page for X" led nowhere. It creates only
+// where nothing is (an existing path is refused, never overwritten), only inside the record, never
+// in the record's own files or a part that is not this caller's to read, and never more than one
+// level: the folder a page goes in must already be there. A person's page is made in the
+// record/people folder with person-profile frontmatter that doctor reads, and a first section gets
+// its observation, the same shape evda_record_person_note keeps.
+export const CREATE_KINDS = ["page", "person", "folder"];
+const PERSON_NAME_MAX = 120;
+export function createEntry(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
+  onlyKeys("evda_create", args, ["kind", "path", "person", "title", "context", "words", "confirmed"], "It starts one new page, person's page or folder where nothing is, and nothing else: it never overwrites, moves or deletes.");
+  if (!CREATE_KINDS.includes(args.kind)) throw refuse(`evda_create "kind" is one of ${CREATE_KINDS.map((k) => JSON.stringify(k)).join(", ")}.`, "BAD_ARGUMENT");
+  if (args.confirmed !== true) throw refuse("evda_create starts something new in their record only on their yes. Offer it in one line, and pass confirmed: true only once they said yes in this conversation.", "NOT_CONFIRMED");
+  const kind = args.kind;
+  const date = localDate(now);
+  const words = args.words === undefined ? null : text(args.words, "words", "evda_create").trim();
+  if (words) refuseSecrets(words, "evda_create");
+
+  if (kind === "folder") {
+    for (const k of ["person", "title", "context", "words"]) if (args[k] !== undefined) throw refuse(`evda_create kind "folder" makes an empty folder and takes no "${k}"; start a page in it next.`, "BAD_ARGUMENT");
+    const { abs, where } = entryPath(evda, "evda_create", args.path, caller, { exists: false, folder: true });
+    if (!existsSync(dirname(abs)) || !statSync(dirname(abs)).isDirectory()) throw refuse(`${rel(evda, dirname(abs)) || "the record"} is not a folder yet. evda_create makes one level at a time: start the folder above first.`, "NO_PARENT");
+    mkdirSync(abs);
+    return { path: where, kind };
+  }
+
+  if (kind === "person") {
+    if (args.path !== undefined || args.title !== undefined) throw refuse('evda_create kind "person" takes the name as "person", not a path or title: the page goes in the people folder under their name.', "BAD_ARGUMENT");
+    const name = oneLine(args.person ?? "", "person", "evda_create", PERSON_NAME_MAX);
+    if (/[\\/:]/.test(name) || name.startsWith(".") || /^readme$/i.test(name)) throw refuse(`evda_create "person" is a name, as it goes on their page; "${name}" cannot be a file name.`, "BAD_ARGUMENT");
+    if ((args.context === undefined) !== (words === null)) throw refuse('evda_create kind "person" takes "context" and "words" together (the first section and its observation), or neither.', "BAD_ARGUMENT");
+    const context = args.context === undefined ? null : oneLine(args.context, "context", "evda_create", PERSON_CONTEXT_MAX);
+    const dir = peopleDir(evda);
+    const want = normName(name);
+    const same = personPages(evda).filter((p) => p.names.has(want) || p.names.has(withoutParen(want)));
+    if (same.length) throw refuse(`${rel(evda, same[0].abs)} already exists: add to it with evda_record_person_note.`, "EXISTS");
+    const { abs, where } = entryPath(evda, "evda_create", `${dir.rel}/${name}.md`, caller, { exists: false });
+    const owner = holderOf(evda).id ?? holderOf(evda).name;
+    const id = slug(name) || "person";
+    const observations = context ? [{ id: `${date}-${localTime(now).replace(":", "")}`, since: date, text: context }] : [];
+    const fm = { kind: "person-profile", id, schemaVersion: "0.1", name, observations };
+    const problems = readEntry("person-profile", fm, { owner }).problems;
+    if (problems.length) throw refuse(`a person page for "${name}" would not read as a person-profile: ${problems[0]}`, "BAD_PROFILE");
+    const body = `# ${name}\n${context ? `\n## ${context} (added ${date})\n\n${words}\n` : ""}`;
+    writeFileSync(abs, `---\n${toYaml(fm)}---\n\n${body}`, { flag: "wx" });
+    return { path: where, kind, observation: observations[0]?.id ?? null };
+  }
+
+  if (args.person !== undefined || args.context !== undefined) throw refuse('evda_create kind "page" takes "path", "title" and "words"; a person\'s page is kind "person".', "BAD_ARGUMENT");
+  const { abs, where } = entryPath(evda, "evda_create", args.path, caller, { exists: false });
+  const people = resolveRole(evda, "record/people");
+  if (people.mapped && people.abs && abs.startsWith(people.abs + sep)) throw refuse(`${where} is in the people folder: a person's page is kind "person", which writes the frontmatter doctor needs.`, "NOT_AN_ENTRY");
+  if (!existsSync(dirname(abs)) || !statSync(dirname(abs)).isDirectory()) throw refuse(`${rel(evda, dirname(abs))} is not a folder yet. Make it first with evda_create kind "folder", on the same yes.`, "NO_PARENT");
+  const title = args.title === undefined ? where.split("/").pop().replace(/\.md$/i, "") : oneLine(args.title, "title", "evda_create");
+  const content = `# ${title}\n${words ? `\n## ${date}\n\n${words}\n` : ""}`;
+  writeFileSync(abs, content, { flag: "wx" });
+  return { path: where, kind };
+}
+
+// 3e. The owner's setup answers (HQ-2228), into AGENTS.md's "What this EVÐA is", in the
+// evda_record_correction shape: one named section, one named line, and nothing else in the file
+// changes. The core's setup step asks each answer to be written there "in their exact words"; a chat
+// app had no tool to do it. A field is written once, when it is empty: a filled one is the owner's
+// to change, in their own file, so the agent never rewrites what they said.
+export const SETUP_FIELDS = ["Agent name", "Who I am", "What I want this for", "How I want it to talk to me", "The AI I use with it, and its training setting"];
+const SETUP_HEADING = /^## What this EV(?:Ð|D)A is[ \t]*$/m;
+export function setupAnswer(evda, args = {}) {
+  onlyKeys("evda_setup_answer", args, ["field", "words"], "It fills one empty field of \"What this EVÐA is\" and nothing else.");
+  if (!SETUP_FIELDS.includes(args.field)) throw refuse(`evda_setup_answer "field" is one of ${SETUP_FIELDS.map((f) => JSON.stringify(f)).join(", ")}.`, "BAD_FIELD");
+  if (typeof args.words !== "string" || args.words.trim() === "") throw refuse('evda_setup_answer needs "words": the owner\'s answer, exactly as they said it.', "EMPTY");
+  const words = args.words.trim();
+  if (/\n/.test(words)) throw refuse('evda_setup_answer "words" is one line: a field holds one line of their answer.', "MULTILINE");
+  if (words.length > WORDS_MAX) throw refuse(`evda_setup_answer "words" is ${words.length} characters; at most ${WORDS_MAX}.`, "TOO_LONG");
+  refuseSecrets(words, "evda_setup_answer");
+  const a = agentsFile(evda);
+  if (!a) throw refuse('this record maps no "agents" role, so it has no AGENTS.md to write the answer into.', "NO_ROLE");
+  if (isSealed(a.abs)) throw refuse(`${a.rel} ${SEALED_WHY.replace(/^It /, "is ")}`, "SEALED");
+  const raw = readFileSync(a.abs, "utf8");
+  // Only the owner's text: the installer's generated block is never written.
+  const parts = splitFence(raw);
+  const pieces = parts ? [["before", parts.before], ["after", parts.after]] : [["whole", raw]];
+  for (const [name, piece] of pieces) {
+    const h = SETUP_HEADING.exec(piece);
+    if (!h) continue;
+    const start = h.index + h[0].length;
+    const next = piece.slice(start).search(/^## /m);
+    const end = next < 0 ? piece.length : start + next;
+    const section = piece.slice(start, end);
+    const label = args.field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const line = new RegExp(`^- \\*\\*${label}:\\*\\*([ \\t]*)(.*)$`, "m").exec(section);
+    if (!line) throw refuse(`${a.rel}'s "What this EVÐA is" has no "${args.field}" line. Add "- **${args.field}:**" there first (templates/AGENTS.md has the wording).`, "NO_FIELD");
+    if (line[2].trim() !== "") throw refuse(`"${args.field}" already reads: ${line[2].trim()}. A filled field is the owner's to change, in their own file.`, "ALREADY_SET");
+    const at = start + line.index;
+    const newPiece = `${piece.slice(0, at)}- **${args.field}:** ${words}${piece.slice(at + line[0].length)}`;
+    const newRaw = !parts ? newPiece : name === "before" ? newPiece + parts.generated + parts.after : parts.before + parts.generated + newPiece;
+    writeFileSync(a.abs, newRaw);
+    return { path: a.rel, field: args.field };
+  }
+  throw refuse(`${a.rel} has no "## What this EVÐA is" section outside the generated block. Add it first (templates/AGENTS.md has the wording).`, "NO_SECTION");
+}
+
+// Whether setup is unfinished: some field of "What this EVÐA is" is there and empty.
+export function setupPending(agentsText) {
+  const h = SETUP_HEADING.exec(agentsText ?? "");
+  if (!h) return false;
+  const rest = agentsText.slice(h.index + h[0].length);
+  const next = rest.search(/^## /m);
+  const section = next < 0 ? rest : rest.slice(0, next);
+  return SETUP_FIELDS.some((f) => new RegExp(`^- \\*\\*${f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\*\\*[ \\t]*$`, "m").test(section));
+}
+
 // 4. File what another AI said about the owner, verbatim, under imports/, labeled with its source
 // and date. A second import from the same source on the same day is appended to that file.
 export function importText(evda, args = {}, { now = new Date() } = {}) {
@@ -231,8 +1183,7 @@ export function search(evda, args = {}, { caller = callerFrom() } = {}) {
   const files = recordFiles(evda);
   const ledger = resolveRole(evda, "ledger");
   if (ledger.mapped && ledger.fileExists) files.push(ledger.file);
-  const matches = [];
-  let more = 0;
+  const found = [];
   const ctx = readContext(evda);
   const refused = [];
   // Whether any searched file is sealed or holds a sealed section, decided without the query, so
@@ -251,12 +1202,22 @@ export function search(evda, args = {}, { caller = callerFrom() } = {}) {
     const shown = aiView(raw);
     if (shown.sections) sealed = true;
     const body = shown.text;
+    // A line's date (HQ-2324): the date the heading it sits under names, else the file's own date,
+    // so a people page's 10/2 section ranks with 10/2 and not with the page's first line.
+    const own = fileDate(abs, raw) ?? "";
+    let under = null;
     body.split("\n").forEach((line, i) => {
+      const h = /^#{1,6} (.*)$/.exec(line);
+      if (h) under = headingDate(h[1]) ?? (/^#{1,2} /.test(line) ? null : under);
       if (!line.toLowerCase().includes(needle)) return;
-      if (matches.length >= limit) { more += 1; return; }
-      matches.push({ path: rel(evda, abs), line: i + 1, text: line.length > 400 ? `${line.slice(0, 400)}...` : line });
+      found.push({ path: rel(evda, abs), line: i + 1, date: under ?? own, text: line.length > 400 ? `${line.slice(0, 400)}...` : line });
     });
   }
+  // Recent first (HQ-2324): on 2026-10-07 a search for chemistry filled its limit with February
+  // before it reached 10/2. Newest date first; undated lines last; ties keep the record's order.
+  found.sort((a, b) => (a.date === b.date ? 0 : !a.date ? 1 : !b.date ? -1 : b.date.localeCompare(a.date)));
+  const matches = found.slice(0, limit);
+  const more = found.length - matches.length;
   return { query: args.query, searched: files.length, matches, more, refused, heldBack: heldBack(refused, { sealed }) };
 }
 
@@ -274,6 +1235,53 @@ export function readFile(evda, args = {}, { caller = callerFrom() } = {}) {
   return { path: rel(evda, abs), text, truncated: false };
 }
 
+// 5a'. HQ-2066: the owner's own edit of one note, made on their phone, saved only when the note is
+// still what they read. `base` is the SHA-256 (hex) of the text evda_read returned; when the file
+// now hashes to anything else it was changed elsewhere since, and nothing is written, so an edit on
+// the phone never overwrites one made on the computer (the Mac's save safety, HQ-2049). A note
+// evda_read did not return whole (a sealed section cut out, or truncated for size) is refused, since
+// writing back what was shown would drop what was not. The machinery other tools own (the operating
+// layer, circles, grants, mounts, messages, the ledger, proposals, the root and dot-folders) is
+// refused as for evda_append; a note this caller may not read is not its to replace. A line of the
+// new text that was not in the old one is checked for secrets, so a note that already holds a
+// secret-shaped line can still be edited around it.
+export const versionOf = (text) => createHash("sha256").update(String(text), "utf8").digest("hex");
+const REPLACE_MACHINERY = ["circles", "grants", "mounts", "messages", "ledger"];
+export function replaceNote(evda, args = {}, { caller = callerFrom() } = {}) {
+  const tool = "evda_replace";
+  onlyKeys(tool, args, ["path", "text", "base"], "It replaces one note's whole text when the note is unchanged since base, and nothing else.");
+  if (typeof args.text !== "string") throw refuse(`${tool} needs "text", the note's whole new text.`, "BAD_ARGUMENT");
+  if (args.text.length > MAX_READ) throw refuse(`${tool} "text" is ${args.text.length} characters; a note replaced here holds at most ${MAX_READ}.`, "TOO_LONG");
+  if (typeof args.base !== "string" || !/^[0-9a-f]{64}$/i.test(args.base.trim())) throw refuse(`${tool} needs "base", the SHA-256 in hex of the text evda_read returned, so a note changed since is never overwritten.`, "BAD_ARGUMENT");
+  if (typeof args.path !== "string" || args.path.trim() === "") throw refuse(`${tool} needs "path": the note, relative to the record, as evda_read gave it.`, "BAD_ARGUMENT");
+  const want = args.path.trim();
+  const abs = resolve(evda.dir, want);
+  if (!abs.startsWith(evda.dir + sep)) throw refuse(`${want} is outside the record.`, "OUTSIDE");
+  const where = rel(evda, abs);
+  if (!/\.md$/i.test(abs)) throw refuse(`${where} is not a Markdown note; only a .md note is edited here.`, "NOT_AN_ENTRY");
+  if (!existsSync(abs) || !statSync(abs).isFile()) throw refuse(`no note is at ${where}; it may have been moved or deleted since it was read.`, "MISSING");
+  const a = agentsFile(evda);
+  if (a && resolve(a.abs) === abs) throw refuse(`${where} is the operating layer, which is edited on the computer.`, "NOT_AN_ENTRY");
+  const parts = where.split("/");
+  if (parts.length < 2 || parts.some((p) => p.startsWith(".")) || parts[0] === PROPOSALS) throw refuse(`${where} is one of the record's own files, not a note.`, "NOT_AN_ENTRY");
+  for (const role of REPLACE_MACHINERY) {
+    const r = resolveRole(evda, role);
+    if (r.mapped && r.abs && (abs === r.abs || abs.startsWith(r.abs + sep))) throw refuse(`${where} is part of the record's own machinery, not a note.`, "NOT_AN_ENTRY");
+  }
+  const may = mayRead(readContext(evda), abs, caller);
+  if (!may.ok) throw refuse(`${may.why} It is not yours to replace.`, may.kind === "sealed" ? "SEALED" : may.kind === "noted" ? "NOTED" : "NOT_THIS_READER");
+  const raw = readFileSync(abs, "utf8");
+  if (aiView(raw).text !== raw) throw refuse(`${where} has a sealed section, so what was read is not the whole note; edit it on the computer.`, "SEALED");
+  if (raw.length > MAX_READ) throw refuse(`${where} is ${raw.length} characters, more than evda_read returns whole; edit it on the computer.`, "TOO_LONG");
+  if (versionOf(raw) !== args.base.trim().toLowerCase()) throw refuse(`${where} changed since it was read, so this edit would overwrite that change. Read it again and make the edit on what is there now.`, "CHANGED");
+  const old = new Set(raw.split("\n"));
+  refuseSecrets(args.text.split("\n").filter((l) => !old.has(l)).join("\n"), tool);
+  if (aiView(args.text).text !== args.text) throw refuse(`${tool}: the new text opens a sealed section, which is made on the computer.`, "SEALED");
+  if (args.text === raw) return { path: where, changed: false, version: versionOf(raw) };
+  writeFileSync(abs, args.text);
+  return { path: where, changed: true, version: versionOf(args.text) };
+}
+
 // 5b. "Just note this": the owner's words, verbatim, as a noted capture no AI reads. Refuses
 // anything secret-shaped, like every other write.
 export function noteTool(evda, args = {}, { now = new Date() } = {}) {
@@ -298,7 +1306,8 @@ export function releaseTool(evda, args = {}, { now = new Date() } = {}) {
 }
 
 // 5d. Tell the owner something (HQ-1246): one new message file under the messages role, which the
-// phone app shows as a card. Never edits one; refuses anything secret-shaped, like every write.
+// phone app shows as a card once paired and synced -- this call never confirms that part (HQ-2161).
+// Never edits one; refuses anything secret-shaped, like every write.
 export function message(evda, args = {}, { now = new Date() } = {}) {
   onlyKeys("evda_message", args, ["title", "body", "from"], "It writes one new message for the owner and nothing else: it takes no path, and it never edits a message once written.");
   return writeMessage(evda, args, { now, refuseSecrets });