@edda-business/mcp 0.60.0 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edda-business/mcp",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Edda — the company data layer for AI agents.",
   "license": "Apache-2.0",
   "repository": {

package/src/server.js

@@ -13,21 +13,23 @@
  * Tools, by group (v0.56 — consolidated, Cerebras-style):
  *   RETRIEVE  search (unified, scope=all|company|personal|notes) · get_context ·
  *             get_account · who_knows · query · attention · verify
- *   WRITE     save_note · save_to_vault · update_vault_file · propose_company_file ·
- *             propose_company_files (bulk) · create_folder
+ *   WRITE     save_note · save_personal_file · update_personal_file · add_company_wiki_page ·
+ *             add_company_wiki_pages (bulk) · create_company_wiki_folder
  *   FIX       merge_contacts (action=merge|split)
  *   RUN       list_integrations · connect_integration
  *
  * Deprecated aliases kept for back-compat (forward to the above, removed after a window):
  *   search_company_knowledge · search_my_vault · search_notes → search
- *   propose_vault_file → save_to_vault      unmerge_contacts → merge_contacts(action:split)
+ *   save_to_vault/propose_vault_file → save_personal_file   ·   update_vault_file → update_personal_file
+ *   propose_company_file → add_company_wiki_page   ·   propose_company_files → add_company_wiki_pages
+ *   create_folder → create_company_wiki_folder      ·   unmerge_contacts → merge_contacts(action:split)
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post, del } from "./client.js";
 
-export const SERVER_VERSION = "0.60.0";
+export const SERVER_VERSION = "0.62.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -78,7 +80,7 @@ export function createServer() {
     description:
       "Edda — the company knowledge layer for AI agents. The agent reads engineered, " +
       "epistemics-tagged context instead of raw rows. Call get_context before preparing for a " +
-      "meeting or a decision about a person; search_company_knowledge for how the company works; " +
+      "meeting or a decision about a person; search for how the company works; " +
       "save_note to keep a brief or transcript on a contact.",
     icons: [
       { src: "https://opennous.cloud/newlogoP.png", mimeType: "image/png", sizes: ["64x64"] },
@@ -585,7 +587,7 @@ export function createServer() {
   // same direct personal-vault save (the member owns their vault, so no inbox step).
   server.tool(
     "propose_vault_file",
-    "DEPRECATED — use `save_to_vault`. Saves a markdown file into the member's own private vault folder.",
+    "DEPRECATED — use `save_personal_file`. Saves a markdown file into the member's own private knowledge.",
     {
       folder: z.string().describe("The vault folder (inbox | projects | decisions | companies | people | resources | archive)."),
       name: z.string().describe("The file name, ending in .md."),
@@ -693,48 +695,49 @@ export function createServer() {
 
   // ===========================================================================
   // TOOL: propose_company_file  —  POST /v2/company/pages
-  // The WRITE side of the company vault (search_company_knowledge is the read side).
+  // The WRITE side of the company wiki (search is the read side).
   // Writes an in-app company page directly (no GitHub). Members with a write role
   // publish it live; viewers land it in the company inbox for an admin to approve.
   // ===========================================================================
+  const ADD_WIKI_PAGE_SCHEMA = {
+    name: z.string().describe("The page name, e.g. 'Refund Policy' or 'Q3 Planning — 2026-08-22'. A '.md' suffix is added if missing."),
+    content: z.string().describe("The full markdown content of the page."),
+    visibility: z.enum(["owner", "department", "company"]).optional().describe("Who can see the page: 'department' (the team it's filed in — default), 'company' (everyone), or 'owner' (just you)."),
+    folder: z.string().optional().describe("Folder to file under, by NAME or path. Top-level folders are fixed — a bare name becomes a project under Projects (e.g. 'Agency' → Projects/Agency); 'Top-Level/Sub' nests under a fixed folder. Created if missing (write role). Use this OR folder_id."),
+    subfolder: z.string().optional().describe("Optional subfolder within `folder`, e.g. 'Specs'."),
+    folder_id: z.string().optional().describe("Id of an existing company folder to file under (alternative to `folder`). Omit both to use the default folder."),
+  };
+  const runAddCompanyWikiPage = async ({ name, content, visibility, folder, subfolder, folder_id }) => {
+    try {
+      const r = await post("/v2/company/pages", { name, content, visibility, folder, subfolder, folder_id });
+      const live = r?.page?.status === "live";
+      const where = live ? `published live to the company wiki — searchable now` : `sent to the company inbox for an admin to approve`;
+      return { content: [{ type: "text", text: `"${r?.page?.name ?? name}" ${where}.` }] };
+    } catch (e) {
+      const msg = String(e?.message || e);
+      if (msg.includes("forbidden") || msg.includes("(403)")) return { content: [{ type: "text", text: `Not saved — you don't have access to write to this company wiki.` }] };
+      if (msg.includes("bad_folder")) return { content: [{ type: "text", text: `Not saved — that folder_id isn't a company folder in this workspace. Omit it to use the default folder.` }] };
+      throw e;
+    }
+  };
+  server.tool(
+    "add_company_wiki_page",
+    "Add a markdown page to the COMPANY WIKI — the shared, declared knowledge (policies, playbooks, " +
+    "decisions, SOPs, how-we-work) every member's agent can read via search. A member with a write role " +
+    "publishes it live; a viewer's page lands in the company inbox for an admin to approve. File it with " +
+    "`folder` — a name or path like 'Projects/Data Centre' (created if missing) — plus optional `subfolder`. " +
+    "Set `visibility`: 'department' (the team it's filed in — default), 'company' (everyone), or 'owner' " +
+    "(just you); a page in a project inherits the project's Shared-with setting for OTHER departments. To add " +
+    "many at once use add_company_wiki_pages. NOT the member's private files (use save_personal_file), NOT a contact note (save_note).",
+    ADD_WIKI_PAGE_SCHEMA,
+    runAddCompanyWikiPage,
+  );
+  // DEPRECATED alias → add_company_wiki_page. Kept so existing agents keep working.
   server.tool(
     "propose_company_file",
-    "Add a markdown page to the SHARED COMPANY vault — the workspace's declared knowledge " +
-    "(policies, playbooks, decisions, SOPs, how-we-work) that every member's agent can read via " +
-    "search_company_knowledge. This writes the page IN-APP: a member with a write role publishes " +
-    "it live immediately; a viewer's page lands in the company inbox for an admin to approve. File " +
-    "it with `folder` — a name or path like 'Projects/Data Centre' (created if missing) — plus an " +
-    "optional `subfolder`. Set `visibility` to scope who sees it: 'department' (the team it's filed " +
-    "in — the default), 'company' (everyone), or 'owner' (just you). A page in a project inherits the " +
-    "project's Shared-with setting for OTHER departments. To add many pages at once, use " +
-    "propose_company_files. NOT the member's private vault (use save_to_vault), NOT a contact note (save_note).",
-    {
-      name: z.string().describe("The page name, e.g. 'Refund Policy' or 'Q3 Planning — 2026-08-22'. A '.md' suffix is added if missing."),
-      content: z.string().describe("The full markdown content of the page."),
-      visibility: z.enum(["owner", "department", "company"]).optional().describe("Who can see the page: 'department' (the team it's filed in — default), 'company' (everyone), or 'owner' (just you)."),
-      folder: z.string().optional().describe("Folder to file under, by NAME or path, e.g. 'Projects/Data Centre'. Created if it doesn't exist (needs a write role). Use this OR folder_id."),
-      subfolder: z.string().optional().describe("Optional subfolder within `folder`, e.g. 'Specs'."),
-      folder_id: z.string().optional().describe("Id of an existing company folder to file under (alternative to `folder`). Omit both to use the default 'wiki' folder."),
-    },
-    async ({ name, content, visibility, folder, subfolder, folder_id }) => {
-      try {
-        const r = await post("/v2/company/pages", { name, content, visibility, folder, subfolder, folder_id });
-        const live = r?.page?.status === "live";
-        const where = live
-          ? `published live to the company vault — searchable now`
-          : `sent to the company inbox for an admin to approve`;
-        return { content: [{ type: "text", text: `"${r?.page?.name ?? name}" ${where}.` }] };
-      } catch (e) {
-        const msg = String(e?.message || e);
-        if (msg.includes("forbidden") || msg.includes("(403)")) {
-          return { content: [{ type: "text", text: `Not saved — you don't have access to write to this company vault.` }] };
-        }
-        if (msg.includes("bad_folder")) {
-          return { content: [{ type: "text", text: `Not saved — that folder_id isn't a company folder in this workspace. Omit it to use the default 'wiki' folder.` }] };
-        }
-        throw e;
-      }
-    },
+    "DEPRECATED — use `add_company_wiki_page`. Adds a markdown page to the shared company wiki.",
+    ADD_WIKI_PAGE_SCHEMA,
+    runAddCompanyWikiPage,
   );
 
 
@@ -742,63 +745,83 @@ export function createServer() {
   // TOOL: create_folder  —  POST /v2/company/folders { path }
   // Create a folder / nested path in the shared company tree so pages can be filed into it.
   // ===========================================================================
+  const CREATE_WIKI_FOLDER_SCHEMA = { path: z.string().describe("Folder name or path. A bare name → a project under Projects; 'Top-Level/Sub' nests under a fixed top-level folder.") };
+  const runCreateCompanyWikiFolder = async ({ path }) => {
+    try {
+      const r = await post("/v2/company/folders", { path });
+      const made = r?.created?.length ? ` (created ${r.created.join(" / ")})` : " (already existed)";
+      return { content: [{ type: "text", text: `Folder "${r?.folder?.name ?? path}" ready${made}. folder_id: ${r?.folder?.id ?? "?"}` }] };
+    } catch (e) {
+      const msg = String(e?.message || e);
+      if (msg.includes("read_only") || msg.includes("(403)")) return { content: [{ type: "text", text: "You don't have a write role in this company wiki, so you can't create folders here." }] };
+      if (msg.includes("bad_path")) return { content: [{ type: "text", text: "Couldn't create that path — give a folder name or 'Parent/Child' path." }] };
+      throw e;
+    }
+  };
+  server.tool(
+    "create_company_wiki_folder",
+    "Create a folder in the COMPANY WIKI tree so you can file pages into it. The TOP-LEVEL folders are FIXED " +
+    "(Company · Projects · Decisions · Companies · People · Raw Documents · Archive) — you cannot add new ones. " +
+    "A bare name (or a path that doesn't start with one of those) becomes a PROJECT under Projects: 'Agency' → " +
+    "Projects/Agency. To nest under a specific top-level folder, start the path with it, e.g. 'Company/Policies' " +
+    "or 'Projects/Data Centre/Specs'. A project gets a 'Shared with' control the Ambassador uses to grant " +
+    "departments. A write role is required; the folder appears immediately. Then add pages with " +
+    "add_company_wiki_page / add_company_wiki_pages using the same path. Returns the folder id.",
+    CREATE_WIKI_FOLDER_SCHEMA,
+    runCreateCompanyWikiFolder,
+  );
+  // DEPRECATED alias → create_company_wiki_folder.
   server.tool(
     "create_folder",
-    "Create a folder (or a nested path) in the SHARED COMPANY knowledge tree so you can file pages into it. " +
-    "Pass `path` as a name or slash-path, e.g. 'Projects/Data Centre' — every missing level is created. A " +
-    "folder directly under 'Projects' becomes a project (it gets a 'Shared with' control the Ambassador uses " +
-    "to grant departments). A write role is required and the folder appears immediately. Then add pages with " +
-    "propose_company_file / propose_company_files using the same `folder` path. Returns the folder id.",
-    { path: z.string().describe("Folder name or path, e.g. 'Projects/Data Centre' or 'Playbooks'.") },
-    async ({ path }) => {
-      try {
-        const r = await post("/v2/company/folders", { path });
-        const made = r?.created?.length ? ` (created ${r.created.join(" / ")})` : " (already existed)";
-        return { content: [{ type: "text", text: `Folder "${r?.folder?.name ?? path}" ready${made}. folder_id: ${r?.folder?.id ?? "?"}` }] };
-      } catch (e) {
-        const msg = String(e?.message || e);
-        if (msg.includes("read_only") || msg.includes("(403)")) return { content: [{ type: "text", text: "You don't have a write role in this company vault, so you can't create folders here." }] };
-        if (msg.includes("bad_path")) return { content: [{ type: "text", text: "Couldn't create that path — give a folder name or 'Parent/Child' path." }] };
-        throw e;
-      }
-    },
+    "DEPRECATED — use `create_company_wiki_folder`. Creates a folder in the shared company wiki tree.",
+    CREATE_WIKI_FOLDER_SCHEMA,
+    runCreateCompanyWikiFolder,
   );
 
   // ===========================================================================
   // TOOL: propose_company_files  —  POST /v2/company/pages/batch
   // Bulk-add many pages into ONE company folder (resolved/created once).
   // ===========================================================================
+  const ADD_WIKI_PAGES_SCHEMA = {
+    folder: z.string().optional().describe("Folder to file all pages under. Top-level is fixed — a bare name becomes a project under Projects (e.g. 'Agency' → Projects/Agency); 'Top-Level/Sub' nests under a fixed folder. Created if missing."),
+    subfolder: z.string().optional().describe("Optional subfolder within `folder`."),
+    folder_id: z.string().optional().describe("Id of an existing folder (alternative to `folder`)."),
+    visibility: z.enum(["owner", "department", "company"]).optional().describe("Default visibility for the pages (a page can override its own). Default 'department'."),
+    pages: z.array(z.object({
+      name: z.string().describe("Page name."),
+      content: z.string().optional().describe("Markdown content."),
+      visibility: z.enum(["owner", "department", "company"]).optional().describe("Optional per-page visibility."),
+    })).describe("The pages to add: each { name, content, visibility? }."),
+  };
+  const runAddCompanyWikiPages = async ({ folder, subfolder, folder_id, visibility, pages }) => {
+    try {
+      const r = await post("/v2/company/pages/batch", { folder, subfolder, folder_id, visibility, pages });
+      const where = r?.status === "live" ? "published live — searchable now" : "sent to the company inbox for an admin to approve";
+      return { content: [{ type: "text", text: `${r?.count ?? 0} page(s) ${where} in "${r?.folder ?? folder ?? "wiki"}".` }] };
+    } catch (e) {
+      const msg = String(e?.message || e);
+      if (msg.includes("forbidden") || msg.includes("(403)")) return { content: [{ type: "text", text: "You don't have access to write to this company wiki." }] };
+      if (msg.includes("bad_folder")) return { content: [{ type: "text", text: "That folder path couldn't be resolved or created — check the name, or pass folder_id." }] };
+      if (msg.includes("too_many")) return { content: [{ type: "text", text: "Too many pages — max 50 per call. Split into batches." }] };
+      if (msg.includes("pages_required")) return { content: [{ type: "text", text: "Give at least one page ({ name, content })." }] };
+      throw e;
+    }
+  };
   server.tool(
-    "propose_company_files",
-    "Add MANY markdown pages to the shared company vault in ONE call — all into the SAME folder (resolved or " +
-    "created once). Use it to bulk-file: 'put these 10 docs in Data Centre'. Same rules as propose_company_file: " +
-    "a write role publishes them live; a viewer sends the whole batch to the company inbox. Name the target with " +
+    "add_company_wiki_pages",
+    "Add MANY markdown pages to the COMPANY WIKI in ONE call — all into the SAME folder (resolved or created " +
+    "once). Use it to bulk-file: 'put these 10 docs in Data Centre'. Same rules as add_company_wiki_page: a " +
+    "write role publishes them live; a viewer sends the whole batch to the company inbox. Name the target with " +
     "`folder` (a path, created if missing) + optional `subfolder`, or an existing `folder_id`. Max 50 pages.",
-    {
-      folder: z.string().optional().describe("Folder path to file all pages under, e.g. 'Projects/Data Centre'. Created if missing."),
-      subfolder: z.string().optional().describe("Optional subfolder within `folder`."),
-      folder_id: z.string().optional().describe("Id of an existing folder (alternative to `folder`)."),
-      visibility: z.enum(["owner", "department", "company"]).optional().describe("Default visibility for the pages (a page can override its own). Default 'department'."),
-      pages: z.array(z.object({
-        name: z.string().describe("Page name."),
-        content: z.string().optional().describe("Markdown content."),
-        visibility: z.enum(["owner", "department", "company"]).optional().describe("Optional per-page visibility."),
-      })).describe("The pages to add: each { name, content, visibility? }."),
-    },
-    async ({ folder, subfolder, folder_id, visibility, pages }) => {
-      try {
-        const r = await post("/v2/company/pages/batch", { folder, subfolder, folder_id, visibility, pages });
-        const where = r?.status === "live" ? "published live — searchable now" : "sent to the company inbox for an admin to approve";
-        return { content: [{ type: "text", text: `${r?.count ?? 0} page(s) ${where} in "${r?.folder ?? folder ?? "wiki"}".` }] };
-      } catch (e) {
-        const msg = String(e?.message || e);
-        if (msg.includes("forbidden") || msg.includes("(403)")) return { content: [{ type: "text", text: "You don't have access to write to this company vault." }] };
-        if (msg.includes("bad_folder")) return { content: [{ type: "text", text: "That folder path couldn't be resolved or created — check the name, or pass folder_id." }] };
-        if (msg.includes("too_many")) return { content: [{ type: "text", text: "Too many pages — max 50 per call. Split into batches." }] };
-        if (msg.includes("pages_required")) return { content: [{ type: "text", text: "Give at least one page ({ name, content })." }] };
-        throw e;
-      }
-    },
+    ADD_WIKI_PAGES_SCHEMA,
+    runAddCompanyWikiPages,
+  );
+  // DEPRECATED alias → add_company_wiki_pages.
+  server.tool(
+    "propose_company_files",
+    "DEPRECATED — use `add_company_wiki_pages`. Bulk-adds pages to the shared company wiki.",
+    ADD_WIKI_PAGES_SCHEMA,
+    runAddCompanyWikiPages,
   );
 
   // ===========================================================================
@@ -845,35 +868,43 @@ export function createServer() {
   // TOOL: save_to_vault  —  POST /v2/personal/files
   // Save a file into the MEMBER'S OWN private vault folder. Extracts a PDF/DOCX to text.
   // ===========================================================================
+  const SAVE_PERSONAL_SCHEMA = {
+    folder: z.string().describe("The personal folder: inbox | projects | decisions | companies | people | raw documents | archive."),
+    name: z.string().describe("The file name, e.g. 'Q3 Plan.md' or 'vendor-contract.pdf'."),
+    content: z.string().optional().describe("The text/markdown content, when you already have it as text."),
+    file: z.string().optional().describe("A PDF or DOCX as base64 (a data: URL is fine). It's extracted to text automatically. Provide this OR content."),
+    mime: z.string().optional().describe("The file's MIME type, e.g. 'application/pdf' or the docx type — helps pick the right extractor."),
+    subfolder: z.string().optional().describe("Optional subfolder within the folder."),
+  };
+  const runSavePersonalFile = async ({ folder, name, content, file, mime, subfolder }) => {
+    try {
+      const r = await post("/v2/personal/files", { folder, name, content, file_base64: file, mime, subfolder });
+      return { content: [{ type: "text", text: `"${name}" is waiting in your Inbox to approve — once you do, it files into ${r?.folder || folder} and becomes searchable.` }] };
+    } catch (e) {
+      const msg = String(e?.message || e);
+      if (msg.includes("no_text_extracted")) return { content: [{ type: "text", text: `Couldn't read any text from that file — a scanned/image-only PDF has no extractable text. Text, markdown, or a text-based PDF/DOCX works.` }] };
+      if (msg.includes("content_or_file_required")) return { content: [{ type: "text", text: `Nothing to save — pass either text content or a base64 file.` }] };
+      throw e;
+    }
+  };
+  server.tool(
+    "save_personal_file",
+    "Save a file into the MEMBER'S OWN personal knowledge (their private files — 'My Knowledge'). It lands in " +
+    "their INBOX for review with the target folder you name remembered (inbox, projects, decisions, companies, " +
+    "people, raw documents, archive); the member approves it in the app, which files it and makes it searchable. " +
+    "Nothing enters their knowledge without their approval. Use it when the member asks you to keep or file " +
+    "something — 'save this to raw documents', 'put this PDF in projects'. Pass markdown/text as `content`, OR a " +
+    "PDF/DOCX as base64 in `file` (auto-extracted). PRIVATE to the member. NOT the company wiki (use " +
+    "add_company_wiki_page), NOT a note on a contact (use save_note).",
+    SAVE_PERSONAL_SCHEMA,
+    runSavePersonalFile,
+  );
+  // DEPRECATED alias → save_personal_file.
   server.tool(
     "save_to_vault",
-    "Save a file into the MEMBER'S OWN private knowledge vault. It lands in their INBOX for review " +
-    "with the target folder you name remembered (inbox, projects, decisions, companies, people, " +
-    "resources, archive, thoughts); the member approves it in the app, which files it into that folder " +
-    "and makes it searchable. Nothing enters their knowledge without their approval. Use it when the " +
-    "member asks you to keep or file something — 'save this to resources', 'put this PDF in projects'. " +
-    "Pass markdown/text as `content`, OR a PDF/DOCX as base64 in `file` (extracted to text automatically). " +
-    "PRIVATE to the member. NOT the shared company vault (use propose_company_file), NOT a note on a " +
-    "contact (use save_note).",
-    {
-      folder: z.string().describe("The vault folder: inbox | projects | decisions | companies | people | resources | archive | thoughts."),
-      name: z.string().describe("The file name, e.g. 'Q3 Plan.md' or 'vendor-contract.pdf'."),
-      content: z.string().optional().describe("The text/markdown content, when you already have it as text."),
-      file: z.string().optional().describe("A PDF or DOCX as base64 (a data: URL is fine). It's extracted to text automatically. Provide this OR content."),
-      mime: z.string().optional().describe("The file's MIME type, e.g. 'application/pdf' or the docx type — helps pick the right extractor."),
-      subfolder: z.string().optional().describe("Optional subfolder within the folder."),
-    },
-    async ({ folder, name, content, file, mime, subfolder }) => {
-      try {
-        const r = await post("/v2/personal/files", { folder, name, content, file_base64: file, mime, subfolder });
-        return { content: [{ type: "text", text: `"${name}" is waiting in your Inbox to approve — once you do, it files into ${r?.folder || folder} and becomes searchable.` }] };
-      } catch (e) {
-        const msg = String(e?.message || e);
-        if (msg.includes("no_text_extracted")) return { content: [{ type: "text", text: `Couldn't read any text from that file — a scanned/image-only PDF has no extractable text. Text, markdown, or a text-based PDF/DOCX works.` }] };
-        if (msg.includes("content_or_file_required")) return { content: [{ type: "text", text: `Nothing to save — pass either text content or a base64 file.` }] };
-        throw e;
-      }
-    }
+    "DEPRECATED — use `save_personal_file`. Saves a file into the member's own private knowledge.",
+    SAVE_PERSONAL_SCHEMA,
+    runSavePersonalFile,
   );
 
   // ===========================================================================
@@ -882,32 +913,41 @@ export function createServer() {
   // then replaces/appends + re-embeds. save_to_vault is for NEW files (→ Inbox);
   // this edits one that's already live.
   // ===========================================================================
+  const UPDATE_PERSONAL_SCHEMA = {
+    file_id: z.string().optional().describe("The file's id (from a search/save result). Provide this OR path."),
+    path: z.string().optional().describe("The file's path, e.g. 'raw documents/Edda Architecture.md'. Provide this OR file_id."),
+    content: z.string().describe("The new markdown content. Replaces the file's content unless append is true."),
+    append: z.boolean().optional().describe("If true, append this to the end of the file instead of replacing it."),
+  };
+  const runUpdatePersonalFile = async ({ file_id, path, content, append }) => {
+    try {
+      const r = await post("/v2/personal/files/update", { file_id, path, content, append });
+      return { content: [{ type: "text", text: r?.note || "Updated the file." }] };
+    } catch (e) {
+      const msg = String(e?.message || e);
+      if (msg.includes("not_found")) return { content: [{ type: "text", text: "Couldn't find that file — check the file_id or path (folder/name.md)." }] };
+      if (msg.includes("file_id_or_path_required")) return { content: [{ type: "text", text: "Tell me which file to edit — pass file_id or path." }] };
+      if (msg.includes("content_required")) return { content: [{ type: "text", text: "Give me the new content to write." }] };
+      throw e;
+    }
+  };
+  server.tool(
+    "update_personal_file",
+    "Edit an EXISTING file in the member's own personal knowledge — revise it or append to it. Identify the file " +
+    "by `file_id` (from a search or save result) or by `path` ('folder/[subfolder/]name.md'). The previous " +
+    "content is saved to version history FIRST (never lost), then your new content replaces it — or is added to " +
+    "the end with append:true — and the file is re-embedded; the member sees a fresh 'updated' time. Use this to " +
+    "keep a living document current: a rolling brief, a spec, a running log. For a NEW file use save_personal_file " +
+    "(which lands in the Inbox for approval); this edits one that already exists and is live.",
+    UPDATE_PERSONAL_SCHEMA,
+    runUpdatePersonalFile,
+  );
+  // DEPRECATED alias → update_personal_file.
   server.tool(
     "update_vault_file",
-    "Edit an EXISTING file in the member's own vault — revise it or append to it. Identify the file by " +
-    "`file_id` (from a search or save result) or by `path` ('folder/[subfolder/]name.md'). The previous " +
-    "content is saved to version history FIRST (never lost), then your new content replaces it — or is added " +
-    "to the end with append:true — and the file is re-embedded; the member sees a fresh 'updated' time. Use " +
-    "this to keep a living document current: a rolling brief, a spec, a running log. For a NEW file use " +
-    "save_to_vault (which lands in the Inbox for approval); this edits one that already exists and is live.",
-    {
-      file_id: z.string().optional().describe("The file's id (from a search/save result). Provide this OR path."),
-      path: z.string().optional().describe("The file's vault path, e.g. 'resources/Edda Architecture.md'. Provide this OR file_id."),
-      content: z.string().describe("The new markdown content. Replaces the file's content unless append is true."),
-      append: z.boolean().optional().describe("If true, append this to the end of the file instead of replacing it."),
-    },
-    async ({ file_id, path, content, append }) => {
-      try {
-        const r = await post("/v2/personal/files/update", { file_id, path, content, append });
-        return { content: [{ type: "text", text: r?.note || "Updated the file." }] };
-      } catch (e) {
-        const msg = String(e?.message || e);
-        if (msg.includes("not_found")) return { content: [{ type: "text", text: "Couldn't find that file — check the file_id or path (folder/name.md)." }] };
-        if (msg.includes("file_id_or_path_required")) return { content: [{ type: "text", text: "Tell me which file to edit — pass file_id or path." }] };
-        if (msg.includes("content_required")) return { content: [{ type: "text", text: "Give me the new content to write." }] };
-        throw e;
-      }
-    }
+    "DEPRECATED — use `update_personal_file`. Edits/append an existing file in the member's own knowledge.",
+    UPDATE_PERSONAL_SCHEMA,
+    runUpdatePersonalFile,
   );
 
   server.tool(