create-evda 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,20 @@ Plain-English notes on how Iris behaves differently after each version. Not a co
 
 ## Unreleased
 
+Organizing is on from the start. Setup installs the morning organize on a Mac (a launchd job that
+runs your own Claude each morning at 8:00, or when the computer wakes), says so in one line, and
+offers off: answer no during setup, pass `--no-routines`, or later run `evda routine morning
+--uninstall`. The weekly look back is still offered, not on. When your AI's part of a routine cannot
+run, the report now says why in words you can act on (Claude is not signed in on this computer: open
+Claude and sign in), and the filing part still runs.
+
+Your agent can message you. `evda_message` (and `evda message`) writes one new file in your record's
+`messages/` folder, which the EVÐA phone app shows as a card, and your reply comes back as a file beside
+it. `evda_replies` (and `evda replies`) hands your agent each reply once at the start of its next run,
+and again if you change it. A new record has the folder; an older one gets it the first time a message
+is sent, and `evda.json` can map it elsewhere. A message refuses anything shaped like a password, and a
+reply you seal or just note is not shown to your agent.
+
 A note you asked to have just noted, or a sealed one, stays that way wherever EVDA copies it.
 `evda organize` no longer copies a just-noted capture into its day: the day gets one line saying where
 it is, and once you release it the next organize files its words. Gathering a pile quotes nothing of a

package/bin/evda.mjs

@@ -34,7 +34,7 @@ import { parity, formatParity } from "../lib/parity.mjs";
 import { note, releaseNote, ownerSearch, readContext, readersFor, describeReaders, parseReaders, READ_BY } from "../lib/readers.mjs";
 import { runHook } from "../lib/guard.mjs";
 import { markdownFiles } from "../lib/circles.mjs";
-import { refuseSecrets } from "../lib/tools.mjs";
+import { refuseSecrets, message as messageTool, replies as repliesTool } from "../lib/tools.mjs";
 
 const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
 
@@ -102,9 +102,10 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
                                  undo an apply byte for byte; refused when a placed file was edited
   evda look-back [dir] [--model M]
                                  the week, read back by the owner's claude -p, appended to a report
-  evda routine <morning|weekly> [dir] [--launchd] [--install]
+  evda routine <morning|weekly> [dir] [--launchd] [--install] [--uninstall]
                                  print a scheduled routine for Claude, or a launchd fallback; --install
-                                 writes the launchd job, and nothing is scheduled without it
+                                 writes the launchd job, --uninstall removes it (setup installs the
+                                 morning organize unless told no)
   evda preset list               the organizations this package ships, and who each suits
   evda preset show <id>          one preset's folders
   evda preset apply <id> [--dry] [dir]
@@ -134,6 +135,12 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
                                  or project, or a folder of effort files. CHECKED n, or SKIPPED and why
   evda note "<words>" [--in dir] just note it: a capture no AI reads until you release it (words from stdin with -)
   evda release <path> [dir]      you can read that now: clear the just-noted flag on one entry
+  evda message --title "<title>" [--from NAME] [--in dir] "<body>"
+                                 tell the owner something: one new file in the messages role, a card
+                                 in their phone app (body from stdin with -)
+  evda replies [--peek] [--in dir] [--json]
+                                 the owner's replies not seen yet, marked seen unless --peek; read
+                                 under read_by as the AI $EVDA_READER names (claude, local, ...)
   evda search <words> [dir]      your own search, on this device, no model; just-noted and sealed entries included and marked
   evda readers [dir]             which AI reads each part of the record, from read_by
   evda local-model               how to run a model on your own computer and point a circle at it
@@ -410,7 +417,7 @@ async function main(argv) {
     }
 
     case "routine": {
-      // evda routine <morning|weekly> [dir] [--launchd] [--install]
+      // evda routine <morning|weekly> [dir] [--launchd] [--install] [--uninstall]
       const { routineMain } = await import("../lib/routines.mjs");
       return routineMain(args, { pickDir, flagValue });
     }
@@ -507,6 +514,32 @@ async function main(argv) {
       return 0;
     }
 
+    case "message": {
+      // Like note, the body may hold a slash, so the record is --in <dir> or the locator.
+      const take = (flag) => { const i = args.indexOf(flag); if (i < 0) return undefined; const v = args[i + 1]; if (v === undefined) throw new EvdaError(`${flag} needs a value`, { exit: 2 }); args.splice(i, 2); return v; };
+      const dirArg = take("--in");
+      const title = take("--title");
+      const from = take("--from");
+      const dir = locate({ explicit: dirArg }).dir;
+      let body = args.join(" ");
+      if (body === "-" || body === "") body = readFileSync(0, "utf8");
+      const r = messageTool(openEvda(dir), { title, body, ...(from === undefined ? {} : { from }) });
+      console.log(`Sent the message ${r.id}, filed at ${r.path}.`);
+      return 0;
+    }
+
+    case "replies": {
+      const i = args.indexOf("--in");
+      const dir = locate({ explicit: i >= 0 ? args[i + 1] : undefined }).dir;
+      const peek = args.includes("--peek");
+      const r = repliesTool(openEvda(dir), peek ? { peek: true } : {});
+      if (args.includes("--json")) { console.log(JSON.stringify({ replies: r.replies, marked: r.marked }, null, 2)); return 0; }
+      for (const x of r.replies) console.log(`## ${x.title}  (${x.id}, ${x.date})\n\n${x.reply}\n`);
+      if (r.heldBack) console.log(r.heldBack);
+      console.log(`CHECKED ${r.dir}/  ${r.replies.length} new repl${r.replies.length === 1 ? "y" : "ies"}, ${r.marked} marked seen${peek ? " (peek)" : ""}`);
+      return 0;
+    }
+
     case "release": {
       const { dir, entry } = pickReleaseArgs(args);
       const r = releaseNote(openEvda(dir), entry);

package/create-evda.mjs

@@ -30,7 +30,7 @@ import { readPointer, setPointer, pointerPath } from "./lib/locate.mjs";
 import { FOLDER_MANIFEST } from "./lib/folders.mjs";
 import { EvdaError } from "./lib/errors.mjs";
 import { clients, installSkill, installGuard } from "./lib/connect.mjs";
-import { desktopInstructions } from "./lib/routines.mjs";
+import { defaultRoutines, installAtSetup } from "./lib/routines.mjs";
 import { installHook } from "./lib/hooks.mjs";
 import { applyPreset, listPresets, planLines, presetIds, NONE } from "./lib/presets.mjs";
 import { FILING_MODES } from "./lib/day-file.mjs";
@@ -53,6 +53,7 @@ const CANONICAL = {
   circles: "circles",
   grants: "grants",
   mounts: "mounts",
+  messages: "messages",
 };
 
 // What each record folder holds (Spec 07, section 2), written as folder.evda.json beside the
@@ -61,6 +62,7 @@ const FOLDER_TYPES = {
   "record/daily": "record",
   "record/captures": "capture",
   "record/people": "person",
+  messages: "message",
 };
 
 const USAGE = `usage: create-evda <dir> [--agent-name NAME] [--owner NAME] [--purpose TEXT] [--voice TEXT] [--platform ${PLATFORM_KEYS.join("|")}] [--training-off] [--filing everything|asked] [--no-prompt-hook] [--yes] [--name NAME] [--kind person|agent|company] [--id ATLAS-ID] [--layers record,ledger] [--skill] [--routines morning,weekly] [--preset ${presetIds().join("|")}|none] [--use] [--no-pointer] [--no-guard]`;
@@ -149,6 +151,9 @@ export function scaffold(opts) {
   const today = localDate();
   const mapping = { agents: CANONICAL.agents };
   for (const layer of opts.layers) for (const role of rolesForLayer(layer)) mapping[role] = CANONICAL[role];
+  // Messages from the owner's agent, and their replies (HQ-1246): every record has the folder, in
+  // whatever layers, because the phone app's Dispatch reads it.
+  mapping.messages = CANONICAL.messages;
 
   mkdirSync(dir, { recursive: true });
   for (const [role, rel] of Object.entries(mapping)) if (role !== "agents") mkdirSync(join(dir, rel), { recursive: true });
@@ -322,11 +327,10 @@ export async function main(argv, io = null) {
     log("");
     log(`Skill: ${r.action} ${r.path}`);
   }
-  for (const key of opts.routines ?? []) {
-    log("");
-    for (const l of desktopInstructions(key, dir).split("\n")) log(l);
-    log(`Or schedule it with launchd on a Mac: evda routine ${key} ${dir} --install`);
-  }
+  // Organizing is on unless the owner said otherwise (HQ-1246): no flag and no answer means the
+  // morning organize is installed.
+  const env = io?.env ?? process.env;
+  for (const l of installAtSetup(opts.routines ?? defaultRoutines(env), dir, { env, platform: io?.platform ?? process.platform })) log(l);
   log("");
   for (const l of INTRO.split("\n")) log(l);
   log("");

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

@@ -54,6 +54,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 +89,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 +172,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 +252,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",
@@ -511,7 +542,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 };
+}