@leadbay/mcp 0.32.4 → 0.32.6

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog — @leadbay/mcp
 
+## 0.32.6 — 2026-09-01
+
+The 401 auto-retry is GET-only — replaying a write could double-execute a
+mutation that already committed — but `mapErrorResponse` wrote its hint as if
+`request()` had always retried. On `leadbay_create_topup_link` (a POST) the
+agent was told the call had already been retried when it had been attempted
+exactly once. Covers acceptance criteria 4 and 5 of product#3998; the 401 itself
+is a backend bug fixed in leadbay/backend#1989.
+
+- The GET-only rule is extracted into `retriesOn401` so the retry path and the
+  error mapper read one source of truth, and the actual outcome is threaded into
+  `mapErrorResponse` rather than assumed.
+- The not-retried hint states only the fact and never the reason. A GET with
+  `retryOn401:false` (the startup auth probe) is not a write, and the earlier
+  text told it that it was. Why the retry didn't run is not actionable for the
+  agent — only that this was attempt one — so the flag stays a boolean.
+- `readOnlyHint: false` on both Stripe tools. Each mints a Stripe session, and
+  for an org with no customer yet the shared `getStripeCustomer` path creates
+  the customer and persists `organizations.stripe_customer_id`.
+- The two Stripe tools stay in `granularReadTools`. `readOnlyHint` (a client
+  confirmation hint) and `includeWrite` (a capability gate over the user's
+  Leadbay data) are different axes, and this repo already treats them that way
+  — `leadbay_preview_bulk_enrichment` sits in `granularWriteTools` with
+  `readOnlyHint: true`. Moving them would leave a `--no-write` user who hits
+  quota with no top-up link at all, which is the exact failure product#3998 was
+  filed for.
+
+## 0.32.5 — 2026-09-01
+
+`leadbay_update_contact` returned `NOT_FOUND` / 404 on 100% of the calls ever
+made to it (product#3997). Not a missing route and not a backend bug.
+
+Leadbay holds contacts in two id namespaces — `org_contacts` (the org's own
+directory) and `paid_contacts` (enrichment results) — with separate models,
+separate DAOs and separate ids. `POST /contacts/{id}/update` resolves
+`orgContacts.findById` only, so a paid id can only ever 404.
+
+`research_lead_by_id` merges `/leads/{id}/enrich/contacts` and
+`/leads/{id}/contacts` into `contacts.reachable` / `contacts.candidates`, split
+by **whether the person is messagable right now, not by which endpoint they came
+from**. That split is right for outreach and wrong for identity: an enriched
+paid contact sits in the same list as an org contact, and the agent had nothing
+to distinguish them by. Roughly half the ids we handed out were unusable by a
+tool the server instructions tell the agent to call after every outreach.
+
+- The `source` field (`"org"` / `"paid"`) was already on the wire but undeclared
+  and unexplained. It is now documented in `research_lead_by_id`'s output schema
+  as the thing that decides whether an id can be passed to
+  `leadbay_update_contact`.
+- `leadbay_update_contact`'s description states which namespace it accepts,
+  what a 404 means, and routes a correction to a paid contact through
+  `leadbay_add_contact` instead — the enrichment row is a provider's answer and
+  is not ours to edit.
+- New: `research-contact-source-provenance.test.ts`, covering the case the
+  reachability split hides — an enriched paid contact and an org contact in the
+  SAME `reachable` list, distinguished only by `source`.
 ## 0.32.4 — 2026-09-01
 
 `leadbay_account_status.notifications` was permanently `[]` on the hosted server
@@ -27,7 +83,6 @@ answer, and the ledger is not called.
   responses.** Reviving it would mean a `GET /notifications` per tool call to
   decorate every response. The cost lands on the check-in entry point only,
   which is where the daily-rhythm channel is actually read.
-
 ## 0.32.0 — 2026-09-01
 
 A poll-budget timeout stops being an error (product#4007). The import wizard's

package/dist/bin.js

@@ -213,12 +213,13 @@ function parseRetryAfter(value) {
   }
   return null;
 }
-var LENS_CACHE_TTL_MS, TASTE_CACHE_TTL_MS, ME_CACHE_TTL_MS, MAX_CONCURRENT, DEFAULT_REQUEST_TIMEOUT_MS, requestSignalStore, REGIONS, API_VERSION, API_PREFIX, _mockFixtures, _mockJournal, LeadbayClient;
+var LENS_CACHE_TTL_MS, TASTE_CACHE_TTL_MS, retriesOn401, ME_CACHE_TTL_MS, MAX_CONCURRENT, DEFAULT_REQUEST_TIMEOUT_MS, requestSignalStore, REGIONS, API_VERSION, API_PREFIX, _mockFixtures, _mockJournal, LeadbayClient;
 var init_client = __esm({
   "../core/dist/client.js"() {
     "use strict";
     LENS_CACHE_TTL_MS = 5 * 60 * 1e3;
     TASTE_CACHE_TTL_MS = 10 * 60 * 1e3;
+    retriesOn401 = (method) => method.toUpperCase() === "GET";
     ME_CACHE_TTL_MS = 60 * 1e3;
     MAX_CONCURRENT = 5;
     DEFAULT_REQUEST_TIMEOUT_MS = 6e5;
@@ -396,15 +397,16 @@ var init_client = __esm({
       // error envelope says so.
       //
       // Arrow-function field so `this` stays bound even when the method is passed
-      // as a bare reference (see request()'s ternary). Retries are GET-ONLY: a 401
-      // on a write (POST/PUT/DELETE) may arrive AFTER the mutation already committed
-      // server-side, so blindly re-sending it would double-execute the write. Reads
-      // are idempotent, so retrying them is safe. The 250ms backoff releases the
-      // concurrency slot first (release → sleep → re-acquire) so a wave of 401s
-      // doesn't pin all MAX_CONCURRENT slots in setTimeout and stall the queue.
+      // as a bare reference (see request()'s ternary). Retries are GET-ONLY (see
+      // retriesOn401): a 401 on a write (POST/PUT/DELETE) may arrive AFTER the
+      // mutation already committed server-side, so blindly re-sending it would
+      // double-execute the write. Reads are idempotent, so retrying them is safe.
+      // The 250ms backoff releases the concurrency slot first (release → sleep →
+      // re-acquire) so a wave of 401s doesn't pin all MAX_CONCURRENT slots in
+      // setTimeout and stall the queue.
       httpsRequestWithRetry = async (method, url, headers, body, timeoutMs) => {
         const res = await httpsRequest(method, url, headers, body, timeoutMs);
-        if (res.status === 401 && method.toUpperCase() === "GET") {
+        if (res.status === 401 && retriesOn401(method)) {
           this.releaseSemaphore();
           try {
             await new Promise((r) => setTimeout(r, 250));
@@ -423,6 +425,7 @@ var init_client = __esm({
           throw this.makeError("NOT_AUTHENTICATED", "Not logged in to Leadbay", "Set LEADBAY_TOKEN in your MCP client config, or run: npx -y -p @leadbay/mcp@latest installer", path);
         }
         const retryOn401 = opts?.retryOn401 !== false;
+        const retriedOn401 = retryOn401 && retriesOn401(method);
         await this.acquireSemaphore();
         try {
           const url = `${this._baseUrl}${API_PREFIX}${path}`;
@@ -443,7 +446,7 @@ var init_client = __esm({
             return null;
           }
           if (res.status < 200 || res.status >= 300) {
-            throw this.mapErrorResponse(res.status, res.body, path, res.headers);
+            throw this.mapErrorResponse(res.status, res.body, path, res.headers, retriedOn401);
           }
           return JSON.parse(res.body);
         } catch (e) {
@@ -453,6 +456,7 @@ var init_client = __esm({
         }
       }
       async requestVoid(method, path, body) {
+        const retriedOn401 = retriesOn401(method);
         if (process.env.LEADBAY_MOCK === "1") {
           await this.mockRequest(method, path, body);
           return;
@@ -477,7 +481,7 @@ var init_client = __esm({
             retry_after: parseRetryAfter(res.headers["retry-after"])
           };
           if (res.status < 200 || res.status >= 300) {
-            throw this.mapErrorResponse(res.status, res.body, path, res.headers);
+            throw this.mapErrorResponse(res.status, res.body, path, res.headers, retriedOn401);
           }
         } catch (e) {
           throw this.mapTransportError(e, `${method} ${path}`);
@@ -491,6 +495,7 @@ var init_client = __esm({
       // mirror request() exactly. Used by leadbay_import_leads to upload CSVs to
       // the wizard at POST /1.6/imports.
       async requestRawBinary(method, path, contentType, body) {
+        const retriedOn401 = retriesOn401(method);
         if (process.env.LEADBAY_MOCK === "1") {
           return this.mockRequestBinary(method, path, contentType, body);
         }
@@ -515,7 +520,7 @@ var init_client = __esm({
             return null;
           }
           if (res.status < 200 || res.status >= 300) {
-            throw this.mapErrorResponse(res.status, res.body, path, res.headers);
+            throw this.mapErrorResponse(res.status, res.body, path, res.headers, retriedOn401);
           }
           return JSON.parse(res.body);
         } catch (e) {
@@ -603,7 +608,7 @@ var init_client = __esm({
         }
         return envelope;
       }
-      mapErrorResponse(status, rawBody, endpoint, headers) {
+      mapErrorResponse(status, rawBody, endpoint, headers, retried) {
         let parsed;
         try {
           parsed = JSON.parse(rawBody);
@@ -612,7 +617,7 @@ var init_client = __esm({
         }
         const retryAfter = parseRetryAfter(headers["retry-after"]);
         if (status === 401) {
-          return this.makeError("AUTH_EXPIRED", "Leadbay rejected this request (401)", "Leadbay tokens don't expire on a timer, so this isn't a stale token. A 401 here is usually a Leadbay-side hiccup, but can also mean the user logged out. Try again shortly; if it persists, offer to report it to the team.", endpoint, null, status);
+          return this.makeError("AUTH_EXPIRED", "Leadbay rejected this request (401)", retried ? "Tokens don't expire on a timer, so this isn't stale. Already auto-retried once and it 401'd again \u2014 usually a Leadbay-side hiccup, but can also mean the user logged out. Try again shortly, else report it." : "Tokens don't expire on a timer, so this isn't stale. This call wasn't auto-retried, so it's the first attempt \u2014 a Leadbay-side hiccup, or the user logged out. Try again once, else report it.", endpoint, null, status);
         }
         if (status === 429 || status === 402 || parsed?.error === "quota_exceeded" || parsed?.error?.code === "quota_exceeded") {
           const hintBase = retryAfter ? `Wait ${retryAfter}s before retrying` : "Wait, then retry";
@@ -715,7 +720,7 @@ var init_client = __esm({
         try {
           const res = await this.httpsRequestWithRetry("GET", `${this._baseUrl}${API_PREFIX}/users/me`, { Authorization: `Bearer ${this.token}` }, void 0, opts?.timeoutMs);
           if (res.status < 200 || res.status >= 300) {
-            throw this.mapErrorResponse(res.status, res.body, "/users/me", res.headers);
+            throw this.mapErrorResponse(res.status, res.body, "/users/me", res.headers, retriesOn401("GET"));
           }
           const me = JSON.parse(res.body);
           const observed = me.telemetry_enabled;
@@ -10289,9 +10294,9 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 **Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
 
-Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`.
+Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on an EXISTING contact \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -10311,7 +10316,18 @@ One-line confirmation naming the contact and what changed. No table.
 
 Edit an existing contact in place \u2014 change their \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\`, or name.
 
-Pass the contact's **own** \`contact_id\` (the \`id\` field from \`leadbay_research_lead_by_id\` or a contacts list) \u2014 **not** the parent lead id.
+Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
+
+**Only your organization's own directory contacts can be edited.** Leadbay holds contacts in two separate id namespaces and this endpoint resolves one of them:
+
+| \`source\` on the contact | What it is | Editable here |
+|---|---|---|
+| \`"org"\` | A row in your organization's contact directory \u2014 added by you or your team, or promoted from an import | **yes** |
+| \`"paid"\` | An enrichment result bought from a data provider | **no** \u2014 returns \`NOT_FOUND\` / 404 |
+
+\`leadbay_research_lead_by_id\` returns both, merged into \`contacts.reachable\` / \`contacts.candidates\` and split by whether the person is messagable right now \u2014 **not** by which namespace they came from. So read \`source\` on the contact before calling this. If it is \`"paid"\` and the user wants different details on record, add the corrected person with \`leadbay_add_contact\` instead; the enrichment row is a provider's answer and is not ours to edit.
+
+A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
 **\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
 
@@ -14650,8 +14666,10 @@ var init_create_topup_link = __esm({
     createTopupLink = {
       name: "leadbay_create_topup_link",
       annotations: {
+        // Not read-only: this POSTs a new Stripe Checkout Session into existence.
+        // Clients read readOnlyHint to decide whether to ask the user to confirm.
         title: "Generate Stripe checkout URL for AI-credits top-up",
-        readOnlyHint: true,
+        readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: true
@@ -14684,8 +14702,12 @@ var init_open_billing_portal = __esm({
     openBillingPortal = {
       name: "leadbay_open_billing_portal",
       annotations: {
+        // Not read-only, despite being a GET: the backend mints a Stripe portal
+        // session, and for an org with no customer yet it also creates the Stripe
+        // customer and persists organizations.stripe_customer_id. Same
+        // getStripeCustomer path as leadbay_create_topup_link.
         title: "Generate Stripe customer-portal URL for subscription management",
-        readOnlyHint: true,
+        readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
         openWorldHint: true
@@ -19141,7 +19163,7 @@ var init_research_lead_by_id = __esm({
           },
           contacts: {
             type: "object",
-            description: "Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend's paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable.",
+            description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact \u2014 a `"paid"` id returns NOT_FOUND there.',
             properties: {
               reachable: { type: "array", items: { type: "object" } },
               candidates: { type: "array", items: { type: "object" } }
@@ -32961,7 +32983,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.32.4";
+var VERSION = "0.32.6";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -2797,6 +2797,7 @@ import { readdirSync, readFileSync, existsSync } from "fs";
 import { join } from "path";
 var LENS_CACHE_TTL_MS = 5 * 60 * 1e3;
 var TASTE_CACHE_TTL_MS = 10 * 60 * 1e3;
+var retriesOn401 = (method) => method.toUpperCase() === "GET";
 var ME_CACHE_TTL_MS = 60 * 1e3;
 var MAX_CONCURRENT = 5;
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e5;
@@ -3154,15 +3155,16 @@ var LeadbayClient = class _LeadbayClient {
   // error envelope says so.
   //
   // Arrow-function field so `this` stays bound even when the method is passed
-  // as a bare reference (see request()'s ternary). Retries are GET-ONLY: a 401
-  // on a write (POST/PUT/DELETE) may arrive AFTER the mutation already committed
-  // server-side, so blindly re-sending it would double-execute the write. Reads
-  // are idempotent, so retrying them is safe. The 250ms backoff releases the
-  // concurrency slot first (release → sleep → re-acquire) so a wave of 401s
-  // doesn't pin all MAX_CONCURRENT slots in setTimeout and stall the queue.
+  // as a bare reference (see request()'s ternary). Retries are GET-ONLY (see
+  // retriesOn401): a 401 on a write (POST/PUT/DELETE) may arrive AFTER the
+  // mutation already committed server-side, so blindly re-sending it would
+  // double-execute the write. Reads are idempotent, so retrying them is safe.
+  // The 250ms backoff releases the concurrency slot first (release → sleep →
+  // re-acquire) so a wave of 401s doesn't pin all MAX_CONCURRENT slots in
+  // setTimeout and stall the queue.
   httpsRequestWithRetry = async (method, url, headers, body, timeoutMs) => {
     const res = await httpsRequest(method, url, headers, body, timeoutMs);
-    if (res.status === 401 && method.toUpperCase() === "GET") {
+    if (res.status === 401 && retriesOn401(method)) {
       this.releaseSemaphore();
       try {
         await new Promise((r) => setTimeout(r, 250));
@@ -3181,6 +3183,7 @@ var LeadbayClient = class _LeadbayClient {
       throw this.makeError("NOT_AUTHENTICATED", "Not logged in to Leadbay", "Set LEADBAY_TOKEN in your MCP client config, or run: npx -y -p @leadbay/mcp@latest installer", path);
     }
     const retryOn401 = opts?.retryOn401 !== false;
+    const retriedOn401 = retryOn401 && retriesOn401(method);
     await this.acquireSemaphore();
     try {
       const url = `${this._baseUrl}${API_PREFIX}${path}`;
@@ -3201,7 +3204,7 @@ var LeadbayClient = class _LeadbayClient {
         return null;
       }
       if (res.status < 200 || res.status >= 300) {
-        throw this.mapErrorResponse(res.status, res.body, path, res.headers);
+        throw this.mapErrorResponse(res.status, res.body, path, res.headers, retriedOn401);
       }
       return JSON.parse(res.body);
     } catch (e) {
@@ -3211,6 +3214,7 @@ var LeadbayClient = class _LeadbayClient {
     }
   }
   async requestVoid(method, path, body) {
+    const retriedOn401 = retriesOn401(method);
     if (process.env.LEADBAY_MOCK === "1") {
       await this.mockRequest(method, path, body);
       return;
@@ -3235,7 +3239,7 @@ var LeadbayClient = class _LeadbayClient {
         retry_after: parseRetryAfter(res.headers["retry-after"])
       };
       if (res.status < 200 || res.status >= 300) {
-        throw this.mapErrorResponse(res.status, res.body, path, res.headers);
+        throw this.mapErrorResponse(res.status, res.body, path, res.headers, retriedOn401);
       }
     } catch (e) {
       throw this.mapTransportError(e, `${method} ${path}`);
@@ -3249,6 +3253,7 @@ var LeadbayClient = class _LeadbayClient {
   // mirror request() exactly. Used by leadbay_import_leads to upload CSVs to
   // the wizard at POST /1.6/imports.
   async requestRawBinary(method, path, contentType, body) {
+    const retriedOn401 = retriesOn401(method);
     if (process.env.LEADBAY_MOCK === "1") {
       return this.mockRequestBinary(method, path, contentType, body);
     }
@@ -3273,7 +3278,7 @@ var LeadbayClient = class _LeadbayClient {
         return null;
       }
       if (res.status < 200 || res.status >= 300) {
-        throw this.mapErrorResponse(res.status, res.body, path, res.headers);
+        throw this.mapErrorResponse(res.status, res.body, path, res.headers, retriedOn401);
       }
       return JSON.parse(res.body);
     } catch (e) {
@@ -3361,7 +3366,7 @@ var LeadbayClient = class _LeadbayClient {
     }
     return envelope;
   }
-  mapErrorResponse(status, rawBody, endpoint, headers) {
+  mapErrorResponse(status, rawBody, endpoint, headers, retried) {
     let parsed;
     try {
       parsed = JSON.parse(rawBody);
@@ -3370,7 +3375,7 @@ var LeadbayClient = class _LeadbayClient {
     }
     const retryAfter = parseRetryAfter(headers["retry-after"]);
     if (status === 401) {
-      return this.makeError("AUTH_EXPIRED", "Leadbay rejected this request (401)", "Leadbay tokens don't expire on a timer, so this isn't a stale token. A 401 here is usually a Leadbay-side hiccup, but can also mean the user logged out. Try again shortly; if it persists, offer to report it to the team.", endpoint, null, status);
+      return this.makeError("AUTH_EXPIRED", "Leadbay rejected this request (401)", retried ? "Tokens don't expire on a timer, so this isn't stale. Already auto-retried once and it 401'd again \u2014 usually a Leadbay-side hiccup, but can also mean the user logged out. Try again shortly, else report it." : "Tokens don't expire on a timer, so this isn't stale. This call wasn't auto-retried, so it's the first attempt \u2014 a Leadbay-side hiccup, or the user logged out. Try again once, else report it.", endpoint, null, status);
     }
     if (status === 429 || status === 402 || parsed?.error === "quota_exceeded" || parsed?.error?.code === "quota_exceeded") {
       const hintBase = retryAfter ? `Wait ${retryAfter}s before retrying` : "Wait, then retry";
@@ -3473,7 +3478,7 @@ var LeadbayClient = class _LeadbayClient {
     try {
       const res = await this.httpsRequestWithRetry("GET", `${this._baseUrl}${API_PREFIX}/users/me`, { Authorization: `Bearer ${this.token}` }, void 0, opts?.timeoutMs);
       if (res.status < 200 || res.status >= 300) {
-        throw this.mapErrorResponse(res.status, res.body, "/users/me", res.headers);
+        throw this.mapErrorResponse(res.status, res.body, "/users/me", res.headers, retriesOn401("GET"));
       }
       const me = JSON.parse(res.body);
       const observed = me.telemetry_enabled;
@@ -12682,9 +12687,9 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 **Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
 
-Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`.
+Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on an EXISTING contact \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -12704,7 +12709,18 @@ One-line confirmation naming the contact and what changed. No table.
 
 Edit an existing contact in place \u2014 change their \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\`, or name.
 
-Pass the contact's **own** \`contact_id\` (the \`id\` field from \`leadbay_research_lead_by_id\` or a contacts list) \u2014 **not** the parent lead id.
+Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
+
+**Only your organization's own directory contacts can be edited.** Leadbay holds contacts in two separate id namespaces and this endpoint resolves one of them:
+
+| \`source\` on the contact | What it is | Editable here |
+|---|---|---|
+| \`"org"\` | A row in your organization's contact directory \u2014 added by you or your team, or promoted from an import | **yes** |
+| \`"paid"\` | An enrichment result bought from a data provider | **no** \u2014 returns \`NOT_FOUND\` / 404 |
+
+\`leadbay_research_lead_by_id\` returns both, merged into \`contacts.reachable\` / \`contacts.candidates\` and split by whether the person is messagable right now \u2014 **not** by which namespace they came from. So read \`source\` on the contact before calling this. If it is \`"paid"\` and the user wants different details on record, add the corrected person with \`leadbay_add_contact\` instead; the enrichment row is a provider's answer and is not ours to edit.
+
+A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
 **\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
 
@@ -16819,8 +16835,10 @@ function coerceCsvValue(v) {
 var createTopupLink = {
   name: "leadbay_create_topup_link",
   annotations: {
+    // Not read-only: this POSTs a new Stripe Checkout Session into existence.
+    // Clients read readOnlyHint to decide whether to ask the user to confirm.
     title: "Generate Stripe checkout URL for AI-credits top-up",
-    readOnlyHint: true,
+    readOnlyHint: false,
     destructiveHint: false,
     idempotentHint: false,
     openWorldHint: true
@@ -16846,8 +16864,12 @@ var createTopupLink = {
 var openBillingPortal = {
   name: "leadbay_open_billing_portal",
   annotations: {
+    // Not read-only, despite being a GET: the backend mints a Stripe portal
+    // session, and for an org with no customer yet it also creates the Stripe
+    // customer and persists organizations.stripe_customer_id. Same
+    // getStripeCustomer path as leadbay_create_topup_link.
     title: "Generate Stripe customer-portal URL for subscription management",
-    readOnlyHint: true,
+    readOnlyHint: false,
     destructiveHint: false,
     idempotentHint: false,
     openWorldHint: true
@@ -20921,7 +20943,7 @@ var researchLeadById = {
       },
       contacts: {
         type: "object",
-        description: "Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend's paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable.",
+        description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact \u2014 a `"paid"` id returns NOT_FOUND there.',
         properties: {
           reachable: { type: "array", items: { type: "object" } },
           candidates: { type: "array", items: { type: "object" } }
@@ -29547,7 +29569,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.32.4" : "0.0.0-dev";
+var VERSION = true ? "0.32.6" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var logger = {

package/dist/installer-electron.js

@@ -1804,7 +1804,7 @@ var init_installer_gui = __esm({
     init_install_dxt();
     init_install_shared();
     init_oauth();
-    VERSION = true ? "0.32.4" : "0.0.0-dev";
+    VERSION = true ? "0.32.6" : "0.0.0-dev";
     MESSAGES = {
       en: {
         installer: {

package/dist/installer-gui.js

@@ -1067,7 +1067,7 @@ async function oauthLogin(opts) {
 }
 
 // installer/installer-gui.ts
-var VERSION = true ? "0.32.4" : "0.0.0-dev";
+var VERSION = true ? "0.32.6" : "0.0.0-dev";
 var MESSAGES = {
   en: {
     installer: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.32.4",
+  "version": "0.32.6",
   "mcpName": "io.github.leadbay/leadbay-mcp",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",