@edda-business/mcp 0.61.0 → 0.63.0

package/package.json

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

package/src/client.js

@@ -24,7 +24,10 @@ function resolvedEnv(name) {
   return v;
 }
 
-const API_URL = resolvedEnv("NOUS_API_URL") || "https://api.opennous.cloud";
+// Prefer the EDDA_* env vars; fall back to the legacy NOUS_* names so existing configs keep working.
+const envKey = () => resolvedEnv("EDDA_API_KEY") ?? resolvedEnv("NOUS_API_KEY");
+const envUrl = () => resolvedEnv("EDDA_API_URL") ?? resolvedEnv("NOUS_API_URL");
+const API_URL = envUrl() || "https://api.opennous.cloud";
 
 // Per-request key context for the hosted HTTP server. Empty in stdio mode.
 export const apiKeyStore = new AsyncLocalStorage();
@@ -35,17 +38,16 @@ export function runWithApiKey(apiKey, fn) {
   return apiKeyStore.run({ apiKey }, fn);
 }
 
-// Credential written by `nous login` (the browser device-auth flow). The CLI and
-// the MCP server share ~/.nous/config.json, so a user who runs the login command
-// gets a key — and, for self-host, the API URL — the MCP picks up on the next
-// call, with no paste and no env var.
+// Credential written by the CLI login (the browser device-auth flow). The CLI and the MCP server
+// share a config.json, so a user who runs the login command gets a key — and, for self-host, the
+// API URL — the MCP picks up on the next call, with no paste and no env var. Checks ~/.edda first,
+// then legacy ~/.nous.
 function readFileConfig() {
-  try {
-    const dir = resolvedEnv("NOUS_CONFIG_DIR") || path.join(os.homedir(), ".nous");
-    return JSON.parse(fs.readFileSync(path.join(dir, "config.json"), "utf8"));
-  } catch {
-    return null;
+  const dirs = [resolvedEnv("EDDA_CONFIG_DIR"), resolvedEnv("NOUS_CONFIG_DIR"), path.join(os.homedir(), ".edda"), path.join(os.homedir(), ".nous")].filter(Boolean);
+  for (const dir of dirs) {
+    try { return JSON.parse(fs.readFileSync(path.join(dir, "config.json"), "utf8")); } catch { /* try next */ }
   }
+  return null;
 }
 function clean(v) {
   return v && !String(v).includes("${") ? v : undefined;   // drop unresolved ${...} markers
@@ -54,25 +56,22 @@ function fileApiKey() { return clean(readFileConfig()?.apiKey); }
 function fileApiUrl() { return clean(readFileConfig()?.apiUrl); }
 
 function currentApiKey() {
-  return apiKeyStore.getStore()?.apiKey ?? resolvedEnv("NOUS_API_KEY") ?? fileApiKey();
+  return apiKeyStore.getStore()?.apiKey ?? envKey() ?? fileApiKey();
 }
 
-// Resolve the API base per call: env → ~/.nous/config.json (set by `nous login
-// --url` on self-host) → cloud default. So a self-hoster who logs in via the CLI
-// gets the MCP pointed at their own instance automatically.
+// Resolve the API base per call: env → config.json (set by the CLI login on self-host) → cloud
+// default. So a self-hoster who logs in via the CLI gets the MCP pointed at their own instance.
 function currentApiUrl() {
-  return resolvedEnv("NOUS_API_URL") ?? fileApiUrl() ?? "https://api.opennous.cloud";
+  return envUrl() ?? fileApiUrl() ?? "https://api.opennous.cloud";
 }
 
-// stdio-only preflight. A key may come from the env OR from `nous login`'s
-// credential file. This is advisory — the server still starts without one so
-// the user can run the login command after installing the plugin, and the key
-// is resolved per-call.
+// stdio-only preflight. A key may come from the env OR the CLI login credential file. Advisory —
+// the server still starts without one so the user can log in after installing, key resolved per-call.
 export function validateConfig() {
-  if (!resolvedEnv("NOUS_API_KEY") && !fileApiKey()) {
+  if (!envKey() && !fileApiKey()) {
     throw new Error(
       "No Edda API key found. Run `npx @edda-business/cli login` to sign in (or `npx @edda-business/cli init` " +
-      "to set up from scratch), or set NOUS_API_KEY."
+      "to set up from scratch), or set EDDA_API_KEY."
     );
   }
 }

package/src/index.js

@@ -8,9 +8,10 @@
  * variant see http.js; the tools themselves live in server.js.
  *
  * Required env:
- *   NOUS_API_KEY   — workspace API key (Settings -> API Keys)
+ *   EDDA_API_KEY   — workspace API key (Sources -> API Keys). Encodes the workspace + scope.
  * Optional:
- *   NOUS_API_URL   — API base URL (default: https://api.opennous.cloud)
+ *   EDDA_API_URL   — API base URL for your instance, e.g. https://api.whitehayai.com
+ * (Legacy NOUS_API_KEY / NOUS_API_URL are still accepted as a fallback.)
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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.61.0";
+export const SERVER_VERSION = "0.63.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"] },
@@ -572,6 +574,80 @@ export function createServer() {
     },
   );
 
+  // ===========================================================================
+  // TOOL: list_my_files  —  GET /v2/personal/tree
+  // Navigate the member's personal PARA vault like a filesystem: Inbox · Projects ·
+  // Areas · Resources · Archive · People · Companies. Returns every file as a path.
+  // ===========================================================================
+  server.tool(
+    "list_my_files",
+    "List the files in your personal workspace — a PARA knowledge tree (Inbox, Projects, Areas, " +
+    "Resources, Archive, People, Companies) of markdown files you own. Use this to SEE what's there " +
+    "and navigate it like a filesystem before reading or writing. Returns each file's path " +
+    "(e.g. 'projects/acme-rollout/notes.md'); read one with read_my_file, write with save_personal_file.",
+    {
+      folder: z.string().optional().describe("Optional: only list files under this top-level folder (e.g. 'projects')."),
+    },
+    async ({ folder }) => {
+      const d = await get("/v2/personal/tree");
+      let files = d.files ?? [];
+      if (folder) files = files.filter((f) => f.folder === String(folder).toLowerCase());
+      if (!files.length) return { content: [{ type: "text", text: folder ? `No files in ${folder}/ yet.` : "Your personal workspace is empty." }] };
+      const lines = files.map((f) => `  ${f.path}${f.status === "inbox_pending" ? "  (pending approval)" : ""}`).join("\n");
+      return { content: [{ type: "text", text: `${files.length} file(s):\n${lines}` }] };
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: read_my_file  —  GET /v2/personal/file?path=…
+  // Read one personal-vault file by its path.
+  // ===========================================================================
+  server.tool(
+    "read_my_file",
+    "Read one file from your personal workspace by its path (e.g. 'companies/acme.md' or " +
+    "'projects/acme-rollout/notes.md'). Use list_my_files first to find the path. Returns the " +
+    "markdown content so you can work with it, then save changes with save_personal_file.",
+    {
+      path: z.string().describe("The file path: 'folder/[subfolder/]name.md' (folder is one of inbox/projects/areas/resources/archive/people/companies)."),
+    },
+    async ({ path }) => {
+      try {
+        const d = await get("/v2/personal/file", { path });
+        let text = `# ${d.path}\n\n${d.content || "(empty)"}`;
+        const out = (d.outgoing ?? []).filter((l) => l.resolved);
+        const back = d.backlinks ?? [];
+        if (out.length || back.length) {
+          text += `\n\n---\n`;
+          if (out.length) text += `Links to: ${out.map((l) => `${l.target}${l.kind.startsWith("relation:") ? ` (${l.kind.slice(9)})` : ""}`).join(", ")}\n`;
+          if (back.length) text += `Linked from: ${back.map((l) => l.source).join(", ")}\n`;
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (e) {
+        const msg = String(e?.message || "");
+        return { content: [{ type: "text", text: msg.includes("404") ? `No file at ${path}. Use list_my_files to see what's there.` : `Couldn't read ${path}.` }] };
+      }
+    },
+  );
+
+  // ===========================================================================
+  // TOOL: create_project  —  POST /v2/personal/project
+  // Scaffold a project folder with the standard sub-structure.
+  // ===========================================================================
+  server.tool(
+    "create_project",
+    "Create a new project in your workspace, scaffolded with the standard structure: Context, " +
+    "Working Documents, Decisions, People & Companies, Deliverables, Raw Documents, Archive. " +
+    "Use this when you start a real piece of work so everything about it has a home. Then write " +
+    "files into projects/<name>/<subfolder>/… (e.g. the current status goes in Context).",
+    {
+      name: z.string().describe("The project name, e.g. 'Acme rollout'."),
+    },
+    async ({ name }) => {
+      const d = await post("/v2/personal/project", { name });
+      return { content: [{ type: "text", text: `Created project "${d.project}" at ${d.path}/ with: ${(d.folders || []).join(", ")}.` }] };
+    },
+  );
+
   // ===========================================================================
   // TOOL: propose_vault_file  —  POST /v2/personal/propose
   // Propose a markdown file into the member's PERSONAL vault. It lands in their
@@ -585,7 +661,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 +769,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. 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 '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,65 +819,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 in the SHARED COMPANY knowledge 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 propose_company_file / propose_company_files using the same path. Returns the folder id.",
-    { 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.") },
-    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 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? }."),
-    },
-    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,
   );
 
   // ===========================================================================
@@ -847,35 +942,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,
   );
 
   // ===========================================================================
@@ -884,32 +987,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(