create-evda 0.1.3 → 0.1.5

package/README.md

@@ -14,7 +14,7 @@ npx create-evda my-evda
 
 ## Setup
 
-On a terminal, `create-evda` asks one question at a time: what to call your agent (Iris unless you rename it), who you are, what you want this for, how it should talk to you, and which AI you will use. It shows where that AI's training setting is, links the provider's own page, and does not finish until you type yes. The answers go into "What this EVÐA is" at the top of `AGENTS.md`, in your words. It suggests dictation: Apple's built in dictation, or Wispr Flow with data collection turned off. Last, it offers to bring in what an AI you already use knows about you; see below.
+On a terminal, `create-evda` asks one question at a time: what to call your agent (Iris unless you rename it), who you are, what you want this for, how to organize it (a preset, or start plain), how it should talk to you, and which AI you will use. It shows where that AI's training setting is, links the provider's own page, and does not finish until you type yes. The answers go into "What this EVÐA is" at the top of `AGENTS.md`, in your words. It suggests dictation: Apple's built in dictation, or Wispr Flow with data collection turned off. Last, it offers to bring in what an AI you already use knows about you; see below.
 
 Unattended, nothing is asked:
 
@@ -23,7 +23,7 @@ npx create-evda my-evda --yes --agent-name Iris --owner "Dana" --purpose "why wo
   --voice "direct" --platform claude --training-off
 ```
 
-`--platform` takes `claude`, `chatgpt` (ChatGPT and Codex), `gemini`, `cursor` or `other`. Without `--training-off` the AI line stays empty and the agent asks about training in the first session. A run with no terminal on stdin is treated as `--yes`.
+`--platform` takes `claude`, `chatgpt` (ChatGPT and Codex), `gemini`, `cursor` or `other`. `--preset` takes a preset id or `none`; unattended, no flag means none. Without `--training-off` the AI line stays empty and the agent asks about training in the first session. A run with no terminal on stdin is treated as `--yes`.
 
 ## Any AI
 
@@ -33,13 +33,57 @@ npx create-evda my-evda --yes --agent-name Iris --owner "Dana" --purpose "why wo
 
 Setup ends by asking whether to bring in what an AI you already talk to knows about you. Say yes and it prints a prompt: paste that into ChatGPT, Claude, or whatever you use, and it writes out what it remembers or has guessed about you, in plain text. Bring the answer to your first session and your agent files it verbatim under `record/imports/YYYY-MM-DD-<source>.md`, with the source and date at the top. It is filed as what that AI said, never as your own words, and every line in it is a claim to check with you over time, not a fact.
 
+## Talk to it from the AI you already use
+
+`evda mcp` serves your record as an MCP server on stdio, so Claude Code, Codex and the Claude desktop app can read and write it from any folder. EVÐA holds no API key and calls no model: the AI is yours, signed in as you, and it reaches the record only through these tools.
+
+    evda_operating_layer   AGENTS.md, read first every session
+    evda_recent            the last few days of the record
+    evda_write             your words, verbatim, appended to today's daily file. It takes no path and never edits
+    evda_import            what another AI said about you, filed under record/imports with its source and date
+    evda_search            plain text search inside the record, on this machine
+    evda_circles           your circles and their policies
+    evda_propose_circle    a proposal file under proposals/. Never a circle, never a grant
+    evda_presets           the preset library, or one preset's folders
+    evda_propose_structure what a preset would add to this record, in plain words. Writes nothing
+    evda_apply_preset      adds a preset's folders; refused unless confirmed: true, the owner's yes
+    evda_doctor            evda doctor, as a report
+
+Every write appends, refuses anything shaped like a password, key or token, and says the path it wrote. `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
+codex mcp add evda -- /path/to/node /path/to/evda.mjs mcp ~/my-evda                 # Codex
+```
+
+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.
+
+**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 organizer.** `evda organize` goes through what you left inward. It copies each dated capture, verbatim, into the daily file of its date, once, and appends a report to `reports/organize/<date>.md`: people a recent note mentions, imports to check, undated notes, notes under no role. It moves nothing. With `--with-ai` it hands the judgment to your own `claude -p`, with the skill and read-only EVÐA tools, and appends its answer to the report. `evda look-back` does the same for the week.
+
+**Routines.** Setup offers a morning organize and a weekly look back, each optional, and schedules nothing without a yes. `evda routine morning` prints what to put in a local routine in the Claude desktop app (Code tab, then Routines, then New routine, then Local). `evda routine morning --install` writes and loads a launchd job instead, on a Mac. A cloud routine cannot read local files, so it cannot reach a record.
+
+## Presets
+
+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) and optional `routines` (offered, never scheduled). Three ship: `projects-and-areas` (numbered top folders for inbox, projects, areas, resources, archive, captures, metadata and attachments), `journal`, and `student`. Setup offers them after purpose, with "none, start plain".
+
+    evda preset list
+    evda preset show <id>
+    evda preset apply <id> [--dry] [dir]
+    evda preset diff <id> [dir]      what the preset has that this record does not
+
+Applying only adds: missing directories are created and missing manifests written; a manifest that already says the same is skipped, one that says something else (or a file where a folder would go) is a `CONFLICT` that is left as it is, and nothing is moved, renamed or deleted. A second apply writes nothing. Exit 1 when there was a conflict. `test/presets.test.mjs` validates every shipped preset, so a malformed one fails a test rather than a person.
+
+`evda doctor` reads folder manifests across the whole record root, not only under the record roles, skipping dot-directories and `node_modules` and not following symlinks.
+
 ## Circles and other people
 
 Everything is private until you share it. A circle is a part of the record you choose to share, plus who may read it. Audience and content are set separately: a public circle has the widest audience and the least content. Ask the agent to share something and it proposes a circle with a plain policy and waits for your yes; it never creates one, adds a reader, or moves an entry on its own. Another person reads a circle through a grant naming their own record (`evda grant family --to sam.atlas --kind person`), and `evda revoke` takes it back. A part can be more private than its circle, never less.
 
 ## The package
 
-`@evda/person-record` in this repository, published as `create-evda`. The person layer over the substrate. An EVÐA is a directory that knows what it is: a person's record in their own words, a ledger of reads about them held loosely, and the operating instructions beside them, so that any agent on any model can open it and act correctly with no outside context. The files are the truth. Nothing here is required to read or write a record; `evda doctor` says whether one is well formed and `evda reindex` rebuilds the derived directory, and both can be thrown away. It has no runtime dependencies (`test/deps.test.mjs` asserts it) and never makes a network call.
+`@evda/person-record` in this repository, published as `create-evda`. The person layer over the substrate. An EVÐA is a directory that knows what it is: a person's record in their own words, a ledger of reads about them held loosely, and the operating instructions beside them, so that any agent on any model can open it and act correctly with no outside context. The files are the truth. Nothing here is required to read or write a record; `evda doctor` says whether one is well formed and `evda reindex` rebuilds the derived directory, and both can be thrown away. It has no runtime dependencies (`test/deps.test.mjs` asserts it) and never makes a network call. The MCP server is a small JSON-RPC implementation in `lib/mcp.mjs`, not the SDK, for the same reason.
 
 Design contract: Spec 04 (the hypothesis ledger), Spec 05 (the data layer), Spec 06 (the guarantee) and Spec 07 (holders, circles, references and views) in the EVÐA project. A short copy of what this package settles is in `docs/canon/person-record.md`.
 
@@ -97,6 +141,17 @@ The tree above is what the scaffolder creates and not a requirement. `evda.json`
     evda status [dir]              one screen
     evda where                     which record the locator resolves to, and by which rule
     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 skill install [--project <dir>]
+                                   install the evda skill for Claude Code
+    evda organize [dir] [--dry-run] [--with-ai] [--model M]
+                                   file captures into their day and report what belongs where; moves nothing
+    evda look-back [dir]           the week, read back by your own claude -p, appended to a report
+    evda routine <morning|weekly> [dir] [--launchd] [--install]
+                                   a Claude desktop routine, or a launchd job with --install
+    evda preset list | show <id> | apply <id> [--dry] [dir] | diff <id> [dir]
+                                   organize the record from the preset library; apply only adds
 
 The record is found through the locator: a directory argument, then `$EVDA_HOME`, then the nearest ancestor of the working directory holding `evda.json`, then `~/.evda/current`. Nothing assumes it was launched inside one.
 

package/bin/evda.mjs

@@ -48,16 +48,44 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
   evda revoke <circle> --to <record-id> [dir]
   evda access <circle> --as <record-id> [dir]
                                  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 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 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 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 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.
 Exit codes: 0 ok, 1 the record has a problem and it was named, 2 refused (nothing written).`;
 
+function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
 // 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/`.
@@ -67,7 +95,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"];
+const VALUE_FLAGS = ["to", "kind", "name", "role", "by", "as", "model", "project", "hour", "weekday"];
 function flagValue(args, name) {
   const eq = args.find((a) => a.startsWith(`--${name}=`));
   if (eq) return eq.slice(name.length + 3);
@@ -105,6 +133,94 @@ async function main(argv) {
       return mod.main(args);
     }
 
+    case "mcp": {
+      // 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;
+    }
+
+    case "organize": {
+      const { dir, flags } = pickDir(args);
+      const { organize } = await import("../lib/organize.mjs");
+      const r = await organize(openEvda(dir), { withAi: flags.includes("--with-ai"), dryRun: flags.includes("--dry-run"), model: flagValue(args, "model") });
+      console.log(r.summary);
+      return r.exit;
+    }
+
+    case "look-back": {
+      const { dir } = pickDir(args);
+      const { lookBack } = await import("../lib/organize.mjs");
+      const r = await lookBack(openEvda(dir), { model: flagValue(args, "model") });
+      console.log(r.summary);
+      return r.exit;
+    }
+
+    case "skill": {
+      // evda skill install [--project <dir>]   copy the evda skill for Claude Code
+      const { installSkill } = await import("../lib/connect.mjs");
+      if (args[0] !== "install") throw new EvdaError("usage: evda skill install [--project <dir>]", { exit: 2 });
+      const project = flagValue(args, "project");
+      const r = installSkill({ project: project ? resolve(project) : null });
+      console.log(`${r.action} ${r.path}`);
+      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);
+      const { connectText } = await import("../lib/connect.mjs");
+      console.log(connectText(dir));
+      return 0;
+    }
+
+    case "routine": {
+      // evda routine <morning|weekly> [dir] [--launchd] [--install]
+      const { routineMain } = await import("../lib/routines.mjs");
+      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 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;
+      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 "where": {
       const found = locate({});
       console.log(`${found.dir}  (via ${found.via})`);

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]
-//                     [--name NAME] [--layers record,ledger[,circles]] [--force]
+//                     [--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
 // does not finish until the owner confirms model training is off for the AI they chose. With
@@ -28,6 +28,9 @@ import { doctor } from "./lib/doctor.mjs";
 import { readPointer, setPointer, pointerPath } from "./lib/locate.mjs";
 import { FOLDER_MANIFEST } from "./lib/folders.mjs";
 import { EvdaError } from "./lib/errors.mjs";
+import { clients, installSkill } from "./lib/connect.mjs";
+import { desktopInstructions } from "./lib/routines.mjs";
+import { applyPreset, listPresets, planLines, presetIds, NONE } from "./lib/presets.mjs";
 import { PLATFORMS, PLATFORM_KEYS, LOADERS, DESKTOP_FILESYSTEM, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, trainingSection } from "./lib/setup.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -54,12 +57,13 @@ const FOLDER_TYPES = {
   "record/people": "person",
 };
 
-const USAGE = `usage: create-evda <dir> [--agent-name NAME] [--owner NAME] [--purpose TEXT] [--voice TEXT] [--platform ${PLATFORM_KEYS.join("|")}] [--training-off] [--yes] [--name NAME] [--kind person|agent|company] [--id ATLAS-ID] [--layers record,ledger] [--use] [--no-pointer]`;
+const USAGE = `usage: create-evda <dir> [--agent-name NAME] [--owner NAME] [--purpose TEXT] [--voice TEXT] [--platform ${PLATFORM_KEYS.join("|")}] [--training-off] [--yes] [--name NAME] [--kind person|agent|company] [--id ATLAS-ID] [--layers record,ledger] [--skill] [--routines morning,weekly] [--preset ${presetIds().join("|")}|none] [--use] [--no-pointer]`;
 
 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,
   };
   const args = argv.flatMap((a) => {
     const eq = /^(--[a-z-]+)=([\s\S]*)$/.exec(a);
@@ -77,6 +81,18 @@ export function parseArgs(argv) {
     else if (a === "--use") opts.use = true;
     else if (a === "--yes" || a === "-y") opts.yes = true;
     else if (a === "--training-off") opts.trainingOff = true;
+    else if (a === "--skill") opts.skill = true;
+    else if (a === "--no-skill") opts.skill = false;
+    else if (a === "--no-routines") opts.routines = [];
+    else if (a === "--routines") {
+      opts.routines = value(++i, a).split(",").map((s) => s.trim()).filter(Boolean);
+      const bad = opts.routines.filter((r) => !["morning", "weekly"].includes(r));
+      if (bad.length) throw new EvdaError(`--routines takes morning, weekly or both, got ${bad.join(", ")}`, { exit: 2 });
+    }
+    else if (a === "--preset") {
+      opts.preset = value(++i, a).trim();
+      if (opts.preset !== NONE && !presetIds().includes(opts.preset)) throw new EvdaError(`--preset takes ${[...presetIds(), NONE].join(", ")}, got ${opts.preset}`, { exit: 2 });
+    }
     else if (a === "--name") opts.name = value(++i, a);
     else if (a === "--owner") opts.owner = value(++i, a);
     else if (a === "--agent-name") opts.agentName = value(++i, a);
@@ -223,7 +239,7 @@ export async function main(argv, io = null) {
     refuseNonEmpty(opts.dir, opts.force);
     const term = io ?? (await terminalIO());
     try {
-      opts = await interview(opts, term);
+      opts = await interview(opts, term, { presets: listPresets() });
     } finally {
       term.close?.();
     }
@@ -232,6 +248,13 @@ export async function main(argv, io = null) {
   const { dir, pointer } = scaffold(opts);
   log(`created an EVDA at ${dir}`);
   log(`locator ${pointer.path}: ${pointer.action}\n`);
+  // The chosen preset only adds folders to the fresh record, and doctor below reads what it wrote.
+  if (opts.preset && opts.preset !== NONE) {
+    const plan = applyPreset(dir, opts.preset);
+    log(`preset ${plan.id}: ${plan.title}`);
+    for (const l of planLines(plan)) log(l);
+    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.");
@@ -250,6 +273,19 @@ export async function main(argv, io = null) {
     for (const k of chosen) log(`  ${PLATFORMS[k].label}: ${PLATFORMS[k].training[0]}${PLATFORMS[k].url ? ` ${PLATFORMS[k].url}` : ""}`);
   }
   log("");
+  log("Or connect your AI to this record from any folder, through the evda MCP server. No key and no model call in EVÐA:");
+  for (const c of clients(dir)) if (c.key !== "project") { log(`  ${c.label}:`); for (const l of c.text.split("\n")) log(`    ${l}`); }
+  if (opts.skill) {
+    const r = installSkill({ env: io?.env ?? process.env });
+    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`);
+  }
+  log("");
   log(`Then freewrite: what happened today, what is on your mind, what felt slightly off. Your words go into record/ as you talk. README.md says the rest.`);
   if (!asked) log(DICTATION);
   return 0;

package/lib/clients.mjs

@@ -0,0 +1,48 @@
+// How each AI client adds the EVDA MCP server, given the command that starts it. No node: imports,
+// so the EVDA app's webview renders the same text `evda connect` prints (lib/connect.mjs).
+
+export const SERVER_NAME = "evda";
+
+const shellQuote = (s) => (/^[A-Za-z0-9_./:@=+-]+$/.test(s) ? s : `'${String(s).replace(/'/g, "'\\''")}'`);
+const tomlString = (s) => JSON.stringify(s);
+
+// `desktopConfig` is where claude_desktop_config.json lives on this machine, when known.
+export function clientsFor(command, args, { desktopConfig = null } = {}) {
+  const argv = [command, ...args].map(shellQuote).join(" ");
+  return [
+    {
+      key: "claude-code",
+      label: "Claude Code",
+      steps: ["Run this once, from any folder. --scope user makes your EVÐA available in every Claude Code session."],
+      text: `claude mcp add --scope user ${SERVER_NAME} -- ${argv}`,
+      file: null,
+    },
+    {
+      key: "codex",
+      label: "Codex",
+      steps: ["Run this once, or add the block under it to ~/.codex/config.toml."],
+      text: [
+        `codex mcp add ${SERVER_NAME} -- ${argv}`,
+        "",
+        `[mcp_servers.${SERVER_NAME}]`,
+        `command = ${tomlString(command)}`,
+        `args = [${args.map(tomlString).join(", ")}]`,
+      ].join("\n"),
+      file: "~/.codex/config.toml",
+    },
+    {
+      key: "claude-desktop",
+      label: "Claude desktop app",
+      steps: [`Open Settings, then Developer, then Edit Config, and add "${SERVER_NAME}" under "mcpServers". Quit the app fully and open it again.`],
+      text: JSON.stringify({ mcpServers: { [SERVER_NAME]: { command, args } } }, null, 2),
+      file: desktopConfig ?? "claude_desktop_config.json",
+    },
+    {
+      key: "project",
+      label: "One folder only (.mcp.json)",
+      steps: ["Put this in .mcp.json at the root of a folder, and Claude Code offers the server in that folder only."],
+      text: JSON.stringify({ mcpServers: { [SERVER_NAME]: { type: "stdio", command, args } } }, null, 2),
+      file: ".mcp.json",
+    },
+  ];
+}

package/lib/connect.mjs

@@ -0,0 +1,84 @@
+// Connecting an AI to a record: the MCP server command, how each client adds it, and the evda skill.
+//
+// One source for every surface that shows these steps: `evda connect`, the end of create-evda, the
+// README and the EVDA app all read from here, so no two of them can give different config.
+//
+// Checked against each client's own docs on 2026-09-17:
+//   Claude Code     https://code.claude.com/docs/en/mcp  (`claude mcp add ... -- cmd args`, .mcp.json)
+//   Codex           https://developers.openai.com/codex/mcp  (`codex mcp add ... -- cmd`, config.toml)
+//   Claude desktop  https://modelcontextprotocol.io/quickstart/user  (claude_desktop_config.json)
+//   Skills          https://code.claude.com/docs/en/skills  (~/.claude/skills/<name>/SKILL.md)
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { clientsFor, SERVER_NAME } from "./clients.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = resolve(HERE, "..");
+export const SKILL_NAME = "evda";
+export const SKILL_SOURCE = join(PACKAGE_ROOT, "skills", SKILL_NAME, "SKILL.md");
+export { SERVER_NAME };
+
+// The command a client runs to start the server for one record. When this package is installed
+// somewhere stable, the absolute node and bin paths: a desktop app starts servers with a minimal
+// PATH, so a bare `node` or `npx` may not be found. When it is running out of an npx cache, which
+// npm may clear, the npx form instead.
+export function serverCommand(recordDir, { execPath = process.execPath, bin = join(PACKAGE_ROOT, "bin", "evda.mjs"), env = process.env } = {}) {
+  const dir = resolve(recordDir);
+  let real = bin;
+  try { real = realpathSync(bin); } catch { /* not on disk yet, as in a test */ }
+  if (/[\\/]_npx[\\/]/.test(real)) return { command: "npx", args: ["-y", "-p", "create-evda@latest", "evda", "mcp", dir] };
+  return { command: stableNode(execPath, env), args: [real, "mcp", dir] };
+}
+
+// A `node` on PATH that is this same binary, when there is one: Homebrew's /opt/homebrew/bin/node
+// survives an upgrade, and the versioned Cellar path process.execPath reports does not.
+function stableNode(execPath, env) {
+  let target;
+  try { target = realpathSync(execPath); } catch { return execPath; }
+  for (const d of String(env.PATH ?? "").split(delimiter)) {
+    if (!d) continue;
+    const candidate = join(d, process.platform === "win32" ? "node.exe" : "node");
+    try { if (realpathSync(candidate) === target) return candidate; } catch { /* not here */ }
+  }
+  return execPath;
+}
+
+export function desktopConfigPath(platform = process.platform, env = process.env) {
+  if (platform === "darwin") return join(env.HOME ?? homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (platform === "win32") return join(env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  return null;
+}
+
+// Every client's setup for one record, as data. `text` fields are what a person copies.
+export function clients(recordDir, opts = {}) {
+  const { command, args } = serverCommand(recordDir, opts);
+  return clientsFor(command, args, { desktopConfig: desktopConfigPath() });
+}
+
+export function connectText(recordDir, opts = {}) {
+  const lines = [`Connect your AI to ${resolve(recordDir)}. No key and no model call in EVDA: your AI reads and writes the record through these tools.`, ""];
+  for (const c of clients(recordDir, opts)) {
+    lines.push(`${c.label}:`);
+    for (const s of c.steps) lines.push(`  ${s}`);
+    lines.push("", ...c.text.split("\n").map((l) => `    ${l}`), "");
+  }
+  lines.push(`Then install the skill for Claude Code so it acts as Iris through these tools: evda skill install`);
+  return lines.join("\n");
+}
+
+// Copy the evda skill into Claude Code's skills folder: the person's (~/.claude/skills) or one
+// project's (<dir>/.claude/skills). An existing copy with the same bytes is left alone; a different
+// one is replaced, because the skill is the installer's and carries no owner edits.
+export function installSkill({ project = null, env = process.env } = {}) {
+  const base = project ? join(project, ".claude", "skills") : join(env.HOME ?? homedir(), ".claude", "skills");
+  const path = join(base, SKILL_NAME, "SKILL.md");
+  const shipped = readFileSync(SKILL_SOURCE, "utf8");
+  if (existsSync(path) && readFileSync(path, "utf8") === shipped) return { path, action: "already current:" };
+  const action = existsSync(path) ? "updated" : "installed";
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, shipped);
+  return { path, action };
+}

package/lib/doctor.mjs

@@ -318,12 +318,11 @@ export function doctor(dir, { out = console.log, via = "argument" } = {}) {
     else ok(grants.length, "grants", `across ${new Set(grants.map((g) => g.circle).filter(Boolean)).size} circle(s), ${grants.filter((g) => g.holder?.kind === "agent").length} to agents`);
   }
 
-  // 12. folder manifests (Spec 07, section 2): each record folder says what its entries are and
-  // which connectors feed its references. A manifest that is not JSON refuses the run.
+  // 12. folder manifests (Spec 07, section 2): each folder says what its entries are and which
+  // connectors feed its references. Read across the whole record root, not only the record roles
+  // (lib/folders.mjs folderManifests says why). A manifest that is not JSON refuses the run.
   let folders = [];
-  if (recordRoles.length === 0) {
-    skip("folder manifests", "no record role resolved to a directory");
-  } else {
+  {
     try {
       folders = folderManifests(evda);
     } catch (e) {
@@ -335,7 +334,7 @@ export function doctor(dir, { out = console.log, via = "argument" } = {}) {
       for (const p of f.problems) (p.level === "fail" ? fail : warn)(`folder ${relative(dir, f.dir) || "."}`, p.message);
       out(`        ${(relative(dir, f.dir) || ".").padEnd(24)} type ${f.type ?? "?"}  connectors [${f.connectors.join(", ")}]  views [${f.views.map((v) => v.view).join(", ")}]`);
     }
-    if (folders.length === 0) skip("folder manifests", `no record folder carries ${FOLDER_MANIFEST}`);
+    if (folders.length === 0) skip("folder manifests", `no folder in the record carries ${FOLDER_MANIFEST}`);
     else ok(folders.length, "folder manifests", `${folders.filter((f) => f.connectors.length).length} with connectors`);
 
     // 12b. views (Spec 07, section 5): a manifest's `views` declare the markdown files the renderer

package/lib/folders.mjs

@@ -112,24 +112,38 @@ export function validateFolderManifest(m, rel) {
   return out;
 }
 
-// Every folder manifest under the record's record roles, deepest last. Each item is
-// { rel, abs, dir, ...validateFolderManifest }. Throws only on a manifest that is not JSON.
+// Every folder manifest in the record. Each item is { rel, abs, dir, ...validateFolderManifest }.
+// Throws only on a manifest that is not JSON.
+//
+// The record roles are walked first, in role order and deepest last, then the rest of the record
+// root, because a folder a preset or the owner made outside every role still says what it holds and
+// is still read. Until HQ-1216 only the roles were walked, and a malformed manifest one level outside
+// them printed OK. The walk skips dot-directories and node_modules and does not follow a symlink
+// below a role or the root, so a link cannot pull another tree, or the same tree twice, into the count.
+//
+// FALSIFIED 2026-09-17: a fresh scaffold with Outside/folder.evda.json holding {"kind":"person"}
+// (no type). The roles-only walk (main at 2788455) printed "CHECKED 3 folder manifests" and
+// "OK  9 check(s), 0 warning(s)", exit 0. This walk prints "FAIL  folder Outside
+// Outside/folder.evda.json: has no "type". ..." and "CHECKED 4 folder manifests", exit 1.
 export function folderManifests(evda) {
   const out = [];
-  const roots = resolveAll(evda).filter((r) => r.known && r.mapped && r.layer === "record" && r.exists && r.isDir);
+  const seen = new Set();
   const walk = (dir) => {
+    if (seen.has(dir)) return;
+    seen.add(dir);
     const m = readFolderManifest(dir);
     if (m !== null) {
       const abs = join(dir, FOLDER_MANIFEST);
       out.push({ rel: relative(evda.dir, abs), abs, dir, ...validateFolderManifest(m, relative(evda.dir, abs)) });
     }
-    for (const name of readdirSync(dir).sort()) {
-      if (name.startsWith(".")) continue;
-      const p = join(dir, name);
-      if (statSync(p).isDirectory()) walk(p);
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      if (e.isDirectory()) walk(join(dir, e.name));
     }
   };
-  for (const r of roots) walk(r.abs);
+  for (const r of resolveAll(evda).filter((x) => x.known && x.mapped && x.layer === "record" && x.exists && x.isDir)) walk(r.abs);
+  walk(evda.dir);
   return out;
 }