create-evda 0.1.9 → 0.1.11

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,23 +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, readdirSync, 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, headings } from "./record.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 } from "./circles.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, 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 };
 
@@ -158,13 +165,13 @@ export function coreBeside(evda, agents, agentsText) {
 // 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, not the whole file (HQ-2163) and not its first line either
-// (HQ-2227): this tool is for triage across many files, and pulling every matching file whole into
-// a hosted chat put sensitive captures into it unread. A first line did the same at a smaller size:
-// a capture is often one line long, so on 2026-10-05 a claude.ai question about deadlines got the
-// text of a relationship capture and an edibles night through it. A heading is what the owner or
-// the filing tool chose to title an entry; the words under it are read by path, when the question
-// needs them. The whole text of one file is `evda_read`'s job, by path. `full: true` is
+// 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.
 //
@@ -196,7 +203,7 @@ export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(
     const acknowledged = acknowledgementsFor(path, marks);
     files.push(full
       ? { date, path, text: shown.text, acknowledged }
-      : { date, path, headings: headings(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;
@@ -219,6 +226,40 @@ export function recent(evda, args = {}, { now = new Date(), caller = callerFrom(
   };
 }
 
+// 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.
@@ -282,10 +323,52 @@ export function write(evda, args = {}, { now = new Date(), session = null, toolN
   }
   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
@@ -303,6 +386,7 @@ 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+$/, "");
@@ -326,8 +410,14 @@ export async function writeVerified(evda, args = {}, { verifyDelayMs = VERIFY_DE
 // replaces, exactly as the section's own instructions ask.
 const CHANGE_MAX = 400;
 const WORDS_MAX = 400;
-export function recordCorrection(evda, args = {}, { now = new Date() } = {}) {
-  onlyKeys("evda_record_correction", args, ["words", "change", "supersedes"], "It appends one dated line to \"What I have been taught\" and nothing else: it takes no path, and it never edits or replaces an earlier entry.");
+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");
@@ -341,26 +431,48 @@ export function recordCorrection(evda, args = {}, { now = new Date() } = {}) {
     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, so it has no AGENTS.md to write the correction into.', "NO_ROLE");
+  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, so a correction has nowhere to land. Add that heading first (templates/AGENTS.md has the wording); evda doctor names this too.`, "NO_SECTION");
+    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 date = localDate(now);
-  const said = words ? `"${words}" -> ` : "";
-  const supersededNote = supersedes ? ` Supersedes ${supersedes}.` : "";
-  const line = `- ${date}: ${said}${change}${supersededNote}\n`;
-  const sep = owner.endsWith("\n") ? "" : "\n";
-  const newOwner = owner + sep + line;
+  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" };
@@ -393,10 +505,59 @@ 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" });
-  return { path: `${AGENT_LOG_REL}/${r.path}`, bytes: r.bytes, section: r.section };
+  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
@@ -416,19 +577,84 @@ function peopleDir(evda) {
   return r;
 }
 
-// Files in `dir` whose name (without .md) matches `name`, case-insensitively, exact match first.
-// No folders (CLAUDE.md: one file per person), so this never recurses.
-function findPersonFiles(dir, name) {
-  const want = String(name).trim().toLowerCase().replace(/\s+/g, " ");
-  const all = readdirSync(dir.abs, { withFileTypes: true })
-    .filter((e) => e.isFile() && /\.md$/i.test(e.name) && e.name.toLowerCase() !== "readme.md")
-    .map((e) => e.name);
-  const stem = (f) => f.replace(/\.md$/i, "").toLowerCase();
-  const exact = all.filter((f) => stem(f) === want);
-  return exact.length ? exact : all.filter((f) => stem(f).startsWith(want));
+// 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() } = {}) {
+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");
@@ -439,13 +665,14 @@ export function recordPersonNote(evda, args = {}, { now = new Date() } = {}) {
   const words = text(args.words, "words", "evda_record_person_note");
   refuseSecrets(words, "evda_record_person_note");
 
-  const dir = peopleDir(evda);
-  const matches = findPersonFiles(dir, args.person);
-  if (matches.length === 0) throw refuse(`no page for "${args.person.trim()}" in ${dir.rel}. This tool never creates one; offer to make the page first.`, "MISSING");
-  if (matches.length > 1) throw refuse(`"${args.person.trim()}" matches more than one page in ${dir.rel} (${matches.join(", ")}). Say which one.`, "AMBIGUOUS");
+  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 = join(dir.abs, matches[0]);
+  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);
@@ -499,41 +726,368 @@ const APPEND_ELSEWHERE = [
   ["messages", "is a message file, which evda_message and the phone write."],
   ["ledger", "is the hypothesis ledger, which has its own format and tools."],
 ];
-export function appendEntry(evda, args = {}, { now = new Date(), caller = callerFrom() } = {}) {
-  onlyKeys("evda_append", args, ["path", "words"], "It adds one dated section to the end of an entry that already exists and nothing else: it never creates a file and never edits what is there.");
-  if (typeof args.path !== "string" || args.path.trim() === "") throw refuse('evda_append needs "path": the existing entry, relative to the record, as evda_search or evda_recent gave it.', "BAD_ARGUMENT");
-  const words = text(args.words, "words", "evda_append");
-  refuseSecrets(words, "evda_append");
-  const want = args.path.trim();
+// 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 (!/\.md$/i.test(abs)) throw refuse(`${where} is not a Markdown entry; only a .md entry grows by a dated section.`, "NOT_AN_ENTRY");
-  if (!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 a page, and start it only on their yes.`, "MISSING");
+  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");
-  if (!where.includes("/") || where.split("/").some((p) => p.startsWith("."))) throw refuse(`${where} is one of the record's own files, not an entry.`, "NOT_AN_ENTRY");
-  const top = where.split("/")[0];
-  if (top === PROPOSALS) throw refuse(`${where} is one of the record's own files, not an entry.`, "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 (r.mapped && r.abs && (abs === r.abs || abs.startsWith(r.abs + sep))) throw refuse(`${where} ${why}`, "NOT_AN_ENTRY");
+    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 heading = `## ${date}`;
+  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 = lastHeading === heading;
+  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
@@ -629,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
@@ -649,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 }) };
 }
 
@@ -672,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() } = {}) {