create-evda 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,101 @@ Plain-English notes on how Iris behaves differently after each version. Not a co
 
 ## Unreleased
 
+On a machine that does not write the day (`EVDA_DAY_WRITER` set), the Claude Code prompt hook no
+longer appends to the local day file. It sends each message to the writer through the command in
+`EVDA_DAY_WRITER_SEND` (evda_write's arguments as JSON on stdin), and a message the writer cannot take
+waits in this machine's own outbox (`EVDA_PROMPT_OUTBOX`, default `~/.evda/outbox`) and goes with the
+next one, filed once. The keep-record hook's reminder there names evda_write. The day-writer guard
+now sees a day file named through a variable the same command set, `$HOME` or `~`. `evda doctor`
+warns when evda.json says `"filing": "everything"` and no prompt hook is installed (HQ-2817).
+
+An EVÐA made with `evda adopt` now has the steps for turning training off. Iris gives those steps
+only from the "Turning training off" section of `README.md`, and an adopted folder kept its own
+README, which never had that section, or the ones on what each AI company says and running a model
+on your own computer. The adopt now adds those three sections after your README as one block marked
+as EVÐA's, leaving your text exactly as it was, or writes the whole README when you had none.
+`evda adopt --revert` takes the block back out, and `evda upgrade` keeps it current. `evda doctor`
+fails a record whose `AGENTS.md` sends Iris to a `README.md` section that is not there, and says to
+run `evda upgrade`, which adds it.
+
+`evda doctor` run from a git checkout now says, just before its verdict, when that checkout is behind
+origin/main or is not main, so a pass from an old branch no longer reads as main's pass. It fetches
+main first with a five-second limit; offline, with no origin, or from an installed copy it still runs
+every check and says it could not compare. On current main it says nothing extra, and the exit code is
+unchanged. `EVDA_DOCTOR_FETCH=0` skips the fetch.
+
+When a filing names pages your EVÐA already has (a person, a project, a topic) or open tickets on your
+board, and the conversation adds to none of them, Iris is now asked once, naming them, whether what you said adds to one; adding
+nothing is a fine answer. In Claude Code the record's Stop hook asks before the session stops, and in
+the chat apps the next tool result asks. A record with the Stop hook installed shows it as older in
+`evda doctor` until `evda hook install` refreshes it.
+
+Claude Cowork can reach your EVÐA now. Cowork does not start the servers in the desktop app's
+config and does not read your folder's hooks, so `evda plugin` builds a plugin for your record (its
+evda tools, the hooks that keep it, and a skill that has Iris read the operating layer first), and
+you upload the zip in Customize, then Plugins, then Upload plugin. `create-evda` and `evda connect`
+print the command. The plugin's hooks act only in Cowork, so the same plugin syncing into Claude Code
+files nothing twice.
+
+`evda secret migrate` moves the passwords in Credentials/ files sealed before they went to the
+Keychain: each value goes into the Keychain, and the file keeps a pointer in its place, the same as a
+new gather does. A file whose Keychain write fails stays exactly as it was, an item already in the
+Keychain is never overwritten, and running it again changes nothing. `--dry` says what it would move.
+Two lines with the same label in one file (two "Password:" lines) now get separate Keychain items,
+where before the second overwrote the first.
+
+The EVÐA app's setup now asks how to organize your EVÐA right after what you want it for, offering
+the same presets as `create-evda`, or starting plain. `evda preset list --json` prints the list it
+reads.
+
+`create-evda --help`, `create-evda -h`, `evda init --help` and `evda mcp --help` now print how to use
+them and stop. Before, `create-evda -h` made a folder named `-h` and `evda mcp --help` started serving
+your record. On a Mac, `create-evda` now says it is installing the daily morning organize as a
+launchd job before it does, with `--yes` too, and names `--no-routines` to skip it. Gathering a pile
+now skips what apps leave behind (Office lock files, empty files, a Recently Deleted folder, Google
+Takeout's `archive_browser.html`) and lists each one, with why, in the proposal.
+
+`evda publish public` now leaves a markdown file's `sources:` frontmatter out of what it exports. That
+field lists the private files a public page was written from, so it never belonged in public, and it
+was making the publish refuse every run once a page carried one. A private path in a page's body
+still refuses the publish exactly as before.
+
+When Iris files something, it is now told which pages you already have that the words name (a person,
+a topic, a project) and which shared circles that reaches, such as a public entry derived from the
+folder it just wrote to. It is information for Iris to judge, so it still decides what to write, and
+nothing noted, sealed, or set for a different AI is ever named.
+
+When your work lives on a board (`"work": "harlequin:"`), filing also names the open tickets the
+words reference, by `HQ-` number or by a distinctive run of a ticket's title, at most five, so a
+conversation about a ticket's subject points Iris at the ticket. A done or obsolete ticket is never
+named. The board is read in the background with the same credentials as `evda work` (or the env file
+`EVDA_WORK_ENV_FILE` names), so a slow or unreachable board never slows a filing.
+
+A people folder now keeps one file per person, and `evda doctor` says so when it does not: a folder
+inside it, a name with a parenthetical when nobody else shares the name, and a stub that only
+points at another page each fail, and so does a page with no person-profile frontmatter, which
+doctor cannot read. Gathering a pile writes every page it puts in a people folder as a profile, and
+migrating people now types a page with no dated section (its one observation is the day it was
+typed) and a page that already has frontmatter, keeping what that frontmatter says. Applying a preset that makes a people folder also makes `Processing/` beside it
+for the docs where you work something through, and a README in the folder saying the rule.
+
+In the Claude app, Iris starts a chat knowing what your last days were about, not only when you
+wrote: each recent entry comes with its one line of context and the opening of your words, and the
+people whose pages gained a dated section this week are listed with those sections. Searching your
+record shows the most recent matches first. Iris answers you in the reply itself and says what it
+filed in one line after, instead of writing its answer into a page. And the Claude app now reads
+your whole instructions file at the start of a chat, up to about 100,000 characters, where it used
+to get some sections as a heading to fetch. Noted and sealed entries still never appear.
+
+In a chat app, Iris now writes where it writes from a terminal. A correction you give it lands in
+the file you keep corrections in, when `evda.json` names it as `"corrections"`, as a dated section
+in your words; before, a record without a "What I have been taught" heading lost every one. Iris can
+add a row to a log kept as a table (a food log, a spike log, a weekends board) with
+`evda_append_row`, and put a new section inside the part of a file it belongs in with
+`evda_append`'s `under`, so a queued idea no longer lands under "Completed". When Iris offers to
+start a page, a person's page or a folder and you say yes, `evda_create` makes it, and never where
+something already is.
+
 When two of your machines share one record through iCloud, one of them can be the only one that
 writes the daily note. Set EVDA_DAY_WRITER on every other machine and add hooks/evda-day-writer-guard.mjs
 to that machine's own Claude Code settings: an agent there that tries to write the note directly is

package/README.md

@@ -109,11 +109,16 @@ codex mcp add evda -- /path/to/node /path/to/evda.mjs mcp ~/my-evda
 
 **One layer, sized per app.** `evda_operating_layer` serves the core and AGENTS.md to every app, but a section that only makes sense with a shell (scripts to run, hosts to ssh to, local MCP servers) is noise in a chat app. Put `<!-- evda:surface terminal -->` on the line right after a `## ` heading and that section, with its subsections, goes only to coding agents (Claude Code, Codex). Every other app, including one the server has never heard of, gets the rest, in as few parts as its tool result limit allows, and is told which sections were left out. A record with no marker reads the same everywhere. The server knows the app by `initialize`'s `clientInfo` name, and the remote server logs that name and version, nothing else of it.
 
-For the Claude desktop app, add the same command under `mcpServers` in `claude_desktop_config.json` (Settings, then Developer, then Edit Config) and restart the app. `create-evda` prints all three at the end of setup.
+**Each surface reaches a record its own way.** `create-evda` and `evda connect` print every one of these with your record's path filled in.
+
+- **Claude Code** (terminal, IDE, the desktop app's Code tab): `claude mcp add` above for every folder, and in sessions opened in the record its own `.claude/settings.json` hooks and `.claude/skills/` load on their own.
+- **The Claude desktop app's chat**: add the same command under `mcpServers` in `claude_desktop_config.json` (Settings, then Developer, then Edit Config) and restart the app. That file reaches only the chat: Cowork does not start its servers.
+- **Claude Cowork**: `evda plugin <dir>` builds a plugin for this one record, a folder and a zip under `.evda/plugin/` (or `--out <zip>`), and the upload is the one step left to you: in the Claude app, Customize, then Plugins, then Add, then Upload plugin, and choose the zip. Cowork reads no folder's `CLAUDE.md`, `AGENTS.md` or hooks, so the plugin carries all three ways in: the record's MCP server (`evda mcp <dir>`, the path baked in, because Cowork does not ask for plugin settings), a skill that loads the operating layer before the first reply, and hooks that run the record's own keep-record hook, prompt-filing hook (with "everything") and read guard, the files `evda hook install` keeps current. It works in Cowork tasks that run on your computer. The plugin also loads in Claude Code sessions signed in to the same account; its hooks stay quiet there (they act only when Claude Code runs a Cowork task), and `claude plugin disable <name>@synced` takes it out of Claude Code. Move the folder and you build and upload it again.
+- **claude.ai** (web and phone): no local server reaches it. `evda mcp --http` serves the record over HTTPS behind OAuth, through a tunnel, as a connector you add in Settings, then Connectors.
 
 **The skill.** `skills/evda/SKILL.md` (Agent Skills format) tells Claude Code to act as Iris through the tools: load the operating layer first, file verbatim, never quiz, circles only on your yes. `evda skill install` copies it to `~/.claude/skills/evda/`; setup offers it.
 
-**The record keeps itself.** You never have to say "save this". In Claude Code, setup (when you pick Claude) installs a Stop hook in the record's own `.claude/settings.json`: a session that read the record or heard you out and filed nothing to the day's record is asked once, before it stops, to file your words. It runs only in sessions opened in the record; your global settings are not touched. `evda hook install` adds it to a record made earlier, and `evda doctor` says whether it is installed and current. In apps with no hooks (the Claude desktop app, ChatGPT), the MCP server itself adds one line to its tool results once a conversation has read the record and filed nothing, and goes quiet after the first write.
+**The record keeps itself.** You never have to say "save this". In Claude Code, setup (when you pick Claude) installs a Stop hook in the record's own `.claude/settings.json`: a session that read the record or heard you out and filed nothing to the day's record is asked once, before it stops, to file your words. It runs only in sessions opened in the record; your global settings are not touched. `evda hook install` adds it to a record made earlier, and `evda doctor` says whether it is installed and current. In Cowork the plugin from `evda plugin` runs the same hooks. In apps with no hooks (the Claude desktop app's chat, ChatGPT), the MCP server itself adds one line to its tool results once a conversation has read the record and filed nothing, and goes quiet after the first write. A second check rides on both: a write's answer names the existing entries its words bear on, and a conversation that was named some and added to none of them is asked once, naming them (and any open board tickets it named), with adding nothing as a fine answer. It goes quiet after a write to one of them or once asked. The Stop hook reads those names back out of the Claude Code transcript and the MCP server keeps them per chat, so nothing about it is stored in your files.
 
 **Filing is the owner's answer.** Setup asks once whether to file everything they say automatically (the default) or only when they ask, and writes it to `evda.json` as `"filing": "everything"` or `"asked"`; a record with no answer is asked at first connect, and `evda_filing` records the reply. `evda_write`'s description leads with when to call it, because a deferred tool in the Claude app shows only that first line. One conversation is one `## HH:MM` section of the day. With "everything", Claude Code also gets a UserPromptSubmit hook, `.claude/hooks/evda-file-prompt.mjs`, that files each message verbatim as it is sent. `evda gather scan <conversations.json> --into <record>` reads a Claude.ai or ChatGPT export and, on apply, adds the owner's own messages the record lacks under each conversation's date and time.
 
@@ -127,7 +132,7 @@ For the Claude desktop app, add the same command under `mcpServers` in `claude_d
 
 How a record is organized comes from a library, so an agent proposes a folder that already exists in it instead of inventing one. Each preset is `presets/<id>/preset.json`: an `id`, a `title`, `for` (who it suits), `folders` (each a path, and for a typed folder its `type`, `connectors` and `views`, validated by the same code as `folder.evda.json`), optional `circles` (proposed as proposal files, never created), optional `routines` (offered, never scheduled), and `mapping`, the folders that fill the four roles. Every folder a preset makes fills a role, and a preset that has one filling none fails its test. Two ship: `projects-and-areas` (numbered folders for projects, areas with courses under Academics, resources, work, captures, the daily journal and attachments) and `journal`. A course is a collection, so there is no student preset, and there is no archive folder: finished is a status. Setup offers them after purpose, with "none, start plain". Applying one adds the role paths the record lacks to `evda.json`; a role key the record already uses keeps its path, and the preset's folder fills the same role under a facet key named for it.
 
-    evda preset list
+    evda preset list [--json]        --json: one line, [{id, title, for}], what the EVÐA app's setup offers
     evda preset show <id>
     evda preset apply <id> [--dry] [dir]
     evda preset diff <id> [dir]      what the preset has that this record does not
@@ -169,11 +174,11 @@ Writes:
                              grant file per reader and circle
       .evda/version          the schema version actually on disk
       .evda/due.jsonl        derived from the ledger's Due lines
-      .evda/digest.md        derived from the fenced block of AGENTS.md, under 4096 bytes
+      .evda/digest.md        derived from the fenced block of AGENTS.md, under 6144 bytes
 
 The training instructions in the scaffolded README and in setup come from one table, `lib/setup.mjs`, with a link to each provider's page.
 
-The tree above is what the scaffolder creates and not a requirement. `evda.json` carries a `mapping` from roles to paths, and every tool reads roles. An existing folder of notes becomes an EVÐA by adding `evda.json` with a mapping that names where things already are, and nothing moves.
+The tree above is what the scaffolder creates and not a requirement. `evda.json` carries a `mapping` from roles to paths, and every tool reads roles. An existing folder of notes becomes an EVÐA by adding `evda.json` with a mapping that names where things already are, and nothing moves. `evda adopt <dir>` writes that mapping: an Iris Vault (`00_Inbox` through `06_Metadata`) maps without a question, any other folder is placed by its name or named back to the owner to answer with `--map <folder>=<role>`, and it adds `AGENTS.md`, `.evda/`, the Claude Code hooks, one `@AGENTS.md` line at the end of the owner's `CLAUDE.md`, and the `README.md` sections `AGENTS.md` sends the agent to (turning training off, what each AI company says, running a model locally) as one marked block after the owner's own `README.md`, which `evda upgrade` keeps current. Every other file stays byte for byte, and `evda adopt --revert <manifest>` puts the folder back exactly as it was. A chat app runs it through `evda_adopt`, which writes nothing without `confirmed: true`.
 
 ### Four roles, and records inside records
 
@@ -214,6 +219,8 @@ An `evda.json` anywhere below the root starts a sub-record, with no depth limit.
     evda use <dir>                 point ~/.evda/current at a record
     evda mcp [dir]                 serve the record over MCP on stdio for Claude Code, Codex or the Claude app
     evda connect [dir]             the MCP setup for each client, with this record's path
+    evda plugin [dir] [--out <zip>]
+                                   a Claude plugin for this record, for Cowork: its server, hooks and skill
     evda skill install [--project <dir>]
                                    install the evda skill for Claude Code
     evda hook install [dir]        the keep-record Stop hook and the read guard, in the record's .claude/settings.json,

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";
@@ -76,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,
@@ -102,17 +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
@@ -200,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/`.
@@ -209,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 = ["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"];
+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);
@@ -305,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")) {
@@ -393,13 +426,74 @@ 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>]", { exit: 2 });
+      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);
@@ -464,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);
@@ -484,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;
@@ -512,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.");
@@ -619,7 +729,8 @@ async function main(argv) {
 
     case "doctor": {
       const { dir, via } = pickDir(args);
-      return doctor(dir, { via }).exit;
+      // The package root this doctor runs from, so it can say whether that is current main (HQ-2736).
+      return doctor(dir, { via, checkout: fileURLToPath(new URL("..", import.meta.url)) }).exit;
     }
 
     case "guard":
@@ -836,6 +947,11 @@ 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();
+      // HQ-2812: the README.md sections the operating layer sends the agent to, kept as EVÐA's
+      // marked block (added when one is missing, refreshed when it is there); the owner's text is
+      // never touched.
+      const { ensureReadme, readmeLine } = await import("../lib/readme.mjs");
+      console.log(`upgrade: ${readmeLine(ensureReadme(dir, { agents: replaceFence(text, shipped) }))}`);
       if (parts.generated === shipped) {
         stampInstalledVersion(dir, packageVersion());
         console.log("upgrade: the generated block already matches what this tool ships. Nothing outside it was read.");
@@ -861,6 +977,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]);

package/create-evda.mjs

@@ -40,8 +40,9 @@ import { applyPreset, listPresets, planLines, presetIds, NONE } from "./lib/pres
 import { FILING_MODES } from "./lib/day-file.mjs";
 import { installPromptHook } from "./lib/hooks.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 { PLATFORMS, PLATFORM_KEYS, PARTS_LINE, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, readerFor, INTRO } from "./lib/setup.mjs";
 import { describeReaders, parseReaders } from "./lib/readers.mjs";
+import { renderReadme } from "./lib/readme.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = join(HERE, "templates");
@@ -70,7 +71,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 = {
@@ -181,7 +189,7 @@ export function scaffold(opts) {
   // agent asks at first connect.
   if (opts.filing) manifest.filing = opts.filing;
   writeIfAbsent(join(dir, "evda.json"), JSON.stringify(manifest, null, 2) + "\n");
-  writeIfAbsent(join(dir, "README.md"), render("README.md", { training: trainingSection(), terms: termsSection(), intro: INTRO, localModel: localModelSection() }));
+  writeIfAbsent(join(dir, "README.md"), renderReadme());
   // The owner section of AGENTS.md holds the setup answers in the owner's words. The AI line is
   // written only when training off was confirmed; empty, it is what makes the agent ask.
   const answers = {
@@ -224,12 +232,6 @@ export function scaffold(opts) {
   return { dir, manifest, pointer, guard, hook, promptHook };
 }
 
-// The local-model doc as a README section: its title dropped and its headings one level down.
-function localModelSection() {
-  const text = readFileSync(join(HERE, "docs", "local-model.md"), "utf8");
-  return text.split("\n").slice(1).join("\n").replace(/^## /gm, "### ").trim();
-}
-
 // Day one. The record's first daily file records the one true thing that has happened to it: it
 // was created. It says so in three lines and says where the owner's words go, then gets out of the
 // way. It is not an example note, it asks nothing, and it schedules nothing; every later file
@@ -277,8 +279,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);
@@ -346,7 +349,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("");