@edda-business/mcp 0.53.0 → 0.56.0

package/package.json

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

package/src/server.js

@@ -10,19 +10,23 @@
  * sees raw rows — it gets engineered, epistemics-tagged context. It never
  * "updates" — it records observations; Edda derives.
  *
- * Tools, by group:
- *   READ    get_context · get_account · query · attention · verify ·
- *           search_notes · search_company_knowledge · search_my_vault
- *   WRITE   save_note · propose_vault_file · propose_company_file · merge_contacts
- *   CORRECT unmerge_contacts
- *   RUN     list_integrations · connect_integration
+ * 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 · propose_company_file
+ *   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)
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post, del } from "./client.js";
 
-export const SERVER_VERSION = "0.53.0";
+export const SERVER_VERSION = "0.56.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -146,7 +150,8 @@ export function createServer() {
         lines.push("DOCUMENTS (notes & meeting records — use search_notes to search their content):");
         for (const d of ctx.documents) {
           const when = d.date ? `  [${relAge(d.date)}]` : "";
-          lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}${when}`);
+          const from = d.source_member ? `  · from ${d.source_member}` : "";
+          lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}${from}${when}`);
           if (d.snippet) lines.push(`    ${d.snippet}`);
         }
         lines.push("");
@@ -306,18 +311,45 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "merge_contacts",
-    "Merge two duplicate records for the SAME person into one account. Use when the same human exists " +
-    "twice — e.g. one record from a LinkedIn connection (no email) and one from a Cal.com booking (email, " +
-    "truncated name) that never got linked. Pass `keep` (the survivor) and `drop` (the duplicate to fold in); " +
-    "each may be an email, LinkedIn URL, entity UUID, or name. Lossless — the duplicate's identifiers (a second " +
-    "email, a LinkedIn URL) re-attach to the survivor, so a future match on EITHER resolves to the one account — " +
-    "and reversible. If a name matches several people you'll get candidates: confirm the survivor with the user, " +
-    "then re-call with the chosen entity ids. Prefer passing the keep that already has the most history.",
+    "Reconcile identity — MERGE two duplicate records for the same person into one, or SPLIT a wrongly-merged " +
+    "record back out. Set `action`: 'merge' (default) folds `drop` into the survivor `keep`; 'split' reverses a " +
+    "merge (pass the merged-away id as `drop`, or just `keep` to undo the most recent merge into it). Merge is " +
+    "lossless + reversible — the duplicate's identifiers re-attach to the survivor so a future match on either " +
+    "resolves to one account. If a name matches several people you'll get candidates to disambiguate. Use merge " +
+    "when the same human exists twice (a LinkedIn connection with no email + a Cal.com booking that never linked); " +
+    "use split when two DIFFERENT people were merged by mistake.",
     {
-      keep: z.string().describe("The survivor to keep — email, LinkedIn URL, entity UUID, or name."),
-      drop: z.string().describe("The duplicate to fold into keep — email, LinkedIn URL, entity UUID, or name."),
+      action: z.enum(["merge", "split"]).optional().describe("'merge' (default) folds drop into keep; 'split' reverses a prior merge."),
+      keep: z.string().optional().describe("The survivor — email, LinkedIn URL, entity UUID, or name. For split, the account to undo the most recent merge into (if drop is omitted)."),
+      drop: z.string().optional().describe("For merge: the duplicate to fold into keep. For split: the merged-away entity id from the merge result."),
     },
-    async ({ keep, drop }) => {
+    async ({ action, keep, drop }) => {
+      // SPLIT — reverse a prior merge (was unmerge_contacts).
+      if (action === "split") {
+        if (!drop && !keep) return { content: [{ type: "text", text: "To split, give the merged-away id as `drop`, or the `keep` survivor whose last merge to undo." }] };
+        try {
+          const u = await post("/v2/accounts/unmerge", { drop_id: drop, keep });
+          if (u.status === "ambiguous") {
+            const opts = (u.candidates ?? []).map(c => `  • ${c.name ?? "(unnamed)"}  [${c.entity_id}]`).join("\n");
+            return { content: [{ type: "text", text: `"${keep}" matches several people. Re-call merge_contacts action:split with one of these entity ids as keep:\n${opts}` }] };
+          }
+          const lines = [
+            `Split — ${u.drop_id} is its own account again.`,
+            `  identifiers restored: ${u.identifiers}, claims: ${u.claims}, observations: ${u.observations}, relationships: ${u.relationships}`,
+            u.contact_restored ? `  the contact record was recreated.` : null,
+          ].filter(Boolean);
+          return { content: [{ type: "text", text: lines.join("\n") }] };
+        } catch (e) {
+          const msg = /not_reversible/.test(e.message) ? "That merge can't be reversed — it predates reversible-merge tracking, or it was already split."
+            : /no_reversible_merge/.test(e.message) ? "No un-reversed merge on that survivor to undo."
+            : /entity_not_found/.test(e.message) ? "Couldn't find that survivor — check the keep identifier."
+            : `Couldn't split: ${e.message}`;
+          return { content: [{ type: "text", text: msg }] };
+        }
+      }
+
+      // MERGE (default).
+      if (!keep || !drop) return { content: [{ type: "text", text: "To merge, pass both `keep` (survivor) and `drop` (duplicate)." }] };
       const r = await post("/v2/accounts/merge", { keep, drop });
 
       if (r.status === "ambiguous") {
@@ -337,21 +369,17 @@ export function createServer() {
         (r.relationships_repointed || r.relationships_removed)
           ? `  relationships: ${r.relationships_repointed} re-pointed, ${r.relationships_removed} pruned` : null,
         moved ? `  re-pointed: ${moved}` : null,
-        `Reversible: if this was wrong, unmerge_contacts with drop_id "${r.drop_id}" puts it all back.`,
+        `Reversible: if this was wrong, merge_contacts action:split drop "${r.drop_id}" puts it all back.`,
       ].filter(Boolean);
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );
 
+  // DEPRECATED — use merge_contacts with action:'split'. Kept so existing agents keep working.
   server.tool(
     "unmerge_contacts",
-    "REVERSE a merge — split a wrongly-merged duplicate back out into its own account. Identify the " +
-    "merge to undo either by `drop_id` (the tombstone's id, exactly as merge_contacts reported it) or by " +
-    "`keep` (an identifier for the survivor — undoes the MOST RECENT merge into it). Every re-pointed " +
-    "identifier, claim, observation, relationship and the record itself go back where they were. " +
-    "Forward-only: it can only reverse merges made after reversible-merge tracking existed — an older " +
-    "merge returns a clear 'not reversible'. Use this when two DIFFERENT people were merged by mistake; " +
-    "it is not for editing a correctly-merged account.",
+    "DEPRECATED — use `merge_contacts` with action:'split'. Reverses a merge, splitting a wrongly-merged " +
+    "record back into its own account (by `drop_id`, or by `keep` to undo the most recent merge into it).",
     {
       drop_id: z.string().optional().describe("The merged-away entity's id, from the merge_contacts result. Provide this OR keep."),
       keep: z.string().optional().describe("The survivor (email, LinkedIn URL, entity UUID, or name) — undoes the most recent un-reversed merge into it."),
@@ -569,134 +597,111 @@ export function createServer() {
   // consent. Distinct from `save_note` (which attaches a document to a CONTACT's
   // record) — this is the member's private vault, not an account.
   // ===========================================================================
+  // DEPRECATED — use save_to_vault. Kept so existing agents keep working; forwards to the
+  // same direct personal-vault save (the member owns their vault, so no inbox step).
   server.tool(
     "propose_vault_file",
-    "Propose a markdown file into the member's personal vault (their private notes, not an " +
-    "account). It lands in their INBOX as a proposal — the member approves it before it's filed " +
-    "into a folder and synced to their Git; nothing is written without their approval. Use this to " +
-    "draft a thought, a decision record, a brief, or content for the member to review and keep. " +
-    "Pick the destination folder. This is NOT for notes on a contact (use save_note) and NOT for the " +
-    "GTM profile (use sync_icp).",
+    "DEPRECATED — use `save_to_vault`. Saves a markdown file into the member's own private vault folder.",
     {
-      folder: z.enum(["inbox", "projects", "decisions", "accounts", "people", "resources", "archive"])
-        .describe("Where it files once approved. ROUTING: accounts = a note or brief about a specific COMPANY (subfolder = the account). people = a note or brief about a specific PERSON (subfolder = the person). projects = ongoing/recurring analysis or an initiative, WITH a subfolder (pipeline/funnel review -> projects 'pipeline'; campaign analysis -> projects 'campaigns'; an initiative -> projects '<name>'). decisions = a decision. resources = reference material, research, or anything to publish/send (post, newsletter, outbound copy, write-up). archive = old or inactive material. Don't pick 'inbox' — that's where it lands to await approval."),
-      name: z.string().describe("The file name, ending in .md, for what it is plus the date, e.g. 'Pipeline Review — 2026-08-12.md'."),
-      content: z.string().describe("The full markdown content of the file."),
-      subfolder: z.string().optional().describe("REQUIRED for 'projects' — the area: 'pipeline', 'campaigns', or the initiative name. Leave empty for 'briefs' (flat) and other folders."),
+      folder: z.string().describe("The vault folder (inbox | projects | decisions | companies | people | resources | archive)."),
+      name: z.string().describe("The file name, ending in .md."),
+      content: z.string().describe("The full markdown content."),
+      subfolder: z.string().optional().describe("Optional subfolder within the folder."),
     },
     async ({ folder, name, content, subfolder }) => {
-      await post("/v2/personal/propose", { folder, name, content, subfolder });
-      return { content: [{ type: "text", text: `Proposed "${name}" into ${folder}. It's waiting in the member's inbox for approval.` }] };
+      const r = await post("/v2/personal/files", { folder, name, content, subfolder });
+      return { content: [{ type: "text", text: `Saved "${name}" to your ${r?.folder || folder} vault — it's searchable now.` }] };
     },
   );
 
   // ===========================================================================
-  // TOOL: search_notes  —  POST /v2/notes/search
-  // Semantic search over saved notes & documents (briefs, transcripts, notes).
-  // The retrieval counterpart to save_note — pull relevant document content
-  // instead of dumping whole documents into context.
+  // TOOL: search  —  POST /v2/search   (unified; replaces the three scoped searches)
+  // One retrieval surface across company knowledge + personal vault + notes, ACL-
+  // filtered per layer and fused best-first. `scope` narrows it. Cerebras-style:
+  // one search, the agent orchestrates; get_context is the synthesized counterpart.
   // ===========================================================================
+  const runSearch = async ({ question, scope, limit, folder }) => {
+    const r = await post("/v2/search", { question, scope, limit, folder });
+    if (!r.documents?.length) {
+      return { content: [{ type: "text", text: `Nothing matched "${question}"${scope && scope !== "all" ? ` in ${scope}` : ""}.` }] };
+    }
+    const lines = [`Results for "${question}"${scope && scope !== "all" ? ` (${scope})` : ""}:`, ""];
+    for (const d of r.documents) {
+      const tag = d.scope === "company" ? (d.kind === "derived" ? "[company·derived]" : "[company]")
+        : d.scope === "personal" ? "[my vault]" : "[note]";
+      const where = d.ref ? `${d.ref} · ` : "";
+      const from = d.source_member ? ` · from ${d.source_member}` : "";
+      const match = d.similarity == null ? "recent" : pct(d.similarity);
+      lines.push(`  ${tag} ${where}${String(d.name ?? "").replace(/\.md$/, "")}${from}  (${match})`);
+      if (d.snippet) lines.push(`    ${d.snippet}`);
+      if (d.entity_id) lines.push(`    (entity_id: ${d.entity_id})`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+  };
+
   server.tool(
-    "search_notes",
-    "Semantically search the saved notes & documents (meeting briefs, transcripts, meeting notes) " +
-    "kept on contacts. Use this to pull relevant content from the record — e.g. 'what did we discuss " +
-    "about pricing', 'objections raised in past meetings', or to compare across a contact's meetings. " +
-    "Pass `focus` to restrict to one person/company, or omit it to search across everyone. Returns the " +
-    "matching documents (type, title, date, similarity, snippet); get the full body with get_account.",
+    "search",
+    "Search the company's knowledge in one call — DECLARED + DERIVED company knowledge (policies, playbooks, " +
+    "decisions, and what actually happened on accounts), the member's OWN private vault (their notes/drafts), " +
+    "and NOTES kept on contacts — each ACL-filtered, fused best-first. This is the default retrieval tool: reach " +
+    "for it before answering from generic knowledge. Narrow with `scope`: 'company', 'personal', 'notes', or " +
+    "'all' (default — everything this key may read). Returns matching items tagged by layer with a snippet. For " +
+    "a synthesized brief on ONE person/company use get_context; for who knows a topic use who_knows.",
     {
-      question: z.string().describe("Natural-language query to match against document content."),
-      focus: z.string().optional().describe("Optional — restrict to one person/company (email, LinkedIn URL, domain, or entity UUID)."),
-      limit: z.number().optional().describe("Max documents to return (default 8)."),
-    },
-    async ({ question, focus, limit }) => {
-      const r = await post("/v2/notes/search", { question, focus, limit });
-      if (!r.documents?.length) {
-        return { content: [{ type: "text", text: `No saved documents matched "${question}".` }] };
-      }
-      const lines = [`Documents matching "${question}":`, ""];
-      for (const d of r.documents) {
-        const when = d.date ? `  [${relAge(d.date)}]` : "";
-        // similarity is null for recency-matched hits (a note too fresh to be
-        // embedded yet) — label those "recent" instead of a bogus 0%.
-        const match = d.similarity == null ? "recent" : pct(d.similarity);
-        lines.push(`  ${d.type.replace(/_/g, " ")}${d.title ? ` · ${d.title}` : ""}  (${match})${when}`);
-        if (d.snippet) lines.push(`    ${d.snippet}`);
-        lines.push(`    (entity_id: ${d.entity_id})`);
-      }
-      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
+      question: z.string().describe("Natural-language query."),
+      scope: z.enum(["all", "company", "personal", "notes"]).optional().describe("Which layer(s) to search. Default 'all' — fused across every layer this key can read."),
+      limit: z.number().optional().describe("Max results (default 8, max 20)."),
+      folder: z.string().optional().describe("Optional — for scope 'personal', restrict to one vault folder."),
     },
+    async (args) => runSearch(args),
   );
 
-  // ===========================================================================
-  // TOOL: search_company_knowledge  —  POST /v2/company/search
-  // Semantic search over the SHARED company vault (declared knowledge — policies,
-  // playbooks, decisions, the knowledge base) the workspace keeps in the Brain.
-  // Permission-filtered server-side: a doc surfaces only if agents may read it, and
-  // admins-only docs only to an admin key — so this never returns anything the
-  // caller isn't allowed to see. Use it before answering from generic knowledge.
-  // ===========================================================================
+  // ── Deprecated aliases → search. Kept so existing agents/configs keep working; removed after a window. ──
   server.tool(
     "search_company_knowledge",
-    "Search the company's knowledge across BOTH layers of the brain: DECLARED knowledge (curated policies, " +
-    "playbooks, decisions — the shared Company vault) and DERIVED knowledge (distilled from real activity — " +
-    "what actually happened in emails, meetings, threads). Hybrid retrieval (semantic + full-text + recency, " +
-    "fused) returns one best-first answer spanning both. Use this when a question is about how THIS company " +
-    "works, its rules, its plays, a past decision, or what happened on an account — before falling back on " +
-    "generic knowledge. Results are permission-filtered: you only ever see what the company allows agents to " +
-    "read, and never anyone's private raw. Each hit is tagged [declared] or [derived].",
-    {
-      question: z.string().describe("Natural-language query to match against the company's declared and derived knowledge."),
-      limit: z.number().optional().describe("Max documents to return (default 8)."),
-    },
-    async ({ question, limit }) => {
-      const r = await post("/v2/company/search", { question, limit });
-      if (!r.documents?.length) {
-        return { content: [{ type: "text", text: `Nothing in the company knowledge matched "${question}".` }] };
-      }
-      const lines = [`Company knowledge matching "${question}":`, ""];
-      for (const d of r.documents) {
-        const tag = d.kind === "derived" ? "[derived]" : "[declared]";
-        const where = d.ref ? `${d.ref} · ` : "";
-        lines.push(`  ${tag} ${where}${String(d.name ?? "").replace(/\.md$/, "")}  (${pct(d.similarity)})`);
-        if (d.snippet) lines.push(`    ${d.snippet}`);
-      }
-      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
-    },
+    "DEPRECATED — use `search` with scope 'company'. Searches the shared company knowledge (declared + derived).",
+    { question: z.string(), limit: z.number().optional() },
+    async ({ question, limit }) => runSearch({ question, scope: "company", limit }),
+  );
+  server.tool(
+    "search_my_vault",
+    "DEPRECATED — use `search` with scope 'personal'. Searches the member's own private vault.",
+    { question: z.string(), folder: z.string().optional(), limit: z.number().optional() },
+    async ({ question, folder, limit }) => runSearch({ question, scope: "personal", limit, folder }),
+  );
+  server.tool(
+    "search_notes",
+    "DEPRECATED — use `search` with scope 'notes'. Searches notes/documents kept on contacts.",
+    { question: z.string(), limit: z.number().optional() },
+    async ({ question, limit }) => runSearch({ question, scope: "notes", limit }),
   );
 
   // ===========================================================================
-  // TOOL: search_my_vault  —  POST /v2/personal/search
-  // Semantic search over the MEMBER'S OWN personal vault (their private PKM). The
-  // counterpart to search_company_knowledge (shared) — this is the member's private
-  // notes, hard-scoped server-side to the member this key acts for. Never another
-  // member's vault.
+  // TOOL: who_knows  —  POST /v2/who-knows
+  // Expertise routing: internal people whose own knowledge (meetings, notes,
+  // messages) matches a topic, ranked. Honest by construction — someone only
+  // surfaces if their distilled knowledge actually matched.
   // ===========================================================================
   server.tool(
-    "search_my_vault",
-    "Semantically search the member's OWN personal vault — their private notes, thoughts, decisions, " +
-    "project docs, briefs, and drafts (their PKM). Use this when a question is about what the user has " +
-    "personally written, decided, or been thinking about — 'my notes on X', 'what did I decide about Y', " +
-    "'my draft for Z'. This is PRIVATE to this member and never exposes anyone else's vault. For the " +
-    "company's shared knowledge use search_company_knowledge; for facts about accounts use get_context/query. " +
-    "NOTE: if you're running where this member's vault is linked as local files, prefer reading those files " +
-    "directly — fresher, fuller, and their private notes never leave the machine. On-device, use the CLI: " +
-    "`nous vault search <query>`, `nous vault read <path>`, or `nous vault path`. Use THIS tool only when you " +
-    "are NOT on those files (a remote agent, Slack, or the web).",
+    "who_knows",
+    "Find the internal people who know about a topic — ranked by how much of their OWN knowledge " +
+    "(meetings, notes, messages distilled into the brain) matches it. Use for 'who knows about X', " +
+    "'who's the expert on Y', 'who should I ask about Z'. Returns people with a relevance score and a " +
+    "sample of the matching knowledge. Honest by construction: someone only appears if their knowledge " +
+    "genuinely matched — an empty result means no one's tracked knowledge covers it yet.",
     {
-      question: z.string().describe("Natural-language query to match against the member's own vault notes."),
-      folder: z.enum(["inbox", "projects", "decisions", "accounts", "people", "resources", "archive", "thoughts", "briefs", "content", "company"]).optional().describe("Optional — restrict to one vault folder."),
-      limit: z.number().optional().describe("Max files to return (default 6)."),
+      topic: z.string().describe("The topic/area/system to find experts on."),
+      limit: z.number().optional().describe("Max people to return (default 5, max 20)."),
     },
-    async ({ question, folder, limit }) => {
-      const r = await post("/v2/personal/search", { question, folder, limit });
-      if (!r.documents?.length) {
-        return { content: [{ type: "text", text: `Nothing in your personal vault matched "${question}".` }] };
+    async ({ topic, limit }) => {
+      const r = await post("/v2/who-knows", { topic, limit });
+      if (!r.people?.length) {
+        return { content: [{ type: "text", text: `No one's tracked knowledge matched "${topic}" yet.` }] };
       }
-      const lines = [`Your vault notes matching "${question}":`, ""];
-      for (const d of r.documents) {
-        const match = d.similarity == null ? "recent" : pct(d.similarity);
-        lines.push(`  ${d.path ?? d.name}  (${match})`);
-        if (d.snippet) lines.push(`    ${d.snippet}`);
+      const lines = [`People who know about "${topic}":`, ""];
+      for (const p of r.people) {
+        lines.push(`  ${p.name}  (${p.mentions} matching${p.relevance != null ? `, relevance ${p.relevance}` : ""})`);
+        if (p.sample) lines.push(`    ${p.sample}`);
       }
       return { content: [{ type: "text", text: lines.join("\n").trim() }] };
     },
@@ -710,27 +715,37 @@ export function createServer() {
   // ===========================================================================
   server.tool(
     "propose_company_file",
-    "Add or update a markdown file in 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. Use this to contribute company-wide knowledge everyone " +
-    "should have. ADMIN-ONLY: only an owner/admin may write the company vault; a regular member's " +
-    "agent can read it but will get a permission message here. This is NOT the member's private " +
-    "notes (use propose_vault_file) and NOT a note on a contact (use save_note). Pick the " +
-    "destination company folder (it must be an existing folder in the company vault).",
+    "Propose a markdown file for 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 OPENS A PULL REQUEST against the connected company repo for a " +
+    "human to review and merge in GitHub — nothing goes live until it's merged (company knowledge " +
+    "is shared + institutional, so review-before-publish is the default; on merge the normal git " +
+    "sync ingests it). Use it to contribute company-wide knowledge. ADMIN-ONLY: only an owner/admin " +
+    "may propose; a regular member's agent can READ the vault but gets a permission message here. " +
+    "NOT the member's private notes (use propose_vault_file), NOT a note on a contact (use save_note).",
     {
       folder: z.string().describe("The company-vault folder to file under (e.g. 'company-wiki', 'decisions', 'projects', 'clients'). Must be an existing company folder; no slashes."),
       name: z.string().describe("The file name, ending in .md, e.g. 'Refund Policy.md' or 'Q3 Planning — 2026-08-22.md'."),
       content: z.string().describe("The full markdown content of the file."),
       subfolder: z.string().optional().describe("Optional subfolder within the folder."),
+      message: z.string().optional().describe("Optional PR title / commit message describing the change."),
+      pr_group: z.string().optional().describe("Optional key to batch several proposals from one work session into a SINGLE pull request (same key → same PR)."),
     },
-    async ({ folder, name, content, subfolder }) => {
+    async ({ folder, name, content, subfolder, message, pr_group }) => {
       try {
-        await post("/v2/company/propose", { folder, name, content, subfolder });
-        return { content: [{ type: "text", text: `Filed "${name}" into the company vault (${folder}). It's now searchable by the team's agents via search_company_knowledge.` }] };
+        const r = await post("/v2/company/propose", { folder, name, content, subfolder, message, pr_group });
+        const how = r?.added_to_existing ? "added to the open PR" : "opened a pull request";
+        return { content: [{ type: "text", text: `Proposed "${name}" — ${how}${r?.pr_url ? `: ${r.pr_url}` : ""}. Review the diff and merge it in GitHub to publish into company knowledge.` }] };
       } catch (e) {
         const msg = String(e?.message || e);
         if (msg.includes("admins_only") || msg.includes("(403)")) {
-          return { content: [{ type: "text", text: `Not filed — writing to the company vault is admin-only. You can READ it with search_company_knowledge, but only an owner/admin can add to it.` }] };
+          return { content: [{ type: "text", text: `Not proposed — writing to the company vault is admin-only. You can READ it with search_company_knowledge, but only an owner/admin can propose changes.` }] };
+        }
+        if (msg.includes("no_company_repo")) {
+          return { content: [{ type: "text", text: `Not proposed — no company GitHub repo is connected. An admin connects one under Company vault first.` }] };
+        }
+        if (msg.includes("repo_write_denied")) {
+          return { content: [{ type: "text", text: `Not proposed — the connected repo token is read-only. An admin must reconnect it with Contents:write + Pull requests:write.` }] };
         }
         throw e;
       }
@@ -779,6 +794,40 @@ 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.
+  // ===========================================================================
+  server.tool(
+    "save_to_vault",
+    "Save a file into the MEMBER'S OWN private knowledge vault, in a folder they name " +
+    "(inbox, projects, decisions, companies, people, resources, archive, thoughts). Use it when the " +
+    "member asks you to keep or file something for them — 'save this to projects', 'put this PDF in " +
+    "resources'. Pass markdown/text as `content`, OR a PDF/DOCX as base64 in `file` (it's extracted to " +
+    "text automatically and stored so they can search it later). PRIVATE to the member — nothing is " +
+    "shared until they promote it to their department. 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: `Saved "${name}" to your ${r?.folder || folder} vault — it's searchable now.` }] };
+      } 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(
     "list_integrations",
     "List the integrations connected to this workspace (Gmail, HubSpot, Apollo, Instantly, LinkedIn, …) " +