create-evda 0.1.6 → 0.1.8

package/lib/circle-plan.mjs

@@ -39,6 +39,7 @@ import { circleManifest, readCircles, writeCircle, opaqueIdOf, circlesDir, isRel
 import { grant } from "./grants.mjs";
 import { openEvda, readManifest, writeManifest } from "./manifest.mjs";
 import { EvdaError } from "./errors.mjs";
+import { defaultPartsPlan } from "./setup.mjs";
 
 export const PLAN_FILE = "plan.json";
 
@@ -221,7 +222,8 @@ export function declare(dir, plan, { circlesRel = "06_Metadata/Circles", grantsR
   mkdirSync(join(dir, manifest.mapping.grants), { recursive: true });
   const evda = openEvda(dir);
   const existing = new Map((readCircles(evda) ?? []).filter((c) => c.manifest !== null).map((c) => [c.name, c.manifest]));
-  const owner = holder ?? manifest.owner?.name ?? manifest.id;
+  // An owner with no name yet (create-evda run with no --owner) is named by the record id.
+  const owner = holder || manifest.owner?.name || manifest.id;
 
   const written = [];
   for (const c of planned.circles) {
@@ -232,6 +234,8 @@ export function declare(dir, plan, { circlesRel = "06_Metadata/Circles", grantsR
       isPublic: c.public,
       holders: [owner],
       members: numbered(c.members.map((m) => ({ path: m.path }))),
+      // A plan circle may start the circle's rules (Spec 07, section 6); the default parts start empty.
+      policy: plan.circles.find((p) => p.name === c.name)?.policy ?? null,
       description: c.public ? "Public: anyone may read it." : `Private: read by the devices granted it, and no one else.`,
     });
     written.push(writeCircle(evda, c.name, m, { overwrite: true }));
@@ -275,3 +279,22 @@ export function deviceCircles(plan, device, view = null) {
     : [];
   return { atlasId: d.atlasId, holds, never: plan.circles.map((c) => c.name).filter((n) => !holds.includes(n)), drift };
 }
+
+// The default parts (HQ-1925): journal and private, from setup.mjs `defaultPartsPlan`, declared by
+// create-evda on a new record and, on the owner's yes, over an adopted record that has none. A
+// record that already has a private part is left exactly as it is, so a yes can never replace
+// parts the owner declared. `dryRun` answers whether the default is needed and writes nothing.
+// Returns { needed, declared, parts }, parts being the private part names it has or would have.
+export function defaultParts(dir, { dryRun = false, circlesRel = "circles", grantsRel = "grants", at = new Date() } = {}) {
+  const evda = openEvda(dir);
+  const have = (readCircles(evda) ?? []).filter((c) => c.manifest && c.manifest.public !== true && !c.mount).map((c) => c.name).sort();
+  if (have.length) return { needed: false, declared: false, parts: have };
+  const m = evda.manifest;
+  const slug = String(m.name ?? "record").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "record";
+  const recordId = typeof m.id === "string" && m.id ? m.id : `${slug}.atlas`;
+  const plan = defaultPartsPlan(m.mapping ?? {}, recordId);
+  const parts = plan.circles.map((c) => c.name).sort();
+  if (dryRun) return { needed: true, declared: false, parts };
+  declare(dir, plan, { circlesRel, grantsRel, recordId, at });
+  return { needed: false, declared: true, parts };
+}

package/lib/folders.mjs

@@ -27,7 +27,7 @@ import { SCHEMES } from "./references.mjs";
 import { EvdaError } from "./errors.mjs";
 
 export const FOLDER_MANIFEST = "folder.evda.json";
-export const FOLDER_TYPES = ["record", "person", "project", "course", "source", "concept", "event", "log", "ticket", "capture", "piece", "blob", "rule", "hypothesis"];
+export const FOLDER_TYPES = ["record", "person", "project", "course", "source", "concept", "event", "log", "ticket", "capture", "piece", "blob", "rule", "hypothesis", "message"];
 export const FOLDER_KEYS = ["type", "connectors", "views"];
 export const VIEW_KEYS_REQUIRED = ["view", "of", "in", "path"];
 export const VIEW_KEYS = [...VIEW_KEYS_REQUIRED, "status", "group"];

package/lib/gather-apply.mjs

@@ -287,9 +287,14 @@ function plan(evda, p, { mode }) {
     if (md && pl.refs?.length) add.references = referencesYaml(pl.refs.map((ref) => ({ ref, label: refLabel(ref, i.heading ?? basename(to, ".md")) })));
     if (md && statusFor.has(pl.item)) add.status = `status: ${statusFor.get(pl.item)}`;
     if (md && pl.circle && falsified("apply-writes-share")) add.share = `share: [${pl.circle}]`;
+    // A credential kept in the Credentials folder is sealed (HQ-1368): evda_search, evda_recent and
+    // evda_read refuse it to every caller without naming it, and no tool releases it.
+    if (md && pl.sealed && !i.sealed) add.sealed = `${SEALED}: true`;
     // The item's own bytes, frontmatter included, so `noted: true` and `sealed: true` ride into the
     // record with it (HQ-1414). EVDA_CARRY_FALSIFY=gather-apply:<flag> drops that line on the way in.
     let bytes = withFrontmatter(buf, add);
+    // A note that already said `sealed: false` (or anything but true) is sealed all the same.
+    if (add.sealed && !/^sealed:[ \t]*true[ \t]*$/m.test(bytes.toString("utf8").split(/\n---/)[0])) bytes = Buffer.from(bytes.toString("utf8").replace(/^sealed:.*$/m, `${SEALED}: true`), "utf8");
     for (const flag of [NOTED, SEALED]) if (md && !carries("gather-apply", flag)) bytes = Buffer.from(bytes.toString("utf8").replace(new RegExp(`^${flag}:[ \\t]*true[ \\t]*\\n`, "m"), ""), "utf8");
     const st = statSync(src);
     out.writes.push({
@@ -424,7 +429,7 @@ export async function applyGather(p, into, { mode = "copy", dry = false, now = n
     const covers = f ? f.path + c.covers.slice(f.proposal.path.length) : c.covers;
     if (!pl.writes.some((w) => w.to.startsWith(`${covers}/`))) continue;
     const before = tree(evda.dir);
-    const r = proposeCircle(evda, { name: c.name, who: "Only the people the owner grants it to, by name.", what: `${covers}/`, why: `The owner said yes to its own circle for these notes while gathering a pile (proposal ${p.id}).` }, { now });
+    const r = proposeCircle(evda, { name: c.name, who: c.readBy === "none" ? "Only the owner, on their own devices. No AI reads it (read_by: none), and no agent host holds it." : "Only the people the owner grants it to, by name.", what: `${covers}/`, why: `The owner said yes to its own circle for these notes while gathering a pile (proposal ${p.id}).` }, { now });
     const after = tree(evda.dir);
     for (const d of after.dirs.filter((x) => !before.dirs.includes(x))) t.dirs.push(d);
     t.created.push({ path: r.path, sha256: sha256(readFileSync(join(evda.dir, r.path))), size: statSync(join(evda.dir, r.path)).size });

package/lib/gather.mjs

@@ -59,13 +59,41 @@ export const GATHER_VERSION = 1;
 // The person-layer kinds an item is typed with, and the folder type each lives under.
 export const GATHER_KINDS = ["note", "person", "project", "event", "log", "source", "piece", "blob", "capture"];
 export const FOLDER_TYPE_FOR = { note: "record", person: "person", project: "project", event: "event", log: "log", source: "source", piece: "piece", blob: "blob", capture: "capture" };
-export const FALSIFY_MODES = ["touch-source", "copy-contacts", "ask-everything", "answer-no-replace", "keep-secrets", "examine-nothing", "no-role"];
+export const FALSIFY_MODES = ["touch-source", "copy-contacts", "ask-everything", "answer-no-replace", "credentials-ordinary", "examine-nothing", "no-role"];
 // The role each kind fills when the preset has no folder for it (Spec 07 section 2, HQ-1371):
 // what happened, dated, is journal; one folder per thing is collections; what is known is knowledge.
 export const ROLE_FOR_KIND = { note: "journal", capture: "journal", log: "journal", person: "collections", project: "collections", event: "collections", piece: "collections", blob: "collections", course: "collections", source: "knowledge", areas: "collections" };
 // A person is asked about once this many files mention them and no page for them exists.
 export const PEOPLE_MIN_FILES = 3;
 
+// A credential written as a labeled line in a note (HQ-1368): "password: ...", "pw: ...", "PIN: ...",
+// "wifi password: ...", "api key = ...", "token: ...", "secret: ...", recovery or backup codes, a seed
+// phrase. A label at the start of the line, a separator, and a value after it; prose that only
+// mentions a password ("I forgot my password again") has no value after a separator and is not one.
+// A short value for a password-like label (a sentence after "Password:" is prose, not a password);
+// a code or phrase label may carry many words, or its value on the next line.
+const CRED_QUALIFIER = String.raw`(?:(?:wi-?fi|home|network|router|guest|email|e-mail|bank|account|admin|root|master|login|app|door|alarm|phone|sim|card|atm|debit|garage)\s+)*`;
+const CRED_SHORT = String.raw`pass(?:word|wd|code|phrase)?|pwd|pw|pin(?:\s*code)?|api[\s_-]*key|access[\s_-]*key|secret(?:[\s_-]*key)?|(?:auth[\s_-]*|access[\s_-]*|api[\s_-]*)?token|private[\s_-]*key|login`;
+const CRED_LONG = String.raw`(?:recovery|backup|2fa|mfa|one[\s-]*time)[\s_-]*(?:codes?|keys?|phrase)|seed[\s_-]*(?:phrase|words)|mnemonic(?:[\s_-]*phrase)?|secret[\s_-]*phrase`;
+const CRED_LINE = new RegExp(String.raw`^\s*(?:[-*+•>]\s+|\d+[.)]\s+)?[*_\x60]*${CRED_QUALIFIER}(?:(${CRED_LONG})|(${CRED_SHORT}))[*_\x60]*\s*(?:[:=]|\s[-\u2013]\s)[*_\x60]*\s*(.*)$`, "i");
+export function credentialLine(lines) {
+  const all = Array.isArray(lines) ? lines : String(lines ?? "").split("\n");
+  for (let n = 0; n < all.length; n++) {
+    const m = CRED_LINE.exec(all[n]);
+    if (!m) continue;
+    const label = (m[1] ?? m[2]).toLowerCase().replace(/[\s_-]+/g, " ");
+    const value = m[3].replace(/[*_\x60]+$/g, "").trim();
+    if (m[1]) {
+      if (value || (all[n + 1] ?? "").trim()) return label;
+      continue;
+    }
+    if (!value) continue;
+    if (value.split(/\s+/).length > 3) continue;
+    return label;
+  }
+  return null;
+}
+
 const falsified = (mode) => (process.env.EVDA_GATHER_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
 const posix = (p) => p.split(sep).join("/");
 const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
@@ -75,6 +103,7 @@ const APP_DIRS = { ".obsidian": "obsidian" };
 const ARCHIVE_EXT = new Set([".zip", ".tar", ".gz", ".tgz", ".7z", ".rar"]);
 const BINARY_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".heic", ".webp", ".pdf", ".mov", ".mp4", ".m4a", ".mp3", ".wav", ".xlsx", ".xls", ".docx", ".doc", ".pptx", ".key", ".pages", ".numbers", ".sqlite", ".db"]);
 const TEXT_MAX = 2 * 1024 * 1024;
+const NOTE_SIZED = 20000; // characters: longer text is read for therapy words only in its name and heading
 // Folder names that hold things without saying what they are about, so they are not a subject.
 const CONTAINERS = new Set(["documents", "desktop", "downloads", "notes", "daily", "inbox", "captures", "vault", "obsidian vault", "misc", "stuff", "untitled folder", "new folder", "export", "icloud drive"]);
 const COURSE = /\b[A-Z]{2,4}\s?\d{3}[A-Z]?\b/;
@@ -256,8 +285,11 @@ function typeItem({ rel, buf, ext, projectRoot }) {
   if (ARCHIVE_EXT.has(ext)) return { ...item, kind: "blob", archive: true, why: ["an archive file"] };
   if (BINARY_EXT.has(ext) || isBinary(buf) || buf.length > TEXT_MAX) return { ...item, kind: "blob", why: [BINARY_EXT.has(ext) ? `a ${ext.slice(1)} file` : "binary bytes"] };
   const raw = buf.toString("utf8");
-  const secret = raw.split("\n").map(secretShape).find(Boolean);
-  if (secret && !falsified("keep-secrets")) return { ...item, kind: "note", refused: `holds ${secret}`, why: [`holds ${secret}`] };
+  // A file holding a secret or a credential line is never refused (his call, 2026-09-27: "just put
+  // it in a safer place"): it is typed from its path alone, and placed sealed in a Credentials
+  // folder that no AI reads or is told of, unless the owner says no. Nothing of it is quoted.
+  const secret = raw.split("\n").map(secretShape).find(Boolean) ?? (credentialLine(raw) ? `a ${credentialLine(raw)} line` : null);
+  if (secret) return { ...item, kind: "note", credential: `holds ${secret}`, why: [`holds ${secret}`], ...(DAY.test(name) ? { daily: true, dated: name } : {}) };
   if (ext === ".vcf") {
     const cards = vcards(raw);
     return { ...item, kind: "person", mode: "reference", why: [`a Contacts export of ${cards.length} card(s)`], cards: cards.map((c) => ({ name: c.name, ref: `contacts:${c.uid ?? slugId(c.name)}`, ...(falsified("copy-contacts") ? { payload: c.payload } : {}) })) };
@@ -277,7 +309,10 @@ function typeItem({ rel, buf, ext, projectRoot }) {
   const heading = headingOf(body);
   const lines = body.split("\n").map((l) => l.trim()).filter(Boolean);
   const facts = { heading, dated: LEADING_DAY.exec(name)?.[1] ?? (DAY.test(fm.date ?? "") ? fm.date : null), daily: DAY.test(name) };
-  if (THERAPY.test(body)) facts.sensitive = { kind: "therapy", word: THERAPY.exec(body)[1] };
+  // A therapy note says so in its name or heading, or in the words of something note-sized. One mention deep in a book or a
+  // long export (a Gutenberg Meditations says "counsellor" once, 5,800 lines in) does not make it a session note.
+  const said = THERAPY.exec(basename(rel)) ?? THERAPY.exec(heading ?? "") ?? (body.length <= NOTE_SIZED ? THERAPY.exec(body) : null);
+  if (said) facts.sensitive = { kind: "therapy", word: said[1] };
   const att = ATTENDEES.exec(body);
   if (att) facts.attendees = att[1].split(/,|\band\b/).map((s) => s.trim()).filter((s) => /^[A-Z][\p{L}'-]+(?: [A-Z][\p{L}'-]+)+$/u.test(s));
   const declared = (fm.kind ?? fm.type ?? "").toLowerCase();
@@ -333,7 +368,7 @@ export function scan(sources, { now = new Date() } = {}) {
       const item = { id: `s${si}:${f.rel}`, source: `s${si}`, path: f.rel, size: f.size, sha256: sha256(buf), ...facts };
       if (projectRoot) item.project = projectRoot;
       item.subject = subjectOf(f.rel, projectRoot);
-      if (!item.refused && !item.sealed && !item.noted && item.kind !== "blob" && item.mode !== "reference") item.text = seal.buf.toString("utf8");
+      if (!item.refused && !item.credential && !item.sealed && !item.noted && item.kind !== "blob" && item.mode !== "reference") item.text = seal.buf.toString("utf8");
       out.items.push(item);
     }
   });
@@ -415,6 +450,9 @@ export function choosePreset(items, projects) {
 
 // Where a kind lives under a preset: the preset's own folder when it has one, else a folder the
 // pile needs and the preset does not have, named here and marked as such.
+// The folder credentials are kept in: every file sealed, so no AI reads it, no tool releases it, and
+// no AI is told it is there (HQ-1368, his call 2026-09-27).
+export const CREDENTIALS = "Credentials";
 const NEEDED = { note: "Notes", capture: "Captures", person: "People", project: "Projects", event: "Events", log: "Logs", source: "Sources", piece: "Writing", blob: "Attachments", areas: "Notes" };
 
 // The role a path under the preset fills: the longest mapping path at or above it.
@@ -462,21 +500,30 @@ export function place(p) {
     return NEEDED[key];
   };
   const therapyOwn = ans["circle:therapy"] === "yes";
+  // Credentials go to their own folder unless the owner says no; yes is the default.
+  const credentialsOwn = ans.credentials !== "no" && !falsified("credentials-ordinary");
   const placements = [];
   const taken = new Map();
   // The role a destination fills: the preset's mapping, else the needed folder's own role.
   const roleOf = (to) => presetRole(preset, to) ?? (falsified("no-role") ? null : undefined) ?? [...needed.values()].find((n) => to === n.path || to.startsWith(`${n.path}/`))?.role ?? null;
+  // Names are claimed without case: on a Mac "wifi.md" and "Wifi.md" are one file.
   const claim = (to, id) => {
     let t = to;
-    for (let n = 2; taken.has(t) && taken.get(t) !== id; n++) t = to.replace(/(\.[^./]+)?$/, (e) => ` (${n})${e ?? ""}`);
-    taken.set(t, id);
+    for (let n = 2; taken.has(t.toLowerCase()) && taken.get(t.toLowerCase()) !== id; n++) t = to.replace(/(\.[^./]+)?$/, (e) => ` (${n})${e ?? ""}`);
+    taken.set(t.toLowerCase(), id);
     return t;
   };
   for (const i of p.items) {
     const file = asMarkdown(i, basename(i.path));
     let pl;
     if (i.refused) pl = { status: "refused", to: null, why: `${i.refused}; left where it is and quoted nowhere. Keep the secret in a password manager.` };
-    else if (i.present) pl = { status: "present", to: null, at: i.present, why: `already in the record at ${i.present}; left where it is` };
+    else if (i.credential && credentialsOwn && /\.md$/i.test(file)) {
+      pl = { status: "placed", to: `${CREDENTIALS}/${file}`, sealed: true, why: `${i.credential}; kept in ${CREDENTIALS}/, sealed, so only the owner opens it on their own devices, no AI reads it and no tool releases it` };
+      needed.set(CREDENTIALS, { path: CREDENTIALS, type: "record", role: "collections" });
+    } else if (i.credential && credentialsOwn) {
+      // Only markdown carries `sealed: true`, so a credential in any other format is never copied.
+      pl = { status: "refused", to: null, why: `${i.credential} and is not a note that can be sealed; left where it is and quoted nowhere. Keep the secret in a password manager.` };
+    } else if (i.present) pl = { status: "present", to: null, at: i.present, why: `already in the record at ${i.present}; left where it is` };
     else if (i.archive) pl = { status: "unplaced", to: null, why: "an archive file; unpack it and gather the folder" };
     else if (i.cards) pl = { status: "reference", to: null, why: "held by Contacts; a person page keeps a contacts: reference, never the card" };
     else if (i.kind === "project") {
@@ -511,6 +558,7 @@ export function place(p) {
     placements.push({ item: `new:person:${who.name}`, status: "create", to, role: roleOf(to), refs: who.ref ? [who.ref] : [], mentions: who.files.length });
   }
   const circles = therapyOwn ? [{ name: "therapy", covers: h.areas ? `${h.areas}/Therapy` : "Therapy", status: "proposed only: a proposal file at apply, never a circle" }] : [];
+  if (credentialsOwn && placements.some((x) => x.sealed)) circles.push({ name: "credentials", covers: CREDENTIALS, readBy: "none", status: "proposed only: a proposal file at apply, never a circle; every file in it is sealed already" });
   const used = new Map();
   for (const pl of placements) {
     if (!pl.to) continue;
@@ -542,6 +590,8 @@ function candidates(p) {
     if (!proj.finished && !falsified("ask-everything")) continue;
     out.push({ id: `finished:${proj.id}`, kind: "finished", options: ["finished", "live"], text: `${proj.name} looks finished (${basename(proj.files.find((f) => f === proj.finished?.file) ?? proj.root)} says "${proj.finished?.word ?? "nothing"}"). Is it finished, or live? It stays where it is; finished is its status.`, about: proj.name });
   }
+  const creds = p.items.filter((i) => i.credential && !i.present);
+  if (creds.length) out.push({ id: "credentials", kind: "credentials", options: ["yes", "no"], default: "yes", text: `${creds.length} note(s) look like they hold passwords or keys: keep them sealed in a Credentials folder, so only you open them on your own devices and no AI reads them?`, about: "credentials" });
   const therapy = p.items.filter((i) => i.sensitive?.kind === "therapy");
   if (therapy.length) out.push({ id: "circle:therapy", kind: "circle", options: ["yes", "no"], text: `${therapy.length} file(s) read like therapy notes. Give them their own circle, so only who you choose reads them?`, about: "therapy" });
   return out;
@@ -651,7 +701,7 @@ export function answer(p, questionId, value, { now = new Date() } = {}) {
 
 // Items it could not place, or typed only by elimination, handed to the owner's claude -p.
 export function withOwnersAi(p, { model = null, env = process.env } = {}) {
-  const unsure = p.items.filter((i) => !i.refused && !i.sealed && !i.noted && !i.present && (i.confidence === "low" || p.placements.find((x) => x.item === i.id)?.status === "unplaced") && !i.archive);
+  const unsure = p.items.filter((i) => !i.refused && !i.credential && !i.sealed && !i.noted && !i.present && (i.confidence === "low" || p.placements.find((x) => x.item === i.id)?.status === "unplaced") && !i.archive);
   if (!unsure.length) { p.ai = { status: "SKIPPED", why: "nothing was unsure" }; return { ok: true, p }; }
   const kinds = GATHER_KINDS.join(", ");
   const lines = unsure.map((i) => `- ${i.id} (typed ${i.kind}${i.heading ? `, titled "${i.heading}"` : ""})`);
@@ -750,7 +800,7 @@ export function summaryText(p, { detail = false } = {}) {
   if (detail) { lines.push("", "Every placement:"); for (const x of byStatus("placed")) lines.push(`- ${x.item} -> ${x.to}`); }
   const open = p.questions.filter((q) => q.answer === undefined);
   lines.push("", open.length ? `${open.length} question(s) for the owner:` : "No open questions.");
-  for (const q of open) lines.push(`- [${q.id}] ${q.text} (${q.options.join(" / ")})`);
+  for (const q of open) lines.push(`- [${q.id}] ${q.text} (${q.options.join(" / ")}${q.default ? `, default ${q.default}` : ""})`);
   return lines.join("\n");
 }
 

package/lib/mcp.mjs

@@ -9,9 +9,11 @@
 // stdout carries protocol messages only. Nothing in this file or the tools it calls prints to
 // stdout; doctor's report is captured into the tool result.
 //
-// Every tool here reads and writes files on this machine, with one exception: evda_check_update
-// asks the npm registry for the tooling's latest version number. That is the server's only network
-// call, it carries nothing from the record, and it installs nothing.
+// Every tool here reads and writes files on this machine, with two exceptions. evda_check_update
+// asks the npm registry for the tooling's latest version number; it carries nothing from the record
+// and installs nothing. The device tools (evda_pair_device, evda_sync_devices, HQ-1217) talk to the
+// relay that carries the record between the owner's own devices, and what they send is sealed on
+// this machine: the relay cannot read it.
 
 import { createInterface } from "node:readline";
 import { SCHEMA_VERSION } from "./manifest.mjs";
@@ -28,6 +30,7 @@ import { createSubrecord } from "./subrecord.mjs";
 import { FALSIFY } from "./mcp-auth.mjs";
 import { filingOf, FILING_MODES } from "./day-file.mjs";
 import { readManifest, writeManifest } from "./manifest.mjs";
+import * as pairing from "./pairing.mjs";
 
 // Newest first. The server answers with the client's version when it supports it, and with the
 // newest otherwise; the client decides whether to continue.
@@ -54,6 +57,7 @@ export function instructions(filing) {
     "Never quiz them. Never create a circle or grant; propose one with evda_propose_circle only when they ask to share, and wait for their yes.",
     "Organization comes from the preset library (evda_presets): propose with evda_propose_structure, and apply with evda_apply_preset only after their yes.",
     "When they point you at a pile they already have (a folder, an export), call evda_gather, then ask the questions from evda_gather_questions one at a time in your own words, and record each answer with evda_gather_answer. When every question is answered and the owner says yes to the summary, apply it with evda_gather_apply and confirmed: true; tell them the reversal manifest it names.",
+    DISPATCH_LINE,
     PRIVACY_INSTRUCTIONS,
   ];
   return lines.join(" ");
@@ -88,6 +92,12 @@ export const PRIVACY_SECTION = [
   "- To keep a conversation out of training, the option is the provider's incognito or temporary chat. Claude's incognito chats are never used for training; ChatGPT keeps a Temporary Chat up to 30 days; others may offer the same.",
 ].join("\n");
 
+// Dispatch (HQ-1246), one line on every surface an agent reads first: the server instructions and
+// the operating layer. The vault's AGENTS-template.md is the core's source; until it carries this
+// line, this is where it lives, and evda_operating_layer serves it above AGENTS.md.
+export const DISPATCH_LINE = "Call evda_replies at the start of a run: it returns the owner's replies to your messages that you have not seen yet. When the owner should hear something from you (what you did, a question), send it with evda_message, which shows it on their phone as a card; a thing only filed waits until they go looking.";
+export const DISPATCH_SECTION = `## Messages to the owner\n\n${DISPATCH_LINE}`;
+
 const str = (description) => ({ type: "string", description });
 
 // summarize() already names the command for the two statuses that ask the owner to run one. Over
@@ -165,7 +175,7 @@ export const TOOLS = [
     annotations: { readOnlyHint: true, openWorldHint: false },
     run: (evda, args) => {
       const r = tools.operatingLayer(evda, args);
-      return { text: `${chatSection(evda, r.text)}\n\n${PRIVACY_SECTION}\n\n${r.text}`, data: { path: r.path } };
+      return { text: `${chatSection(evda, r.text)}\n\n${DISPATCH_SECTION}\n\n${PRIVACY_SECTION}\n\n${r.text}`, data: { path: r.path } };
     },
   },
   {
@@ -245,6 +255,30 @@ export const TOOLS = [
       return { text: `Noted at ${r.path}. No AI reads it until the owner says it can.`, data: r };
     },
   },
+  {
+    name: "evda_message",
+    title: "Tell the owner something",
+    description: "Sends the owner a message: writes it as one new file in the record's messages folder, which their phone app shows as a card, and returns its id and path. Use it for what they should hear from you (what you did, a question for them); a reply comes back through evda_replies. Never edits a message once written. Refuses anything shaped like a password, key or token.",
+    inputSchema: { type: "object", properties: { title: str("One line: what the card says at a glance."), body: str("The message, in markdown."), from: str("The agent's name. Default: the name in the operating layer.") }, required: ["title", "body"], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.message(evda, args);
+      return { text: `Sent the message ${r.id}, filed at ${r.path}. The owner's reply, when there is one, comes back through evda_replies.`, data: r };
+    },
+  },
+  {
+    name: "evda_replies",
+    title: "Read the owner's replies",
+    description: "Call at the start of a run: returns the owner's replies to your messages that you have not seen yet (message id, title, reply, date) and marks them seen, so each shows once; a reply the owner changes shows again. peek: true returns them without marking.",
+    inputSchema: { type: "object", properties: { peek: { type: "boolean", description: "true to read without marking them seen." } }, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args, ctx) => {
+      const r = tools.replies(evda, args, { caller: ctx.caller });
+      const body = r.replies.map((x) => `<reply to="${x.id}" title=${JSON.stringify(x.title)} date="${x.date}">\n${x.reply}\n</reply>`).join("\n\n");
+      const main = r.replies.length ? `${r.replies.length} new repl${r.replies.length === 1 ? "y" : "ies"} from the owner${args.peek ? " (peek: not marked seen)" : ""}.\n\n${body}` : "No new replies from the owner.";
+      return { text: r.heldBack ? `${main}\n\n${r.heldBack}` : main, data: { replies: r.replies, marked: r.marked } };
+    },
+  },
   {
     name: "evda_filing",
     title: "Record how filing works",
@@ -496,10 +530,51 @@ export const TOOLS = [
       return { text: `${r.text}\n\nexit ${r.exit}`, data: { exit: r.exit }, isError: r.exit !== 0 };
     },
   },
+  {
+    name: "evda_pair_device",
+    title: "Pair a phone",
+    description: "Call only when the owner asks to pair, add or connect a phone or another device to their EVÐA. Returns a one-time pairing code and a QR link for the phone, and the steps to do on it. The code works once, for 10 minutes, and the device gets only the parts named (journal by default). Show the code to the owner and no one else.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "What to call the device, such as phone. Default phone." },
+        parts: { type: "array", items: { type: "string" }, description: "The private parts of the record the device may read and add to. Default [\"journal\"]." },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    run: async (evda, args) => {
+      tools.onlyKeys("evda_pair_device", args, ["name", "parts"]);
+      const r = await pairing.pair(evda.dir, { name: args.name, parts: args.parts });
+      return { text: pairing.pairText(r) };
+    },
+  },
+  {
+    name: "evda_sync_devices",
+    title: "Sync with paired devices",
+    description: "Call after the owner used a pairing code on their phone, or when they ask to sync their devices: adds a device that used its code, takes in what paired devices wrote, and sends what changed here. Answers in plain words.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    run: async (evda, args) => {
+      tools.onlyKeys("evda_sync_devices", args, []);
+      return { text: (await pairing.sync(evda.dir)).join("\n") };
+    },
+  },
+  {
+    name: "evda_devices",
+    title: "Paired devices",
+    description: "Lists the devices paired with the owner's EVÐA, whether each is waiting, paired or removed, and which parts each reads. Removing one is a command the owner runs: evda remove <device>.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: async (evda, args) => {
+      tools.onlyKeys("evda_devices", args, []);
+      return { text: (await pairing.devices(evda.dir)).join("\n") };
+    },
+  },
   {
     name: "evda_check_update",
     title: "Check for newer EVDA tooling",
-    description: "Asks the npm registry whether a newer version of the EVDA tooling exists, and returns the one line that says so. At most one real check an hour; inside that hour it reports the cached result. A check that fails reports the status as UNKNOWN, never as up to date. This is the only tool that reaches the network, it sends nothing from the record, and it changes nothing: taking the update is a command the owner runs in their own terminal.",
+    description: "Asks the npm registry whether a newer version of the EVDA tooling exists, and returns the one line that says so. At most one real check an hour; inside that hour it reports the cached result. A check that fails reports the status as UNKNOWN, never as up to date. It sends nothing from the record, and it changes nothing: taking the update is a command the owner runs in their own terminal.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     annotations: { readOnlyHint: true, openWorldHint: true },
     run: async (evda) => {
@@ -511,7 +586,7 @@ export const TOOLS = [
 ];
 
 export const RESOURCES = [
-  { uri: "evda://agents", name: "AGENTS.md", title: "The operating layer", mimeType: "text/markdown", read: (evda) => { const t = tools.operatingLayer(evda).text; return `${chatSection(evda, t)}\n\n${t}`; } },
+  { uri: "evda://agents", name: "AGENTS.md", title: "The operating layer", mimeType: "text/markdown", read: (evda) => { const t = tools.operatingLayer(evda).text; return `${chatSection(evda, t)}\n\n${DISPATCH_SECTION}\n\n${t}`; } },
   {
     uri: "evda://today",
     name: "today",

package/lib/messages.mjs

@@ -0,0 +1,205 @@
+// Dispatch through the record (HQ-1246): the owner's agent writes a message, the phone app shows it
+// as a card, and the owner's reply comes back as a file the agent reads on its next run.
+//
+// The format, which the phone app (iris-mobile, the EVÐA target) reads exactly:
+//
+//   <messages role>/YYYY-MM-DD-HHMM-<slug>.md          one message, written once by the agent
+//     ---
+//     id: <the filename stem>
+//     from: "<agent name>"
+//     title: "<title>"
+//     date: "<ISO 8601 with offset>"
+//     ---
+//     <markdown body>
+//
+//   <messages role>/<same stem>.reply.md               the owner's reply, written by the app
+//     ---
+//     in_reply_to: <the message id>
+//     date: "<ISO 8601 with offset>"
+//     ---
+//     <reply text>
+//
+//   <messages role>/.seen.json                          { "<id>": "<reply date seen>" }, the agent's
+//
+// The messages role resolves through evda.json like every other role, `messages/` when unmapped. A
+// message is never edited after it is written: a second message in the same minute with the same
+// slug gets `-2`, `-3`, and a file already at a name (a reply, or anything sealed) is never touched.
+// "Answered" is the reply file existing, never a stored flag. What the agent has seen is keyed by the
+// reply's date, so a reply the app rewrites after the agent read it shows again.
+//
+// Replies are read the way every other tool reads (lib/readers.mjs): a sealed reply is in no answer
+// and a sealed section is cut out, a noted reply or one in a circle set to a different reader is held
+// back and named, and nothing held back is marked seen.
+//
+// EVDA_MESSAGES_FALSIFY=<mode,...>, for the tests. Each breaks exactly one rule:
+//   overwrite     a colliding name is written over instead of getting a suffix
+//   orphans       a reply with no message is returned
+//   seen-by-id    a reply whose id was ever seen stays hidden, whatever its date
+//   strict-seen   a .seen.json that does not parse throws instead of reading as empty
+//   no-secrets    the secret check is skipped
+//   default-path  the evda.json mapping is ignored and messages/ is always used
+//   raw-slug      the title goes into the filename unslugged
+//   no-readers    replies are shown without asking lib/readers.mjs
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { resolveRole, agentsFile } from "./roles.mjs";
+import { frontmatterOf } from "./circles.mjs";
+import { readContext, mayRead, heldBack, callerFrom, aiView } from "./readers.mjs";
+import { localDate } from "./day-file.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const MESSAGES_ROLE = "messages";
+export const MESSAGES_DEFAULT = "messages";
+export const SEEN_FILE = ".seen.json";
+export const REPLY_SUFFIX = ".reply.md";
+export const DEFAULT_FROM = "Iris";
+const TITLE_MAX = 200;
+const FROM_MAX = 60;
+const BODY_MAX = 200_000;
+const SLUG_MAX = 60;
+
+export const MESSAGES_FALSIFY_MODES = ["overwrite", "orphans", "seen-by-id", "strict-seen", "no-secrets", "default-path", "raw-slug", "no-readers"];
+const falsified = (mode) => (process.env.EVDA_MESSAGES_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+const pad = (n) => String(n).padStart(2, "0");
+const refuse = (message, code) => new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+
+// A local time as ISO 8601 with its offset: 2026-09-25T12:04:00-05:00.
+export function isoLocal(d) {
+  const off = -d.getTimezoneOffset();
+  const sign = off >= 0 ? "+" : "-";
+  const a = Math.abs(off);
+  return `${localDate(d)}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${sign}${pad(Math.floor(a / 60))}:${pad(a % 60)}`;
+}
+
+// A title as a filename part: accents folded, lowercase ASCII letters and digits joined by single
+// hyphens, at most 60 characters. A title with nothing left (all emoji, all Greek) is "message".
+export function slugify(title) {
+  if (falsified("raw-slug")) return String(title);
+  const s = String(title).normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return s.slice(0, SLUG_MAX).replace(/-+$/, "") || "message";
+}
+
+// Where messages live: the role's mapping, else messages/ at the record root. resolveRole refuses a
+// mapping that leaves the record.
+export function messagesDir(evda) {
+  const r = falsified("default-path") ? { mapped: false } : resolveRole(evda, MESSAGES_ROLE);
+  if (r.mapped) {
+    if (r.exists && !r.isDir) throw refuse(`the messages role is mapped to ${r.rel}, which is a file; it holds a folder.`, "BAD_MAPPING");
+    return { abs: r.abs, rel: r.rel.replace(/\/+$/, "") };
+  }
+  return { abs: join(evda.dir, MESSAGES_DEFAULT), rel: MESSAGES_DEFAULT };
+}
+
+// The agent's name as the operating layer's owner section gives it, else Iris.
+export function agentName(evda) {
+  try {
+    const a = agentsFile(evda);
+    if (!a) return DEFAULT_FROM;
+    const m = /^- \*\*Agent name:\*\*[ \t]*(\S.*)$/m.exec(readFileSync(a.abs, "utf8"));
+    return m?.[1]?.trim() || DEFAULT_FROM;
+  } catch {
+    return DEFAULT_FROM;
+  }
+}
+
+function oneLine(value, name, max) {
+  if (typeof value !== "string" || value.trim() === "") throw refuse(`evda_message needs "${name}".`, "EMPTY");
+  const v = value.trim();
+  if (/[\r\n]/.test(v)) throw refuse(`evda_message "${name}" is one line.`, "LINES");
+  if (v.length > max) throw refuse(`evda_message "${name}" is ${v.length} characters; at most ${max}.`, "TOO_LONG");
+  return v;
+}
+
+// Write one new message. `refuseSecrets` is passed in by lib/tools.mjs so this module and evda_write
+// refuse with the same check and the same words.
+export function writeMessage(evda, args, { now = new Date(), refuseSecrets } = {}) {
+  const title = oneLine(args.title, "title", TITLE_MAX);
+  if (typeof args.body !== "string" || args.body.trim() === "") throw refuse('evda_message needs "body", what you are telling the owner.', "EMPTY");
+  if (args.body.length > BODY_MAX) throw refuse(`evda_message "body" is ${args.body.length} characters; one message holds at most ${BODY_MAX}.`, "TOO_LONG");
+  const from = args.from === undefined ? agentName(evda) : oneLine(args.from, "from", FROM_MAX);
+  if (!falsified("no-secrets")) for (const s of [title, args.body, from]) refuseSecrets(s, "evda_message");
+  const dir = messagesDir(evda);
+  mkdirSync(dir.abs, { recursive: true });
+  const base = `${localDate(now)}-${pad(now.getHours())}${pad(now.getMinutes())}-${slugify(title)}`;
+  const taken = (stem) => existsSync(join(dir.abs, `${stem}.md`)) || existsSync(join(dir.abs, `${stem}${REPLY_SUFFIX}`));
+  let stem = base;
+  if (!falsified("overwrite")) for (let n = 2; taken(stem); n++) stem = `${base}-${n}`;
+  const abs = join(dir.abs, `${stem}.md`);
+  const text = ["---", `id: ${stem}`, `from: ${JSON.stringify(from)}`, `title: ${JSON.stringify(title)}`, `date: ${JSON.stringify(isoLocal(now))}`, "---", "", args.body.replace(/\n+$/, ""), ""].join("\n");
+  // "wx": never replace a file, even one that appeared between the check and the write.
+  writeFileSync(abs, text, { flag: falsified("overwrite") ? "w" : "wx" });
+  return { id: stem, path: relative(evda.dir, abs).split(sep).join("/") };
+}
+
+// What the agent has seen, as { id: reply date }. Missing, unreadable, or not a JSON object of
+// strings: empty, so every reply shows and the next mark rewrites the file whole.
+export function readSeen(dirAbs) {
+  const p = join(dirAbs, SEEN_FILE);
+  if (!existsSync(p)) return {};
+  let v;
+  try { v = JSON.parse(readFileSync(p, "utf8")); } catch (e) { if (falsified("strict-seen")) throw e; return {}; }
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return {};
+  return Object.fromEntries(Object.entries(v).filter(([, d]) => typeof d === "string"));
+}
+
+function writeSeen(dirAbs, seen) {
+  const p = join(dirAbs, SEEN_FILE);
+  const t = `${p}.tmp-${process.pid}`;
+  writeFileSync(t, JSON.stringify(seen, null, 2) + "\n");
+  renameSync(t, p);
+}
+
+// The text after a file's frontmatter.
+function bodyOf(text) {
+  const lines = text.split("\n");
+  if (lines[0] !== "---") return text;
+  const end = lines.indexOf("---", 1);
+  return end === -1 ? text : lines.slice(end + 1).join("\n");
+}
+
+const dateString = (v) => (v instanceof Date ? v.toISOString() : typeof v === "string" && v.trim() !== "" ? v.trim() : null);
+
+// The owner's replies the agent has not seen: { replies: [{ id, title, reply, date, path }], heldBack,
+// marked }. Marks each one returned as seen unless `peek`. A reply with no message is not one.
+export function unseenReplies(evda, { peek = false } = {}, { caller = callerFrom() } = {}) {
+  const dir = messagesDir(evda);
+  if (!existsSync(dir.abs) || !statSync(dir.abs).isDirectory()) return { replies: [], heldBack: "", marked: 0, dir: dir.rel };
+  const seen = readSeen(dir.abs);
+  const ctx = readContext(evda);
+  const refused = [];
+  let sealed = false;
+  const replies = [];
+  for (const name of readdirSync(dir.abs).sort()) {
+    if (!name.endsWith(REPLY_SUFFIX) || name.startsWith(".")) continue;
+    const id = name.slice(0, -REPLY_SUFFIX.length);
+    const abs = join(dir.abs, name);
+    if (!statSync(abs).isFile()) continue;
+    const msgAbs = join(dir.abs, `${id}.md`);
+    if (!existsSync(msgAbs) && !falsified("orphans")) continue;
+    if (!falsified("no-readers")) {
+      const may = mayRead(ctx, abs, caller);
+      if (!may.ok) { refused.push(may); continue; }
+    }
+    const raw = readFileSync(abs, "utf8");
+    const front = frontmatterOf(raw) ?? {};
+    const date = dateString(front.date) ?? statSync(abs).mtime.toISOString();
+    if (falsified("seen-by-id") ? id in seen : seen[id] === date) continue;
+    const shown = falsified("no-readers") ? { text: raw, sections: 0 } : aiView(raw);
+    if (shown.sections) sealed = true;
+    let title = id;
+    if (existsSync(msgAbs)) {
+      const mraw = readFileSync(msgAbs, "utf8");
+      const mfront = frontmatterOf(mraw);
+      if (typeof mfront?.title === "string" && mfront.title.trim()) title = mfront.title.trim();
+    }
+    replies.push({ id, title, reply: bodyOf(shown.text).replace(/^\n+|\n+$/g, ""), date, path: relative(evda.dir, abs).split(sep).join("/") });
+  }
+  replies.sort((a, b) => (a.date === b.date ? a.id.localeCompare(b.id) : a.date.localeCompare(b.date)));
+  if (!peek && replies.length) {
+    for (const r of replies) seen[r.id] = r.date;
+    writeSeen(dir.abs, seen);
+  }
+  return { replies, heldBack: heldBack(refused, { sealed }), marked: peek ? 0 : replies.length, dir: dir.rel };
+}