create-evda 0.1.3 → 0.1.5

package/lib/mcp.mjs

@@ -0,0 +1,301 @@
+// `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";
+import * as presets from "./presets.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.",
+  "Organization comes from the preset library (evda_presets): propose with evda_propose_structure, and apply with evda_apply_preset only after 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_presets",
+    title: "List presets",
+    description: "Lists the ways to organize a record that EVDA ships (the preset library), each with who it suits, or with an id shows one preset's folders. Read only. A new folder is proposed from a preset here, never invented.",
+    inputSchema: { type: "object", properties: { id: str("A preset id, to show that one. Omit to list them all.") }, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = presets.presetsTool(evda, args);
+      if (r.presets) return { text: r.presets.map((p) => `${p.id}: ${p.title}. ${p.for} (${p.folders} folders)`).join("\n") };
+      const p = r.preset;
+      return { text: [`${p.id}: ${p.title}. ${p.for}`, ...p.folders.map((f) => `- ${f.path}/ ${f.type ?? "untyped"}${f.connectors?.length ? `, connectors ${f.connectors.join(", ")}` : ""}${f.note ? `: ${f.note}` : ""}`), ...(p.routines?.length ? [`routines it suits: ${p.routines.join(", ")}`] : [])].join("\n") };
+    },
+  },
+  {
+    name: "evda_propose_structure",
+    title: "Propose a preset's structure",
+    description: "Shows what applying a preset would add to this record, as a plan and a plain-language summary to show the owner. It never writes. Folders that already match are left alone, one that differs is reported and never changed, and nothing is ever moved, renamed or deleted.",
+    inputSchema: { type: "object", properties: { id: str("The preset id, from evda_presets.") }, required: ["id"], additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = presets.proposeStructureTool(evda, args);
+      return { text: `${r.summary}\n\nPlan:\n${presets.planLines(r.plan).join("\n") || "  nothing to add"}` };
+    },
+  },
+  {
+    name: "evda_apply_preset",
+    title: "Apply a preset",
+    description: "Adds a preset's folders and folder manifests to the record. Call it only after showing the owner evda_propose_structure and the owner said yes to this preset in this conversation; pass confirmed: true only then. It only adds: it never moves, renames, deletes or overwrites, and a circle in the preset becomes a proposal file, never a circle.",
+    inputSchema: {
+      type: "object",
+      properties: { id: str("The preset id the owner said yes to."), confirmed: { type: "boolean", description: "true only when the owner said yes to this preset in this conversation." } },
+      required: ["id", "confirmed"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = presets.applyPresetTool(evda, args);
+      const n = r.plan.create.length + r.plan.write.length;
+      return { text: `${n ? `Applied the ${r.plan.title} preset.` : `Nothing was written: the record already has the ${r.plan.title} preset.`}\n${r.lines.join("\n")}` };
+    },
+  },
+  {
+    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));
+}

package/lib/organize.mjs

@@ -0,0 +1,224 @@
+// `evda organize`: go through what the owner left inward and say where it belongs. Moves nothing.
+//
+// The mechanical part is deterministic and done here:
+//   - each dated capture is copied, verbatim, into the daily file of its date, once. A marker comment
+//     in the daily file records the copy, so a second run files nothing twice and a rebuilt .evda/
+//     cannot make it forget.
+//   - the report lists what needs a person's judgment: people a recent note mentions whose file has
+//     nothing from that note, imports to check, undated notes, and notes that sit under no role.
+// The report is appended to reports/organize/<date>.md. Nothing is moved, renamed or deleted, and
+// nothing is written into circles/ or grants/.
+//
+// The judgment part runs through the owner's own AI (`--with-ai`): `claude -p` with the evda skill
+// and read-only EVDA tools, given the report. Its answer is appended to the same report. EVDA holds
+// no key and calls no model; `claude` is the owner's install, signed in as the owner.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { resolveRole, resolveAll } from "./roles.mjs";
+import { mdFiles, fileDate } from "./record.mjs";
+import { secretShape } from "./references.mjs";
+import { importsDir, localDate, localTime } from "./tools.mjs";
+import { serverCommand, SKILL_SOURCE } from "./connect.mjs";
+import { SERVER_NAME } from "./clients.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const REPORTS = "reports";
+const marker = (rel) => `<!-- evda:capture ${rel} -->`;
+const posix = (p) => p.split("\\").join("/");
+
+function stripFrontmatter(text) {
+  if (!text.startsWith("---\n")) return text;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return text;
+  return text.slice(text.indexOf("\n", end + 1) + 1);
+}
+
+function secretLine(text) {
+  for (const line of text.split("\n")) {
+    const s = secretShape(line);
+    if (s) return s;
+  }
+  return null;
+}
+
+// A person's names: the first `# ` heading and the file's stem with - and _ as spaces.
+function personNames(abs, text) {
+  const names = new Set();
+  const h = /^# (.+)$/m.exec(text);
+  if (h) names.add(h[1].trim());
+  names.add(basename(abs, ".md").replace(/[-_]+/g, " ").trim());
+  return [...names].filter((n) => n.length >= 2);
+}
+
+const mentions = (text, name) => new RegExp(`(^|[^\\p{L}\\p{N}])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}($|[^\\p{L}\\p{N}])`, "iu").test(text);
+
+// What organize would do and has to say, without writing. `window` is how many days back a note
+// counts as recent for the people check.
+export function plan(evda, { now = new Date(), window = 7 } = {}) {
+  const rel = (abs) => posix(relative(evda.dir, abs));
+  const daily = resolveRole(evda, "record/daily");
+  const captures = resolveRole(evda, "record/captures");
+  const people = resolveRole(evda, "record/people");
+  if (!daily.mapped || !daily.exists) throw new EvdaError('organize needs a "record/daily" role that exists; it files captures into their day.', { code: "NO_ROLE", exit: 2 });
+  const start = new Date(now);
+  start.setDate(start.getDate() - (window - 1));
+  const from = localDate(start);
+  const out = { filings: [], people: [], imports: [], undated: [], unplaced: [], refused: [], examined: 0 };
+
+  // Captures into their day.
+  if (captures.mapped && captures.exists) {
+    for (const abs of mdFiles(captures.abs)) {
+      out.examined += 1;
+      const text = readFileSync(abs, "utf8");
+      const date = fileDate(abs, text);
+      if (!date) { out.undated.push(rel(abs)); continue; }
+      const secret = secretLine(text);
+      if (secret) { out.refused.push({ path: rel(abs), why: `holds ${secret}; not copied` }); continue; }
+      const target = join(daily.abs, `${date}.md`);
+      if (existsSync(target) && readFileSync(target, "utf8").includes(marker(rel(abs)))) continue;
+      out.filings.push({ from: rel(abs), to: rel(target), date, body: stripFrontmatter(text).replace(/\n+$/, "") });
+    }
+  }
+  for (const abs of mdFiles(daily.abs)) {
+    out.examined += 1;
+    if (!fileDate(abs, readFileSync(abs, "utf8"))) out.undated.push(rel(abs));
+  }
+
+  // People a recent note mentions, whose file carries nothing from that note.
+  if (people.mapped && people.exists) {
+    const recent = [...mdFiles(daily.abs), ...(captures.mapped && captures.exists ? mdFiles(captures.abs) : [])]
+      .map((abs) => ({ abs, text: readFileSync(abs, "utf8") }))
+      .filter((f) => { const d = fileDate(f.abs, f.text); return d && d >= from; });
+    for (const p of mdFiles(people.abs)) {
+      out.examined += 1;
+      const ptext = readFileSync(p, "utf8");
+      for (const name of personNames(p, ptext)) {
+        for (const f of recent) {
+          if (!mentions(f.text, name)) continue;
+          if (ptext.includes(rel(f.abs)) || ptext.includes(basename(f.abs, ".md"))) continue;
+          if (out.people.some((x) => x.person === rel(p) && x.note === rel(f.abs))) continue;
+          out.people.push({ person: rel(p), name, note: rel(f.abs) });
+        }
+      }
+    }
+  }
+
+  // Imports: each is a claim to check with the owner over time. Recent ones are listed.
+  const imp = importsDir(evda);
+  if (existsSync(imp.abs)) {
+    for (const abs of mdFiles(imp.abs)) {
+      out.examined += 1;
+      const d = fileDate(abs, readFileSync(abs, "utf8"));
+      if (d && d >= from) out.imports.push(rel(abs));
+    }
+  }
+
+  // Notes under the record's folder that no role or the imports folder claims.
+  const claimed = resolveAll(evda).filter((r) => r.mapped && r.exists && r.isDir).map((r) => r.abs);
+  claimed.push(imp.abs);
+  const root = dirname(daily.abs);
+  if (root !== evda.dir && existsSync(root)) {
+    const walk = (d) => {
+      for (const n of readdirSync(d).sort()) {
+        if (n.startsWith(".")) continue;
+        const abs = join(d, n);
+        if (claimed.includes(abs)) continue;
+        if (statSync(abs).isDirectory()) walk(abs);
+        else if (n.endsWith(".md")) { out.examined += 1; out.unplaced.push(rel(abs)); }
+      }
+    };
+    walk(root);
+  }
+  return out;
+}
+
+export function reportText(p, { now = new Date(), window = 7 } = {}) {
+  const lines = [`## Run ${localTime(now)}`, ""];
+  lines.push(`Examined ${p.examined} note(s). Moved nothing.`, "");
+  lines.push("### Filed");
+  if (p.filings.length) for (const f of p.filings) lines.push(`- ${f.from} copied verbatim into ${f.to}`);
+  else lines.push("- Nothing new to file.");
+  lines.push("", `### People mentioned in the last ${window} days`);
+  if (p.people.length) for (const x of p.people) lines.push(`- ${x.note} mentions ${x.name}; ${x.person} has nothing from it yet.`);
+  else lines.push("- None without a note on their file.");
+  lines.push("", "### Imports to check with the owner over time");
+  if (p.imports.length) for (const i of p.imports) lines.push(`- ${i}: what another AI said, not their words.`);
+  else lines.push("- None recent.");
+  if (p.undated.length) { lines.push("", "### Undated, so not filed"); for (const u of p.undated) lines.push(`- ${u}: needs a YYYY-MM-DD at the start of its name, or a date: line.`); }
+  if (p.unplaced.length) { lines.push("", "### Under no role"); for (const u of p.unplaced) lines.push(`- ${u}: not in daily, captures, people or imports.`); }
+  if (p.refused.length) { lines.push("", "### Not copied"); for (const r of p.refused) lines.push(`- ${r.path}: ${r.why}. Keep the secret in a password manager and take it out of the note.`); }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function appendReport(evda, kind, date, block) {
+  const dir = join(evda.dir, REPORTS, kind);
+  mkdirSync(dir, { recursive: true });
+  const abs = join(dir, `${date}.md`);
+  if (!existsSync(abs)) writeFileSync(abs, `# ${kind === "organize" ? "Organize" : "Look back"}, ${date}\n\nWritten by evda ${kind}. Append only; each run adds a section.\n`);
+  appendFileSync(abs, `\n${block.replace(/\n+$/, "")}\n`);
+  return posix(relative(evda.dir, abs));
+}
+
+// Run the owner's claude -p with the skill and read-only EVDA tools. Returns { ok, text, why }.
+export function askOwnersAi(evda, prompt, { model = null, env = process.env, timeoutMs = 600_000 } = {}) {
+  const bin = env.EVDA_CLAUDE || "claude";
+  const { command, args } = serverCommand(evda.dir);
+  const mcp = JSON.stringify({ mcpServers: { [SERVER_NAME]: { type: "stdio", command, args } } });
+  const allowed = ["evda_operating_layer", "evda_recent", "evda_search", "evda_circles"].map((t) => `mcp__${SERVER_NAME}__${t}`);
+  const skill = existsSync(SKILL_SOURCE) ? readFileSync(SKILL_SOURCE, "utf8") : "";
+  const argv = ["-p", prompt, "--mcp-config", mcp, "--strict-mcp-config", "--allowedTools", allowed.join(","), "--output-format", "text"];
+  if (skill) argv.push("--append-system-prompt", skill);
+  if (model) argv.push("--model", model);
+  const r = spawnSync(bin, argv, { cwd: evda.dir, env, encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  if (r.error) return { ok: false, why: r.error.code === "ENOENT" ? `${bin} is not installed or not on PATH` : String(r.error.message) };
+  if (r.status !== 0) return { ok: false, why: `${bin} -p exited ${r.status}: ${(r.stderr || r.stdout || "").trim().split("\n").slice(-3).join(" ")}` };
+  const text = (r.stdout ?? "").trim();
+  if (!text) return { ok: false, why: `${bin} -p answered with nothing` };
+  return { ok: true, text };
+}
+
+export async function organize(evda, { now = new Date(), window = 7, withAi = false, dryRun = false, model = null, env = process.env } = {}) {
+  const p = plan(evda, { now, window });
+  const date = localDate(now);
+  let report = reportText(p, { now, window });
+  if (dryRun) return { plan: p, report, path: null, exit: 0, summary: `${report}\n(dry run: nothing was written)` };
+
+  for (const f of p.filings) {
+    const abs = join(evda.dir, f.to);
+    const head = existsSync(abs) ? "" : `# ${f.date}\n`;
+    const lead = existsSync(abs) && !readFileSync(abs, "utf8").endsWith("\n") ? "\n" : "";
+    appendFileSync(abs, `${lead}${head}\n## Capture: ${basename(f.from, ".md")}\n\n${marker(f.from)}\n\n${f.body}\n`);
+  }
+  let exit = 0;
+  if (withAi) {
+    const ai = askOwnersAi(evda, [
+      "Use the evda skill's Organizing section. Here is today's organize report for this record.",
+      "For each note that needs a place, answer in one line: the note's path, where it belongs, and the words from the note that say so, quoted.",
+      "Check against the record with the evda tools first. Write nothing. If nothing needs a place, say so in one line.",
+      "",
+      report,
+    ].join("\n"), { model, env });
+    if (ai.ok) {
+      const secret = secretLine(ai.text);
+      report += secret ? `\n### Your AI's read\n\nNot kept: the answer held ${secret}.\n` : `\n### Your AI's read (claude -p)\n\n${ai.text}\n`;
+    } else {
+      report += `\n### Your AI's read\n\nSKIPPED: ${ai.why}. Nothing else in this run depended on it.\n`;
+      exit = 1;
+    }
+  }
+  const path = appendReport(evda, "organize", date, report);
+  return { plan: p, report, path, exit, summary: `${report}\nReport appended to ${path}. Filed ${p.filings.length} capture(s).` };
+}
+
+export async function lookBack(evda, { now = new Date(), model = null, env = process.env } = {}) {
+  const ai = askOwnersAi(evda, "Use the evda skill's Look back section for the last 7 days of this record. Write nothing; your answer is appended to a report.", { model, env });
+  const date = localDate(now);
+  const block = ai.ok
+    ? (secretLine(ai.text) ? `## Run ${localTime(now)}\n\nNot kept: the answer held a secret-shaped line.\n` : `## Run ${localTime(now)}\n\n${ai.text}\n`)
+    : `## Run ${localTime(now)}\n\nSKIPPED: ${ai.why}.\n`;
+  const path = appendReport(evda, "look-back", date, block);
+  return { path, exit: ai.ok ? 0 : 1, summary: `${block}\nAppended to ${path}.` };
+}