create-evda 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,29 @@ Plain-English notes on how Iris behaves differently after each version. Not a co
 
 ## Unreleased
 
+Your phone can join your EVÐA. `evda pair` on the computer your record is on shows a one-time code
+and a QR link; it works once, for 10 minutes, and the phone gets only the parts you name (the
+journal by default). `evda sync` adds the phone once it has used the code, takes in what it wrote,
+and sends what changed; a note written on the phone lands under the day, in your words. `evda
+devices` lists what is paired and `evda remove <device>` removes one: it adds nothing more and
+receives nothing new. You can also ask your AI to pair a phone (`evda_pair_device`). Pairing goes
+through a relay that cannot read what it carries, and needs Node 22.13 or newer; everything else
+still runs on Node 20.
+
+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/README.md

@@ -91,9 +91,12 @@ apply places only what is new, in the record's own folders.
     evda_write_skill       writes or revises a skill at .claude/skills/<name>/SKILL.md. Never outside that folder, never a rule about your life
     evda_create_subrecord  an EVÐA inside this one, with the four roles and its own AGENTS.md, then doctor. Your evda.json changes only on bounded with confirmed: true
     evda_doctor            evda doctor, as a report
-    evda_check_update      whether newer EVDA tooling exists. The only tool that reaches the network
+    evda_pair_device       a one-time code and QR link for your phone, and what to do on it; the phone gets only the parts named
+    evda_sync_devices      adds a phone that used its code, takes in what your devices wrote, sends what changed
+    evda_devices           the devices paired with your EVÐA and what each reads
+    evda_check_update      whether newer EVDA tooling exists
 
-Every write appends, refuses anything shaped like a password, key or token, and says the path it wrote. The one call that leaves this machine is `evda_check_update` asking the npm registry for a version number; it carries nothing from the record and installs nothing, and the update itself is a command you run in a terminal. `evda connect` prints the setup for your record, with its path filled in:
+Every write appends, refuses anything shaped like a password, key or token, and says the path it wrote. Two kinds of call leave this machine. `evda_check_update` asks the npm registry for a version number; it carries nothing from the record and installs nothing, and the update itself is a command you run in a terminal. The device tools talk to the relay that carries your EVÐA between your own devices, and everything they send is sealed here first: the relay cannot read it. `evda connect` prints the setup for your record, with its path filled in:
 
 ```bash
 claude mcp add --scope user evda -- /path/to/node /path/to/evda.mjs mcp ~/my-evda   # Claude Code

package/bin/evda.mjs

@@ -26,7 +26,7 @@ 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 { planCircles, coverage, declare, deviceCircles, planBeside } from "../lib/circle-plan.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";
 import { excluder } from "../lib/sync-rules.mjs";
@@ -34,7 +34,8 @@ 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";
+import * as pairing from "../lib/pairing.mjs";
 
 const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
 
@@ -102,15 +103,24 @@ 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]
                                  add the preset's folders and manifests. Only adds: an existing
                                  manifest that differs is a CONFLICT and is left as it is
   evda preset diff <id> [dir]    what the preset has that this record does not
+  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
+  evda devices [dir] [--json]    the devices paired with this EVÐA, and what each reads
+  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
+                                 --json on pair, devices, remove and sync prints data for an app, no ids
   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
@@ -122,6 +132,10 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
                                  circles and grants roles and their folders; moves and changes no file.
                                  A circle rooted at "" is written as the root itself, and a circle
                                  already declared keeps its id, release, rules, mount and policy
+  evda circles default [--dry-run] [--json] [dir]
+                                 split a record that has no parts into the default two: journal (the
+                                 day files and captures) and private (everything else). A record that
+                                 has parts is left as it is. --dry-run says what it would make
   evda circles check [--plan <file>] [dir]
                                  every syncable file in exactly one circle (CHECKED n files); fails on a
                                  file no circle covers, and on a symlink, iCloud stub or oversize file.
@@ -134,6 +148,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
@@ -165,7 +185,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"];
+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"];
 function flagValue(args, name) {
   const eq = args.find((a) => a.startsWith(`--${name}=`));
   if (eq) return eq.slice(name.length + 3);
@@ -410,7 +430,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 });
     }
@@ -485,6 +505,41 @@ async function main(argv) {
       return 0;
     }
 
+    case "pair": {
+      const { dir } = pickDir(args);
+      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 }));
+      else for (const line of r.lines) console.log(line);
+      return 0;
+    }
+
+    case "devices":
+    case "sync": {
+      const { dir } = pickDir(args);
+      const relay = flagValue(args, "relay");
+      if (args.includes("--json")) {
+        console.log(JSON.stringify(cmd === "devices" ? await pairing.deviceData(dir, { relay }) : await pairing.syncData(dir, { relay })));
+        return 0;
+      }
+      const lines = await pairing[cmd](dir, { relay });
+      for (const line of lines) 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.
+      const values = new Set(VALUE_FLAGS.map((n) => args.indexOf(`--${n}`)).filter((i) => i >= 0).map((i) => i + 1));
+      const at = args.findIndex((a, i) => !a.startsWith("--") && !values.has(i));
+      const name = at >= 0 ? args[at] : flagValue(args, "name");
+      const { dir } = pickDir(at >= 0 ? args.filter((_, i) => i !== at) : args);
+      const lines = await pairing.remove(dir, name, { relay: flagValue(args, "relay") });
+      if (args.includes("--json")) console.log(JSON.stringify({ removed: String(name).trim(), lines }));
+      else for (const line of lines) console.log(line);
+      return 0;
+    }
+
     case "doctor": {
       const { dir, via } = pickDir(args);
       return doctor(dir, { via }).exit;
@@ -507,6 +562,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);
@@ -806,6 +887,16 @@ async function main(argv) {
         console.log(`wrote ${written.length} files: ${written.map((p) => relative(dir, p)).join(", ")}`);
         return 0;
       }
+      if (sub === "default") {
+        // The default parts (HQ-1925), for a record that has none: the app's one button, on the
+        // owner's yes. --dry-run is the question and writes nothing.
+        const r = defaultParts(dir, { dryRun: args.includes("--dry-run") });
+        if (args.includes("--json")) { console.log(JSON.stringify(r)); return 0; }
+        if (r.declared) console.log(`Split into parts: ${r.parts.join(", ")}. Nothing in your files moved.`);
+        else if (r.needed) console.log(`Not split into parts yet. Saying yes makes: ${r.parts.join(", ")}. Nothing was written.`);
+        else console.log(`This EVÐA is already split into parts: ${r.parts.join(", ")}. Nothing was written.`);
+        return 0;
+      }
       if (sub === "check") {
         const evda = openEvda(dir);
         // Without --plan, the plan kept beside the circles (`<circles role>/plan.json`) says what is
@@ -822,7 +913,7 @@ async function main(argv) {
         if (r.checked === 0) { console.log("FAIL CHECKED 0: nothing was examined"); return 1; }
         return r.problems.length ? 1 : 0;
       }
-      throw new EvdaError("circles needs plan, declare or check", { exit: 2 });
+      throw new EvdaError("circles needs plan, declare, default or check", { exit: 2 });
     }
 
     case "parity": {

package/create-evda.mjs

@@ -3,7 +3,7 @@
 //
 //   create-evda <dir> [--agent-name NAME] [--owner NAME] [--purpose TEXT] [--voice TEXT]
 //                     [--platform claude|chatgpt|gemini|cursor|other] [--training-off] [--yes]
-//                     [--filing everything|asked] [--no-prompt-hook]
+//                     [--filing everything|asked] [--no-prompt-hook] [--no-parts]
 //                     [--name NAME] [--layers record,ledger[,circles]] [--preset ID|none] [--force]
 //
 // On a terminal, any setup answer not given as a flag is asked, one question at a time, and setup
@@ -13,7 +13,10 @@
 //
 // Writes the manifest, the operating layer with the owner's answers in its owner section, the
 // loaders for the tools that do not read AGENTS.md on their own, the corpus, the ledger, and
-// .evda/. Then runs `evda doctor` on what it wrote. It creates no example notes: an empty record
+// .evda/. Splits the record into its default parts (HQ-1925): journal, the day files and captures,
+// and private, everything else, both held by this computer, so a phone can be added with no
+// terminal step (--no-parts leaves it unsplit, for parts declared by hand). Then runs `evda doctor`
+// on what it wrote. It creates no example notes: an empty record
 // that fills with a real life is the product. The one file it writes under record/ is today's
 // daily file holding a true event, the record's own creation, so the first session has something
 // dated to read and the owner sees where their words go.
@@ -30,12 +33,13 @@ 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";
 import { installPromptHook } from "./lib/hooks.mjs";
-import { PLATFORMS, PLATFORM_KEYS, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, trainingSection, termsSection, readerFor, INTRO } from "./lib/setup.mjs";
+import { defaultParts } from "./lib/circle-plan.mjs";
+import { PLATFORMS, PLATFORM_KEYS, PARTS_LINE, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, trainingSection, termsSection, readerFor, INTRO } from "./lib/setup.mjs";
 import { describeReaders, parseReaders } from "./lib/readers.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -53,6 +57,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,15 +66,16 @@ 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]`;
+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]`;
 
 export function parseArgs(argv) {
   const opts = {
     layers: ["record", "ledger"], force: false, name: null, owner: "", kind: "person", id: null, pointer: true, use: false,
     yes: false, trainingOff: false, agentName: null, purpose: "", voice: "", platform: null, platformName: null,
-    skill: null, routines: null, preset: null, guard: true, filing: null, promptHook: true,
+    skill: null, routines: null, preset: null, guard: true, filing: null, promptHook: true, parts: true,
   };
   const args = argv.flatMap((a) => {
     const eq = /^(--[a-z-]+)=([\s\S]*)$/.exec(a);
@@ -90,6 +96,7 @@ export function parseArgs(argv) {
     else if (a === "--skill") opts.skill = true;
     else if (a === "--no-guard") opts.guard = false;
     else if (a === "--no-prompt-hook") opts.promptHook = false;
+    else if (a === "--no-parts") opts.parts = false;
     else if (a === "--filing") {
       opts.filing = value(++i, a).trim().toLowerCase();
       if (!FILING_MODES.includes(opts.filing)) throw new EvdaError(`--filing takes ${FILING_MODES.join(" or ")}, got ${args[i]}`, { exit: 2 });
@@ -149,6 +156,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 });
@@ -297,6 +307,12 @@ export async function main(argv, io = null) {
     for (const l of planLines(plan)) log(l);
     log("");
   }
+  // The default parts, after the preset so its folders exist, and before doctor so doctor reads them.
+  if (opts.parts !== false) {
+    const parts = defaultParts(dir);
+    log(parts.parts.includes("journal") ? PARTS_LINE : `parts: ${parts.parts.join(", ")}`);
+    log("");
+  }
   const report = doctor(dir, { out: log, via: "create-evda" });
   if (report.exit !== 0) {
     console.error("\ncreate-evda wrote the layout but doctor does not pass on it. That is a bug in create-evda; the output above says where.");
@@ -322,11 +338,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("");