create-evda 0.1.5 → 0.1.6

package/lib/mcp.mjs

@@ -8,6 +8,10 @@
 //
 // 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.
+//
+// Every tool here reads and writes files on this machine, with one exception: evda_check_update
+// asks the npm registry for the tooling's latest version number. That is the server's only network
+// call, it carries nothing from the record, and it installs nothing.
 
 import { createInterface } from "node:readline";
 import { SCHEMA_VERSION } from "./manifest.mjs";
@@ -15,32 +19,153 @@ import { openEvda } from "./manifest.mjs";
 import { EvdaError } from "./errors.mjs";
 import * as tools from "./tools.mjs";
 import * as presets from "./presets.mjs";
+import * as gather from "./gather.mjs";
+import * as gatherApply from "./gather-apply.mjs";
+import { checkForUpdate, summarize } from "./update-check.mjs";
+import { callerFrom } from "./readers.mjs";
+import { listSkills, getSkill, writeSkill, noticeRepeat, SKILLS_REL } from "./skills.mjs";
+import { createSubrecord } from "./subrecord.mjs";
+import { FALSIFY } from "./mcp-auth.mjs";
+import { filingOf, FILING_MODES } from "./day-file.mjs";
+import { readManifest, writeManifest } from "./manifest.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.",
+// The server's instructions, by the owner's filing answer (HQ-1385). The Claude app was measured not
+// acting on this field (2026-09-22: it told Mike "I only write to EVÐA when you ask me to" while
+// this said to file unasked), so the trigger is also the first words of evda_write's description,
+// which is what a deferred tool shows. This stays for the clients that read it.
+export function instructions(filing) {
+  const lines = [
+    "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.",
+    ...(filing === "asked"
+      ? ["The owner turned automatic filing off: file their words with evda_write only when they ask you to save or file something, and report the path it returns in the past tense."]
+      : ["File every message the owner sends, verbatim, with evda_write in the same turn they say it, and report the path it returns in the past tense. Your first evda_write in this conversation opens its section with one line of context; the rest go under it."]),
+    ...(filing === null ? ["They have not said how filing works yet: evda_operating_layer holds the one question to ask them first, and evda_filing records the answer."] : []),
+    "The day's entry is their words verbatim plus one line of context on what the conversation was about, passed as evda_write's context: that line is yours and is labeled as not theirs, and it is never written into words. Where anything else goes (a person's page, a project, the ledger) is your call by the record's four roles, journal, work, collections and knowledge.",
+    "When you notice a process repeating (the same steps done or explained a second time, the same correction twice), write it once as a skill with evda_write_skill and tell the owner in one line; read the skills there are with evda_skills and follow the one that fits; when a run of one goes wrong, revise it. A skill is how you work, never a rule about their life.",
+    "When they ask for an EVÐA inside this one (a project, a company, an agent), make it with evda_create_subrecord; it runs doctor and returns the report. Sharing, grants and deletes still wait for their explicit yes.",
+    "When they say to just note something, file it with evda_note instead: no AI reads a noted entry, you included, until they say it can, and then evda_release_note clears it. A sealed entry or section is theirs alone: no tool shows it or releases it, and you are never told where it is; when a tool says part of the record is sealed, tell them it is there for them on their own device. When a tool says something was not shown, tell them in one plain sentence what is there and how they open it.",
+    ...(filing === "asked" ? [] : ["Filing is expected without being asked: they should never have to say \"save this\", and a conversation that ends with nothing of theirs filed has lost it."]),
+    "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.",
+    "When they point you at a pile they already have (a folder, an export), call evda_gather, then ask the questions from evda_gather_questions one at a time in your own words, and record each answer with evda_gather_answer. When every question is answered and the owner says yes to the summary, apply it with evda_gather_apply and confirmed: true; tell them the reversal manifest it names.",
+    PRIVACY_INSTRUCTIONS,
+  ];
+  return lines.join(" ");
+}
+
+// What leaves the device (HQ-1413), short here because every connection reads it, and whole in the
+// operating layer below. The providers' facts were verified on 2026-09-23 against their own help
+// pages (Claude privacy.claude.com 10023580, OpenAI help 7730893 and 5722486, Gemini 13594961); a
+// fact not verified is worded "may". test/privacy.test.mjs holds each point on both surfaces.
+export const PRIVACY_INSTRUCTIONS = [
+  "Privacy: the record stays on the owner's devices, and this connector keeps no copy of what passes through it: only the record changes, and only when a write tool is called.",
+  "What a tool returns enters this conversation, which your provider keeps under the owner's own account settings.",
+  "Read only what the question needs, refer to a sensitive entry rather than restating it, and never ask for a noted (and, where supported, sealed) entry or work around one.",
+  "Rating a reply can send the whole conversation to the provider to keep, and possibly to train on, even with training off (verified 2026-09-23 for Claude, ChatGPT and Gemini; the operating layer has each).",
+  "When a conversation has carried personal content from the record and they might rate or share it, tell them so plainly, once, never every turn.",
+  "To keep a conversation out of training, the option is the provider's incognito or temporary chat.",
 ].join(" ");
 
+export const PRIVACY_SECTION = [
+  "## Privacy: what leaves this device",
+  "",
+  "- The record stays on the owner's devices, and this connector keeps no copy of what passes through it: it logs no arguments and no results, and only the record changes, and only when a write tool is called.",
+  "- What a tool returns enters this conversation, which your provider keeps under the owner's own account settings. Anything you restate from the record is part of the conversation too.",
+  "- Read only what the question needs, and refer to a sensitive entry rather than restating it: its path or a few words, not its contents. Health, sex, money and other people's private lives are sensitive unless the owner says otherwise.",
+  "- Never ask for a noted (and, where supported, sealed) entry or work around one, through a search, another file or a summary.",
+  "- What rating a reply does, verified 2026-09-23:",
+  "  - Claude: a thumbs up or down stores the whole conversation for up to 5 years, de-linked from the account, and it may be used for training even with training off. Raw tool results are left out; whatever you restated from them is not.",
+  "  - ChatGPT: feedback makes the whole conversation usable for training even when the owner opted out. How long it is kept is not published.",
+  "  - Gemini: feedback with Keep Activity off sends the last 24 hours of chats, connected-app data included, and keeps them up to 3 years.",
+  "  - Any other provider may do the same, and a shared link may let anyone who has it read the conversation.",
+  "- When a conversation has carried personal content from the record and they might rate or share it, tell them so plainly, once, never every turn: what it would send, and to whom.",
+  "- To keep a conversation out of training, the option is the provider's incognito or temporary chat. Claude's incognito chats are never used for training; ChatGPT keeps a Temporary Chat up to 30 days; others may offer the same.",
+].join("\n");
+
 const str = (description) => ({ type: "string", description });
 
+// summarize() already names the command for the two statuses that ask the owner to run one. Over
+// stdio the owner may have no shell in front of them at all (the Claude desktop app), and `evda
+// update` shells out to npx, so the result says where the command goes and never offers to run it.
+const NEEDS_A_COMMAND = new Set(["UPDATE_AVAILABLE", "UNSTAMPED"]);
+const TERMINAL_NOTE = "Run that command in a terminal on this machine. Nothing here can run it: this server tells the owner an update exists, it never installs one.";
+
+// evda_write's description, by the owner's filing answer. It leads with when to call it, because a
+// deferred connector tool shows the model its name and the first line of its description and
+// nothing else until it is loaded (HQ-1385). An owner who has not answered is filed for as if they
+// said everything, the default setup offers; the operating layer asks them.
+// EVDA_CHAT_FALSIFY=old-description serves the description from before HQ-1385, which says what the
+// tool does and never when, for the test that shows the first line is what files.
+export const WRITE_DESCRIPTION = {
+  everything: "Call on every message the owner sends, unless automatic filing is off: files their words verbatim in today's daily file, one section per conversation (pass context, one line on what it is about, with the first), and returns the path. Append only. Refuses anything shaped like a password, key or token.",
+  asked: "Call only when the owner asks you to save or file something (they turned automatic filing off): files their words verbatim in today's daily file, one section per conversation, and returns the path. Append only. Refuses anything shaped like a password, key or token.",
+  old: "Appends the owner's words, exactly as they said them, to today's daily file under the local time, with one line of context on what the conversation was about when given, 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.",
+};
+const chatFalsified = (mode, env = process.env) => (env.EVDA_CHAT_FALSIFY ?? "").split(",").map((x) => x.trim()).includes(mode);
+
+// The tool list a client sees, with the descriptions that depend on the owner's filing answer.
+export function toolList(filing, env = process.env) {
+  return TOOLS.map(({ run, ...t }) => {
+    if (t.name !== "evda_write") return t;
+    const description = chatFalsified("old-description", env) ? WRITE_DESCRIPTION.old : WRITE_DESCRIPTION[filing === "asked" ? "asked" : "everything"];
+    return { ...t, description };
+  });
+}
+
+// The one setup question, asked at first connect when evda.json has no filing answer (HQ-1385).
+export const FILING_QUESTION = "Should I file everything you say here automatically, or only when you ask? (everything)";
+
+// The few lines a chat app reads before the whole operating layer (HQ-1385): who the agent is,
+// whether to file, one section per conversation, no share marks or circle rules, and "just note".
+// Five lines, and a sixth that asks the setup question when the owner has not answered it.
+export function chatSection(evda, agentsText = "") {
+  const field = (label) => new RegExp(`^- \\*\\*${label}:\\*\\*[ \\t]*(\\S.*)$`, "m").exec(agentsText)?.[1]?.trim() ?? "";
+  const agent = field("Agent name") || "Iris";
+  const owner = (typeof evda.manifest?.owner?.name === "string" && evda.manifest.owner.name.trim()) || field("Who I am") || "the owner";
+  const filing = filingOf(evda.manifest);
+  const lines = [
+    "## In a chat app, read this first",
+    "",
+    `- You are ${agent}, ${owner}'s thinking partner, and this server is their EVÐA; the full operating layer follows and holds for the whole session.`,
+    filing === "asked"
+      ? "- They turned automatic filing off: file their words with evda_write only when they ask you to."
+      : "- File every message they send with evda_write, verbatim (filler and typos intact), in the same turn, without being asked. Report the path in the past tense.",
+    "- One conversation is one section: your first evda_write opens it with one line of context, and the rest go under it.",
+    "- Never write a share mark or a circle rule. When they want to share, propose it and wait for their yes.",
+    "- \"Just note this\" means evda_note: no AI reads that entry, you included, until they say it can.",
+  ];
+  if (filing === null && !chatFalsified("no-consent-question")) lines.push(`- They have not said how filing works yet. Before anything else, ask this one line and nothing more: "${FILING_QUESTION}" Record the answer with evda_filing, then file the messages before it too if they said everything.`);
+  return lines.join("\n");
+}
+
+// Record the owner's filing answer in evda.json. Every other key is kept as it was read.
+export function setFiling(evda, args = {}) {
+  tools.onlyKeys("evda_filing", args, ["filing", "confirmed"]);
+  if (!FILING_MODES.includes(args.filing)) throw tools.refuse(`evda_filing "filing" is ${FILING_MODES.map((m) => JSON.stringify(m)).join(" or ")}.`, "BAD_FILING");
+  if (args.confirmed !== true) throw tools.refuse("evda_filing records the owner's own answer. Ask them, and pass confirmed: true with what they said.", "NOT_CONFIRMED");
+  const m = readManifest(evda.dir);
+  if (m.filing === args.filing) return { filing: args.filing, changed: false };
+  m.filing = args.filing;
+  writeManifest(evda.dir, m);
+  return { filing: args.filing, changed: true };
+}
+
 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.",
+    description: "Call first, every session: returns how to act here, a few lines for a chat app, what leaves this device, and then AGENTS.md whole, the record's operating layer (who the agent is, what this EVDA is for in the owner's words, and how the record is kept).",
     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 } };
+      return { text: `${chatSection(evda, r.text)}\n\n${PRIVACY_SECTION}\n\n${r.text}`, data: { path: r.path } };
     },
   },
   {
@@ -49,21 +174,22 @@ export const TOOLS = [
     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);
+    run: (evda, args, ctx) => {
+      const r = tools.recent(evda, args, { caller: ctx.caller });
       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 } };
+      const main = r.files.length ? `${head}\n\n${body}` : `Nothing${r.refused.length ? " you may read" : ""} in the record is dated ${r.from} to ${r.to}.`;
+      return { text: r.heldBack ? `${main}\n\n${r.heldBack}` : main, 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 },
+    description: WRITE_DESCRIPTION.everything,
+    inputSchema: { type: "object", properties: { words: str("The owner's words, verbatim: filler, hedges and typos intact. Never a summary."), context: str("One line, yours, on what the conversation was about. Written above their words and labeled as not theirs. Never their words.") }, required: ["words"], additionalProperties: false },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    run: (evda, args) => {
-      const r = tools.write(evda, args);
+    run: (evda, args, ctx) => {
+      const r = tools.write(evda, args, { session: ctx.session });
       return { text: `Filed to ${r.path}.`, data: r };
     },
   },
@@ -89,11 +215,66 @@ export const TOOLS = [
     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);
+    run: (evda, args, ctx) => {
+      const r = tools.search(evda, args, { caller: ctx.caller });
       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 };
+      const main = 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).`;
+      return { text: r.heldBack ? `${main}\n\n${r.heldBack}` : main, data: r };
+    },
+  },
+  {
+    name: "evda_read",
+    title: "Read one file of the record",
+    description: "Returns one file of the record, whole, by its path. Refuses, with the reason, a sealed entry, a just-noted entry and a file whose circle is set to be read by a different AI; a sealed section is replaced by one line saying it is there.",
+    inputSchema: { type: "object", properties: { path: str("The file's path, relative to the record.") }, required: ["path"], additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args, ctx) => {
+      const r = tools.readFile(evda, args, { caller: ctx.caller });
+      return { text: `<file path="${r.path}">\n${r.text}\n</file>${r.truncated ? "\n(truncated for size)" : ""}` };
+    },
+  },
+  {
+    name: "evda_note",
+    title: "Just note something",
+    description: "Call only when the owner says to just note something: files their words verbatim as a noted capture and returns the path. No AI reads a noted entry, this one included, until the owner says it can; it stays on their devices and in their own search. Refuses anything shaped like a password, key or token.",
+    inputSchema: { type: "object", properties: { words: str("The owner's words, verbatim.") }, required: ["words"], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.noteTool(evda, args);
+      return { text: `Noted at ${r.path}. No AI reads it until the owner says it can.`, data: r };
+    },
+  },
+  {
+    name: "evda_filing",
+    title: "Record how filing works",
+    description: "Call once, when the owner answers how filing works: records \"everything\" (file every message they send, without being asked) or \"asked\" (only when they ask) in evda.json, and returns what it wrote. Pass confirmed: true only with the answer they gave in this conversation. It changes the one filing key and nothing else.",
+    inputSchema: {
+      type: "object",
+      properties: { filing: { type: "string", enum: FILING_MODES, description: "everything, or asked." }, confirmed: { type: "boolean", description: "true only when the owner gave this answer in this conversation." } },
+      required: ["filing", "confirmed"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = setFiling(evda, args);
+      return { text: r.changed ? `Recorded "filing": "${r.filing}" in evda.json. ${r.filing === "everything" ? "Every message they send is filed from here on, this one included." : "From here on, file only when they ask."}` : `evda.json already says "filing": "${r.filing}". Nothing changed.`, data: r };
+    },
+  },
+  {
+    name: "evda_release_note",
+    title: "Release a noted entry",
+    description: "Clears the just-noted flag on one entry so it can be read, after the owner said in this conversation that this entry can be read now. Pass confirmed: true only then. It changes one frontmatter line and never the words. Refuses a sealed entry: no tool releases one.",
+    inputSchema: {
+      type: "object",
+      properties: { path: str("The noted entry's path, relative to the record."), confirmed: { type: "boolean", description: "true only when the owner said in this conversation that this entry can be read now." } },
+      required: ["path", "confirmed"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args) => {
+      const r = tools.releaseTool(evda, args);
+      return { text: `Released ${r.path}. It reads like any other entry now.`, data: r };
     },
   },
   {
@@ -178,6 +359,132 @@ export const TOOLS = [
       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_gather",
+    title: "Gather a pile into a proposal",
+    description: "Walks the folders or export files the owner names (a Documents folder, a Notes or Obsidian export, a contacts export), types every file, and writes a proposal: a preset, the folders the pile needs, and where each item would go. Anything an app holds becomes a reference, never a copy. It moves, copies and changes nothing in the sources and writes nothing into the record; the proposal is a file outside both. Returns the proposal's id and its summary.",
+    inputSchema: { type: "object", properties: { sources: { type: "array", items: { type: "string" }, minItems: 1, description: "Paths on this machine: folders or export files." }, into: str("The record this pile would grow, when it grows one: what that record already holds is left out, and a person with a page there is not asked about.") }, required: ["sources"], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = gather.gatherTool(evda, args);
+      return { text: `Proposal ${r.p.id}, written to ${r.path}.\n\n${gather.summaryText(r.p)}\n\n${gather.checkedLines(r.p).join("\n")}` };
+    },
+  },
+  {
+    name: "evda_gather_questions",
+    title: "What a gather needs the owner to decide",
+    description: "Returns the open questions on a gather proposal. Each one changes where at least one item goes, and nothing else is ever asked. Ask them one at a time, in conversation, in your own words; never as a list or a quiz.",
+    inputSchema: { type: "object", properties: { proposal: str("The proposal id evda_gather returned.") }, required: ["proposal"], additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = gather.gatherQuestionsTool(evda, args);
+      if (!r.open.length) return { text: `No open questions on ${r.p.id}.` };
+      return { text: r.open.map((q) => `[${q.id}] ${q.text} Answers: ${q.options.join(" or ")}. Moves ${q.affects.length} item(s).`).join("\n") };
+    },
+  },
+  {
+    name: "evda_gather_answer",
+    title: "Record the owner's answer on a gather",
+    description: "Records the owner's answer to one gather question on the proposal, re-places the items it affects, and says what moved. Pass the answer they gave in this conversation, never a guess. It changes the proposal file only; no source file and nothing in the record moves.",
+    inputSchema: {
+      type: "object",
+      properties: { proposal: str("The proposal id."), question: str("The question id, in brackets in evda_gather_questions."), answer: str("One of the question's answers, as the owner gave it.") },
+      required: ["proposal", "question", "answer"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = gather.gatherAnswerTool(evda, args);
+      const open = r.proposal.questions.filter((q) => q.answer === undefined).length;
+      return { text: `Recorded ${args.question} = ${args.answer}. ${r.moved.length} item(s) re-placed:\n${gather.answerLines(r).join("\n")}\n${open} question(s) still open.` };
+    },
+  },
+  {
+    name: "evda_gather_apply",
+    title: "Apply a gather proposal",
+    description: "Writes a gather proposal into a record: a new one made with the proposal's preset when \"into\" is a new folder, or the record named (the open one by default), adopting what it already holds and re-sorting nothing. Copies by default; move: true takes the files out of their sources. Call it only after every question is answered and the owner said yes to applying this proposal in this conversation; pass confirmed: true only then. It writes no share mark and no circle, keeps references as references, runs doctor, and writes a reversal manifest that `evda gather revert` undoes byte for byte.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        proposal: str("The proposal id evda_gather returned."),
+        into: str("A path: the record to grow, or a new folder to make one in. Omit to grow the open record."),
+        move: { type: "boolean", description: "true to move the files out of their sources; copy is the default." },
+        confirmed: { type: "boolean", description: "true only when the owner said yes to applying this proposal in this conversation." },
+      },
+      required: ["proposal", "confirmed"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: async (evda, args) => {
+      const r = await gatherApply.gatherApplyTool(evda, args);
+      return { text: r.lines.join("\n") };
+    },
+  },
+  {
+    name: "evda_skills",
+    title: "List or read the agent's skills",
+    description: `Lists the skills in this record (${SKILLS_REL}/<name>/SKILL.md), each with when to use it, or with a name returns that skill whole. A skill is a process the agent wrote down after repeating it; follow the one whose description fits what is being done. Read only.`,
+    inputSchema: { type: "object", properties: { name: str("A skill's name, to read that one. Omit to list them.") }, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      if (args.name !== undefined) {
+        const r = getSkill(evda, args.name);
+        return { text: `<file path="${r.path}">\n${r.text}\n</file>` };
+      }
+      const r = listSkills(evda);
+      if (!r.skills.length) return { text: `No skills in ${SKILLS_REL} yet. When you repeat a process, write it with evda_write_skill.` };
+      return { text: r.skills.map((x) => `${x.folder}: ${x.description ?? "(no description)"}${x.problems.length ? ` [broken: ${x.problems.join(" ")}]` : ""}`).join("\n") };
+    },
+  },
+  {
+    name: "evda_write_skill",
+    title: "Write down a process as a skill",
+    description: `Writes a skill into the record at ${SKILLS_REL}/<name>/SKILL.md (Claude Code loads it on its own; any app reads it with evda_skills): a kebab-case name, a description saying when to use it, and the steps. Use it when you notice you are doing or explaining the same process a second time, or making the same correction twice, and tell the owner in one line. With revise: true and why (what went wrong on a run), it rewrites one and keeps what it replaced in REVISIONS.md. Refuses a name that would land outside the skills folder, and refuses content that is a rule about the owner's life (a threshold, count or streak about a person): a skill is how you work.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: str("Kebab-case, at most 64 characters: what the process is, such as start-a-project."),
+        description: str("When to use it, starting \"Use when\"."),
+        steps: str("The steps, one numbered line each, in markdown."),
+        revise: { type: "boolean", description: "true to rewrite an existing skill after a run of it went wrong." },
+        why: str("With revise: what went wrong on the run."),
+      },
+      required: ["name", "description", "steps"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    run: (evda, args) => {
+      const r = writeSkill(evda, args);
+      if (r.action === "unchanged") return { text: `${r.path} already says exactly that. Nothing changed.` };
+      return { text: `${r.action === "revised" ? "Revised" : "Wrote"} the skill ${r.name} at ${r.path}${r.revisions ? `; what it replaced is in ${r.revisions}` : ""}. Tell the owner in one line that you ${r.action === "revised" ? "revised" : "wrote"} it and what it is for.` };
+    },
+  },
+  {
+    name: "evda_create_subrecord",
+    title: "Make an EVÐA inside this one",
+    description: "Makes a record inside this record at a path (a project, a company, an agent): its own evda.json with the four roles (journal, work, collections, knowledge) and an AGENTS.md saying what it is for, then runs doctor on this record, which walks the new one, and returns the report. The parent's evda.json is unchanged unless bounded: true, which makes this record's circles stop at the new one and so needs confirmed: true, the owner's yes in this conversation. Refuses a path that is not empty, one inside another sub-record, and one that would hold a folder this record maps. When doctor was clean before and fails after, it removes what it made.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: str("Where in the record it goes, relative, such as Projects/Garden. New or empty."),
+        name: str("Its name. Default: the last part of the path."),
+        purpose: str("What it is for, in the owner's words. Goes into its AGENTS.md."),
+        kind: { type: "string", enum: ["person", "agent", "company"], description: "Who holds it. Default person, the owner." },
+        bounded: { type: "boolean", description: "true to make this record's circles stop at the new one. Changes this record's evda.json; needs confirmed." },
+        confirmed: { type: "boolean", description: "true only when the owner said yes to bounded in this conversation." },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    run: (evda, args) => {
+      const r = createSubrecord(evda, args);
+      const lines = r.doctor.text.split("\n");
+      const shown = lines.length > 200 ? [...lines.slice(0, 20), `  ... ${lines.length - 40} line(s) ...`, ...lines.slice(-20)] : lines;
+      const parent = r.madeParentBounded ? "This record's evda.json now says \"subrecords\": \"bounded\", so its circles stop there." : r.parentBounded ? "This record's evda.json is unchanged; it was already bounded, so its circles stop there." : "This record's evda.json is unchanged, so its circles still cover the new one's files as their own.";
+      return { text: `Made the EVÐA ${r.name} (${r.id}) at ${r.path}, with the four roles and an AGENTS.md. ${parent}\n\nDoctor on this record, exit ${r.doctor.exit}:\n${shown.join("\n")}`, isError: r.doctor.exit !== 0 };
+    },
+  },
   {
     name: "evda_doctor",
     title: "Check the record",
@@ -189,28 +496,79 @@ export const TOOLS = [
       return { text: `${r.text}\n\nexit ${r.exit}`, data: { exit: r.exit }, isError: r.exit !== 0 };
     },
   },
+  {
+    name: "evda_check_update",
+    title: "Check for newer EVDA tooling",
+    description: "Asks the npm registry whether a newer version of the EVDA tooling exists, and returns the one line that says so. At most one real check an hour; inside that hour it reports the cached result. A check that fails reports the status as UNKNOWN, never as up to date. This is the only tool that reaches the network, it sends nothing from the record, and it changes nothing: taking the update is a command the owner runs in their own terminal.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    run: async (evda) => {
+      const result = await checkForUpdate(evda.dir);
+      const line = summarize(result);
+      return { text: NEEDS_A_COMMAND.has(result.status) ? `${line}\n\n${TERMINAL_NOTE}` : line };
+    },
+  },
 ];
 
 export const RESOURCES = [
-  { uri: "evda://agents", name: "AGENTS.md", title: "The operating layer", mimeType: "text/markdown", read: (evda) => tools.operatingLayer(evda).text },
+  { uri: "evda://agents", name: "AGENTS.md", title: "The operating layer", mimeType: "text/markdown", read: (evda) => { const t = tools.operatingLayer(evda).text; return `${chatSection(evda, t)}\n\n${t}`; } },
   {
     uri: "evda://today",
     name: "today",
     title: "Today's daily file",
     mimeType: "text/markdown",
-    read: (evda) => {
-      const r = tools.recent(evda, { days: 1 });
+    read: (evda, ctx) => {
+      const r = tools.recent(evda, { days: 1 }, { caller: ctx.caller });
       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`;
+      if (daily) return daily.text;
+      return r.heldBack ? `# ${r.to}\n\n${r.heldBack}\n` : `# ${r.to}\n\nNothing written today yet.\n`;
     },
   },
 ];
 
+// The nudge (HQ-1376), for the apps with no Stop hook (the Claude desktop app, ChatGPT): the
+// server counts, per session (one stdio process is one session), what was read and what was filed.
+// Once the session has read the record or been handed the owner's content and filed nothing, a tool
+// result carries one line saying so, at most once every NUDGE_EVERY calls, and never after a write.
+// EVDA_RECORD_FALSIFY=no-nudge turns it off, for the test that shows the nudge is what files.
+export const NUDGE = "Nothing from this conversation is filed yet: file their words with evda_write before you finish.";
+export const NUDGE_EVERY = 3;
+const READS = new Set(["evda_recent", "evda_search", "evda_read"]);
+const RECEIVED = new Set(["evda_import", "evda_gather_answer"]);
+const WRITES = new Set(["evda_write", "evda_note"]);
+
+export function newSession() {
+  return { calls: 0, reads: 0, received: 0, writes: 0, lastNudge: -Infinity };
+}
+
+// Count one tool call and say whether its result carries the nudge.
+// The call that reads is not nudged itself: the line goes on the results after it, which is when
+// the owner has had a turn to say something worth filing.
+// An owner who chose to file only when they ask (filing "asked", HQ-1385) is never nudged.
+export function countCall(session, name, { env = process.env, filing = null } = {}) {
+  session.calls += 1;
+  const before = session.reads + session.received;
+  if (WRITES.has(name)) { session.writes += 1; return false; }
+  if (READS.has(name)) session.reads += 1;
+  if (RECEIVED.has(name)) session.received += 1;
+  if (session.writes > 0 || before === 0 || filing === "asked") return false;
+  if ((env.EVDA_RECORD_FALSIFY ?? "").split(",").map((m) => m.trim()).includes("no-nudge")) return false;
+  if (session.calls - session.lastNudge < NUDGE_EVERY) return false;
+  session.lastNudge = session.calls;
+  return true;
+}
+
+// The owner's filing answer as the record says it now, or null when it cannot be read.
+function filingNow(ctx) {
+  try { return filingOf(ctx.evda().manifest); } catch { return null; }
+}
+
 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) {
+// One request in, one response out (or null for a notification), as a promise: evda_check_update
+// awaits the registry, and every other tool still runs to completion synchronously inside its own
+// call. Pure apart from the tools' own file writes, so tests drive it without a process.
+export async 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;
@@ -221,28 +579,39 @@ export function handle(msg, ctx) {
     switch (msg.method) {
       case "initialize": {
         const asked = p.protocolVersion;
+        // Who is calling, for every read that follows: the client's own name, or $EVDA_READER.
+        ctx.caller = callerFrom({ clientName: p.clientInfo?.name ?? null, env: ctx.env ?? process.env });
         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,
+          instructions: instructions(filingNow(ctx)),
         });
       }
       case "ping":
         return ok({});
       case "tools/list":
-        return ok({ tools: TOOLS.map(({ run, ...t }) => t) });
+        return ok({ tools: toolList(filingNow(ctx), ctx.env ?? process.env) });
       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");
+        // EVDA_MCP_FALSIFY=log-args: a debug line with the arguments, the leak test/privacy.test.mjs exists to catch.
+        if (FALSIFY("log-args", process.env)) ctx.log?.(`debug ${p.name} ${JSON.stringify(args)}`);
         try {
-          const r = tool.run(ctx.evda(), args);
+          if (!ctx.caller) ctx.caller = callerFrom({ env: ctx.env ?? process.env });
+          ctx.session ??= newSession();
+          const evda = ctx.evda();
+          const r = await tool.run(evda, args, ctx);
+          const nudge = countCall(ctx.session, tool.name, { filing: filingOf(evda.manifest) }) ? `\n\n${NUDGE}` : "";
+          // A process run twice is pointed at once (HQ-1377), so an agent in an app with no memory of
+          // its own still writes it down as a skill. Only a call that did its work counts as a step.
+          const repeat = r.isError ? null : noticeRepeat(ctx.session, tool.name);
           // 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) });
+          return ok({ content: [{ type: "text", text: `${r.text}${nudge}${repeat ? `\n\n${repeat}` : ""}` }], 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 });
@@ -254,7 +623,9 @@ export function handle(msg, ctx) {
       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()) }] });
+        if (!ctx.caller) ctx.caller = callerFrom({ env: ctx.env ?? process.env });
+        if (res.uri === "evda://today") (ctx.session ??= newSession()).reads += 1;
+        return ok({ contents: [{ uri: res.uri, mimeType: res.mimeType, text: res.read(ctx.evda(), ctx) }] });
       }
       case "resources/templates/list":
         return ok({ resourceTemplates: [] });
@@ -276,11 +647,18 @@ function error(id, 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) };
+  const ctx = { version, log, evda: () => openEvda(dir), session: newSession() };
   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`);
+  // What is still being answered, so a stdin that closes mid-call does not cut the answer off.
+  const inFlight = new Set();
+  const track = (p) => {
+    const settled = p.catch((e) => log(e?.stack ?? String(e)));
+    inFlight.add(settled);
+    settled.finally(() => inFlight.delete(settled));
+  };
   rl.on("line", (line) => {
     if (line.trim() === "") return;
     let msg;
@@ -289,13 +667,24 @@ export function serve({ dir, version, input = process.stdin, output = process.st
     } catch {
       return send(error(null, RPC.PARSE, "parse error"));
     }
+    // A response carries the id it answers, so a tool that awaits the network holds up nothing else.
+    const answer = (m) => handle(m, ctx).catch((e) => {
+      log(e?.stack ?? String(e));
+      return error(m?.id ?? null, RPC.INTERNAL, "internal error; the server's stderr has the detail");
+    });
     if (Array.isArray(msg)) {
-      const out = msg.map((m) => handle(m, ctx)).filter(Boolean);
-      if (out.length) send(out);
+      track(Promise.all(msg.map(answer)).then((out) => {
+        const answers = out.filter(Boolean);
+        if (answers.length) send(answers);
+      }));
       return;
     }
-    const r = handle(msg, ctx);
-    if (r) send(r);
+    track(answer(msg).then((r) => {
+      if (r) send(r);
+    }));
+  });
+  const closed = new Promise((resolveDone) => rl.on("close", resolveDone));
+  return closed.then(async () => {
+    await Promise.all(inFlight);
   });
-  return new Promise((resolveDone) => rl.on("close", resolveDone));
 }