create-evda 0.1.2 → 0.1.4

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.
+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.
 
 Unattended, nothing is asked:
 
@@ -27,7 +27,39 @@ npx create-evda my-evda --yes --agent-name Iris --owner "Dana" --purpose "why wo
 
 ## Any AI
 
-`AGENTS.md` is the one source. Codex, Cursor, GitHub Copilot, Windsurf, Zed, opencode and the other tools on agents.md read it directly. For the two that do not, the scaffold writes a one line loader: `CLAUDE.md` for Claude Code and `GEMINI.md` for Gemini CLI, each `@AGENTS.md`. Aider takes `aider --read AGENTS.md`. A chat app with projects (ChatGPT, Claude) cannot read the folder: paste `AGENTS.md` into the project's instructions and add your record files; what you write there stays in the app until you copy it into `record/`.
+`AGENTS.md` is the one source. Codex, Cursor, GitHub Copilot, Windsurf, Zed, opencode and the other tools on agents.md read it directly. For the two that do not, the scaffold writes a one line loader: `CLAUDE.md` for Claude Code and `GEMINI.md` for Gemini CLI, each `@AGENTS.md`. Aider takes `aider --read AGENTS.md`. The Claude desktop app reads it too, once its Filesystem extension is installed and pointed at this folder (Settings, then Extensions, then Filesystem). ChatGPT and Claude in the browser or app, used through a Project, cannot read or write this folder: a Project's instructions field holds text for that conversation only, and pasting `AGENTS.md` into it does not run an EVDA, because nothing you write there reaches `record/`. Bring what a chat app like that already knows about you in once, as an import, instead: see "Bringing in what an AI already knows" below.
+
+## Bringing in what an AI already knows
+
+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_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.
 
 ## Circles and other people
 
@@ -35,7 +67,7 @@ Everything is private until you share it. A circle is a part of the record you c
 
 ## 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`.
 
@@ -93,6 +125,15 @@ 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
 
 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,6 +48,19 @@ 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 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
@@ -58,6 +71,14 @@ const HELP = `evda: operate an EVDA. The files are the truth; this is optional.
 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 +88,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 +126,54 @@ 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 "where": {
       const found = locate({});
       console.log(`${found.dir}  (via ${found.via})`);

package/create-evda.mjs

@@ -28,7 +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 { PLATFORMS, PLATFORM_KEYS, LOADERS, CHAT_APPS, DICTATION, DEFAULT_AGENT_NAME, platformKey, fillOwnerSection, aiLine, interview, trainingSection } from "./lib/setup.mjs";
+import { clients, installSkill } from "./lib/connect.mjs";
+import { desktopInstructions } from "./lib/routines.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));
 const TEMPLATES = join(HERE, "templates");
@@ -54,12 +56,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] [--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,
   };
   const args = argv.flatMap((a) => {
     const eq = /^(--[a-z-]+)=([\s\S]*)$/.exec(a);
@@ -77,6 +80,14 @@ 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 === "--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);
@@ -243,13 +254,26 @@ export async function main(argv, io = null) {
   log(`Open it with ${agent}:`);
   for (const k of chosen) for (const line of PLATFORMS[k].open) log(`  ${line}`);
   if (opts.platform && opts.platform !== "other") log(`  ${PLATFORMS.other.open[0]}`);
-  for (const line of CHAT_APPS) log(`  ${line}`);
+  for (const line of DESKTOP_FILESYSTEM) log(`  ${line}`);
   if (!opts.trainingOff) {
     log("");
     log(`Model training is not confirmed off yet, so ${agent} asks about it first. Where to turn it off:`);
     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/mcp.mjs

@@ -0,0 +1,258 @@
+// `evda mcp`: the record as an MCP server over stdio, so the AI someone already uses (Claude Code,
+// Codex, the Claude desktop app) can read and write their EVDA.
+//
+// No SDK. The stdio transport is newline-delimited JSON-RPC 2.0 on stdin and stdout, with logs on
+// stderr, and a server that only answers requests needs initialize, ping, tools and resources. That
+// is small enough to write here and keep the package at zero runtime dependencies
+// (test/deps.test.mjs), which is what lets `npx create-evda` install nothing but itself.
+//
+// stdout carries protocol messages only. Nothing in this file or the tools it calls prints to
+// stdout; doctor's report is captured into the tool result.
+
+import { createInterface } from "node:readline";
+import { SCHEMA_VERSION } from "./manifest.mjs";
+import { openEvda } from "./manifest.mjs";
+import { EvdaError } from "./errors.mjs";
+import * as tools from "./tools.mjs";
+
+// Newest first. The server answers with the client's version when it supports it, and with the
+// newest otherwise; the client decides whether to continue.
+export const PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export const SERVER_NAME = "evda";
+
+const INSTRUCTIONS = [
+  "This server is the owner's EVDA: their record, in plain files on this machine.",
+  "Call evda_operating_layer first and follow it for the whole session: it is who you are (Iris unless they renamed you) and how the record is kept.",
+  "File the owner's words verbatim with evda_write in the same turn they say them, and report the path it returns in the past tense.",
+  "Never quiz them. Never create a circle or grant; propose one with evda_propose_circle only when they ask to share, and wait for their yes.",
+].join(" ");
+
+const str = (description) => ({ type: "string", description });
+
+export const TOOLS = [
+  {
+    name: "evda_operating_layer",
+    title: "Read the operating layer",
+    description: "Returns AGENTS.md, the record's operating layer: who the agent is, what this EVDA is for in the owner's words, and how to keep the record. Read it first, every session.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.operatingLayer(evda, args);
+      return { text: r.text, data: { path: r.path } };
+    },
+  },
+  {
+    name: "evda_recent",
+    title: "Read the last few days",
+    description: "Returns every record file dated in the last N days (default 3), newest first, whole.",
+    inputSchema: { type: "object", properties: { days: { type: "integer", minimum: 1, maximum: 90, description: "How many days back, today included. Default 3." } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.recent(evda, args);
+      const body = r.files.map((f) => `<file path="${f.path}" date="${f.date}">\n${f.text}\n</file>`).join("\n\n");
+      const head = `${r.files.length} file(s) dated ${r.from} to ${r.to}${r.omitted ? `, ${r.omitted} more omitted for size (read them with evda_search)` : ""}.`;
+      return { text: r.files.length ? `${head}\n\n${body}` : `Nothing in the record is dated ${r.from} to ${r.to}.`, data: { from: r.from, to: r.to, paths: r.files.map((f) => f.path), omitted: r.omitted } };
+    },
+  },
+  {
+    name: "evda_write",
+    title: "File the owner's words",
+    description: "Appends the owner's words, exactly as they said them, to today's daily file under the local time, and returns the path. Append only: it takes no path and never edits or replaces anything. Refuses anything shaped like a password, key or token.",
+    inputSchema: { type: "object", properties: { words: str("The owner's words, verbatim: filler, hedges and typos intact. Never a summary.") }, required: ["words"], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.write(evda, args);
+      return { text: `Filed to ${r.path}.`, data: r };
+    },
+  },
+  {
+    name: "evda_import",
+    title: "File an import from another AI",
+    description: "Files what another AI (ChatGPT, Claude, Gemini...) said it knows about the owner, verbatim, under imports/ with its source and date, and returns the path. An import is not the owner's words; each line is a claim to check with them over time.",
+    inputSchema: {
+      type: "object",
+      properties: { text: str("The other AI's answer, verbatim."), source: str("Which AI or app said it."), date: str("YYYY-MM-DD the other AI wrote it. Default today.") },
+      required: ["text", "source"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.importText(evda, args);
+      return { text: `Filed the import to ${r.path}.`, data: r };
+    },
+  },
+  {
+    name: "evda_search",
+    title: "Search the record",
+    description: "Plain text search, case-insensitive, over the record, its imports and the ledger, on this machine. Nothing leaves it. Returns each matching line with its path and line number.",
+    inputSchema: { type: "object", properties: { query: str("Words to find."), limit: { type: "integer", minimum: 1, maximum: 500, description: "Most lines to return. Default 50." } }, required: ["query"], additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.search(evda, args);
+      const lines = r.matches.map((m) => `${m.path}:${m.line}: ${m.text}`);
+      const tail = r.more ? `\n${r.more} more match(es) past the limit.` : "";
+      return { text: r.matches.length ? `${r.matches.length} match(es) in ${r.searched} file(s):\n${lines.join("\n")}${tail}` : `No match for ${JSON.stringify(r.query)} in ${r.searched} file(s).`, data: r };
+    },
+  },
+  {
+    name: "evda_circles",
+    title: "List circles",
+    description: "Lists the record's circles (the parts the owner chose to share), who may read each, what it covers and its policy rules. Read only.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.circles(evda, args);
+      if (!r.role) return { text: "This record has no circles layer. Everything in it is private.", data: r };
+      if (!r.circles.length) return { text: "No circles yet. Everything in the record is private.", data: r };
+      const lines = r.circles.map((c) => [
+        `${c.name} (${c.public ? "public" : "private"}): ${c.description ?? "no description"}`,
+        `  members: ${c.members.join(", ") || "none"}; maintainers: ${c.maintainers.join(", ") || "none"}`,
+        ...c.policy.map((p) => `  rule [${p.status}] ${p.rule}`),
+        ...c.problems.map((p) => `  problem: ${p}`),
+      ].join("\n"));
+      return { text: lines.join("\n"), data: r };
+    },
+  },
+  {
+    name: "evda_propose_circle",
+    title: "Propose a circle",
+    description: "Writes a proposal for a circle as a file under proposals/ for the owner to read. It never creates the circle, grants anyone access, or moves an entry: those wait for the owner's explicit yes. Use it only when the owner asks to share something.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: str("Short name for the circle: letters, digits, - and _."),
+        who: str("Who may read it, in plain words."),
+        what: str("What it covers."),
+        policy: { type: "array", items: { type: "string" }, description: "Its rules, one sentence each, in the owner's words where possible." },
+        why: str("Why the owner wants it, in their words."),
+      },
+      required: ["name", "who", "what"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.proposeCircle(evda, args);
+      return { text: `Wrote the proposal to ${r.path}. No circle was created and nobody was granted anything; that waits for the owner's yes.`, data: r };
+    },
+  },
+  {
+    name: "evda_doctor",
+    title: "Check the record",
+    description: "Runs evda doctor on the record and returns its report. Exit 0 means well formed.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.doctorReport(evda, args);
+      return { text: `${r.text}\n\nexit ${r.exit}`, data: { exit: r.exit }, isError: r.exit !== 0 };
+    },
+  },
+];
+
+export const RESOURCES = [
+  { uri: "evda://agents", name: "AGENTS.md", title: "The operating layer", mimeType: "text/markdown", read: (evda) => tools.operatingLayer(evda).text },
+  {
+    uri: "evda://today",
+    name: "today",
+    title: "Today's daily file",
+    mimeType: "text/markdown",
+    read: (evda) => {
+      const r = tools.recent(evda, { days: 1 });
+      const daily = r.files.find((f) => /(^|\/)\d{4}-\d{2}-\d{2}\.md$/.test(f.path) && f.date === r.to);
+      return daily ? daily.text : `# ${r.to}\n\nNothing written today yet.\n`;
+    },
+  },
+];
+
+const RPC = { PARSE: -32700, INVALID: -32600, METHOD: -32601, PARAMS: -32602, INTERNAL: -32603 };
+
+// One request in, one response out (or null for a notification). Pure apart from the tools' own
+// file writes, so tests drive it without a process.
+export function handle(msg, ctx) {
+  const isRequest = msg && typeof msg === "object" && msg.jsonrpc === "2.0" && typeof msg.method === "string";
+  const hasId = msg && Object.prototype.hasOwnProperty.call(msg, "id") && msg.id !== null;
+  if (!isRequest) return hasId || !msg ? error(msg?.id ?? null, RPC.INVALID, "not a JSON-RPC 2.0 request") : null;
+  if (!hasId) return null; // notifications: initialized, cancelled. Nothing to answer.
+  const ok = (result) => ({ jsonrpc: "2.0", id: msg.id, result });
+  const p = msg.params ?? {};
+  try {
+    switch (msg.method) {
+      case "initialize": {
+        const asked = p.protocolVersion;
+        return ok({
+          protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: { listChanged: false }, resources: { listChanged: false, subscribe: false } },
+          serverInfo: { name: SERVER_NAME, title: "EVDA", version: ctx.version },
+          instructions: INSTRUCTIONS,
+        });
+      }
+      case "ping":
+        return ok({});
+      case "tools/list":
+        return ok({ tools: TOOLS.map(({ run, ...t }) => t) });
+      case "tools/call": {
+        const tool = TOOLS.find((t) => t.name === p.name);
+        if (!tool) return error(msg.id, RPC.PARAMS, `unknown tool ${JSON.stringify(p.name)}`);
+        const args = p.arguments ?? {};
+        if (typeof args !== "object" || Array.isArray(args)) return error(msg.id, RPC.PARAMS, "arguments must be an object");
+        try {
+          const r = tool.run(ctx.evda(), args);
+          // Text only. A client that finds structuredContent may show the model that instead of the text
+          // (Claude Code did, 2026-09-17: evda_operating_layer reached the model as {"path":"AGENTS.md"}),
+          // so everything the model needs, paths included, is in the text.
+          return ok({ content: [{ type: "text", text: r.text }], isError: Boolean(r.isError) });
+        } catch (e) {
+          // A refusal is a tool result the model reads and acts on, not a protocol failure.
+          if (e instanceof EvdaError) return ok({ content: [{ type: "text", text: e.message }], isError: true });
+          throw e;
+        }
+      }
+      case "resources/list":
+        return ok({ resources: RESOURCES.map(({ read, ...r }) => r) });
+      case "resources/read": {
+        const res = RESOURCES.find((r) => r.uri === p.uri);
+        if (!res) return error(msg.id, -32002, `resource not found: ${p.uri}`);
+        return ok({ contents: [{ uri: res.uri, mimeType: res.mimeType, text: res.read(ctx.evda()) }] });
+      }
+      case "resources/templates/list":
+        return ok({ resourceTemplates: [] });
+      case "prompts/list":
+        return ok({ prompts: [] });
+      default:
+        return error(msg.id, RPC.METHOD, `method not found: ${msg.method}`);
+    }
+  } catch (e) {
+    ctx.log?.(e.stack ?? String(e));
+    return error(msg.id, RPC.INTERNAL, e instanceof EvdaError ? e.message : "internal error; the server's stderr has the detail");
+  }
+}
+
+function error(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+// Serve on stdio until stdin closes. `dir` is the located record; it is reopened for every call so
+// a record edited by hand between calls is read as it is now.
+export function serve({ dir, version, input = process.stdin, output = process.stdout, log = (s) => process.stderr.write(`[evda mcp] ${s}\n`) }) {
+  const ctx = { version, log, evda: () => openEvda(dir) };
+  openEvda(dir); // refuse to start on something that is not a record
+  log(`serving ${dir} (tool schema ${SCHEMA_VERSION})`);
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  const send = (m) => output.write(`${JSON.stringify(m)}\n`);
+  rl.on("line", (line) => {
+    if (line.trim() === "") return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return send(error(null, RPC.PARSE, "parse error"));
+    }
+    if (Array.isArray(msg)) {
+      const out = msg.map((m) => handle(m, ctx)).filter(Boolean);
+      if (out.length) send(out);
+      return;
+    }
+    const r = handle(msg, ctx);
+    if (r) send(r);
+  });
+  return new Promise((resolveDone) => rl.on("close", resolveDone));
+}