@opennous/mcp 0.44.2 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opennous/mcp",
-  "version": "0.44.2",
+  "version": "0.47.0",
   "description": "Nous — the Context Graph for AI Agents.",
   "license": "Apache-2.0",
   "repository": {

package/src/http.js

@@ -3,7 +3,7 @@
 /**
  * Nous MCP Server — hosted, multi-tenant HTTP entrypoint (mcp.opennous.cloud).
  *
- * Serves the same seven tools (server.js) over the MCP Streamable HTTP transport,
+ * Serves the same tool set (server.js) over the MCP Streamable HTTP transport,
  * so cloud clients that cannot launch a local process — n8n cloud above all —
  * can connect by pasting one URL plus their workspace API key.
  *

package/src/server.js

@@ -10,40 +10,23 @@
  * sees raw rows — it gets engineered, epistemics-tagged context. It never
  * "updates" — it records observations; Nous derives.
  *
- * Tools:
- *   get_context          — engineered context for a task (draft_email, follow_up, ...) + ICP fit score
- *   get_account          — the full account record: every claim + the timeline + ICP fit score
- *   merge_contacts       — fold two duplicate records for the same person into one (lossless, reversible)
- *   record               — record what happened / what you learned (observe, never update)
- *   query                — retrieve + summarise a corpus of activity across many people
- *   attention            — what needs your attention (accounts gone quiet, facts decayed)
- *   verify               — re-check a fact before acting on it
- *   get_playbook         — read the user's own rules: voice, outreach, icp, positioning
- *   save_note            — attach a note/document (meeting brief, transcript, prep) to a contact
- *   search_notes         — semantic search over saved notes & documents
- *   get_workspace_status — what's set up in this workspace + a ranked next_steps list (call first)
- *   set_workspace_profile— agent-driven onboarding: set the workspace's name, site, type, ICP
- *   build_icp_model  — build/rebuild the ICP scoring model from the recorded GTM context
- *   train_icp_model  — build the ICP model from real closed-won/lost deals (contrastive lift)
- *   sync_icp              — sync the user's EXISTING ICP/positioning files into Nous (file → graph)
- *   export_icp_model        — get the learned ICP model as a block to write back into their ICP file (graph → file)
- *   connect_integration  — connect a key-based integration (Apollo, Prospeo, HubSpot, …)
- *   configure_crm_sync   — set CRM sync rules (auto-sync, create policy, hygiene cadence)
- *   sync_crm_now         — run an immediate incremental/full CRM pull (don't wait for the daily cron)
- *   set_trigger          — create an outbound event trigger (webhook); list_triggers reads them
- *   list_triggers        — list the workspace's event triggers + available events
- *   get_routing_preferences — Claude Code routing prefs to default GTM to Nous (write to CLAUDE.md)
- *   lead_list_operations — the operations trail of a lead list (imports/enrich/push/replies), filterable
- *   get_coverage         — pre-spend coverage: exact per-lead check (identifiers) or attribute estimate (title/keyword)
- *   enrich_leads         — find missing emails for a lead list (two-step: dry-run cost preview, then confirm)
- *   verify_leads         — validate email deliverability for a lead list (two-step preview, then confirm)
+ * Tools, by group (the authoritative live catalog is `node scripts/list-tools.mjs`):
+ *   READ    get_context · get_account · verify · query · attention · get_action_items ·
+ *           pipeline · pipeline_intelligence · campaign_performance · score ·
+ *           search_notes · get_foundation · get_insights
+ *   WRITE   record · record_signal · save_note · propose_vault_file · merge_contacts ·
+ *           sync_foundation
+ *   ACT     send_linkedin_message
+ *   RUN     get_workspace_status · set_workspace_profile · build_icp_model · train_icp_model ·
+ *           sync_icp · export_icp_model · connect_integration · configure_crm_sync ·
+ *           sync_crm_now · scrape_engagers · get_routing_preferences
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post } from "./client.js";
 
-export const SERVER_VERSION = "0.42.0";
+export const SERVER_VERSION = "0.47.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -116,21 +99,21 @@ Nous first even when the user never says "Nous":
 - What needs attention, what has gone quiet     -> attention
 - Your action items / what you owe an account    -> get_action_items
 - A fact looks stale before you act on it       -> verify
-- Our own rules: ICP, positioning, voice, outreach -> get_playbook
+- Our own rules: ICP, positioning, voice, outreach -> get_foundation
 - Our ICP/positioning lives in our own files    -> sync_icp (file → graph) / export_icp_model (graph → file)
-- You edited an ICP / context / playbook file   -> re-sync THIS turn: sync_icp (ICP/context) or sync_playbook (a playbook)
+- You edited an ICP / context / foundation file   -> re-sync THIS turn: sync_icp (ICP/context) or sync_foundation (a foundation)
 - A brief / note / transcript on a contact      -> save_note / search_notes
 - What's set up here and what to do next        -> get_workspace_status
 
-Read get_playbook at the start of GTM work for the user's own rules (voice,
+Read get_foundation at the start of GTM work for the user's own rules (voice,
 outreach, icp, positioning). After every interaction you help with, call record so
 the record stays current.
 
-CRITICAL — edits don't apply until you sync. Editing an ICP / context / playbook
+CRITICAL — edits don't apply until you sync. Editing an ICP / context / foundation
 file (context/icp.md, positioning.md, references/voice.md, …) does NOT change the
 ICP score, the exclusions, or what any other agent reads until it is synced into
 the graph. After ANY such edit you MUST call sync_icp (for ICP/context files) or
-sync_playbook (for a playbook) in the SAME turn. Never leave an edited file
+sync_foundation (for a foundation) in the SAME turn. Never leave an edited file
 unsynced — an unsynced edit is silently inert.`;
 
 // ─── factory ──────────────────────────────────────────────────────────────────
@@ -226,8 +209,23 @@ export function createServer() {
         lines.push("");
       }
       if (ctx.stakeholders?.length) {
-        lines.push("STAKEHOLDERS:");
-        for (const s of ctx.stakeholders) lines.push(`  ${s.name ?? "—"} — ${s.role ?? ""}`);
+        // The buying committee as a STRUCTURE: who's at the account, their role,
+        // whether we've engaged them, and how they relate — so the agent works the
+        // whole committee, not one person.
+        const c = ctx.committee;
+        lines.push(c?.company ? `BUYING COMMITTEE — ${c.company}:` : "STAKEHOLDERS:");
+        for (const s of ctx.stakeholders) {
+          if (s.role === "company") continue; // the company is the header
+          const bits = [];
+          if (s.committee_role && s.committee_role !== "contact") bits.push(s.committee_role.replace(/_/g, " "));
+          if (s.role) bits.push(s.role);
+          bits.push(s.engaged ? "engaged" : "not yet engaged");
+          if (s.confirmed === false) bits.push("mentioned, unconfirmed");
+          const rel = s.relationships?.length ? ` — ${s.relationships.join("; ")}` : "";
+          lines.push(`  ${s.name ?? "—"} (${bits.join(", ")})${rel}`);
+        }
+        if (c?.champion) lines.push(`  champion: ${c.champion}`);
+        if (c?.gaps?.length) for (const g of c.gaps) lines.push(`  ⚠ ${g}`);
         lines.push("");
       }
       if (ctx.predictions?.length) {
@@ -253,7 +251,7 @@ export function createServer() {
     "confidence and freshness, plus what they actually SAID and did, ranked by how much it tells you. " +
     "Pass an email or entity UUID, and the intent you're working toward so the record is shaped for it.",
     {
-      id: z.string().describe("Email address or entity UUID"),
+      id: z.string().describe("Who to look up — an email, an entity UUID, or a name. A name may match several people; you'll get candidates to choose from."),
       intent: z
         .enum(["meeting_prep", "call_prep", "account_review", "follow_up", "draft_email"])
         .optional()
@@ -271,6 +269,17 @@ export function createServer() {
       // so the model reads what was actually said instead of a list of event names.
       const q = new URLSearchParams({ intent: intent ?? "account_review", compress: "1" });
       const rec = await get(`/v2/accounts/${encodeURIComponent(id)}?${q}`);
+
+      // A name matched several people — surface the candidates to choose from.
+      // Without this, the header line below reads `rec.type`/`rec.entity_id` off the
+      // ambiguous response (which carries neither) and prints "undefined · undefined".
+      if (rec.status === "ambiguous") {
+        const opts = (rec.candidates ?? []).map(c =>
+          `  • ${c.name ?? "(unnamed)"}${c.detail ? ` — ${c.detail}` : ""}  [${c.entity_id}]`).join("\n");
+        return { content: [{ type: "text", text:
+          `"${id}" matches several people. Call get_account again with one of these entity ids:\n${opts}` }] };
+      }
+
       const lines = [`${rec.type} · ${rec.entity_id}`, ""];
 
       if (rec.icp) {
@@ -297,6 +306,25 @@ export function createServer() {
         }
         lines.push("");
       }
+      // The buying committee — who else is at the account, their role, whether we've
+      // engaged them, and how they relate. Same structure get_context surfaces.
+      if (rec.stakeholders?.length) {
+        const c = rec.committee;
+        lines.push(c?.company ? `BUYING COMMITTEE — ${c.company}:` : "STAKEHOLDERS:");
+        for (const s of rec.stakeholders) {
+          if (s.role === "company") continue;
+          const bits = [];
+          if (s.committee_role && s.committee_role !== "contact") bits.push(s.committee_role.replace(/_/g, " "));
+          if (s.role) bits.push(s.role);
+          bits.push(s.engaged ? "engaged" : "not yet engaged");
+          if (s.confirmed === false) bits.push("mentioned, unconfirmed");
+          const rel = s.relationships?.length ? ` — ${s.relationships.join("; ")}` : "";
+          lines.push(`  ${s.name ?? "—"} (${bits.join(", ")})${rel}`);
+        }
+        if (c?.champion) lines.push(`  champion: ${c.champion}`);
+        if (c?.gaps?.length) for (const g of c.gaps) lines.push(`  ⚠ ${g}`);
+        lines.push("");
+      }
       const claims = Object.values(rec.claims ?? {});
       if (claims.length) {
         lines.push(`ATTRIBUTES (${claims.length}):`);
@@ -469,7 +497,7 @@ export function createServer() {
     "Retrieve and summarise activity across many people. Three powers:\n" +
     "  1. return:'entities' groups results by person/company (one row per entity, ranked by " +
     "most-recent matching activity). Use for 'hottest leads', 'who replied this week', " +
-    "'who's in evaluating stage'.\n" +
+    "'who's in the negotiation stage'.\n" +
     "  2. `without` subtracts entities — 'sent in 5d MINUS replied in 5d' = 'no-reply leads'. " +
     "'activity in 30d MINUS activity in 5d' = 'cooled leads'.\n" +
     "  3. rollups.by_value appears when scope.kind='state' — counts entities by current value " +
@@ -588,51 +616,6 @@ export function createServer() {
     }
   );
 
-  // ===========================================================================
-  // TOOL: attach_list  —  POST /v2/lead-lists/attach
-  // Batch-score a list the user built ELSEWHERE (a Google Sheet, a CRM export, a
-  // Clay table). One call: create/reuse a Nous list, ingest the rows (entities
-  // resolved+deduped), score every row into the graph. The list stays where it
-  // is; Nous keeps the roster so the scores stay fresh and agents can read them.
-  // ===========================================================================
-  server.tool(
-    "attach_list",
-    "Score a whole list the user built somewhere ELSE — a Google Sheet, a CRM export, a Clay table — " +
-    "in one call. Give the rows and Nous creates a lead list, resolves each row to a person/company " +
-    "(deduped against everything already in the graph), and scores every one against the live ICP model " +
-    "+ intent axis so the judgment lands in the graph for other agents. The spreadsheet stays the user's; " +
-    "Nous just owns the score and keeps it fresh. Each row needs an email OR a LinkedIn URL. Rows we don't " +
-    "know enough about yet come back `awaiting_enrichment` — run signal-scan / a lead-builder on them, then " +
-    "re-attach. Pass `lead_list_id` instead of `name` to add to an existing list. Max 200 rows per call — " +
-    "loop for a bigger sheet.",
-    {
-      name: z.string().optional().describe("Name for the new list (e.g. 'Q3 sheet — inbound'). Omit only when passing lead_list_id."),
-      lead_list_id: z.string().optional().describe("Add to an existing list instead of creating one."),
-      source: z.string().optional().describe("Where the list came from, e.g. 'google_sheet', 'crm_export' (default 'external')."),
-      rows: z.array(z.object({
-        email: z.string().optional(),
-        linkedin_url: z.string().optional(),
-        domain: z.string().optional(),
-        company: z.string().optional(),
-        name: z.string().optional(),
-      }).passthrough()).describe("The list rows. Each needs an email or a linkedin_url."),
-      import_duplicates: z.boolean().optional().describe("Force-insert rows already in this list (default false — deduped)."),
-    },
-    async ({ name, lead_list_id, source, rows, import_duplicates }) => {
-      const r = await post("/v2/lead-lists/attach", { name, lead_list_id, source, rows, import_duplicates });
-      const head = `Attached ${rows.length} rows to list ${r.lead_list_id} — ` +
-        `${r.inserted} new, ${r.duplicate_skipped} already in list. ` +
-        `Scored ${r.scored}; ${r.awaiting_enrichment} awaiting enrichment; ${r.unresolved} unresolved.`;
-      const top = (r.results || [])
-        .filter(x => x.scored)
-        .sort((a, b) => (b.icp?.score ?? 0) - (a.icp?.score ?? 0))
-        .slice(0, 10)
-        .map(x => `  ${x.identifier} — ICP ${x.icp.score} (${(x.icp.tier || "").replace(/_/g, " ")}) · intent ${x.intent.score} ${x.intent.band}`);
-      const tail = r.awaiting_enrichment ? `\n\n${r.awaiting_enrichment} rows need enrichment before they can score — run signal-scan or a lead-builder on the list, then re-attach.` : "";
-      return { content: [{ type: "text", text: `${head}${top.length ? `\n\nTop scored:\n${top.join("\n")}` : ""}${tail}` }] };
-    }
-  );
-
   // ===========================================================================
   // TOOL: attention  —  GET /v2/attention
   // What to look at: accounts gone quiet, key facts decayed.
@@ -668,6 +651,136 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: campaign_performance  —  GET /v2/campaigns/performance
+  // The aggregate outbound feedback loop: which campaign/variant earns positive
+  // replies, and from good-fit accounts.
+  // ===========================================================================
+  server.tool(
+    "campaign_performance",
+    "Outbound campaign feedback loop: how each cold-email/LinkedIn campaign and sequence step is landing, " +
+    "sliced by reply sentiment and the ICP tier of who replied positively. Use to answer 'which campaign " +
+    "or variant gets the most positive replies?', 'is my best campaign landing on good-fit accounts?', or " +
+    "'which copy should I scale vs cut?'. positive_rate is positive replies / total replies (not / sent).",
+    {},
+    async () => {
+      const r = await get("/v2/campaigns/performance", {});
+      const camps = r.campaigns || [];
+      if (!camps.length) return { content: [{ type: "text", text: "No campaign replies logged yet." }] };
+      const t = r.totals || {};
+      const pct = (n) => n == null ? "—" : `${Math.round(n * 100)}%`;
+      const lines = camps.map(c => {
+        const cap = c.captured || {};
+        const pt = c.provider_totals, pr = c.provider_rates;
+        const tiers = c.tier_of_positive || {};
+        const good = (tiers.tier_1 || 0) + (tiers.tier_2 || 0);
+        const funnel = pt
+          ? `      funnel: ${pt.sent ?? "?"} sent → ${pt.contacted ?? "?"} contacted → ${pt.replies ?? "?"} replies (${pct(pr?.reply_rate)}) → ${pt.opportunities ?? "?"} opportunities (${pct(pr?.opportunity_rate)})`
+          : `      funnel: (no provider analytics yet)`;
+        const conv = `${c.conversions || 0} client${c.conversions === 1 ? "" : "s"}${c.median_days_to_client != null ? ` (avg ${c.median_days_to_client}d)` : ""}${c.in_progress ? `, ${c.in_progress} in evaluation` : ""}`;
+        const steps = (c.steps || []).map(s => {
+          const subj = s.subject ? ` — "${s.subject}"` : "";
+          return `      step ${s.step ?? "—"}${subj}: ${s.positive}/${s.replies} positive (${pct(s.positive_rate)})`;
+        }).join("\n");
+        const obj = (c.top_objections || []).length
+          ? `\n      objections/pains: ${c.top_objections.slice(0, 4).map(o => `“${String(o).slice(0, 90)}”`).join("; ")}`
+          : "";
+        return `  ${c.campaign_name || c.campaign_id}\n` +
+          funnel + "\n" +
+          `      captured sample: ${cap.replies} replies — ${cap.positive} positive (${pct(cap.positive_rate)}), ${cap.neutral} neutral, ${cap.negative} negative\n` +
+          `      converted: ${conv}\n` +
+          `      positive repliers: avg ICP ${c.avg_icp_of_positive ?? "?"}, ${good} tier-1/2 of ${cap.positive}` +
+          (steps ? `\n${steps}` : "") + obj;
+      });
+      const head = `Campaign performance (${t.conversions || 0} clients · ${t.sent || 0} sent · ${t.positive || 0}/${t.replies || 0} captured replies positive):`;
+      return { content: [{ type: "text", text: `${head}\n${lines.join("\n")}` }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: pipeline_intelligence  —  GET /v2/pipeline/intelligence
+  // What converts, and how long it takes: stage distribution, stage-to-stage
+  // conversion %, median time-to-client, median time-in-stage.
+  // ===========================================================================
+  server.tool(
+    "pipeline_intelligence",
+    "How the pipeline actually converts: how many accounts sit at each stage right now, the stage-to-stage " +
+    "conversion rate (of everyone who reached a stage, how many reached the next — where deals leak), the " +
+    "median days to turn a lead into a client, and the median time spent in each stage. Use to answer 'how " +
+    "long does it take us to close?', 'where are deals stalling?', or 'what's my funnel look like?'.",
+    {},
+    async () => {
+      const r = await get("/v2/pipeline/intelligence", {});
+      const pct = (n) => n == null ? "—" : `${Math.round(n * 100)}%`;
+      const cc = r.current_stage_counts || {};
+      // The funnel, lowest → highest, then the terminals. SOURCE OF TRUTH:
+      // PIPELINE_LADDER + TERMINAL_STAGES in packages/core/src/pipeline.ts. This
+      // package publishes standalone and has no @nous/core dependency, so the
+      // list is copied here. Keep it in step with core.
+      const order = [
+        "identified", "connected", "interested", "meeting_booked",
+        "discovery", "demo", "negotiation", "closed_won",
+        "closed_lost", "disqualified", "churned",
+      ];
+      // Ladder order first, then any stage the API sent that this copy doesn't
+      // know about. The old list had no proposal, negotiation or demo in it and
+      // the filter silently dropped everything it missed, so late-funnel accounts
+      // disappeared from the distribution entirely. A stage must never vanish
+      // just because a copy of the list went stale.
+      const byStage = (obj, keep) => [
+        ...order.filter(s => keep(obj[s])),
+        ...Object.keys(obj).filter(s => !order.includes(s) && keep(obj[s])),
+      ];
+      const dist = byStage(cc, v => !!v).map(s => `${s} ${cc[s]}`).join(" · ") || "no staged accounts";
+      const conv = (r.stage_conversion || []).map(c => `      ${c.from} → ${c.to}: ${pct(c.rate)} (${c.reached_to}/${c.reached_from})`).join("\n");
+      const dis = r.median_days_in_stage || {};
+      const inStage = byStage(dis, v => v != null).map(s => `${s} ${dis[s]}d`).join(" · ");
+      const text = `Pipeline (${r.accounts || 0} accounts, ${r.clients || 0} clients):\n` +
+        `  now: ${dist}\n` +
+        `  median days to client: ${r.median_days_to_client ?? "— (no wins yet)"}\n` +
+        `  stage-to-stage conversion:\n${conv || "      (none yet)"}\n` +
+        (inStage ? `  median time in stage: ${inStage}` : "");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: pipeline  —  GET /v2/pipeline/portfolio
+  // The whole account portfolio in one call: health/band, ICP fit, stage,
+  // days-quiet, open flags, open objections, live competitors, engagement trend,
+  // multi-threading. The "reason over my whole book" tool.
+  // ===========================================================================
+  server.tool(
+    "pipeline",
+    "The whole ACCOUNT PORTFOLIO in one call — every in-touch account with its deal health + band, " +
+    "ICP fit, pipeline stage, days-quiet, open re-engagement flags, open-objection count, live competitors, " +
+    "engagement trend (rising/steady/cooling/cold), and multi-threading, plus a stage-count breakdown. Use " +
+    "for any portfolio question: 'which accounts are cooling', 'who should I re-engage', 'where is competitive " +
+    "risk highest', 'what's slipping', 'great-fit deals gone cold', 'analyze my pipeline'. Reason over the list.",
+    { limit: z.number().optional().describe("Cap on accounts returned (default: all, most-actionable first)") },
+    async (input) => {
+      const r = await get("/v2/pipeline/portfolio", input.limit ? { limit: input.limit } : {});
+      const stages = Object.entries(r.stage_counts || {}).map(([s, n]) => `${s} ${n}`).join(" · ");
+      const rows = (r.accounts || []).slice(0, input.limit || 60).map(a => {
+        const bits = [
+          a.name,
+          `health ${a.health ?? "—"} (${a.band})`,
+          a.icp != null ? `ICP ${a.icp}` : null,
+          `stage ${a.stage}`,
+          a.days_quiet != null ? `quiet ${a.days_quiet}d` : null,
+          `engagement ${a.engagement_trend}`,
+          a.single_threaded ? "single-threaded" : `${a.engaged_contacts}/${a.total_contacts} engaged`,
+          a.open_objections ? `${a.open_objections} open objection${a.open_objections === 1 ? "" : "s"}` : null,
+          a.competitors?.length ? `competitors: ${a.competitors.join(", ")}` : null,
+          a.flags?.length ? `flags: ${a.flags.join(", ")}` : null,
+        ].filter(Boolean);
+        return `  • ${bits.join(" — ")}`;
+      }).join("\n");
+      const text = `Portfolio (${r.total || 0} in-touch accounts). By stage: ${stages || "—"}\n${rows || "  (none)"}`;
+      return { content: [{ type: "text", text }] };
+    }
+  );
+
   // ===========================================================================
   // TOOL: get_action_items  —  GET /v2/action-items
   // Commitments extracted from meetings/emails — what you owe each account.
@@ -740,70 +853,92 @@ export function createServer() {
     }
   );
 
-  // get_gtm_profile removed: the user's GTM lives in their files, mirrored into
-  // the graph as playbooks (get_playbook) plus the learned ICP model. Read
-  // get_playbook for the user's own rules, ICP, and positioning.
-
   // ===========================================================================
-  // TOOLS: get_playbook / sync_playbook  —  the POLICY layer (vs. facts).
-  // Playbooks are versioned rule-docs that GOVERN agent behavior: voice, outreach,
+  // TOOLS: get_foundation / sync_foundation  —  the POLICY layer (vs. facts).
+  // Foundations are versioned rule-docs that GOVERN agent behavior: voice, outreach,
   // icp, positioning. Read the relevant one BEFORE acting; push file edits back so
-  // every agent obeys the same rules. GET/POST /v2/playbooks.
+  // every agent obeys the same rules. GET/POST /v2/foundations.
   // ===========================================================================
-  const getPlaybookSchema = {
+  const getFoundationSchema = {
     kind: z.enum(["voice", "outreach", "icp", "positioning"]).optional()
       .describe("Which policy to read. Omit to list all four."),
   };
-  const getPlaybookHandler = async ({ kind }) => {
-    const r = await get("/v2/playbooks", kind ? { kind } : undefined);
-    const pbs = r.playbooks || [];
+  const getFoundationHandler = async ({ kind }) => {
+    const r = await get("/v2/foundations", kind ? { kind } : undefined);
+    const pbs = r.foundations || [];
     if (!pbs.length) return { content: [{ type: "text", text:
-      "No playbooks set up yet. The user can set them up on the Playbooks page or in their context files." }] };
+      "No foundations set up yet. The user can set them up on the Foundations page or in their context files." }] };
     if (kind) {
       const pb = pbs[0];
       const src = pb.source === "claude_code" ? `mirrors ${pb.file_path}` : "stored in Nous";
       return { content: [{ type: "text", text:
-        `# ${pb.title} — ${pb.kind} playbook (v${pb.version}, ${src})\n\n${pb.body_md}` }] };
+        `# ${pb.title} — ${pb.kind} foundation (v${pb.version}, ${src})\n\n${pb.body_md}` }] };
     }
     const lines = pbs.map(p => `  ${p.kind.padEnd(12)} ${p.title}  (${p.source === "claude_code" ? p.file_path : "stored in Nous"})`);
     return { content: [{ type: "text", text:
-      "The user's playbooks (read one with get_playbook(kind)):\n" + lines.join("\n") }] };
+      "The user's foundations (read one with get_foundation(kind)):\n" + lines.join("\n") }] };
   };
-  server.tool("get_playbook",
-    "Read a PLAYBOOK — the user's policy/rules for a kind of action: voice, outreach, icp, or positioning. " +
-    "These are RULES TO OBEY, not facts. Read the relevant playbook BEFORE you act: before writing outreach " +
+  server.tool("get_foundation",
+    "Read a FOUNDATION — the user's policy/rules for a kind of action: voice, outreach, icp, or positioning. " +
+    "These are RULES TO OBEY, not facts. Read the relevant foundation BEFORE you act: before writing outreach " +
     "read 'voice' and 'outreach'; before scoring or qualifying read 'icp'; for messaging read 'positioning'. " +
     "Omit kind to list all four.",
-    getPlaybookSchema, getPlaybookHandler);
+    getFoundationSchema, getFoundationHandler);
 
-  const syncPlaybookSchema = {
-    kind: z.enum(["voice", "outreach", "icp", "positioning"]).describe("Which playbook to update."),
-    body_md: z.string().describe("The full markdown content of the playbook. Follow the Nous document house style so every playbook reads like a clean text file: a '# Title' line, a '> ' one-paragraph lede, an optional plain 'Key: value' block, a '---' divider, then '## Title-case' sections with plain '- ' bullets. Keep it markdown, no decorative formatting."),
+  const syncFoundationSchema = {
+    kind: z.enum(["voice", "outreach", "icp", "positioning"]).describe("Which foundation to update."),
+    body_md: z.string().describe("The full markdown content of the foundation. Follow the Nous document house style so every foundation reads like a clean text file: a '# Title' line, a '> ' one-paragraph lede, an optional plain 'Key: value' block, a '---' divider, then '## Title-case' sections with plain '- ' bullets. Keep it markdown, no decorative formatting."),
     file_path: z.string().optional().describe("The repo file this mirrors, e.g. 'context/icp/icp.md'. Pass it when syncing a Claude Code file so the source is recorded as the file."),
   };
-  const syncPlaybookHandler = async ({ kind, body_md, file_path }) => {
-    const r = await post(`/v2/playbooks/${kind}`, { body_md, file_path });
+  const syncFoundationHandler = async ({ kind, body_md, file_path }) => {
+    const r = await post(`/v2/foundations/${kind}`, { body_md, file_path });
     return { content: [{ type: "text", text:
-      `Synced the ${r.playbook?.kind || kind} playbook into Nous (v${r.playbook?.version}). Other agents now read the same rules.` }] };
+      `Synced the ${r.foundation?.kind || kind} foundation into Nous (v${r.foundation?.version}). Other agents now read the same rules.` }] };
   };
-  server.tool("sync_playbook",
-    "Push a playbook's content into Nous so the graph stays current. You MUST call this in the SAME turn " +
+  server.tool("sync_foundation",
+    "Push a foundation's content into Nous so the graph stays current. You MUST call this in the SAME turn " +
     "whenever you edit a policy file in the repo (e.g. references/voice.md, outreach rules), passing the " +
     "file's new content and its path, so Nous mirrors it and every other agent obeys the same rules. An " +
-    "edited playbook file that isn't synced is silently inert — other agents keep reading the old rules. " +
-    "MIRROR, DO NOT REWRITE: when the user already has a playbook file, sync it AS-IS. Their file is the " +
+    "edited foundation file that isn't synced is silently inert — other agents keep reading the old rules. " +
+    "MIRROR, DO NOT REWRITE: when the user already has a foundation file, sync it AS-IS. Their file is the " +
     "author and Nous is the mirror — always pass file_path so the next sync knows where an in-app edit " +
     "lands. 'Improving' their wording on the way through means the copy in Nous silently disagrees with " +
     "the copy in their repo, and they will trust neither. If a file looks wrong, SAY SO; don't fix it in " +
     "transit. " +
     "(For the ICP/context files specifically, sync_icp is the sync — use that one.)",
-    syncPlaybookSchema, syncPlaybookHandler);
+    syncFoundationSchema, syncFoundationHandler);
 
-  // The GTM context is no longer written through a dedicated MCP tool. In the file
-  // symbiosis model the user's own files (context/icp.md, positioning.md, …) are
-  // the source of truth: the agent edits those with its own file tools and calls
-  // `sync_icp` to sync them into the graph (and `export_icp_model` to write the learned
-  // model back). The shared POST /v2/workspace/facts route still backs that import.
+  // ===========================================================================
+  // TOOL: get_insights  —  what Nous LEARNED about us from calls (the mirror of
+  // foundations). Insights are auto-extracted from call transcripts into four docs:
+  // product, positioning, market, buyer. READ-ONLY over MCP — the extractor
+  // authors them, not agents. GET /v2/insights[?category=].
+  // ===========================================================================
+  const getInsightsSchema = {
+    category: z.enum(["product", "positioning", "market", "buyer"]).optional()
+      .describe("Which insight doc to read. Omit to list all four."),
+  };
+  const getInsightsHandler = async ({ category }) => {
+    const r = await get("/v2/insights", category ? { category } : undefined);
+    const docs = r.insights || [];
+    if (!docs.length) return { content: [{ type: "text", text:
+      "No insights captured yet. They fill automatically from call transcripts (product, positioning, market, buyer)." }] };
+    if (category) {
+      const d = docs[0];
+      return { content: [{ type: "text", text:
+        `# ${d.title} insights (v${d.version})\n\n${d.body_md || "(empty)"}` }] };
+    }
+    const lines = docs.map(d => `  ${d.category.padEnd(12)} ${d.title}  (v${d.version})`);
+    return { content: [{ type: "text", text:
+      "What Nous learned about us from calls (read one with get_insights(category)):\n" + lines.join("\n") }] };
+  };
+  server.tool("get_insights",
+    "Read INSIGHTS — what Nous learned about US from call transcripts, the mirror of the foundations/foundations " +
+    "the user authors. Four docs: product (what to build), positioning (how to message), market (segments, " +
+    "wedges, channels), buyer (ICP, the pain that drives the purchase). These accumulate automatically after " +
+    "every call. Read them when working on product direction, messaging, GTM strategy, or targeting. Omit " +
+    "category to list all four.",
+    getInsightsSchema, getInsightsHandler);
 
   // ===========================================================================
   // TOOL: save_note  —  POST /v2/notes
@@ -838,6 +973,36 @@ export function createServer() {
     },
   );
 
+  // ===========================================================================
+  // TOOL: propose_vault_file  —  POST /v2/personal/propose
+  // Propose a markdown file into the member's PERSONAL vault. It lands in their
+  // inbox as a proposal — the member approves it before it is filed into a folder
+  // or synced to their Git. This is how an agent contributes to a member's own
+  // notes (thoughts, decisions, briefs, content) without writing anything without
+  // consent. Distinct from `save_note` (which attaches a document to a CONTACT's
+  // record) — this is the member's private vault, not an account.
+  // ===========================================================================
+  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).",
+    {
+      folder: z.enum(["inbox", "thoughts", "decisions", "projects", "briefs", "content", "company"])
+        .describe("Where it files once approved. ROUTING: briefs = a one-off account or meeting brief, filed FLAT (no subfolder). projects = ongoing recurring analysis by area (with a subfolder): pipeline/funnel review -> projects, subfolder 'pipeline'; campaign analysis -> projects, subfolder 'campaigns'; an initiative -> projects, subfolder = its name. content = anything to publish/send (post, newsletter, outbound copy, market/research write-up). decisions = a decision. thoughts = a loose idea. company = the company's own context. 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."),
+    },
+    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.` }] };
+    },
+  );
+
   // ===========================================================================
   // TOOL: search_notes  —  POST /v2/notes/search
   // Semantic search over saved notes & documents (briefs, transcripts, notes).
@@ -878,7 +1043,7 @@ export function createServer() {
   // ===========================================================================
   // TOOL: get_workspace_status  —  GET /v2/workspace/status
   // The "one main call." Nous is operated by the agent, so the agent needs to
-  // know the state of the workspace: is it onboarded, is the GTM playbook built,
+  // know the state of the workspace: is it onboarded, is the GTM foundation built,
   // which integrations are connected, is CRM sync configured, are events live —
   // and what to set up next. Call this at the start of a session.
   // ===========================================================================
@@ -926,7 +1091,7 @@ export function createServer() {
           : " — MISSING. The workspace is not set up until this exists. Scan their repo before you ask them anything."}`
       );
       lines.push(`  ${mark(setup.onboarding?.done)} Profile${setup.onboarding?.done ? "" : ` — missing ${(setup.onboarding?.missing ?? []).join(", ") || "details"}`}`);
-      lines.push(`  ${mark(setup.gtm_playbook?.done)} GTM playbook${setup.gtm_playbook?.model ? " (scoring model live)" : ""}${setup.gtm_playbook?.stale_facts ? ` · ${setup.gtm_playbook.stale_facts} stale fact(s)` : ""}`);
+      lines.push(`  ${mark(setup.gtm_playbook?.done)} GTM foundation${setup.gtm_playbook?.model ? " (scoring model live)" : ""}${setup.gtm_playbook?.stale_facts ? ` · ${setup.gtm_playbook.stale_facts} stale fact(s)` : ""}`);
       if (setup.icp_sync) {
         const sy = setup.icp_sync;
         lines.push(`  ⟳ ICP synced from ${sy.synced_from} (${relAge(sy.synced_at)})${sy.model_changed ? " · model has CHANGED since — run export_icp_model to refresh the file" : ""}`);
@@ -1016,15 +1181,15 @@ export function createServer() {
 
   // ===========================================================================
   // TOOL: build_icp_model  —  POST /v2/workspace/scoring-model
-  // The second half of building the GTM playbook. The agent syncs the GTM context
+  // The second half of building the GTM foundation. The agent syncs the GTM context
   // from the user's files with sync_icp, then calls this to turn it into a weighted
   // ICP scoring model. After this, accounts get scored for fit and
-  // get_workspace_status shows the playbook as done.
+  // get_workspace_status shows the foundation as done.
   // ===========================================================================
   server.tool(
     "build_icp_model",
     "Build (or rebuild) the user's ICP scoring model from their synced GTM context. This is " +
-    "the second half of setting up the GTM playbook: first sync the user's ICP/positioning/pricing " +
+    "the second half of setting up the GTM foundation: first sync the user's ICP/positioning/pricing " +
     "files with sync_icp, then call this to translate that context into a weighted set of scoring " +
     "signals so accounts get scored for fit. (sync_icp usually builds the model on first sync, so you " +
     "often won't need this directly.) If a model already exists it is left alone unless you " +
@@ -1072,7 +1237,7 @@ export function createServer() {
     "customer domains and closed-LOST domains; Nous enriches each, links the contacts you already " +
     "have there, and runs contrastive lift (what's true of winners but not losers) to discover the " +
     "signals that actually predict revenue — then re-scores open accounts. This is the strongest way " +
-    "to build the playbook: a model trained on who actually bought beats one inferred from a " +
+    "to build the foundation: a model trained on who actually bought beats one inferred from a " +
     "description. Ask the user for a handful of each (even 3-5 won + 3-5 lost helps). Domains only " +
     "(e.g. 'acme.com'), no scheme.",
     {
@@ -1341,300 +1506,6 @@ export function createServer() {
     }
   );
 
-  // ===========================================================================
-  // TOOL: set_trigger / list_triggers  —  /v2/workspace/triggers
-  // Outbound event triggers (webhooks) — wire the user's stack to fire when the
-  // record changes.
-  // ===========================================================================
-  server.tool(
-    "set_trigger",
-    "Create an outbound event trigger (a webhook) so an external tool is notified when something " +
-    "happens in the workspace — e.g. a new contact, a reply, a meeting booked. Pass the destination " +
-    "URL and which events to fire on. Call list_triggers first to see the available event names.",
-    {
-      url: z.string().describe("The destination URL the event is POSTed to."),
-      events: z.array(z.string()).describe("Event names to fire on (see list_triggers for the catalog)."),
-      name: z.string().optional().describe("Optional label for the trigger."),
-    },
-    async ({ url, events, name }) => {
-      try {
-        const r = await post("/v2/workspace/triggers", { url, events, name });
-        return { content: [{ type: "text", text: `Trigger created for ${events.join(", ")} → ${url}.` }] };
-      } catch (e) {
-        const msg = String(e?.message ?? e);
-        return { content: [{ type: "text", text: `Couldn't create the trigger: ${msg}. Call list_triggers to see valid event names.` }] };
-      }
-    }
-  );
-  server.tool(
-    "list_triggers",
-    "List the workspace's outbound event triggers (webhooks) and the catalog of available event names.",
-    {},
-    async () => {
-      const r = await get("/v2/workspace/triggers");
-      const lines = [];
-      if (r.triggers?.length) {
-        lines.push(`TRIGGERS (${r.triggers.length}):`);
-        for (const t of r.triggers) lines.push(`  ${t.name || "(unnamed)"} → ${t.url}  [${(t.events || []).join(", ")}]`);
-      } else {
-        lines.push("No triggers set up yet.");
-      }
-      if (r.available_events?.length) {
-        lines.push("", `AVAILABLE EVENTS: ${r.available_events.join(", ")}`);
-      }
-      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
-    }
-  );
-
-  // ===========================================================================
-  // TOOL: lead_list_operations  —  GET /api/lead-lists[/:id/operations]
-  // The operations trail for a lead list: imports, enrichment runs, pushes to
-  // campaigns, and replies — filterable by category and time window. This is how
-  // you answer "what happened on this list?" and attribute campaign performance
-  // back to where the leads came from (the list's source). Call with no
-  // lead_list_id to discover the lists and their ids first.
-  // ===========================================================================
-  server.tool(
-    "lead_list_operations",
-    "(Nous Cloud only) Inspect the operations trail of a lead list — imports, enrichment runs, pushes to campaigns, " +
-    "and classified replies — to report on what happened and attribute outcomes to a list's source. " +
-    "Call with NO lead_list_id to list the workspace's lead lists (id, name, count, source), then " +
-    "call again with an id. Filter with `event` (import | enrich | export | reply) and `days`. " +
-    "Each operation is a run-level summary (one row per import/enrich/push), not per-lead noise.",
-    {
-      lead_list_id: z.string().optional().describe("The lead list's UUID. Omit to list the available lead lists first."),
-      event: z.enum(["import", "enrich", "export", "reply"]).optional().describe("Filter to one category of operation."),
-      days: z.number().optional().describe("Look back this many days (default 30). Pass a large number for all-time."),
-      limit: z.number().optional().describe("Max operations to return (default 100, cap 200)."),
-    },
-    async ({ lead_list_id, event, days, limit }) => {
-      // Discovery mode — no list id yet. Return the lists so the agent can pick.
-      if (!lead_list_id) {
-        const r = await get("/api/lead-lists");
-        const lists = r.lead_lists || [];
-        const lines = lists.length
-          ? [`LEAD LISTS (${lists.length}):`,
-             ...lists.map(l => `  ${l.id}  ${l.name}  · ${l.lead_count ?? 0} leads · source: ${l.source || "—"}`),
-             "", "Call lead_list_operations again with one of these ids (and an optional event filter)."]
-          : ["No lead lists yet."];
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      }
-
-      const r = await get(`/api/lead-lists/${encodeURIComponent(lead_list_id)}/operations`, { event, days, limit });
-      const ops = r.operations || [];
-      const lines = [];
-      const summary = Object.entries(r.by_category || {}).map(([k, v]) => `${k} ${v}`).join(" · ");
-      lines.push(`OPERATIONS${event ? ` · ${event}` : ""} (${ops.length})${summary ? ` — ${summary}` : ""}`);
-      if (!ops.length) {
-        lines.push("", "No operations in this window.");
-      } else {
-        for (const o of ops) {
-          const cat = o.metadata?.category || o.event_type;
-          lines.push(`  ${relAge(o.occurred_at).padEnd(8)} ${String(cat).padEnd(8)} ${o.summary}`);
-        }
-      }
-      return { content: [{ type: "text", text: lines.join("\n").trim() }] };
-    }
-  );
-
-  // ===========================================================================
-  // TOOL: get_coverage  —  POST /v2/dedup (exact) | GET /v2/people/coverage (estimate)
-  // "What do I already have?" before spending on a list elsewhere. One tool, two
-  // modes: pass identifiers for an EXACT per-lead net-new/re-enrich/reuse check
-  // (the pre-spend gate), or a title/keyword for a rough attribute ESTIMATE.
-  // (Replaces the former check_leads + lead_coverage tools.)
-  // ===========================================================================
-  server.tool(
-    "get_coverage",
-    "(Nous Cloud only) Check what you ALREADY have before spending on a list elsewhere (Apollo, Sales Navigator, Clay). " +
-    "Two modes:\n" +
-    "  • EXACT — pass candidate identifiers (emails / linkedin_urls / domains, free in any tool's " +
-    "preview). Returns per-lead buckets: net_new (acquire + enrich), needs_enrichment (you OWN these " +
-    "but stale >90d — re-enrich, don't re-buy), reusable (fresh verified email on file — reuse, spend " +
-    "nothing), plus engaged/recent/known/bounced to skip. Each result carries entity_id, email_status, " +
-    "enriched_at, stale.\n" +
-    "  • ESTIMATE — pass a title and/or keyword instead. Returns how many people you already have " +
-    "matching (e.g. title='founder', keyword='agency'), split by freshness: never-enriched, stale >90d, " +
-    "fresh-verified. Rough by design (title precise; keyword matches title/company/department).\n" +
-    "Pass identifiers for the exact pre-spend check, OR title/keyword for the planning estimate — not both.",
-    {
-      emails: z.array(z.string()).optional().describe("EXACT mode — candidate email addresses (up to 50,000)."),
-      linkedin_urls: z.array(z.string()).optional().describe("EXACT mode — candidate LinkedIn profile URLs (up to 50,000)."),
-      domains: z.array(z.string()).optional().describe("EXACT mode — company domains, 'do I already have anyone here?' (up to 50,000)."),
-      title: z.string().optional().describe("ESTIMATE mode — role match, e.g. 'founder', 'VP Sales' (matches job_title)."),
-      keyword: z.string().optional().describe("ESTIMATE mode — extra match across title/company/department, e.g. 'agency'."),
-      stale_days: z.number().optional().describe("ESTIMATE mode — days after which enrichment counts as stale (default 90)."),
-    },
-    async ({ emails, linkedin_urls, domains, title, keyword, stale_days }) => {
-      const hasIds  = !!(emails?.length || linkedin_urls?.length || domains?.length);
-      const hasAttr = !!(title || keyword);
-      if (hasIds && hasAttr) {
-        return { content: [{ type: "text", text:
-          "Pass identifiers (emails/linkedin_urls/domains) for the exact check, OR title/keyword for the estimate — not both." }] };
-      }
-
-      // EXACT mode — per-identifier coverage against /v2/dedup.
-      if (hasIds) {
-        const body = {};
-        if (emails?.length) body.emails = emails;
-        if (linkedin_urls?.length) body.linkedin_urls = linkedin_urls;
-        if (domains?.length) body.domains = domains;
-        const r = await post("/v2/dedup", body);
-        const s = r.summary || {};
-        const lines = [
-          `COVERAGE (${s.total ?? 0} checked)`,
-          `  net_new          ${s.net_new ?? 0}   → acquire + enrich`,
-          `  needs_enrichment ${s.needs_enrichment ?? 0}   → you OWN these but stale (>90d) → re-enrich, don't re-buy`,
-          `  reusable         ${s.reusable ?? 0}   → fresh verified email on file → reuse, spend nothing`,
-          `  engaged          ${s.engaged ?? 0}   → in an active conversation, don't cold-send`,
-          `  recent           ${s.recent ?? 0}   → contacted <30d, defer`,
-          `  known            ${s.known ?? 0}   → company already in the workspace`,
-          `  bounced/unsub    ${(s.bounced ?? 0) + (s.unsubscribed ?? 0) + (s.suppressed ?? 0)}   → skip`,
-        ];
-        // Surface a few stale entities the caller should re-enrich (with their last date).
-        const stale = (r.results || []).filter(x => x.entity_id && x.stale).slice(0, 15);
-        if (stale.length) {
-          lines.push("", "RE-ENRICH (sample):");
-          for (const x of stale) {
-            lines.push(`  ${x.value}  [${x.enriched_at ? `last enriched ${relAge(x.enriched_at)}` : "never enriched"}]  ${x.entity_id}`);
-          }
-        }
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      }
-
-      // ESTIMATE mode — attribute coverage against /v2/people/coverage.
-      if (hasAttr) {
-        const r = await get("/v2/people/coverage", { title, keyword, stale_days });
-        const lines = [
-          `COVERAGE — ${[title && `title~"${title}"`, keyword && `keyword~"${keyword}"`].filter(Boolean).join(" + ")}`,
-          `  ${r.total ?? 0} already in your workspace`,
-          `    ${r.needs_enrichment ?? 0} need (re-)enrichment  (${r.never_enriched ?? 0} never enriched · ${r.stale ?? 0} stale >90d)`,
-          `    ${r.fresh_verified ?? 0} have a fresh verified email`,
-        ];
-        const sample = r.sample || [];
-        if (sample.length) {
-          lines.push("", "SAMPLE (oldest first):");
-          for (const s of sample.slice(0, 12)) {
-            lines.push(`  ${[s.job_title, s.company].filter(Boolean).join(" @ ") || s.entity_id}  [${s.enriched_at ? `enriched ${relAge(s.enriched_at)}` : "never enriched"}]`);
-          }
-        }
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      }
-
-      return { content: [{ type: "text", text:
-        "Pass at least one of: emails / linkedin_urls / domains (exact check), or title / keyword (estimate)." }] };
-    }
-  );
-
-  // ===========================================================================
-  // TOOLS: enrich_leads / verify_leads  —  POST /api/lead-lists/:id/enrich|verify
-  // The agent OPERATES the lead list. Both are two-step: a dry-run preview that
-  // quotes the chargeable count + provider + $ estimate (report it to the user
-  // first), then a confirmed run as a background job. Target by `filter` so no
-  // ids are needed (enrich {emailStatus:'none'} = all missing an email; verify
-  // defaults to all unverified). BYOK — the $ is the user's own provider spend.
-  // ===========================================================================
-  const fmtCost = (c) => {
-    if (!c) return "no chargeable records — nothing to spend";
-    const money = c.low === c.high ? `~$${c.low.toFixed(2)}` : `~$${c.low.toFixed(2)}–$${c.high.toFixed(2)}`;
-    return `${money} via ${c.label} (${(c.count ?? 0).toLocaleString()} ${c.action})`;
-  };
-  const LEAD_FILTER_SHAPE = {
-    emailStatus: z.enum(["has", "none", "unverified"]).optional().describe("none = no email yet; unverified = has an email but no verification verdict; has = has any email."),
-    domain: z.enum(["has", "none"]).optional().describe("has = a company domain is known; none = no domain."),
-    icp: z.enum(["true", "false"]).optional().describe("true = ICP-qualified leads only."),
-    status: z.string().optional().describe("Lifecycle: pending | sent | replied | bounced."),
-    source: z.string().optional().describe("Substring of where the lead came from (campaign / import name)."),
-    size: z.string().optional().describe("Substring of company size, e.g. '1 to 10'."),
-    channel: z.string().optional().describe("Last-contacted channel substring, or 'none' for not-yet-contacted."),
-  };
-
-  server.tool(
-    "enrich_leads",
-    "(Nous Cloud only) Find missing emails for leads in a lead list, on the workspace's own Prospeo/Apollo key. ALWAYS two " +
-    "steps: call WITHOUT confirm for a dry-run cost preview (chargeable count, provider, $ estimate) — " +
-    "report it and get the user's go-ahead — then call again with confirm:true to run as a background job. " +
-    "Pick leads with `filter` (e.g. {emailStatus:'none'} = every lead missing an email, the usual case) or " +
-    "explicit `ids`; defaults to {emailStatus:'none'}. Call lead_list_operations with no id first to get the " +
-    "list's id.",
-    {
-      lead_list_id: z.string().describe("The lead list's UUID."),
-      filter: z.object(LEAD_FILTER_SHAPE).optional().describe("Pick leads by attribute. Omit (with no ids) to default to all leads missing an email."),
-      ids: z.array(z.string()).optional().describe("Explicit lead ids — an alternative to filter."),
-      confirm: z.boolean().optional().describe("Omit or false = dry-run cost preview only (spends nothing). true = actually run it as a background job."),
-    },
-    async ({ lead_list_id, filter, ids, confirm }) => {
-      const sel = (ids && ids.length) ? { ids } : { filter: filter || { emailStatus: "none" } };
-      const path = `/api/lead-lists/${encodeURIComponent(lead_list_id)}/enrich`;
-      try {
-        if (!confirm) {
-          const r = await post(path, { ...sel, preview: true });
-          const lines = [
-            `ENRICH PREVIEW — list ${lead_list_id}`,
-            `  ${r.total ?? 0} selected · ${r.chargeable ?? 0} chargeable · ${r.reused ?? 0} already on file (free) · ${r.no_identifier ?? 0} no identifier`,
-            `  provider: ${r.provider || "—"}`,
-            `  estimated cost: ${fmtCost(r.cost)}`,
-            "",
-            r.chargeable
-              ? "Report this to the user. To run it, call enrich_leads again with the same selection and confirm:true."
-              : "Nothing chargeable to enrich.",
-          ];
-          return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        const r = await post(path, { ...sel, background: true });
-        return { content: [{ type: "text", text:
-          `Enrichment started — job ${r.job_id}, ${r.total} lead${r.total === 1 ? "" : "s"} queued. It runs in the background; report back to the user that it's running.` }] };
-      } catch (e) {
-        return { content: [{ type: "text", text: `Couldn't enrich: ${e.message}` }] };
-      }
-    }
-  );
-
-  server.tool(
-    "verify_leads",
-    "(Nous Cloud only) Validate email deliverability for leads in a lead list, on the workspace's own MillionVerifier / " +
-    "NeverBounce key. ALWAYS two steps: call WITHOUT confirm for a dry-run cost preview (chargeable count, " +
-    "connected verifiers, $ estimate) — report it to the user — then call again with confirm:true to run as " +
-    "a background job. Defaults to every UNVERIFIED email (has an address, no verdict yet); narrow with " +
-    "`filter` or pass `ids`. If no verifier is connected it says so — tell the user to add a MillionVerifier " +
-    "or NeverBounce key in Integrations.",
-    {
-      lead_list_id: z.string().describe("The lead list's UUID."),
-      filter: z.object(LEAD_FILTER_SHAPE).optional().describe("Pick leads by attribute. Omit (with no ids) to default to all unverified emails."),
-      ids: z.array(z.string()).optional().describe("Explicit lead ids — an alternative to filter."),
-      provider: z.enum(["millionverifier", "neverbounce"]).optional().describe("Which verifier to use. Defaults to MillionVerifier, then NeverBounce."),
-      confirm: z.boolean().optional().describe("Omit or false = dry-run cost preview only. true = actually run it as a background job."),
-    },
-    async ({ lead_list_id, filter, ids, provider, confirm }) => {
-      const sel = (ids && ids.length) ? { ids } : { filter: filter || { emailStatus: "unverified" } };
-      const path = `/api/lead-lists/${encodeURIComponent(lead_list_id)}/verify`;
-      try {
-        if (!confirm) {
-          const r = await post(path, { ...sel, provider, preview: true });
-          const lines = [
-            `VERIFY PREVIEW — list ${lead_list_id}`,
-            `  ${r.total ?? 0} selected · ${r.chargeable ?? 0} chargeable · ${r.reused ?? 0} recently verified (free) · ${r.no_email ?? 0} no email`,
-            `  verifier: ${r.provider || "—"}${r.connected_verifiers ? `  (connected: ${r.connected_verifiers.join(", ") || "none"})` : ""}`,
-            `  estimated cost: ${fmtCost(r.cost)}`,
-            "",
-            r.chargeable
-              ? "Report this to the user. To run it, call verify_leads again with the same selection and confirm:true."
-              : "Nothing chargeable to verify.",
-          ];
-          return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        const r = await post(path, { ...sel, provider, background: true });
-        return { content: [{ type: "text", text:
-          `Verification started — job ${r.job_id}, ${r.total} email${r.total === 1 ? "" : "s"} queued via ${r.provider}. It runs in the background; report back to the user.` }] };
-      } catch (e) {
-        const msg = /no_verifier_connected/.test(e.message)
-          ? "No email verifier is connected. Tell the user to add a MillionVerifier or NeverBounce API key in Integrations, then try again."
-          : `Couldn't verify: ${e.message}`;
-        return { content: [{ type: "text", text: msg }] };
-      }
-    }
-  );
-
   // ===========================================================================
   // TOOL: scrape_engagers
   // On-demand LinkedIn engager scrape — mine who commented/reacted on the
@@ -1678,6 +1549,52 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: send_linkedin_message — the ACT layer. An OUTWARD ACTION: it goes out
+  // through Unipile immediately, it is not a draft. The agent should read the
+  // 'voice'/'outreach' foundations first and `record` the touch after. Derives the
+  // workspace from the API key and runs on the workspace's connected LinkedIn
+  // account. POST /api/linkedin/send-message (verifyAuthEither).
+  // ===========================================================================
+  server.tool(
+    "send_linkedin_message",
+    "SEND a LinkedIn direct message for real, right now, from the workspace's connected LinkedIn " +
+    "account. This is an OUTWARD ACTION, not a draft — it reaches the person the moment you call it, so " +
+    "only send a message the user has approved. Address it one of three ways: `linkedin_url` (their " +
+    "profile URL) or `linkedin_member_id` to start a new conversation, or `chat_id` to REPLY inside an " +
+    "existing thread. It returns the thread's `chat_id` — keep it so the next reply stays in the same " +
+    "thread. Best practice: read the 'voice' and 'outreach' foundations first so the message obeys the " +
+    "user's rules, and `record` the touch afterward so the graph stays current. Requires a connected " +
+    "LinkedIn account (Integrations); it says so if none is connected.",
+    {
+      text: z.string().min(1).describe("The message body to send."),
+      linkedin_url: z.string().optional().describe("The recipient's LinkedIn profile URL. Provide this OR linkedin_member_id (to start a new chat), OR chat_id (to reply in an existing thread)."),
+      linkedin_member_id: z.string().optional().describe("The recipient's LinkedIn member id, if you have it instead of a profile URL."),
+      chat_id: z.string().optional().describe("An existing conversation's chat_id — pass it to reply in-thread instead of opening a new chat."),
+    },
+    async ({ text, linkedin_url, linkedin_member_id, chat_id }) => {
+      if (!linkedin_url && !linkedin_member_id && !chat_id) {
+        return { content: [{ type: "text", text:
+          "Tell me who to message: pass linkedin_url or linkedin_member_id to start a new chat, or chat_id to reply in an existing thread." }] };
+      }
+      try {
+        const r = await post("/api/linkedin/send-message", { text, linkedin_url, linkedin_member_id, chat_id });
+        return { content: [{ type: "text", text:
+          `Message sent over LinkedIn.${r.chat_id ? ` Thread chat_id: ${r.chat_id} (reuse it to reply in-thread).` : ""}` }] };
+      } catch (e) {
+        const msg =
+          /linkedin_not_connected/.test(e.message)
+            ? "No LinkedIn account is connected. Tell the user to connect LinkedIn in Integrations first."
+          : /auth_required/.test(e.message)
+            ? "This API key isn't scoped to a workspace, or LinkedIn isn't connected."
+          : /missing_params/.test(e.message)
+            ? "Couldn't tell who to message — provide linkedin_url, linkedin_member_id, or chat_id."
+            : `Couldn't send the message: ${e.message}`;
+        return { content: [{ type: "text", text: msg }] };
+      }
+    }
+  );
+
   // ===========================================================================
   // TOOL: get_routing_preferences
   // The routing preferences that make THIS agent default to Nous for GTM. The