create-evda 0.1.4 → 0.1.6

package/bin/evda.mjs

@@ -6,9 +6,9 @@
 // ~/.evda/current. Nothing assumes it was launched inside one.
 
 import { resolve, join, relative } from "node:path";
-import { readFileSync, writeFileSync, statSync } from "node:fs";
+import { readFileSync, writeFileSync, statSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { openEvda, readManifest, readVersion, writeVersion, findRoot, SCHEMA_VERSION } from "../lib/manifest.mjs";
+import { openEvda, readManifest, readVersion, writeVersion, findRoot, SCHEMA_VERSION, manifestPath } from "../lib/manifest.mjs";
 import { locate, setPointer, pointerPath } from "../lib/locate.mjs";
 import { resolveAll, agentsFile } from "../lib/roles.mjs";
 import { doctor } from "../lib/doctor.mjs";
@@ -24,6 +24,17 @@ import { resolveReference } from "../lib/resolvers.mjs";
 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 { planCircles, coverage, declare, deviceCircles, planBeside } 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";
+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";
 
 const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
 
@@ -36,6 +47,12 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
   evda upgrade [dir]             replace the installer-owned block of the operating layer; touch nothing else
   evda digest [dir]              print the instruction-only digest of the operating layer
   evda migrate [dir]             forward migrations, each saying what it cannot reverse
+  evda check-update [dir] [--force]
+                                 ask npm for the latest create-evda, throttled to once an hour;
+                                 never silent, a failure prints CHECK_FAILED rather than looking current
+  evda update [dir]              check-update, then upgrade and migrate if a newer version exists.
+                                 Run this through npx so the CLI itself is current first:
+                                   npx -y -p create-evda@latest evda update
   evda vector <vdir> [--check]   the conformance projection of <vdir>/ledger.md (Spec 04 vectors)
   evda references [dir] [--resolve] [--timeout ms]
                                  every reference in the record, its folder's connector, and with
@@ -50,22 +67,82 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
                                  may that record read the circle? exit 0 yes, 2 refused, with why
   evda mcp [dir]                 serve the record over MCP on stdio, for Claude Code, Codex or the
                                  Claude desktop app. No key and no model call: the AI is the owner's
+  evda mcp --http --public-url <https url> [--port 8378] [--host 127.0.0.1] [--log file] [dir]
+                                 the same server over streamable HTTP, behind OAuth, for the Claude
+                                 apps through a tunnel. Binds to localhost; the tunnel is the TLS
+  evda mcp token --new [--ttl 24h] | --revoke-all | --status [dir]
+                                 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 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,
+                                 and the prompt hook that files each message when evda.json says "filing": "everything"
+  evda hook status [dir]         whether each is installed and current
   evda organize [dir] [--dry-run] [--with-ai] [--model M]
                                  file captures into their day and write a report of what belongs where.
                                  Moves nothing. --with-ai hands the judgment to the owner's claude -p
+  evda gather scan <source>... [--into <record>] [--out <file>] [--with-ai] [--model M]
+                                 walk a pile (folders, export files), type each file, and write a
+                                 proposal: a preset, folders, a placement per item. Writes nothing
+                                 into a source or a record; the proposal goes to --out, or
+                                 $EVDA_GATHER_DIR, or ~/.evda/gather/. --into names the record it
+                                 would grow: what it already holds is left out of the proposal
+  evda gather questions <proposal>
+                                 what the owner has to decide, only where it changes a placement
+  evda gather answer <proposal> <question> <value>
+                                 record one answer on the proposal and say what it re-placed
+  evda gather show <proposal> [--all]
+                                 the proposal in plain words
+  evda gather apply <proposal> --into <record> [--copy|--move] [--dry] [--manifest <file>]
+                                 after the owner's yes: write the placements into a record (a new
+                                 one is made with the proposal's preset), copying by default, then
+                                 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 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]
                                  print a scheduled routine for Claude, or a launchd fallback; --install
                                  writes the launchd job, and nothing is scheduled without it
+  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 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
+                                 path another circle covers or a private name or path in the bytes
+  evda circles plan --plan <file> [dir]
+                                 which folders each circle of the plan gets on this disk. Writes nothing
+  evda circles declare --plan <file> [--record-id <id>] [dir]
+                                 write the plan's circles and device grants into the record. Adds the
+                                 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 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.
+                                 Without --plan, reads <circles role>/plan.json for the excludes
+  evda parity --plan <file> --device <name> --shadow <dir> [dir]
+                                 the device's shadow equals the record for the circles it holds, byte for
+                                 byte, and holds nothing of a circle it may never hold (Spec 08 S1)
+  evda work [dir] [--env-file F] [--json]
+                                 the record's efforts from its work role: THE HARLEQUIN by vault_path
+                                 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 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
+  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
   evda use <dir>                 point ~/.evda/current at a record
   evda init <dir> [--yes] [--agent-name N] [--owner O] [--purpose P] [--voice V]
                 [--platform claude|chatgpt|gemini|cursor|other] [--training-off] [--layers record,ledger]
+                [--preset <id>|none]
                                  the same as create-evda: asks on a terminal, runs from flags otherwise
 
 Locator order: directory argument, $EVDA_HOME, the working directory's ancestors, ~/.evda/current.
@@ -88,7 +165,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"];
+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"];
 function flagValue(args, name) {
   const eq = args.find((a) => a.startsWith(`--${name}=`));
   if (eq) return eq.slice(name.length + 3);
@@ -106,6 +183,63 @@ function pickDir(args) {
   return { dir: found.dir, via: found.via, flags, rest };
 }
 
+// `release`'s own positional is a printed entry path, which always contains a "/" (Spec: entries
+// live under record/), so pickDir's "any positional with a slash is the record" rule always ate it.
+// The record here comes from the working directory (or the pointer) by default; a positional is
+// only ever the record when it is a SECOND positional that is itself an EVDA on disk, never the
+// entry path itself.
+function pickReleaseArgs(args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  let explicit = null;
+  let entryParts = positional;
+  if (positional.length > 1) {
+    const last = positional[positional.length - 1];
+    try {
+      if (statSync(last).isDirectory() && existsSync(manifestPath(resolve(last)))) {
+        explicit = last;
+        entryParts = positional.slice(0, -1);
+      }
+    } catch { /* not a directory on disk -> it's part of the entry path */ }
+  }
+  const found = locate({ explicit });
+  return { dir: found.dir, entry: entryParts.join(" ") };
+}
+
+// `evda mcp token`: the owner's side of the remote server's authorization. Printed here, on the
+// machine that holds the record, and typed into the authorization page: never in a URL or a log.
+async function mcpToken(args) {
+  const { dir, flags } = pickDir(args);
+  const auth = await import("../lib/mcp-auth.mjs");
+  const store = auth.openStore(auth.authDir(openEvda(dir)));
+  if (flags.includes("--new")) {
+    const ttl = parseDuration(flagValue(args, "ttl") ?? "24h");
+    const { code, expires } = auth.newOwnerCode(store, { ttlMs: ttl });
+    console.log(code);
+    console.error(`One owner code, good once, until ${new Date(expires).toISOString()}. Type it into the page Claude opens when you connect.`);
+    return 0;
+  }
+  if (flags.includes("--revoke-all")) {
+    const n = auth.revokeAll(store);
+    console.log(`Revoked ${n.clients} client(s), ${n.access} access token(s), ${n.refresh} refresh token(s) and ${n.owner} owner code(s). A connector stops at its next call and has to connect again.`);
+    return 0;
+  }
+  if (flags.includes("--status")) {
+    const s = auth.status(store);
+    console.log(`${s.clients.length} client(s), ${s.access} live access token(s), ${s.refresh} live refresh token(s), ${s.ownerCodes.length} open owner code(s). State: ${store.file}`);
+    for (const c of s.clients) console.log(`  ${c.client_id} ${c.client_name ?? "(no name)"} registered ${new Date(c.created).toISOString()} -> ${c.redirects.join(", ")}`);
+    return 0;
+  }
+  throw new EvdaError("REFUSED: evda mcp token needs --new [--ttl 24h], --revoke-all or --status.", { code: "USAGE", exit: 2 });
+}
+
+function parseDuration(s) {
+  const m = /^(\d+)(m|h|d)$/.exec(String(s));
+  if (!m) throw new EvdaError(`REFUSED: --ttl is a number and m, h or d (got ${JSON.stringify(s)}).`, { code: "BAD_TTL", exit: 2 });
+  const ms = Number(m[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+  if (ms < 60_000 || ms > 7 * 86_400_000) throw new EvdaError("REFUSED: --ttl is between 1m and 7d.", { code: "BAD_TTL", exit: 2 });
+  return ms;
+}
+
 async function main(argv) {
   const [cmd, ...args] = argv;
   switch (cmd) {
@@ -127,8 +261,19 @@ async function main(argv) {
     }
 
     case "mcp": {
+      if (args[0] === "token") return mcpToken(args.slice(1));
+      const { dir, flags } = pickDir(args);
+      if (flags.includes("--http")) {
+        // The record over streamable HTTP with OAuth in front (HQ-1378), for a tunnel to publish.
+        const port = Number(flagValue(args, "port") ?? 8378);
+        const publicUrl = flagValue(args, "public-url");
+        if (!Number.isInteger(port) || port < 0 || port > 65535) throw new EvdaError("REFUSED: --port must be a port number.", { code: "BAD_PORT", exit: 2 });
+        if (!publicUrl) throw new EvdaError("REFUSED: --http needs --public-url, the https address the tunnel serves this on (every URL in the OAuth metadata is built from it).", { code: "NO_PUBLIC_URL", exit: 2 });
+        const { serveHttp } = await import("../lib/mcp-http.mjs");
+        await serveHttp({ dir, version: packageVersion(), port, host: flagValue(args, "host") ?? "127.0.0.1", publicUrl, logFile: flagValue(args, "log"), lifeline: flagValue(args, "lifeline") });
+        return 0;
+      }
       // The record as an MCP server on stdio. stdout is the protocol; everything else is stderr.
-      const { dir } = pickDir(args);
       const { serve } = await import("../lib/mcp.mjs");
       await serve({ dir, version: packageVersion() });
       return 0;
@@ -142,6 +287,68 @@ async function main(argv) {
       return r.exit;
     }
 
+    case "gather": {
+      const g = await import("../lib/gather.mjs");
+      const [sub, ...rest] = args;
+      const values = new Set(["out", "model", "into", "manifest", "owner"].map((n) => rest.indexOf(`--${n}`)).filter((i) => i >= 0).map((i) => i + 1));
+      const positional = rest.filter((a, i) => !a.startsWith("--") && !values.has(i));
+      if (sub === "scan") {
+        if (!positional.length) throw new EvdaError("usage: evda gather scan <source>... [--into <record>] [--out <file>] [--with-ai] [--model M]", { exit: 2 });
+        let p = g.gather(positional, { into: flagValue(rest, "into") ?? null });
+        let exit = 0;
+        if (rest.includes("--with-ai")) {
+          const r = g.withOwnersAi(p, { model: flagValue(rest, "model") ?? null });
+          p = r.p;
+          if (!r.ok) exit = 1;
+        }
+        const out = g.saveProposal(p, flagValue(rest, "out") ?? join(g.gatherDir(), `${p.id}.json`));
+        console.log(g.summaryText(p));
+        if (p.ai) console.log(`\nYour AI: ${p.ai.status}${p.ai.why ? `, ${p.ai.why}` : `, ${p.ai.applied} of ${p.ai.asked} typed, ${p.ai.ignored} line(s) not read`}`);
+        console.log(`\nProposal written to ${out}`);
+        for (const l of g.checkedLines(p)) console.log(l);
+        return p.counts.items === 0 && !p.counts.chats ? 1 : exit;
+      }
+      if (sub === "questions" || sub === "show") {
+        if (!positional[0]) throw new EvdaError(`usage: evda gather ${sub} <proposal>`, { exit: 2 });
+        const { p, abs } = g.loadProposal(positional[0]);
+        if (sub === "show") { console.log(g.summaryText(p, { detail: rest.includes("--all") })); console.log(`\n${abs}`); for (const l of g.checkedLines(p)) console.log(l); return 0; }
+        const open = p.questions.filter((q) => q.answer === undefined);
+        for (const q of open) console.log(`[${q.id}] ${q.text} (${q.options.join(" / ")})  moves ${q.affects.length} item(s)`);
+        for (const q of p.questions.filter((x) => x.answer !== undefined)) console.log(`answered [${q.id}] ${q.answer}`);
+        console.log(open.length ? `CHECKED ${p.questions.length} question(s)  ${open.length} open` : `SKIPPED questions: none open on ${abs}`);
+        return 0;
+      }
+      if (sub === "answer") {
+        const [ref, question, value] = positional;
+        if (!value) throw new EvdaError("usage: evda gather answer <proposal> <question> <value>", { exit: 2 });
+        const { p, abs } = g.loadProposal(ref);
+        const r = g.answer(p, question, value);
+        g.saveProposal(r.proposal, abs);
+        console.log(`Recorded ${question} = ${value} on ${abs}`);
+        for (const l of g.answerLines(r)) console.log(l);
+        console.log(`CHECKED ${r.proposal.items.length} items  ${r.moved.length} re-placed`);
+        return 0;
+      }
+      if (sub === "apply") {
+        const into = flagValue(rest, "into");
+        if (!positional[0] || !into) throw new EvdaError("usage: evda gather apply <proposal> --into <record> [--copy|--move] [--dry] [--manifest <file>] [--owner NAME]", { exit: 2 });
+        if (rest.includes("--copy") && rest.includes("--move")) throw new EvdaError("REFUSED: --copy and --move together. Copy is the default; pass --move to take the files out of the sources.", { exit: 2 });
+        const a = await import("../lib/gather-apply.mjs");
+        const { p, abs } = g.loadProposal(positional[0]);
+        const r = await a.applyGather(p, into, { mode: rest.includes("--move") ? "move" : "copy", dry: rest.includes("--dry"), manifestOut: flagValue(rest, "manifest") ?? null, owner: flagValue(rest, "owner") ?? "", proposalPath: abs });
+        for (const l of r.lines) console.log(l);
+        return r.dry ? 0 : r.doctor.exit === 0 ? 0 : 1;
+      }
+      if (sub === "revert") {
+        if (!positional[0]) throw new EvdaError("usage: evda gather revert <manifest> [--force]", { exit: 2 });
+        const a = await import("../lib/gather-apply.mjs");
+        const r = a.revertGather(positional[0], { force: rest.includes("--force") });
+        for (const l of a.revertLines(r)) console.log(l);
+        return 0;
+      }
+      throw new EvdaError("usage: evda gather scan <source>... | questions <proposal> | answer <proposal> <question> <value> | show <proposal> | apply <proposal> --into <record> | revert <manifest>", { exit: 2 });
+    }
+
     case "look-back": {
       const { dir } = pickDir(args);
       const { lookBack } = await import("../lib/organize.mjs");
@@ -160,6 +367,40 @@ async function main(argv) {
       return 0;
     }
 
+    case "hook": {
+      // evda hook install [dir] | status [dir]   the keep-record Stop hook for Claude Code (HQ-1376)
+      const [sub, ...rest] = args;
+      if (!["install", "status"].includes(sub)) throw new EvdaError("usage: evda hook install [dir] | status [dir]", { exit: 2 });
+      const { dir } = pickDir(rest);
+      // Every hook create-evda installs for a Claude owner (HQ-1377): the keep-record Stop hook and
+      // the read guard, both in the record's own settings and nowhere else.
+      const hooks = await import("../lib/hooks.mjs");
+      const { installGuard, guardStatus } = await import("../lib/connect.mjs");
+      if (sub === "install") {
+        const r = hooks.installHook(dir);
+        console.log(`${r.action}: ${r.settings} runs ${r.hook} in this record's Claude Code sessions, and nowhere else`);
+        const g = installGuard(dir);
+        console.log(`read guard ${g.action} ${g.path}`);
+        // The prompt hook (HQ-1385) files every message, so only the owner's "everything" installs it.
+        const { filingOf } = await import("../lib/day-file.mjs");
+        const { readManifest } = await import("../lib/manifest.mjs");
+        const filing = filingOf(readManifest(dir));
+        if (filing === "everything") {
+          const p = hooks.installPromptHook(dir);
+          console.log(`prompt hook ${p.action}: ${p.settings} runs ${p.hook}, which files each message the owner sends`);
+        } else console.log(`prompt hook not installed: evda.json says ${filing ? `"filing": "${filing}"` : "nothing about filing yet"}, and it is installed only for "everything"`);
+        return 0;
+      }
+      const st = hooks.hookStatus(dir);
+      if (st.problem) { console.log(st.problem); return 1; }
+      console.log(st.registered ? (st.file ? (st.current ? `installed and current: ${hooks.SETTINGS_REL} runs ${hooks.HOOK_REL}` : `installed, older than the shipped hook: run \`evda hook install\``) : `registered, but ${hooks.HOOK_REL} is missing: run \`evda hook install\``) : "not installed: run `evda hook install`");
+      const ph = hooks.promptHookStatus(dir);
+      console.log(ph.registered ? (ph.file ? (ph.current ? `prompt hook installed and current: ${hooks.SETTINGS_REL} runs ${hooks.PROMPT_HOOK_REL}` : "prompt hook installed, older than the shipped hook: run `evda hook install`") : `prompt hook registered, but ${hooks.PROMPT_HOOK_REL} is missing: run \`evda hook install\``) : "prompt hook not installed (it is only for an owner who chose to file everything)");
+      const g = guardStatus(dir);
+      console.log(g.registered ? (g.file ? `read guard installed: ${hooks.SETTINGS_REL} runs ${g.target ?? "evda guard through npx"}` : `read guard registered, but ${g.target} is missing: run \`evda hook install\``) : "read guard not installed: run `evda hook install`");
+      return st.registered && st.file && st.current && g.registered && g.file && (!ph.registered || (ph.file && ph.current)) ? 0 : 1;
+    }
+
     case "connect": {
       // How to add this record's MCP server to each client, with the record's path filled in.
       const { dir } = pickDir(args);
@@ -174,6 +415,62 @@ async function main(argv) {
       return routineMain(args, { pickDir, flagValue });
     }
 
+    case "preset": {
+      // evda preset list | show <id> | apply <id> [--dry] [dir] | diff <id> [dir]
+      const presets = await import("../lib/presets.mjs");
+      const [sub, ...rest] = args;
+      if (sub === "list") {
+        const all = presets.listPresets();
+        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;
+      }
+      const id = rest.find((a) => !a.startsWith("--"));
+      if (!["show", "apply", "diff"].includes(sub) || !id) throw new EvdaError("usage: evda preset list | show <id> | apply <id> [--dry] [dir] | diff <id> [dir]", { exit: 2 });
+      if (sub === "show") {
+        const p = presets.loadPreset(id);
+        console.log(`${p.title} (${p.id}): ${p.for}`);
+        for (const f of p.folders) console.log(`  ${`${f.path}/`.padEnd(32)} ${(f.type ?? "untyped").padEnd(8)}${f.connectors?.length ? `  connectors ${f.connectors.join(", ")}` : ""}${f.note ? `  ${f.note}` : ""}`);
+        for (const c of p.circles ?? []) console.log(`  circle ${c.name} (${c.public ? "public" : "private"}, proposed only): ${c.description}`);
+        for (const [k, v] of Object.entries(p.mapping ?? {})) console.log(`  role ${k.padEnd(24)} ${v}/`);
+        for (const r of p.routines ?? []) console.log(`  routine ${r} (offered, never scheduled without a yes)`);
+        return 0;
+      }
+      const { dir } = pickDir(rest.filter((a, i) => i !== rest.indexOf(id)));
+      if (sub === "diff") {
+        const plan = presets.diffPreset(dir, id);
+        console.log(`evda preset diff ${id}  ${plan.root}`);
+        for (const l of presets.planLines(plan, { diff: true })) console.log(l);
+        if (presets.planIsEmpty(plan)) console.log(`SKIPPED preset diff: this record already has everything ${id} makes`);
+        console.log(`CHECKED ${plan.folders} preset folders  ${plan.create.length} missing, ${plan.write.length} manifest(s) missing, ${plan.matched.length} matching, ${plan.conflicts.length} conflict(s)`);
+        return 0;
+      }
+      const dry = args.includes("--dry");
+      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;
+      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.");
+      return plan.conflicts.length ? 1 : 0;
+    }
+
+    case "work": {
+      // evda work [dir] [--env-file <file>] [--json]: the record's efforts, from THE HARLEQUIN or a
+      // folder of effort files (HQ-1371). Read only.
+      const { readWork } = await import("../lib/work.mjs");
+      const { dir } = pickDir(args);
+      const envFile = flagValue(args, "env-file");
+      const r = await readWork(openEvda(dir), { envFile: envFile ? resolve(envFile) : null });
+      if (args.includes("--json")) console.log(JSON.stringify({ efforts: r.efforts, lines: r.lines }, null, 2));
+      else {
+        for (const e of r.efforts) console.log(`  ${e.id.padEnd(12)} ${String(e.status).padEnd(16)} ${(e.planned_for ?? "").padEnd(10)} ${e.title}`);
+        for (const l of r.lines) console.log(l);
+      }
+      return r.exit;
+    }
+
     case "where": {
       const found = locate({});
       console.log(`${found.dir}  (via ${found.via})`);
@@ -193,6 +490,62 @@ async function main(argv) {
       return doctor(dir, { via }).exit;
     }
 
+    case "guard":
+      return runHook();
+
+    case "note": {
+      // The words may hold a slash ("50/50"), so the record is never guessed from them: --in <dir>,
+      // or the locator.
+      const i = args.indexOf("--in");
+      const dir = locate({ explicit: i >= 0 ? args[i + 1] : undefined }).dir;
+      let words = args.filter((_, j) => i < 0 || (j !== i && j !== i + 1)).join(" ");
+      if (words === "-" || words === "") words = readFileSync(0, "utf8");
+      if (!words.trim()) throw new EvdaError('REFUSED: note needs the words, as an argument or on stdin. Nothing was written.', { exit: 2 });
+      refuseSecrets(words, "evda note");
+      const r = note(openEvda(dir), words);
+      console.log(`Noted at ${r.path}. No AI reads it until you say it can: evda release ${JSON.stringify(r.path)}`);
+      return 0;
+    }
+
+    case "release": {
+      const { dir, entry } = pickReleaseArgs(args);
+      const r = releaseNote(openEvda(dir), entry);
+      console.log(`Released ${r.path}. It reads like any other entry now.`);
+      return 0;
+    }
+
+    case "search": {
+      const { dir, rest } = pickDir(args);
+      const query = rest.join(" ").trim();
+      if (!query) throw new EvdaError("search needs words to find", { exit: 2 });
+      const evda = openEvda(dir);
+      const files = markdownFiles(evda.dir);
+      const hits = ownerSearch(evda, query, { files });
+      for (const h of hits) console.log(`${h.sealed ? "[sealed] " : ""}${h.noted ? "[noted] " : ""}${h.path}:${h.line}: ${h.text.length > 300 ? `${h.text.slice(0, 300)}...` : h.text}`);
+      console.log(`CHECKED ${files.length} files  ${hits.length} match(es), ${hits.filter((h) => h.noted).length} in just-noted entries, ${hits.filter((h) => h.sealed).length} in sealed entries; on this device, no model`);
+      return 0;
+    }
+
+    case "readers": {
+      const { dir } = pickDir(args);
+      const evda = openEvda(dir);
+      const ctx = readContext(evda);
+      const rec = parseReaders(evda.manifest[READ_BY], "evda.json read_by");
+      console.log(`the record: Read by: ${describeReaders(rec.problems.length ? null : rec.readers)}${ctx.circles.length ? " (every part without its own)" : ""}`);
+      for (const c of ctx.circles) {
+        const any = Object.values(c.members).find((m) => m.kind === "path");
+        const probe = any ? (any.isDir ? join(any.abs, ".probe.md") : any.abs) : null;
+        const r = probe ? readersFor(ctx, probe) : { readers: null, isPublic: c.manifest?.public === true, source: null };
+        console.log(`${c.name}: Read by: ${describeReaders(r.readers, { isPublic: r.isPublic })}${r.source === "evda.json" ? " (from evda.json)" : ""}`);
+      }
+      return 0;
+    }
+
+    case "local-model": {
+      console.log(readFileSync(fileURLToPath(new URL("../docs/local-model.md", import.meta.url)), "utf8"));
+      return 0;
+    }
+
     case "reindex": {
       const { dir, flags } = pickDir(args);
       if (flags.includes("--adopt")) {
@@ -267,13 +620,36 @@ async function main(argv) {
       const parts = splitFence(text);
       if (!parts) throw new EvdaError(`${a.rel} has no evda:generated fence. The owner has taken the whole file; there is nothing the installer owns to replace, and nothing was changed.`);
       const shipped = shippedGenerated();
-      if (parts.generated === shipped) { console.log("upgrade: the generated block already matches what this tool ships. Nothing outside it was read."); return 0; }
+      if (parts.generated === shipped) {
+        stampInstalledVersion(dir, packageVersion());
+        console.log("upgrade: the generated block already matches what this tool ships. Nothing outside it was read.");
+        return 0;
+      }
       writeFileSync(a.abs, replaceFence(text, shipped));
       reindex(evda);
+      stampInstalledVersion(dir, packageVersion());
       console.log(`upgrade: replaced the generated block of ${a.rel} (${Buffer.byteLength(parts.generated)} -> ${Buffer.byteLength(shipped)} bytes). Everything outside the fence is untouched. Digest rebuilt.`);
       return 0;
     }
 
+    case "check-update": {
+      const { dir } = pickDir(args);
+      const result = await checkForUpdate(dir, { force: args.includes("--force") });
+      console.log(summarize(result));
+      return result.status === "CHECK_FAILED" ? 1 : 0;
+    }
+
+    case "update": {
+      const { dir } = pickDir(args);
+      const result = await checkForUpdate(dir, { force: true });
+      console.log(summarize(result));
+      if (result.status === "CHECK_FAILED") return 1;
+      if (result.status !== "UPDATE_AVAILABLE" && result.status !== "UNSTAMPED") return 0;
+      const upgradeRc = await main(["upgrade", dir]);
+      if (upgradeRc !== 0) return upgradeRc;
+      return main(["migrate", dir]);
+    }
+
     case "digest": {
       const { dir } = pickDir(args);
       const evda = openEvda(dir);
@@ -408,6 +784,62 @@ async function main(argv) {
       return 0;
     }
 
+    case "publish": {
+      const { dir, rest } = pickDir(args);
+      return publishCommand(dir, rest[0], { out: flagValue(args, "out"), key: flagValue(args, "key") });
+    }
+
+    case "circles": {
+      const sub = args[0];
+      const { dir } = pickDir(args.slice(1));
+      const planFile = flagValue(args, "plan");
+      const plan = planFile ? JSON.parse(readFileSync(resolve(planFile), "utf8")) : null;
+      if (sub === "plan" || sub === "declare") {
+        if (!plan) throw new EvdaError(`circles ${sub} needs --plan <file>`, { exit: 2 });
+        if (sub === "plan") {
+          const { circles, missing } = planCircles(dir, plan);
+          for (const c of circles) console.log(`${c.name}${c.public ? " (public)" : ""}: ${c.members.length} member(s)\n${c.members.map((m) => `  ${m.path === "" ? "(the record root: everything no other circle claims)" : `${m.path}${m.isDir ? "/" : ""}`}`).join("\n")}`);
+          for (const m of missing) console.log(`MISSING root ${m}: nothing is there yet; declared so the path has a circle when it appears`);
+          return 0;
+        }
+        const { written } = declare(dir, plan, { recordId: flagValue(args, "record-id") });
+        console.log(`wrote ${written.length} files: ${written.map((p) => relative(dir, p)).join(", ")}`);
+        return 0;
+      }
+      if (sub === "check") {
+        const evda = openEvda(dir);
+        // Without --plan, the plan kept beside the circles (`<circles role>/plan.json`) says what is
+        // excluded, so this check and doctor exclude what the scan excludes.
+        const beside = plan ? null : planBeside(evda);
+        const excludes = plan?.exclude ?? beside?.plan?.exclude ?? [];
+        // A bounded record's circles stop at its sub-records (HQ-1371); each is checked as its own.
+        const { boundaries } = await import("../lib/records.mjs");
+        const stops = boundaries(evda);
+        if (stops.length) console.log(`STOPS at ${stops.length} sub-record(s): ${stops.join(", ")}`);
+        const r = coverage(dir, circleIndex(evda), { exclude: excluder([...excludes, ...stops]), mountRoot: mountRoot(evda) });
+        for (const p of r.problems) console.log(`FAIL ${p.code} ${p.rel}: ${p.why}`);
+        console.log(`CHECKED ${r.checked} files in ${Object.keys(r.perCircle).length} circles: ${Object.entries(r.perCircle).map(([n, k]) => `${n} ${k}`).join(", ")}; EXCLUDED ${r.excluded} (plan: ${planFile ? relative(dir, resolve(planFile)) : beside ? beside.path : "none, built-in excludes only"})`);
+        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 });
+    }
+
+    case "parity": {
+      const { dir } = pickDir(args);
+      const planFile = flagValue(args, "plan");
+      const device = flagValue(args, "device");
+      const shadow = flagValue(args, "shadow");
+      if (!planFile || !device || !shadow) throw new EvdaError("parity needs --plan <file> --device <name> --shadow <dir>", { exit: 2 });
+      const plan = JSON.parse(readFileSync(resolve(planFile), "utf8"));
+      const evda = openEvda(dir);
+      const { holds, never, drift } = deviceCircles(plan, device, readGrants(evda) === null ? null : grantView(evda));
+      for (const d of drift) console.log(`NOTE plan drift ${d}; the grant files decide`);
+      const r = parity({ source: dir, shadow: resolve(shadow), index: circleIndex(evda), holds, never, exclude: excluder(plan.exclude) });
+      for (const line of formatParity(r)) console.log(line);
+      return r.ok ? 0 : 1;
+    }
+
     case "status": {
       const { dir, via } = pickDir(args);
       const evda = openEvda(dir);