create-evda 0.1.8 → 0.1.10

package/bin/evda.mjs

@@ -25,7 +25,7 @@ import { grant, revoke, readGrants, access } from "../lib/grants.mjs";
 import { holderOf, HOLDER_KINDS } from "../lib/manifest.mjs";
 import { EvdaError, isEntry } from "../lib/errors.mjs";
 import { publishCommand } from "../lib/publish.mjs";
-import { checkForUpdate, summarize, stampInstalledVersion } from "../lib/update-check.mjs";
+import { checkForUpdate, summarize, stampInstalledVersion, isNewer } from "../lib/update-check.mjs";
 import { planCircles, coverage, declare, deviceCircles, planBeside, defaultParts } from "../lib/circle-plan.mjs";
 import { circleIndex, grantView } from "../lib/filechanges.mjs";
 import { mountRoot } from "../lib/declarations.mjs";
@@ -34,8 +34,9 @@ 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, message as messageTool, replies as repliesTool } from "../lib/tools.mjs";
+import { refuseSecrets, message as messageTool, replies as repliesTool, acknowledgeEntry as acknowledgeTool, acknowledgements as acknowledgementsTool } from "../lib/tools.mjs";
 import * as pairing from "../lib/pairing.mjs";
+import { watchRecord, watchRelay } from "../lib/watch.mjs";
 
 const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
 
@@ -75,6 +76,9 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
                                  a one-time owner code for the authorization page, or end every
                                  connection, or say what is connected
   evda connect [dir]             how to add that server to each client, with this record's path
+  evda plugin [dir] [--out <zip>]
+                                 build a Claude plugin for this record (its MCP server, hooks and skill,
+                                 the path baked in), for Claude Cowork: upload it in Customize, Plugins
   evda skill install [--project <dir>]
                                  install the evda skill for Claude Code (~/.claude/skills, or a project)
   evda hook install [dir]        add the keep-record Stop hook and the read guard to the record's .claude/settings.json,
@@ -101,13 +105,31 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
                                  run doctor. Writes a reversal manifest beside the proposal
   evda gather revert <manifest> [--force]
                                  undo an apply byte for byte; refused when a placed file was edited
+  evda adopt <dir> [--dry] [--map <folder>=<role>]... [--filing everything|asked] [--owner NAME]
+                    [--agent-name NAME] [--manifest <file>] [--no-hooks]
+                                 make an existing folder of notes an EVDA where it is: an Iris Vault
+                                 maps without asking, a folder it cannot place is named and answered
+                                 with --map (journal, collections, knowledge, work, or none). Writes
+                                 evda.json, AGENTS.md, one @AGENTS.md line at the end of CLAUDE.md,
+                                 .evda/ and the hooks; every other file stays byte for byte. Writes a
+                                 reversal manifest outside the folder
+  evda adopt --revert <manifest> [--force]
+                                 undo an adopt byte for byte; refused when a file it wrote was edited
+  evda secret <file> [dir] [--keychain <path>]
+                                 a credential note (in Credentials/, or --into a path of its own) with
+                                 every "in your Keychain" pointer read back and filled in, to this
+                                 terminal only (HQ-1916). No MCP tool reads a value this way
+  evda secret migrate [dir] [--dry] [--keychain <path>]
+                                 once, for Credentials/ files sealed before the Keychain move: each
+                                 value goes into the Keychain and the file keeps a pointer. All or
+                                 nothing per file; a second run changes nothing (HQ-2622)
   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] [--uninstall]
                                  print a scheduled routine for Claude, or a launchd fallback; --install
                                  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 list [--json]      the organizations this package ships, and who each suits
   evda preset show <id>          one preset's folders
   evda preset apply <id> [--dry] [dir]
                                  add the preset's folders and manifests. Only adds: an existing
@@ -116,11 +138,24 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
   evda pair [dir] [--name phone] [--parts journal[,people]] [--json]
                                  a one-time code (and a QR link) for a phone to join this EVÐA. It
                                  works once, for 10 minutes, and gives the device only the parts named
+                                 (with no --parts, the part that holds the day folder)
+  evda pair --finish [dir] [--json]
+                                 add a device that used its code, without a full sync. It never waits:
+                                 while a sync runs it says so, and that sync adds the device itself
   evda devices [dir] [--json]    the devices paired with this EVÐA, and what each reads
+  evda watch [dir]               one line (CHANGED <n>) per burst of saves in the record, and INCOMING
+                                 when a device sent something, for the Mac app's sync; runs until stopped
+  evda sync-status [dir] [--json]
+                                 what is syncing on this computer now, since when, and what is still owed
   evda remove <device> [dir]     remove a device: it adds nothing more and receives nothing new
   evda sync [dir]                add devices that used their code, take in what they sent, send what
                                  changed. Pairing needs Node 22.13 or newer; --relay <url> for another relay
+                                 One sync of a record runs at a time (the Mac app, launchd, a terminal); a
+                                 second waits for it, then says so in one line if it is still running
                                  --json on pair, devices, remove and sync prints data for an app, no ids
+  evda compact [dir] [--yes]     give back the space this computer's sync state keeps for sealed copies
+                                 nothing needs: media (which travels by name only) and copies no device is
+                                 still owed. Shows what it would remove; --yes removes them
   evda status [dir]              one screen summary
   evda publish public [dir] --out <dir> --key <seed file>
                                  the public circle as a signed plaintext export; refuses (exit 2) on a
@@ -154,8 +189,14 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
   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 acknowledge <path> [--section "## HH:MM"] [--note "<one line>"] [--by NAME] [--in dir] [--json]
+                                 you said a weighty entry back to the owner: one mark beside the
+                                 record, so no other reader says it again. Already marked prints who
+                                 did it and writes nothing. No path lists every mark
   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 browse [dir] [--folder F | --pins | --operating | --today | --index | --open P | --attachments | --attach P]  one folder of the record, the pinned folders, the files on how it works, today's note, every text file's path, one file, every PDF, image and other attachment's path, or one attachment, as JSON (the app)
+  evda capture [dir] < words     append the words on stdin to today's note, verbatim, under a new timestamped section (the app)
   evda local-model               how to run a model on your own computer and point a circle at it
   evda guard                     the Claude Code read guard (a PreToolUse hook; reads the tool call on stdin)
   evda where                     which EVDA the locator resolves to, and by which rule
@@ -176,6 +217,19 @@ function packageVersion() {
   }
 }
 
+// One command's lines of HELP, cut from it so the two cannot say different things: every entry that
+// starts with `evda <cmd>`, with the indented lines under it.
+function commandHelp(cmd) {
+  const out = [];
+  let inside = false;
+  for (const line of HELP.split("\n")) {
+    if (/^  evda /.test(line)) inside = line.startsWith(`  evda ${cmd} `) || line === `  evda ${cmd}`;
+    else if (!/^ {4,}\S/.test(line)) inside = false;
+    if (inside) out.push(line);
+  }
+  return [`usage: evda ${cmd}`, "", ...out].join("\n");
+}
+
 // A positional argument is the record when it looks like a path or IS a directory on disk. A bare
 // name that exists (`evda doctor my-evda`) must not fall through to the pointer: on 2026-09-16 it
 // did, and `evda doctor scratch` read the record ~/.evda/current pointed at instead of `scratch/`.
@@ -185,7 +239,7 @@ function isDirArg(a) {
 }
 
 // `--name value` or `--name=value`. The value of a `--name value` pair is not a positional.
-const VALUE_FLAGS = ["to", "kind", "name", "role", "by", "as", "model", "project", "hour", "weekday", "out", "key", "plan", "device", "shadow", "record-id", "env-file", "port", "host", "public-url", "log", "lifeline", "ttl", "parts", "relay"];
+const VALUE_FLAGS = ["open", "folder", "to", "kind", "name", "role", "by", "as", "model", "project", "hour", "weekday", "out", "key", "plan", "device", "shadow", "record-id", "env-file", "port", "host", "public-url", "log", "lifeline", "ttl", "parts", "relay", "keychain"];
 function flagValue(args, name) {
   const eq = args.find((a) => a.startsWith(`--${name}=`));
   if (eq) return eq.slice(name.length + 3);
@@ -272,7 +326,7 @@ async function main(argv) {
 
     case "version":
     case "--version":
-      console.log(`evda tool schema ${SCHEMA_VERSION}`);
+      console.log(`evda ${packageVersion()} (tool schema ${SCHEMA_VERSION})`);
       return 0;
 
     case "init": {
@@ -281,6 +335,9 @@ async function main(argv) {
     }
 
     case "mcp": {
+      // `--help` or `-h` anywhere prints the mcp lines of HELP and starts nothing (HQ-1368): before,
+      // `evda mcp --help` took the flag as nothing and served the default record on stdio.
+      if (args.includes("--help") || args.includes("-h")) { console.log(commandHelp("mcp")); return 0; }
       if (args[0] === "token") return mcpToken(args.slice(1));
       const { dir, flags } = pickDir(args);
       if (flags.includes("--http")) {
@@ -369,6 +426,86 @@ async function main(argv) {
       throw new EvdaError("usage: evda gather scan <source>... | questions <proposal> | answer <proposal> <question> <value> | show <proposal> | apply <proposal> --into <record> | revert <manifest>", { exit: 2 });
     }
 
+    // HQ-2797: an existing folder of notes becomes an EVDA where it is.
+    case "adopt": {
+      if (args.includes("--help") || args.includes("-h")) { console.log(commandHelp("adopt")); return 0; }
+      const ad = await import("../lib/adopt.mjs");
+      const revert = flagValue(args, "revert");
+      if (revert !== undefined || args.includes("--revert")) {
+        if (!revert || revert.startsWith("--")) throw new EvdaError("usage: evda adopt --revert <manifest> [--force]", { exit: 2 });
+        const r = ad.revertAdopt(revert, { force: args.includes("--force") });
+        for (const l of ad.revertLines(r)) console.log(l);
+        return 0;
+      }
+      const takes = ["map", "filing", "owner", "agent-name", "manifest"];
+      const maps = [];
+      const positional = [];
+      const opts = { dry: false, hooks: true };
+      for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const eq = /^--([a-z-]+)=([\s\S]*)$/.exec(a);
+        const [flag, inline] = eq ? [eq[1], eq[2]] : a.startsWith("--") ? [a.slice(2), undefined] : [null, undefined];
+        if (flag === null) { positional.push(a); continue; }
+        if (flag === "dry") { opts.dry = true; continue; }
+        if (flag === "no-hooks") { opts.hooks = false; continue; }
+        if (!takes.includes(flag)) throw new EvdaError(`unknown option --${flag}\n\n${commandHelp("adopt")}`, { exit: 2 });
+        const v = inline ?? args[++i];
+        if (v === undefined) throw new EvdaError(`--${flag} needs a value`, { exit: 2 });
+        if (flag === "map") maps.push(v);
+        else if (flag === "filing") { opts.filing = ad.filingKey(v); if (!opts.filing || !v.trim()) throw new EvdaError(`--filing takes everything or asked, got ${v}`, { exit: 2 }); }
+        else if (flag === "owner") opts.owner = v;
+        else if (flag === "agent-name") opts.agentName = v;
+        else if (flag === "manifest") opts.manifestOut = v;
+      }
+      if (positional.length !== 1) throw new EvdaError(commandHelp("adopt"), { exit: 2 });
+      const target = resolve(positional[0]);
+      opts.map = ad.parseMapArgs(maps);
+      opts.version = packageVersion();
+      // The filing question, asked the way setup asks it, when there is a terminal and no answer.
+      if (!opts.dry && opts.filing === undefined && process.stdin.isTTY && process.stdout.isTTY) {
+        const { createInterface } = await import("node:readline/promises");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try { while (!opts.filing) opts.filing = ad.filingKey(await rl.question(`${ad.FILING_QUESTION(opts.agentName)} `)); } finally { rl.close(); }
+      }
+      opts.filing ??= null;
+      const r = ad.adopt(target, opts);
+      for (const l of r.lines) console.log(l);
+      if (r.dry) {
+        if (r.questions.length) { console.log("\nBefore it can be adopted:"); for (const q of r.questions) console.log(`  ${q}`); }
+        else console.log(`\nNothing was written. Run it without --dry to adopt ${target}.`);
+        return 0;
+      }
+      console.log("");
+      for (const l of ad.connectLines(target, opts.filing)) console.log(l);
+      return r.exit;
+    }
+
+    // HQ-1916: a credential note's Keychain pointers, read back and printed to this terminal only.
+    // No MCP tool calls into this, on purpose -- the whole point of the Keychain move is that no AI
+    // reads the value; only the owner does, on their own Mac.
+    case "secret": {
+      const { dir, rest } = pickDir(args);
+      const file = rest[0];
+      if (!file) throw new EvdaError("usage: evda secret <file> [dir] [--keychain <path>] | evda secret migrate [dir] [--dry] [--keychain <path>]", { exit: 2 });
+      // HQ-2622: the one-time move of Credentials/ files sealed before HQ-1916 into the Keychain.
+      if (file === "migrate") {
+        const cm = await import("../lib/credentials-migrate.mjs");
+        const r = cm.migrateCredentials(dir, { keychainPath: flagValue(args, "keychain") ?? process.env.EVDA_KEYCHAIN_PATH ?? null, dry: args.includes("--dry") });
+        for (const l of cm.migrateLines(r)) console.log(l);
+        return r.kept ? 1 : 0;
+      }
+      const g2 = await import("../lib/gather.mjs");
+      const k = await import("../lib/keychain.mjs");
+      const abs = file.includes("/") ? resolve(dir, file) : join(dir, g2.CREDENTIALS, file);
+      if (!existsSync(abs)) throw new EvdaError(`REFUSED: no file at ${abs}.`, { code: "NOT_FOUND", exit: 2 });
+      const text = readFileSync(abs, "utf8");
+      const r = k.resolvePointers(text, { keychainPath: flagValue(args, "keychain") ?? process.env.EVDA_KEYCHAIN_PATH ?? null });
+      console.log(r.text);
+      if (!r.resolved && !r.failed) console.log(`\nSKIPPED Keychain: ${abs} holds no "in your Keychain" pointer -- its value(s) never left the file (not macOS at apply, or the write failed then)`);
+      else console.log(`\nCHECKED ${r.resolved} Keychain pointer(s) resolved, ${r.failed} could not be read`);
+      return r.failed ? 1 : 0;
+    }
+
     case "look-back": {
       const { dir } = pickDir(args);
       const { lookBack } = await import("../lib/organize.mjs");
@@ -421,6 +558,16 @@ async function main(argv) {
       return st.registered && st.file && st.current && g.registered && g.file && (!ph.registered || (ph.file && ph.current)) ? 0 : 1;
     }
 
+    case "plugin": {
+      // evda plugin [dir] [--out <zip>]   the one way Cowork reaches a record (HQ-2802)
+      const out = flagValue(args, "out");
+      const { dir } = pickDir(args);
+      const { buildPlugin, uploadLines } = await import("../lib/plugin.mjs");
+      const r = buildPlugin(dir, { out });
+      for (const l of uploadLines(r)) console.log(l);
+      return 0;
+    }
+
     case "connect": {
       // How to add this record's MCP server to each client, with the record's path filled in.
       const { dir } = pickDir(args);
@@ -441,6 +588,12 @@ async function main(argv) {
       const [sub, ...rest] = args;
       if (sub === "list") {
         const all = presets.listPresets();
+        // --json: one line the EVÐA app's setup reads its choices from, so it offers exactly what
+        // create-evda --preset accepts (HQ-1217).
+        if (rest.includes("--json")) {
+          console.log(JSON.stringify(all.map((p) => ({ id: p.id, title: p.title, for: p.for }))));
+          return all.length ? 0 : 1;
+        }
         for (const p of all) console.log(`${p.id.padEnd(20)} ${p.title}: ${p.for}`);
         console.log(`CHECKED ${all.length} presets`);
         return all.length ? 0 : 1;
@@ -469,7 +622,7 @@ async function main(argv) {
       const plan = presets.applyPreset(dir, id, { dry });
       console.log(`evda preset apply ${id}${dry ? " --dry" : ""}  ${plan.root}`);
       for (const l of presets.planLines(plan)) console.log(l);
-      const wrote = plan.create.length + plan.write.length + plan.views.length + plan.proposed.length + plan.roles.length;
+      const wrote = plan.create.length + plan.write.length + plan.files.length + plan.views.length + plan.proposed.length + plan.roles.length;
       console.log(`CHECKED ${plan.folders} preset folders  ${plan.create.length} ${dry ? "to create" : "created"}, ${plan.write.length} manifest(s) ${dry ? "to write" : "written"}, ${plan.matched.length} skipped, ${plan.conflicts.length} conflict(s)`);
       if (!dry && wrote === 0 && !plan.conflicts.length) console.log("Nothing was written: the record already has this preset.");
       if (dry) console.log("Dry run: nothing was written.");
@@ -507,6 +660,12 @@ async function main(argv) {
 
     case "pair": {
       const { dir } = pickDir(args);
+      // --finish: add a device that used its code, without a full sync (HQ-2017).
+      if (args.includes("--finish")) {
+        if (args.includes("--json")) console.log(JSON.stringify(await pairing.finishData(dir, { relay: flagValue(args, "relay") })));
+        else for (const line of await pairing.finish(dir, { relay: flagValue(args, "relay") })) console.log(line);
+        return 0;
+      }
       const r = await pairing.pair(dir, { name: flagValue(args, "name"), parts: flagValue(args, "parts"), relay: flagValue(args, "relay") });
       // --json is for an app (the EVÐA Mac app, HQ-1925): the code and its QR link, and nothing with an id.
       if (args.includes("--json")) console.log(JSON.stringify({ name: r.name, code: r.code, qr: r.qr, computer: r.computer, expiresAt: r.expiresAt, parts: r.parts }));
@@ -514,6 +673,16 @@ async function main(argv) {
       return 0;
     }
 
+    case "sync-status": {
+      // What is syncing on this computer now, for the Mac app (HQ-2041): who holds the state and
+      // since when, and how much is still owed. Never waits.
+      const { dir } = pickDir(args);
+      const r = await pairing.statusData(dir, { relay: flagValue(args, "relay") });
+      if (args.includes("--json")) console.log(JSON.stringify(r));
+      else console.log(r.holder ? `Syncing: ${r.holder.by === "tick" ? "the background sync" : r.holder.by === "app" ? "the EVÐA app" : "a command"} (${r.holder.op}) since ${new Date(r.holder.since).toLocaleTimeString()}.` : "Nothing is syncing.", r.owed ? `${r.owed} change(s) still owed to a device.` : "");
+      return 0;
+    }
+
     case "devices":
     case "sync": {
       const { dir } = pickDir(args);
@@ -527,6 +696,24 @@ async function main(argv) {
       return 0;
     }
 
+    case "watch": {
+      // For the Mac app (HQ-2068): one line a burst of saves in the record, so it syncs in seconds.
+      // Runs until it is stopped; the app runs the sync, this only says when.
+      const { dir } = pickDir(args);
+      watchRecord(dir, (paths) => console.log(`CHANGED ${paths.length}`));
+      // And the relay: a device's note says INCOMING within seconds, so the app syncs it in then.
+      const relay = flagValue(args, "relay");
+      if (!pairing.pairingUnsupported()) watchRelay(() => pairing.inboundMailboxes(dir, { relay }), () => console.log("INCOMING"));
+      console.log("WATCHING");
+      return await new Promise(() => undefined);
+    }
+
+    case "compact": {
+      const { dir } = pickDir(args);
+      for (const line of await pairing.compact(dir, { yes: args.includes("--yes") })) console.log(line);
+      return 0;
+    }
+
     case "remove": {
       // The device's name comes first and is never read as the record, even when a folder by
       // that name sits in the working directory.
@@ -572,7 +759,7 @@ async function main(argv) {
       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}.`);
+      console.log(`Filed the message ${r.id} at ${r.path}. This does not confirm it reached the owner's phone.`);
       return 0;
     }
 
@@ -588,6 +775,33 @@ async function main(argv) {
       return 0;
     }
 
+    case "acknowledge": {
+      // HQ-2060. A note may hold a slash, so the record is --in <dir> or the locator, as with
+      // note and message. No path lists what every reader has already acknowledged.
+      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 json = args.includes("--json") && (args.splice(args.indexOf("--json"), 1), true);
+      const dirArg = take("--in");
+      const section = take("--section");
+      const note = take("--note");
+      const by = take("--by");
+      const dir = locate({ explicit: dirArg }).dir;
+      const evda = openEvda(dir);
+      const path = args.filter((a) => !a.startsWith("--")).join(" ").trim();
+      if (!path) {
+        const r = acknowledgementsTool(evda);
+        if (json) { console.log(JSON.stringify(r, null, 2)); return 0; }
+        for (const m of r.marks) console.log(`- ${m.key}  (${m.by ?? "unknown"}, ${m.at}): ${m.note}`);
+        console.log(`CHECKED ${r.count} acknowledged entr${r.count === 1 ? "y" : "ies"}`);
+        return 0;
+      }
+      const r = acknowledgeTool(evda, { path, ...(section === undefined ? {} : { section }), ...(note === undefined ? {} : { note }), ...(by === undefined ? {} : { by }) });
+      if (json) { console.log(JSON.stringify(r, null, 2)); return 0; }
+      const what = r.section ? `${r.path} "${r.section}"` : r.path;
+      if (!r.first) console.log(`Already acknowledged by ${r.by ?? "an earlier reader"} at ${r.at}: ${r.note}\nNothing was written. Say nothing about ${what} unless the owner brings it up.`);
+      else console.log(`Marked ${what} acknowledged, as ${r.by}. You reached it first, so every later reader sees this mark and stays quiet.`);
+      return 0;
+    }
+
     case "release": {
       const { dir, entry } = pickReleaseArgs(args);
       const r = releaseNote(openEvda(dir), entry);
@@ -607,6 +821,37 @@ async function main(argv) {
       return 0;
     }
 
+    case "browse": {
+      // The owner's app reads the record through this (HQ-2038): the pinned folders, one folder's
+      // children, or one file opened, each as one JSON line. The rules are lib/browse.mjs.
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const b = await import("../lib/browse.mjs");
+      const bctx = b.browseContext(evda);
+      const open = flagValue(args, "open");
+      const folder = flagValue(args, "folder");
+      const attach = flagValue(args, "attach");
+      const answer = attach !== undefined ? b.attachEntry(evda, attach, { bctx }) : args.includes("--attachments") ? b.attachments(evda, { bctx }) : open !== undefined ? b.openEntry(evda, open, { bctx }) : args.includes("--pins") ? b.pins(evda, { bctx }) : args.includes("--operating") ? b.operating(evda, { bctx }) : args.includes("--today") ? b.today(evda, { bctx }) : args.includes("--index") ? b.index(evda, { bctx }) : b.browse(evda, folder ?? "", { bctx });
+      // Written to the end before returning: on macOS a pipe write is asynchronous, and the exit
+      // that follows cut anything past the pipe's 64 KB buffer (his 71 KB CLAUDE.md, HQ-2038).
+      await new Promise((done) => process.stdout.write(`${JSON.stringify(answer)}\n`, done));
+      return 0;
+    }
+
+    case "capture": {
+      // The app's capture box (HQ-2038): the words come on stdin, verbatim, and are appended to
+      // today's daily note under a new timestamped section, by the same write evda_write makes.
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const chunks = [];
+      for await (const c of process.stdin) chunks.push(c);
+      const words = Buffer.concat(chunks).toString("utf8");
+      const { capture } = await import("../lib/browse.mjs");
+      const r = capture(evda, words);
+      await new Promise((done) => process.stdout.write(`${JSON.stringify(r)}\n`, done));
+      return 0;
+    }
+
     case "readers": {
       const { dir } = pickDir(args);
       const evda = openEvda(dir);
@@ -726,6 +971,13 @@ async function main(argv) {
       console.log(summarize(result));
       if (result.status === "CHECK_FAILED") return 1;
       if (result.status !== "UPDATE_AVAILABLE" && result.status !== "UNSTAMPED") return 0;
+      // HQ-2718: upgrade writes the block THIS tool ships and stamps THIS tool's version. Run by an
+      // installed evda older than the registry, it used to do that and exit 0, leaving the record
+      // behind while the line above told the owner to run the command they had just run.
+      if (isNewer(result.latest, packageVersion())) {
+        console.log(`update: this evda is ${packageVersion()}, older than ${result.latest}, so it cannot install ${result.latest}. Nothing was changed. Run "npx -y -p create-evda@latest evda update" to take it.`);
+        return 1;
+      }
       const upgradeRc = await main(["upgrade", dir]);
       if (upgradeRc !== 0) return upgradeRc;
       return main(["migrate", dir]);
@@ -963,7 +1215,25 @@ async function main(argv) {
 
 // Through realpath: an installed bin is a symlink and resolve() does not follow it (see the same
 // guard in create-evda.mjs, and test/bins.test.mjs).
+/**
+ * A command the EVÐA app runs ends when the app does (HQ-2041). The app names itself in
+ * EVDA_PARENT_PID; once this process's parent is no longer that pid (the app quit or crashed and
+ * this process was handed to launchd), it stops. A lock it held is then stale and taken over.
+ */
+export function watchParent(env = process.env, { ppid = () => process.ppid, exit = (c) => process.exit(c), everyMs = 1000 } = {}) {
+  const want = Number(env.EVDA_PARENT_PID);
+  if (!Number.isInteger(want) || want <= 0) return null;
+  const check = () => {
+    if (ppid() !== want) exit(1);
+  };
+  check();
+  const t = setInterval(check, everyMs);
+  t.unref();
+  return t;
+}
+
 if (process.argv[1] && isEntry(process.argv[1], import.meta.url)) {
+  watchParent();
   main(process.argv.slice(2)).then(
     (code) => process.exit(code),
     (e) => {

package/create-evda.mjs

@@ -33,6 +33,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 { everyChatSetupLines } from "./lib/every-chat.mjs";
 import { defaultRoutines, installAtSetup } from "./lib/routines.mjs";
 import { installHook } from "./lib/hooks.mjs";
 import { applyPreset, listPresets, planLines, presetIds, NONE } from "./lib/presets.mjs";
@@ -69,7 +70,14 @@ const FOLDER_TYPES = {
   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] [--no-parts] [--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]`;
+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] [--no-parts] [--yes] [--name NAME] [--kind person|agent|company] [--id ATLAS-ID] [--layers record,ledger] [--skill] [--routines morning,weekly|--no-routines] [--preset ${presetIds().join("|")}|none] [--use] [--no-pointer] [--no-guard]
+
+On a Mac, setup installs the morning organize as a launchd job (daily at 8:00, your own Claude) unless --no-routines, --yes included, and says so before it does.`;
+
+// `--help` and `-h` anywhere print this and nothing else (HQ-1368): before, `--help` was "unknown
+// option" and `-h` was taken as the folder to create.
+export const HELP_FLAGS = ["--help", "-h"];
+export const wantsHelp = (argv) => argv.some((a) => HELP_FLAGS.includes(a));
 
 export function parseArgs(argv) {
   const opts = {
@@ -276,8 +284,9 @@ export function needsAsking(opts) {
 // only when both stdin and stdout are a terminal. A piped or redirected run is a script, and a
 // script is never asked anything.
 export async function main(argv, io = null) {
-  let opts = parseArgs(argv);
   const out = io?.out ?? console.log;
+  if (wantsHelp(argv)) { out(USAGE); return 0; }
+  let opts = parseArgs(argv);
   const log = opts.quiet ? () => {} : out;
   const tty = io ? Boolean(io.interactive) : Boolean(process.stdin.isTTY && process.stdout.isTTY);
   const asked = tty && !opts.yes && needsAsking(opts);
@@ -332,7 +341,11 @@ export async function main(argv, io = null) {
   }
   log("");
   log("Or connect your AI to this record from any folder, through the evda MCP server. No key and no model call in EVÐA:");
-  for (const c of clients(dir)) if (c.key !== "project") { log(`  ${c.label}:`); for (const l of c.text.split("\n")) log(`    ${l}`); }
+  for (const c of clients(dir)) if (c.key !== "project" && c.key !== "every-chat") { log(`  ${c.label}:`); for (const l of c.text.split("\n")) log(`    ${l}`); }
+  // The every-chat line (HQ-2205), from the one source: a chat that never calls an evda tool is
+  // reached only by the app's own every-chat setting.
+  log("");
+  for (const l of everyChatSetupLines(manifest.filing ?? null)) log(l);
   if (opts.skill) {
     const r = installSkill({ env: io?.env ?? process.env });
     log("");
@@ -341,7 +354,7 @@ export async function main(argv, io = null) {
   // 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);
+  for (const l of installAtSetup(opts.routines ?? defaultRoutines(env), dir, { env, platform: io?.platform ?? process.platform, say: out, launchctl: io?.launchctl ?? null })) log(l);
   log("");
   for (const l of INTRO.split("\n")) log(l);
   log("");