@leadbay/mcp 0.9.1 → 0.10.0

package/dist/bin.js

@@ -8,7 +8,7 @@ import {
   granularReadTools,
   granularWriteTools,
   resolveRegion
-} from "./chunk-ZRTAIXEJ.js";
+} from "./chunk-F3EWCHME.js";
 
 // src/bin.ts
 import { realpathSync } from "fs";
@@ -37,7 +37,7 @@ Run the Leadbay daily check-in for me. Treat this prompt the same way for any eq
 
 # Resilience rules for Leadbay long-running tools
 
-These four rules apply to every Leadbay workflow that calls \`leadbay_pull_leads\`, \`leadbay_bulk_qualify_leads\`, \`leadbay_research_lead\`, \`leadbay_import_and_qualify\`, or \`leadbay_enrich_titles\`. **Treat timeouts and stream-closed errors as transient, not as signals to replan.**
+These four rules apply to every Leadbay workflow that calls \`leadbay_pull_leads\`, \`leadbay_bulk_qualify_leads\`, \`leadbay_research_lead_by_id\`, \`leadbay_import_and_qualify\`, or \`leadbay_enrich_titles\`. **Treat timeouts and stream-closed errors as transient, not as signals to replan.**
 
 ## Rule 1 \u2014 Pin the lens
 
@@ -47,9 +47,9 @@ After your first \`leadbay_pull_leads\` call, capture \`response.lens.id\` into
 
 \`leadbay_bulk_qualify_leads\` and \`leadbay_import_and_qualify\` accept \`wait_for_completion:false\`, which returns \`{status:'running', qualify_id}\` immediately. Then poll \`leadbay_qualify_status\` (or \`leadbay_import_status\`) every ~10s until the job completes. **Use the async pattern by default** \u2014 the blocking default can exceed the MCP client's per-call timeout on large batches and produce a misleading \`"Request timed out"\` even though the server is still working.
 
-## Rule 3 \u2014 Serialize \`leadbay_research_lead\` fan-out
+## Rule 3 \u2014 Serialize \`leadbay_research_lead_by_id\` fan-out
 
-\`leadbay_research_lead\` is composite and reads many sub-resources. Calling it on 10 leads in parallel can saturate the transport and produce \`"Tool permission stream closed"\` errors that look like permission failures but are really backpressure. **Call it sequentially**, or at most 3 in parallel. If one call fails with a stream/timeout error, retry that one call once before moving on; on a second failure, note the lead and continue \u2014 do not abandon the remaining leads.
+\`leadbay_research_lead_by_id\` is composite and reads many sub-resources. Calling it on 10 leads in parallel can saturate the transport and produce \`"Tool permission stream closed"\` errors that look like permission failures but are really backpressure. **Call it sequentially**, or at most 3 in parallel. If one call fails with a stream/timeout error, retry that one call once before moving on; on a second failure, note the lead and continue \u2014 do not abandon the remaining leads.
 
 ## Rule 4 \u2014 Retry, don't replan
 
@@ -122,7 +122,7 @@ If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is nul
 **Column 2 \u2014 Why it fits**
 
 - One sentence, \u2264 20 words.
-- Synthesize from (in priority order, whichever is present) the lead's \`short_description\`, top 2 \`tags[].display_name\`, and the gist of \`qualification_summary.best_response_excerpt\`. The trim payload does NOT carry the longer \`description\` field \u2014 for that, agent must call \`leadbay_research_lead\` or \`leadbay_research_company\`.
+- Synthesize from (in priority order, whichever is present) the lead's \`short_description\`, top 2 \`tags[].display_name\`, and the gist of \`qualification_summary.best_response_excerpt\`. The trim payload does NOT carry the longer \`description\` field \u2014 for that, agent must call \`leadbay_research_lead_by_id\` or \`leadbay_research_lead_by_name_fuzzy\`.
 - Do NOT append \`(boost N)\` \u2014 the \u2756 cap in column 1 already carries that signal.
 - No bullet lists, no line breaks inside the cell.
 
@@ -164,7 +164,7 @@ If the batch returns fewer than 10 qualified leads, top it up: call \`leadbay_bu
 
 # PHASE 4 \u2014 DEEP DIVE (every promising lead)
 
-Call \`leadbay_research_lead\` on **every** lead from your top 10 that the user might realistically prospect today (filter out clearly weak fits if any). Don't pick just one. **Call it sequentially** \u2014 one at a time, or batches of at most 3 in parallel. Do not fire 10 in parallel \u2014 it triggers transport backpressure that surfaces as \`"Tool permission stream closed"\` errors (see Rule 3 above). If a call fails, retry that single lead once; if the retry also fails, note the lead id and continue. Report Phase 4 results even if 1\u20132 leads were unresearchable.
+Call \`leadbay_research_lead_by_id\` on **every** lead from your top 10 that the user might realistically prospect today (filter out clearly weak fits if any). Don't pick just one. **Call it sequentially** \u2014 one at a time, or batches of at most 3 in parallel. Do not fire 10 in parallel \u2014 it triggers transport backpressure that surfaces as \`"Tool permission stream closed"\` errors (see Rule 3 above). If a call fails, retry that single lead once; if the retry also fails, note the lead id and continue. Report Phase 4 results even if 1\u20132 leads were unresearchable.
 
 For each researched lead surface:
 - what makes it promising (1\u20132 sentences citing signals from the research)
@@ -372,7 +372,7 @@ You are working with Leadbay through the \`leadbay_*\` MCP tools. This prompt or
 
 # Resilience rules for Leadbay long-running tools
 
-These four rules apply to every Leadbay workflow that calls \`leadbay_pull_leads\`, \`leadbay_bulk_qualify_leads\`, \`leadbay_research_lead\`, \`leadbay_import_and_qualify\`, or \`leadbay_enrich_titles\`. **Treat timeouts and stream-closed errors as transient, not as signals to replan.**
+These four rules apply to every Leadbay workflow that calls \`leadbay_pull_leads\`, \`leadbay_bulk_qualify_leads\`, \`leadbay_research_lead_by_id\`, \`leadbay_import_and_qualify\`, or \`leadbay_enrich_titles\`. **Treat timeouts and stream-closed errors as transient, not as signals to replan.**
 
 ## Rule 1 \u2014 Pin the lens
 
@@ -382,9 +382,9 @@ After your first \`leadbay_pull_leads\` call, capture \`response.lens.id\` into
 
 \`leadbay_bulk_qualify_leads\` and \`leadbay_import_and_qualify\` accept \`wait_for_completion:false\`, which returns \`{status:'running', qualify_id}\` immediately. Then poll \`leadbay_qualify_status\` (or \`leadbay_import_status\`) every ~10s until the job completes. **Use the async pattern by default** \u2014 the blocking default can exceed the MCP client's per-call timeout on large batches and produce a misleading \`"Request timed out"\` even though the server is still working.
 
-## Rule 3 \u2014 Serialize \`leadbay_research_lead\` fan-out
+## Rule 3 \u2014 Serialize \`leadbay_research_lead_by_id\` fan-out
 
-\`leadbay_research_lead\` is composite and reads many sub-resources. Calling it on 10 leads in parallel can saturate the transport and produce \`"Tool permission stream closed"\` errors that look like permission failures but are really backpressure. **Call it sequentially**, or at most 3 in parallel. If one call fails with a stream/timeout error, retry that one call once before moving on; on a second failure, note the lead and continue \u2014 do not abandon the remaining leads.
+\`leadbay_research_lead_by_id\` is composite and reads many sub-resources. Calling it on 10 leads in parallel can saturate the transport and produce \`"Tool permission stream closed"\` errors that look like permission failures but are really backpressure. **Call it sequentially**, or at most 3 in parallel. If one call fails with a stream/timeout error, retry that one call once before moving on; on a second failure, note the lead and continue \u2014 do not abandon the remaining leads.
 
 ## Rule 4 \u2014 Retry, don't replan
 
@@ -412,8 +412,8 @@ leadbay_pull_leads           leadbay_pull_followups
 leadbay_daily_check_in      leadbay_followup_check_in
         \u2502                            \u2502
         \u2502  optional:                 \u2502  filters by user phrasing:
-        \u2502  research_company /        \u2502  geo, sector, recency,
-        \u2502  research_lead             \u2502  liked / pushback / outcome
+        \u2502  research_lead_by_name_fuzzy /  \u2502  geo, sector, recency,
+        \u2502  research_lead_by_id        \u2502  liked / pushback / outcome
         \u2502  (deepen profile)          \u2502
         \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
                     \u25BC
@@ -579,7 +579,7 @@ If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is nul
 **Column 2 \u2014 Why it fits**
 
 - One sentence, \u2264 20 words.
-- Synthesize from (in priority order, whichever is present) the lead's \`short_description\`, top 2 \`tags[].display_name\`, and the gist of \`qualification_summary.best_response_excerpt\`. The trim payload does NOT carry the longer \`description\` field \u2014 for that, agent must call \`leadbay_research_lead\` or \`leadbay_research_company\`.
+- Synthesize from (in priority order, whichever is present) the lead's \`short_description\`, top 2 \`tags[].display_name\`, and the gist of \`qualification_summary.best_response_excerpt\`. The trim payload does NOT carry the longer \`description\` field \u2014 for that, agent must call \`leadbay_research_lead_by_id\` or \`leadbay_research_lead_by_name_fuzzy\`.
 - Do NOT append \`(boost N)\` \u2014 the \u2756 cap in column 1 already carries that signal.
 - No bullet lists, no line breaks inside the cell.
 
@@ -618,7 +618,7 @@ When the response carries \`social_urls\` (the post-fix multi-platform URL block
 ABOVE the table, add a 1\u20132 sentence "Standouts from this batch" line that calls out the 3 highest-\`ai_agent_lead_score\` rows \u2014 this is supplementary commentary, not a replacement for the table.
 
 # PHASE 4 \u2014 RECOMMEND
-Recommend the single most-promising lead from this batch and offer to research it deeply with \`leadbay_research_lead\`. Do not actually call \`research_lead\` yet \u2014 wait for my go.
+Recommend the single most-promising lead from this batch and offer to research it deeply with \`leadbay_research_lead_by_id\`. Do not actually call \`research_lead_by_id\` yet \u2014 wait for my go.
 `;
 var leadbay_refine_audience = `
 Refine the Leadbay audience prompt to: {{arg:instruction}}
@@ -661,17 +661,17 @@ The response carries either a completed result or an async handle. Render a brie
 
 **When the user's request implied a downstream use** ("import then prep outreach for them"), emit \`Imported leadIds: <up to 5 ids, then '+N more'>\` \u2014 just the ids. Let the next composite render the leads.
 
-Defer the full list of imported leads to \`leadbay_pull_leads\` or \`leadbay_research_lead\` in NEXT STEPS.
+Defer the full list of imported leads to \`leadbay_pull_leads\` or \`leadbay_research_lead_by_id\` in NEXT STEPS.
 
 
 # PHASE 2 \u2014 DEEP DIVE
-When the import resolves, call \`leadbay_research_lead\` on the new leadId. Render the result using the canonical single-record card layout \u2014 detect MODE A (Discovery) since the user asked to "research" a domain rather than to prepare outreach:
+When the import resolves, call \`leadbay_research_lead_by_id\` on the new leadId. Render the result using the canonical single-record card layout \u2014 detect MODE A (Discovery) since the user asked to "research" a domain rather than to prepare outreach:
 
 ## RENDERING \u2014 single-record research card, mode-adaptive
 
 Present as a single-record card, not a table. This tool gets invoked in two distinct user contexts \u2014 detect which and adapt the body density accordingly.
 
-**MODE A \u2014 Discovery.** The user is evaluating whether to pursue this company as a target. Signals: "tell me about", "what do they do", "is this a fit", "research [company]", arrival via a click-through from \`leadbay_pull_leads\`, no prior outreach context in the conversation. Next step is usually qualify, deep-dive via \`leadbay_research_lead\`, or decide whether to start outreach.
+**MODE A \u2014 Discovery.** The user is evaluating whether to pursue this company as a target. Signals: "tell me about", "what do they do", "is this a fit", "research [company]", arrival via a click-through from \`leadbay_pull_leads\`, no prior outreach context in the conversation. Next step is usually qualify, deep-dive via \`leadbay_research_lead_by_id\`, or decide whether to start outreach.
 
 **MODE B \u2014 Contact preparation.** The user is about to call or email someone at this company and needs the talking points. Signals: "I'm calling them", "draft an email", "before my call", "outreach prep", "what should I say", or the conversation has already touched on a specific contact. Next step is usually \`leadbay_prepare_outreach\`.
 
@@ -758,7 +758,7 @@ on "leadbay leads", "best NEW leads", "what's new today", "show me the
 day's batch", "let's prospect". Do NOT trigger on follow-up phrasings
 ("what should I follow up on", "before my trip") \u2014 those go to
 \`leadbay_followup_check_in\`.
-`, "arguments": [], "expected_calls": ["leadbay_account_status", "leadbay_pull_leads", "leadbay_research_lead", "leadbay_bulk_qualify_leads", "leadbay_enrich_contacts"], "failure_modes": ["Calls leadbay_report_outreach without explicit user authorization", "Surfaces fewer than 10 leads when more are available, or fails to top up via leadbay_qualify_top_n when the batch is short", `Replaces the canonical pull_leads table layout with prose per row (the per-tool RENDERING block is the structural contract; "Today's nudges" goes above it, not in place of it)`, "Skips the nudge paragraph entirely \u2014 the table alone is fine but adding the nudge is the value-add", "Skips deep research on promising leads (Phase 4) \u2014 the agent must call leadbay_research_lead on each, not just one", "Triggers contact enrichment without asking the user first (it consumes quota)", "Skips the STOP byproduct and proposes next actions on its own", 'Fires 10 parallel leadbay_research_lead calls and treats "stream closed" errors as terminal \u2014 must serialize and retry singletons', "Re-pulls leadbay_pull_leads without passing the captured lensId, allowing a backend lens shift to discard the Phase 2 batch", 'Treats a "Request timed out" from leadbay_bulk_qualify_leads as terminal instead of retrying with wait_for_completion:false + qualify_status polling', 'Triggers on a follow-up query (e.g., "leads I should follow up with") that should have routed to `leadbay_followup_check_in` \u2014 the two entry points are different data sources (Discover wishlist vs Monitor view) per \xA71.6'] },
+`, "arguments": [], "expected_calls": ["leadbay_account_status", "leadbay_pull_leads", "leadbay_research_lead_by_id", "leadbay_bulk_qualify_leads", "leadbay_enrich_contacts"], "failure_modes": ["Calls leadbay_report_outreach without explicit user authorization", "Surfaces fewer than 10 leads when more are available, or fails to top up via leadbay_qualify_top_n when the batch is short", `Replaces the canonical pull_leads table layout with prose per row (the per-tool RENDERING block is the structural contract; "Today's nudges" goes above it, not in place of it)`, "Skips the nudge paragraph entirely \u2014 the table alone is fine but adding the nudge is the value-add", "Skips deep research on promising leads (Phase 4) \u2014 the agent must call leadbay_research_lead_by_id on each, not just one", "Triggers contact enrichment without asking the user first (it consumes quota)", "Skips the STOP byproduct and proposes next actions on its own", 'Fires 10 parallel leadbay_research_lead_by_id calls and treats "stream closed" errors as terminal \u2014 must serialize and retry singletons', "Re-pulls leadbay_pull_leads without passing the captured lensId, allowing a backend lens shift to discard the Phase 2 batch", 'Treats a "Request timed out" from leadbay_bulk_qualify_leads as terminal instead of retrying with wait_for_completion:false + qualify_status polling', 'Triggers on a follow-up query (e.g., "leads I should follow up with") that should have routed to `leadbay_followup_check_in` \u2014 the two entry points are different data sources (Discover wishlist vs Monitor view) per \xA71.6'] },
   leadbay_followup_check_in: { "name": "leadbay_followup_check_in", "short_description": `Run the canonical follow-up check-in: surface KNOWN leads from the
 Monitor view that need re-engagement today, ranked by AI urgency,
 with the canonical pull_followups table layout. Trigger when the
@@ -766,19 +766,19 @@ user asks "follow up", "already known leads", "leads I haven't
 contacted", "leads in [city]", "before my trip", "this week",
 "this month", "what's overdue", "who should I re-engage", or
 anything that implies pre-existing pipeline context.
-`, "arguments": [], "expected_calls": ["leadbay_pull_followups", "leadbay_research_lead", "leadbay_prepare_outreach"], "failure_modes": ["Calls leadbay_pull_leads (the Discover entry point) instead of leadbay_pull_followups \u2014 these are different data sources; the Discover queue does NOT contain Monitor's known-but-cold pipeline", 'Iterates pages of leadbay_pull_leads filtering by engagement_count to "fake" a follow-up view (a real bug observed in 0.9.0 \u2014 the right move is to call pull_followups directly)', "Replaces the canonical pull_followups table layout with prose per row (the per-tool RENDERING block is the structural contract; commentary belongs above or below)", 'Skips the cross-mode pivot offer at the end ("Want to see NEW leads from your wishlist instead?" routes to leadbay_pull_leads)'] },
+`, "arguments": [], "expected_calls": ["leadbay_pull_followups", "leadbay_research_lead_by_id", "leadbay_prepare_outreach"], "failure_modes": ["Calls leadbay_pull_leads (the Discover entry point) instead of leadbay_pull_followups \u2014 these are different data sources; the Discover queue does NOT contain Monitor's known-but-cold pipeline", 'Iterates pages of leadbay_pull_leads filtering by engagement_count to "fake" a follow-up view (a real bug observed in 0.9.0 \u2014 the right move is to call pull_followups directly)', "Replaces the canonical pull_followups table layout with prose per row (the per-tool RENDERING block is the structural contract; commentary belongs above or below)", 'Skips the cross-mode pivot offer at the end ("Want to see NEW leads from your wishlist instead?" routes to leadbay_pull_leads)'] },
   leadbay_import_file: { "name": "leadbay_import_file", "short_description": "Import a user-supplied CSV/file into Leadbay through five phases with\nevidence gates \u2014 scan, derive, resolve identities, preserve & commit,\nthen optionally qualify and report. The job is to maximize how many\nrows the Leadbay system actually ingests and matches.\n", "arguments": [{ "name": "file", "description": "Path or user-visible name of the CSV/file to import. If omitted, use the file the user attached or referenced.", "required": false }, { "name": "instruction", "description": 'Additional user goal, e.g. "then qualify the leads", "preserve owner phone as a custom field", or "only import restaurants in Manhattan".', "required": false }], "expected_calls": ["leadbay_resolve_import_rows", "leadbay_list_mappable_fields", "leadbay_create_custom_field", "leadbay_import_leads", "leadbay_import_and_qualify", "leadbay_add_note", "leadbay_import_status"], "failure_modes": ["Picks LEADBAY_ID from score alone, name-only, fuzzy-name-only, root-domain-only, brand-only, postcode-only, or city-only evidence", "Drops meaningful business notes or CRM record links instead of preserving them as custom fields or lead notes", "Treats a consumer mailbox domain (gmail.com, hotmail.com, ...) as the company domain", "Skips deriving company_domain from a business email when no website column exists (this kills match rate)", "Skips the COLUMN PRESERVATION PLAN byproduct before importing", "Skips the DECISION LOG byproduct before writing LEADBAY_ID", "Returns the imported records WITHOUT writing LEADBAY_ID values back into the user's file (leaves the user no audit trail of what matched)", "Fabricates leadIds, contact emails, or mapping IDs not present in the file or a tool response"] },
-  leadbay_log_outreach: { "name": "leadbay_log_outreach", "short_description": "Log outreach (an email I sent, a call I made, a meeting I had) on a\nspecific lead. Captures verification so the SDR pipeline trusts the entry.\n", "arguments": [{ "name": "lead_id", "description": "The lead UUID. Get it from leadbay_pull_leads or leadbay_research_lead.", "required": true }, { "name": "summary", "description": "1-2 sentences describing what I did (e.g. 'Sent intro email to CTO citing recent Hornsea contract').", "required": true }], "expected_calls": ["leadbay_report_outreach"], "failure_modes": ["Calls leadbay_report_outreach without first collecting a verification source", "Fabricates a gmail_message_id or calendar_event_id (the human team treats verification as canonical)", "Records outreach to a different lead_id than the one the user supplied", "Skips the dry_run step when the user is unsure what would be sent"] },
+  leadbay_log_outreach: { "name": "leadbay_log_outreach", "short_description": "Log outreach (an email I sent, a call I made, a meeting I had) on a\nspecific lead. Captures verification so the SDR pipeline trusts the entry.\n", "arguments": [{ "name": "lead_id", "description": "The lead UUID. Get it from leadbay_pull_leads or leadbay_research_lead_by_id.", "required": true }, { "name": "summary", "description": "1-2 sentences describing what I did (e.g. 'Sent intro email to CTO citing recent Hornsea contract').", "required": true }], "expected_calls": ["leadbay_report_outreach"], "failure_modes": ["Calls leadbay_report_outreach without first collecting a verification source", "Fabricates a gmail_message_id or calendar_event_id (the human team treats verification as canonical)", "Records outreach to a different lead_id than the one the user supplied", "Skips the dry_run step when the user is unsure what would be sent"] },
   leadbay_prospecting_overview: { "name": "leadbay_prospecting_overview", "short_description": `Orientation for working with Leadbay from any host \u2014 discovery vs.
 follow-up, the outreach loop, outcome recording, imports, pushback /
 snooze, and the connected-outreach-tool registry. Trigger when the
 conversation involves Leadbay leads, prospecting, pipeline, follow-up,
 outreach, or lens / ICP \u2014 anything from "show me my leads" to "what
 should I follow up on" to "I'll send via lemlist".
-`, "arguments": [], "expected_calls": ["leadbay_account_status", "leadbay_pull_leads", "leadbay_pull_followups", "leadbay_research_company", "leadbay_research_lead", "leadbay_prepare_outreach", "leadbay_report_outreach", "leadbay_set_pushback", "leadbay_remove_pushback", "leadbay_bulk_qualify_leads", "leadbay_enrich_titles", "leadbay_import_leads", "leadbay_add_note", "leadbay_adjust_audience"], "failure_modes": ['Drives outreach without asking the user "how did it go?" afterwards \u2014 leaving prospecting_actions and epilogue_status stale', 'Says "epilogue" in user-facing dialogue instead of "outcome"', 'Says "Monitor" in user-facing dialogue instead of "follow-ups"', 'Treats a "not now / next quarter" reply as a note instead of routing through the pushback mechanism', "Drafts outreach in a generic format when the user has a connected sequencer (lemlist, Outreach.io, etc.) that has its own idiom", "Re-pulls leads without passing the captured lensId, allowing a backend lens shift to discard prior work", "Skips the STOP byproduct in any multi-step workflow it triggers", "Calls leadbay_pull_leads (Discover wishlist) for a follow-up query, or leadbay_pull_followups (Monitor view) for a discovery query \u2014 the two entry points read from different backend tables; the right orchestrators are leadbay_daily_check_in (discovery) and leadbay_followup_check_in (follow-up)"] },
-  leadbay_qualify_top_n: { "name": "leadbay_qualify_top_n", "short_description": "Bulk-qualify the top N un-qualified leads in the active lens. Uses\nleadbay_bulk_qualify_leads with a sensible default budget.\n", "arguments": [{ "name": "count", "description": "How many leads to qualify (default 10, max 25). Higher counts may take 5+ minutes.", "required": false }], "expected_calls": ["leadbay_bulk_qualify_leads", "leadbay_qualify_status", "leadbay_pull_leads", "leadbay_research_lead"], "failure_modes": ["Picks a count larger than the user asked for (or larger than the max 25)", "Glosses over still-running leads in the summary instead of naming them", "Recommends a lead from the existing qualified pool instead of one from this batch's actual results", 'Replaces the canonical pull_leads table with prose when rendering the newly-qualified batch (the per-tool RENDERING block is the structural contract; "standouts" commentary sits above it)', "Expands the qualify-status sentence into a card or table instead of the one-line status-inline render"] },
+`, "arguments": [], "expected_calls": ["leadbay_account_status", "leadbay_pull_leads", "leadbay_pull_followups", "leadbay_research_lead_by_id", "leadbay_research_lead_by_name_fuzzy", "leadbay_prepare_outreach", "leadbay_report_outreach", "leadbay_set_pushback", "leadbay_remove_pushback", "leadbay_bulk_qualify_leads", "leadbay_enrich_titles", "leadbay_import_leads", "leadbay_add_note", "leadbay_adjust_audience"], "failure_modes": ['Drives outreach without asking the user "how did it go?" afterwards \u2014 leaving prospecting_actions and epilogue_status stale', 'Says "epilogue" in user-facing dialogue instead of "outcome"', 'Says "Monitor" in user-facing dialogue instead of "follow-ups"', 'Treats a "not now / next quarter" reply as a note instead of routing through the pushback mechanism', "Drafts outreach in a generic format when the user has a connected sequencer (lemlist, Outreach.io, etc.) that has its own idiom", "Re-pulls leads without passing the captured lensId, allowing a backend lens shift to discard prior work", "Skips the STOP byproduct in any multi-step workflow it triggers", "Calls leadbay_pull_leads (Discover wishlist) for a follow-up query, or leadbay_pull_followups (Monitor view) for a discovery query \u2014 the two entry points read from different backend tables; the right orchestrators are leadbay_daily_check_in (discovery) and leadbay_followup_check_in (follow-up)"] },
+  leadbay_qualify_top_n: { "name": "leadbay_qualify_top_n", "short_description": "Bulk-qualify the top N un-qualified leads in the active lens. Uses\nleadbay_bulk_qualify_leads with a sensible default budget.\n", "arguments": [{ "name": "count", "description": "How many leads to qualify (default 10, max 25). Higher counts may take 5+ minutes.", "required": false }], "expected_calls": ["leadbay_bulk_qualify_leads", "leadbay_qualify_status", "leadbay_pull_leads", "leadbay_research_lead_by_id"], "failure_modes": ["Picks a count larger than the user asked for (or larger than the max 25)", "Glosses over still-running leads in the summary instead of naming them", "Recommends a lead from the existing qualified pool instead of one from this batch's actual results", 'Replaces the canonical pull_leads table with prose when rendering the newly-qualified batch (the per-tool RENDERING block is the structural contract; "standouts" commentary sits above it)', "Expands the qualify-status sentence into a card or table instead of the one-line status-inline render"] },
   leadbay_refine_audience: { "name": "leadbay_refine_audience", "short_description": "Refine the kind of leads Leadbay surfaces beyond firmographics, with a\nfree-text instruction. Handles the clarification round-trip if the new\nprompt is ambiguous.\n", "arguments": [{ "name": "instruction", "description": "The refinement (e.g. 'focus on hospitals running their own IT'). Set to plain English.", "required": true }], "expected_calls": ["leadbay_refine_prompt", "leadbay_account_status"], "failure_modes": ["Calls leadbay_answer_clarification on the user's behalf instead of surfacing the clarification verbatim", "Glosses over the clarification options instead of presenting them as offered", "Promises immediate effect when status='applied' actually triggers an async intelligence recompute"] },
-  leadbay_research_a_domain: { "name": "leadbay_research_a_domain", "short_description": "Import a company by domain and run deep qualification + research in one\npass. Use when a colleague mentions a name and you want everything Leadbay\nknows about it.\n", "arguments": [{ "name": "domain", "description": "The company's primary domain (e.g. 'acme.com'). Protocol/path are stripped.", "required": true }], "expected_calls": ["leadbay_import_and_qualify", "leadbay_research_lead"], "failure_modes": ["Fabricates qualification answers not present in any tool response", "Reports certainty about fit when qualification didn't actually run (e.g. quota_blocked)", "Skips the research step after import completes", "Renders the research_lead result as a freeform narrative instead of the canonical research-company-card layout (the card with header score bar, pill row, signal sections, contacts table is the structural contract; commentary belongs ABOVE or BELOW it)", "Enumerates every imported lead in prose instead of the terse single-record summary from the import-result rendering snippet"] }
+  leadbay_research_a_domain: { "name": "leadbay_research_a_domain", "short_description": "Import a company by domain and run deep qualification + research in one\npass. Use when a colleague mentions a name and you want everything Leadbay\nknows about it.\n", "arguments": [{ "name": "domain", "description": "The company's primary domain (e.g. 'acme.com'). Protocol/path are stripped.", "required": true }], "expected_calls": ["leadbay_import_and_qualify", "leadbay_research_lead_by_id"], "failure_modes": ["Fabricates qualification answers not present in any tool response", "Reports certainty about fit when qualification didn't actually run (e.g. quota_blocked)", "Skips the research step after import completes", "Renders the research_lead_by_id result as a freeform narrative instead of the canonical research-company-card layout (the card with header score bar, pill row, signal sections, contacts table is the structural contract; commentary belongs ABOVE or BELOW it)", "Enumerates every imported lead in prose instead of the terse single-record summary from the import-result rendering snippet"] }
 };
 var PROMPT_CATALOG_HEADER = `This server exposes the following workflow prompts via \`prompts/list\` and \`prompts/get\`. Some MCP clients render them as slash commands; if your client does not, you (the agent) should invoke them directly via \`prompts/get\` when the user's request matches one of the triggers described below.`;
 var PROMPT_CATALOG_BULLETS = {
@@ -882,7 +882,7 @@ var CATALOG = [
     arguments: [
       {
         name: "lead_id",
-        description: "The lead UUID. Get it from leadbay_pull_leads or leadbay_research_lead.",
+        description: "The lead UUID. Get it from leadbay_pull_leads or leadbay_research_lead_by_id.",
         required: true
       },
       {
@@ -965,7 +965,7 @@ function listResourceTemplates() {
     {
       uriTemplate: "lead://{uuid}/profile",
       name: "Lead profile",
-      description: "Full profile for a single Leadbay lead by UUID. Read-only. Cached client-side; cheaper than calling leadbay_research_lead when you already have the id.",
+      description: "Full profile for a single Leadbay lead by UUID. Read-only. Cached client-side; cheaper than calling leadbay_research_lead_by_id when you already have the id.",
       mimeType: "application/json"
     },
     {
@@ -1016,9 +1016,221 @@ async function readResource(uri, client) {
   );
 }
 
+// src/host-widgets.ts
+var BUILTIN_WIDGETS_PARAGRAPH = 'Prefer host-native widgets over inline markdown when the data shape fits. Three to know: (1) `places_map_display_v0` \u2014 for \u22652 locations / map / travel intent. Pass `{name, address, latitude, longitude, notes}` per location; the host enriches via Google Places. (2) `message_compose_v1` \u2014 for any outreach draft (email / message / call opener). Pass 2\u20133 strategic variants with goal-oriented labels ("Push for alignment", "Reference M&A signal") \u2014 NOT tone labels. (3) `ask_user_input_v0` \u2014 for the NEXT STEPS questions every Leadbay tool emits. Pass `single_select` with 2\u20134 mutually-exclusive options from the tool\'s NEXT STEPS table. When the host doesn\'t expose the named widget, fall back to the per-tool markdown RENDERING block. The directive is host-conditional; the fallback is automatic.';
+
+// src/telemetry.ts
+import { PostHog } from "posthog-node";
+import * as Sentry from "@sentry/node";
+
+// src/telemetry-constants.ts
+var EMBEDDED_POSTHOG_KEY = "phc_N9SnA7OULuAlXReQJZ0Y3rPI4eC0mJLpMRbzgqamhHR";
+var EMBEDDED_POSTHOG_HOST = "https://eu.i.posthog.com";
+var EMBEDDED_SENTRY_DSN = "https://301f1c433433b76132956ed5415bea19@o4505874436849664.ingest.us.sentry.io/4511419984248832";
+
+// src/telemetry-events.ts
+var EV_TOOL_CALL = "mcp tool called";
+var EV_QUOTA_HIT = "mcp quota hit";
+var EV_TOPUP_LINK = "mcp topup link created";
+
+// src/telemetry.ts
+var NOOP_TELEMETRY = {
+  identify: async () => {
+  },
+  captureToolCall: () => {
+  },
+  captureQuotaHit: () => {
+  },
+  captureTopupLink: () => {
+  },
+  captureException: () => {
+  },
+  shutdown: async () => {
+  }
+};
+function parseTelemetryEnv(raw) {
+  if (raw === void 0 || raw === "") return true;
+  const v = raw.trim().toLowerCase();
+  if (v === "false" || v === "0" || v === "no" || v === "off") return false;
+  return true;
+}
+function initTelemetry(opts) {
+  if (!parseTelemetryEnv(process.env.LEADBAY_TELEMETRY_ENABLED)) return NOOP_TELEMETRY;
+  if (process.env.NODE_ENV === "test") return NOOP_TELEMETRY;
+  const posthogKey = process.env.LEADBAY_POSTHOG_KEY ?? EMBEDDED_POSTHOG_KEY;
+  const sentryDsn = process.env.LEADBAY_SENTRY_DSN ?? EMBEDDED_SENTRY_DSN;
+  if (!posthogKey && !sentryDsn) return NOOP_TELEMETRY;
+  const { version, logger } = opts;
+  const environment = process.env.LEADBAY_ENV ?? (version.includes("-dev.") ? "dev" : "production");
+  let posthog = null;
+  let sentryReady = false;
+  let initError = null;
+  try {
+    if (posthogKey) {
+      posthog = new PostHog(posthogKey, {
+        host: process.env.LEADBAY_POSTHOG_HOST ?? EMBEDDED_POSTHOG_HOST,
+        flushAt: 20,
+        flushInterval: 1e4,
+        disableGeoip: false
+      });
+    }
+  } catch (err) {
+    initError = err;
+    posthog = null;
+  }
+  try {
+    if (sentryDsn) {
+      Sentry.init({
+        dsn: sentryDsn,
+        release: `@leadbay/mcp@${version}`,
+        environment,
+        tracesSampleRate: 0,
+        profilesSampleRate: 0,
+        defaultIntegrations: false,
+        integrations: [Sentry.httpIntegration()],
+        sendDefaultPii: false
+      });
+      sentryReady = true;
+    }
+  } catch (err) {
+    initError = initError ?? err;
+    sentryReady = false;
+  }
+  if (initError) {
+    logger?.warn?.(`telemetry init failed: ${initError.message ?? initError}`);
+  }
+  if (!posthog && !sentryReady) return NOOP_TELEMETRY;
+  let me = null;
+  let identityPromise = null;
+  const pendingEvents = [];
+  let region = "unknown";
+  const baseProps = () => ({
+    mcp_version: version,
+    node_version: process.versions.node,
+    platform: process.platform,
+    region
+  });
+  const distinctIdFor = () => {
+    if (me?.email) return me.email;
+    if (me?.id) return `mcp:user-${me.id}`;
+    return "mcp:unknown";
+  };
+  const groupsFor = () => {
+    return me?.organization?.id ? { organization: me.organization.id } : void 0;
+  };
+  const doCapture = (event, properties) => {
+    if (!posthog) return;
+    try {
+      posthog.capture({
+        distinctId: distinctIdFor(),
+        event,
+        properties: { ...baseProps(), ...properties },
+        groups: groupsFor()
+      });
+    } catch (err) {
+      logger?.warn?.(`posthog capture failed: ${err?.message ?? err}`);
+    }
+  };
+  const emit = (event, properties) => {
+    if (!posthog) return;
+    if (!me) {
+      pendingEvents.push({ event, properties });
+      return;
+    }
+    doCapture(event, properties);
+  };
+  const flushPending = () => {
+    if (!posthog || pendingEvents.length === 0) return;
+    const buf = pendingEvents.splice(0, pendingEvents.length);
+    for (const { event, properties } of buf) {
+      doCapture(event, properties);
+    }
+  };
+  return {
+    identify(client) {
+      if (identityPromise) return identityPromise;
+      region = client.region;
+      identityPromise = (async () => {
+        try {
+          const resolved = await client.resolveMe();
+          me = resolved;
+          if (posthog && resolved.email) {
+            try {
+              posthog.identify({
+                distinctId: resolved.email,
+                properties: {
+                  email: resolved.email,
+                  leadbay_id: resolved.id,
+                  leadbay_name: resolved.name,
+                  leadbay_organization: resolved.organization?.name,
+                  leadbay_organization_id: resolved.organization?.id
+                }
+              });
+            } catch (err) {
+              logger?.warn?.(`posthog identify failed: ${err?.message ?? err}`);
+            }
+          }
+          if (sentryReady) {
+            try {
+              Sentry.setUser({
+                id: resolved.id,
+                email: resolved.email,
+                username: resolved.name
+              });
+            } catch (err) {
+              logger?.warn?.(`sentry setUser failed: ${err?.message ?? err}`);
+            }
+          }
+          flushPending();
+        } catch (err) {
+          logger?.warn?.(
+            `telemetry identify failed (${err?.message ?? err}); flushing events anonymously`
+          );
+          me = {
+            id: "unknown",
+            organization: { id: "unknown", name: "unknown" }
+          };
+          flushPending();
+        }
+      })();
+      return identityPromise;
+    },
+    captureToolCall(props) {
+      emit(EV_TOOL_CALL, { ...props });
+    },
+    captureQuotaHit(props) {
+      emit(EV_QUOTA_HIT, { ...props });
+    },
+    captureTopupLink(props) {
+      emit(EV_TOPUP_LINK, { ...props });
+    },
+    captureException(err, ctx) {
+      if (!sentryReady) return;
+      try {
+        Sentry.withScope((scope) => {
+          scope.setTag("tool", ctx.tool);
+          if (me?.organization?.id) {
+            scope.setTag("organization", me.organization.id);
+          }
+          Sentry.captureException(err);
+        });
+      } catch (e) {
+        logger?.warn?.(`sentry captureException failed: ${e?.message ?? e}`);
+      }
+    },
+    async shutdown() {
+      const tasks = [];
+      if (posthog) tasks.push(posthog.shutdown(2e3).catch(() => void 0));
+      if (sentryReady) tasks.push(Sentry.close(2e3).catch(() => void 0));
+      await Promise.allSettled(tasks);
+    }
+  };
+}
+
 // src/server.ts
 var VERIFICATION_MANDATE = "After every email, call, message, or meeting with a lead's contact, you MUST call leadbay_report_outreach with verification={source, ref} (gmail_message_id from the Gmail send, calendar_event_id from a booking, or user_confirmed='<the user's literal confirmation>'). Skipping or fabricating verification poisons the human team's pipeline.";
 var MENTAL_MODEL_PARAGRAPH = "How Leadbay works (mental model): Leadbay is a sales inbox, not a queryable database. Each day the user logs back in, a fresh batch of leads is delivered. Batch size is paced by how many leads the user has actually acted on recently \u2014 some workflows produce a big stream of smaller prospects, others a narrow stream of bigger ones. Pulling more won't produce more; the user acting on leads (outreach, skips, saves) does.";
+var QUOTA_AND_TOPUP_PARAGRAPH = "Quota & top-ups: when a tool returns QUOTA_EXCEEDED / 429, the user has TWO options \u2014 wait for the window reset (daily / weekly / monthly resets shown in leadbay_account_status), OR top up AI credits (top-ups clear the throttle IMMEDIATELY \u2014 they are not subject to the same window). Always offer BOTH options; default-recommending 'wait until tomorrow' is wrong when a 30-second top-up unblocks the same call. If the host exposes leadbay_create_topup_link, OFFER it on every quota wall: 'Want me to generate a top-up link?' \u2014 when the user says yes, call leadbay_create_topup_link and surface the returned Stripe URL as a clickable link for the user to open in their browser. (Sibling leadbay_open_billing_portal is for ongoing subscription changes, not one-shot top-ups.) AFTER the user has topped up: do NOT keep refusing operations. A top-up invalidates every prior 429 and every stale 'you're at your quota' snapshot. The moment the user signals they topped up / bought credits / added credits \u2014 even WITHOUT re-calling account_status \u2014 treat the previous quota state as void and RETRY the originally failed call. (Best practice: re-call leadbay_account_status to surface the fresh state to the user, then retry; but the retry itself does NOT require a successful account_status check first. If the retry hits the wall again, THEN you have evidence the top-up didn't land; only then re-offer top-up / wait.) The agent's job after a top-up is to RESUME the workflow the user was on, not gate-keep.";
 function buildScoringParagraph(has) {
   const base = "Two scoring layers: every lead has a basic `score` (firmographic \u2014 already decent, usually correlates with AI). Roughly the top 10 of each batch are also AI-qualified (targeted web research + qualification questions \u2192 `ai_agent_lead_score`, surfaced as `qualification_summary` on leadbay_pull_leads). Leads past the top ~10 are not worse \u2014 the system is saving resources.";
   const deepenTools = [];
@@ -1030,7 +1242,7 @@ function buildScoringParagraph(has) {
   return base;
 }
 function buildStartHereParagraph(has) {
-  const base = "Start with leadbay_account_status to see the user's state, then leadbay_pull_leads to surface fresh leads. Use leadbay_research_lead to dig into one lead deeply (qualification answers, signals, contacts).";
+  const base = "Start with leadbay_account_status to see the user's state, then leadbay_pull_leads to surface fresh leads. Use leadbay_research_lead_by_id to dig into one lead deeply (qualification answers, signals, contacts).";
   const compositeNames = ["bulk_qualify_leads", "adjust_audience", "refine_prompt", "enrich_titles"].filter((n) => has(`leadbay_${n}`));
   if (compositeNames.length > 0) {
     return base + ` When the user wants more leads, narrower audience, refined criteria, or contact enrichment, use the matching composite tool (${compositeNames.join(" / ")}) \u2014 they hide lens permissions, region routing, polling, and selection state from you.`;
@@ -1113,6 +1325,7 @@ function buildServerInstructions(exposed) {
     parts.push(VERIFICATION_MANDATE);
   }
   parts.push(MENTAL_MODEL_PARAGRAPH);
+  parts.push(QUOTA_AND_TOPUP_PARAGRAPH);
   parts.push(buildScoringParagraph(has));
   parts.push(buildStartHereParagraph(has));
   parts.push(buildRhythmParagraph(has));
@@ -1120,6 +1333,7 @@ function buildServerInstructions(exposed) {
   if (promptsCatalog) parts.push(promptsCatalog);
   parts.push(RESOURCES_PARAGRAPH);
   parts.push(buildProtocolPrimitivesParagraph(has));
+  parts.push(BUILTIN_WIDGETS_PARAGRAPH);
   return parts.join("\n\n");
 }
 function formatErrorForLLM(err) {
@@ -1250,8 +1464,10 @@ function buildServer(client, opts = {}) {
   });
   const DEBUG_RAW = process.env.LEADBAY_DEBUG ?? "";
   const DEBUG_ON = DEBUG_RAW === "1" || DEBUG_RAW.toLowerCase() === "true";
+  const telemetry = opts.telemetry ?? NOOP_TELEMETRY;
+  const isLeadbayBusinessError = (err) => err != null && typeof err === "object" && err.error === true && typeof err.code === "string";
   server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
-    const debugStart = DEBUG_ON ? Date.now() : 0;
+    const callStart = Date.now();
     const name = req.params.name;
     const tool = toolByName.get(name);
     if (!tool) {
@@ -1307,9 +1523,33 @@ function buildServer(client, opts = {}) {
         elicit
       });
       if (result && typeof result === "object" && result.error === true) {
+        const envText = formatErrorForLLM(result);
+        const envDur = Date.now() - callStart;
+        const envCode = result.code ?? "Error";
+        if (envCode === "QUOTA_EXCEEDED") {
+          telemetry.captureQuotaHit({
+            tool: name,
+            retry_after_s: result._meta?.retry_after,
+            endpoint: result._meta?.endpoint
+          });
+        }
+        telemetry.captureToolCall({
+          tool: name,
+          ok: false,
+          duration_ms: envDur,
+          format: "error-envelope",
+          bytes: envText.length,
+          error_code: envCode
+        });
+        if (DEBUG_ON) {
+          process.stderr.write(
+            `[leadbay-mcp debug] tool=${name} dur=${envDur}ms ok=false code=${envCode}
+`
+          );
+        }
         return {
           content: [
-            { type: "text", text: formatErrorForLLM(result) }
+            { type: "text", text: envText }
           ],
           isError: true
         };
@@ -1323,11 +1563,21 @@ function buildServer(client, opts = {}) {
         if (tool.outputSchema && env.structured !== null && typeof env.structured === "object" && !Array.isArray(env.structured)) {
           out.structuredContent = env.structured;
         }
+        const mdDur = Date.now() - callStart;
+        const mdBytes = env.markdown.length;
+        telemetry.captureToolCall({
+          tool: name,
+          ok: true,
+          duration_ms: mdDur,
+          format: "markdown",
+          bytes: mdBytes
+        });
+        if (name === "leadbay_create_topup_link" && typeof env.structured?.url === "string") {
+          telemetry.captureTopupLink({ tool: name });
+        }
         if (DEBUG_ON) {
-          const dur = Date.now() - debugStart;
-          const bytes = env.markdown.length;
           process.stderr.write(
-            `[leadbay-mcp debug] tool=${name} dur=${dur}ms ok=true bytes=${bytes} format=markdown
+            `[leadbay-mcp debug] tool=${name} dur=${mdDur}ms ok=true bytes=${mdBytes} format=markdown
 `
           );
         }
@@ -1341,28 +1591,66 @@ function buildServer(client, opts = {}) {
       if (tool.outputSchema && result !== null && typeof result === "object" && !Array.isArray(result)) {
         response.structuredContent = result;
       }
+      const okText = response.content[0]?.text ?? "";
+      const okBytes = typeof okText === "string" ? okText.length : 0;
+      const okDur = Date.now() - callStart;
+      telemetry.captureToolCall({
+        tool: name,
+        ok: true,
+        duration_ms: okDur,
+        format: "json",
+        bytes: okBytes
+      });
+      if (name === "leadbay_create_topup_link" && typeof result?.url === "string") {
+        telemetry.captureTopupLink({ tool: name });
+      }
       if (DEBUG_ON) {
-        const dur = Date.now() - debugStart;
-        const text = response.content[0]?.text ?? "";
-        const bytes = typeof text === "string" ? text.length : 0;
         process.stderr.write(
-          `[leadbay-mcp debug] tool=${name} dur=${dur}ms ok=true bytes=${bytes}
+          `[leadbay-mcp debug] tool=${name} dur=${okDur}ms ok=true bytes=${okBytes}
 `
         );
       }
       return response;
     } catch (err) {
+      const errDur = Date.now() - callStart;
+      const errText = formatErrorForLLM(err);
+      const code = err?.code ?? err?.name ?? "Error";
+      if (isLeadbayBusinessError(err)) {
+        if (err.code === "QUOTA_EXCEEDED") {
+          telemetry.captureQuotaHit({
+            tool: name,
+            retry_after_s: err._meta?.retry_after,
+            endpoint: err._meta?.endpoint
+          });
+        }
+        telemetry.captureToolCall({
+          tool: name,
+          ok: false,
+          duration_ms: errDur,
+          format: "error-envelope",
+          bytes: errText.length,
+          error_code: code
+        });
+      } else {
+        telemetry.captureException(err, { tool: name });
+        telemetry.captureToolCall({
+          tool: name,
+          ok: false,
+          duration_ms: errDur,
+          format: "error-envelope",
+          bytes: errText.length,
+          error_code: code
+        });
+      }
       if (DEBUG_ON) {
-        const dur = Date.now() - debugStart;
-        const code = err?.code ?? err?.name ?? "Error";
         process.stderr.write(
-          `[leadbay-mcp debug] tool=${name} dur=${dur}ms ok=false code=${code}
+          `[leadbay-mcp debug] tool=${name} dur=${errDur}ms ok=false code=${code}
 `
         );
       }
       return {
         content: [
-          { type: "text", text: formatErrorForLLM(err) }
+          { type: "text", text: errText }
         ],
         isError: true
       };
@@ -1373,7 +1661,7 @@ function buildServer(client, opts = {}) {
 
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.9.1";
+var VERSION = "0.10.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -1409,6 +1697,13 @@ ENV VARS
                          journaled in-process and return {mocked: true, would_call: {...}}.
   LEADBAY_MOCK_DIR       (optional) Fixture directory. Default: ./.context/leadbay-live-shapes/
   LEADBAY_LOG_LEVEL      (optional) "debug" | "info" | "error" (default "error"). Logs to stderr.
+  LEADBAY_TELEMETRY_ENABLED  (optional) Default "true". Sends product usage events
+                         (tool name, duration, ok flag, error code) to PostHog and
+                         unexpected errors to Sentry, helping Leadbay improve the MCP.
+                         Events are tied to your Leadbay account email (so MCP usage
+                         consolidates with web-app usage in our analytics). Tool
+                         arguments, response bodies, and lead PII are NEVER captured.
+                         Set to "false" to opt out. See README "Privacy & telemetry".
 
 EXAMPLE Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json)
   {
@@ -1418,7 +1713,8 @@ EXAMPLE Claude Desktop config (~/Library/Application Support/Claude/claude_deskt
         "args": ["-y", "@leadbay/mcp@0.3"],
         "env": {
           "LEADBAY_TOKEN": "lb_...",
-          "LEADBAY_REGION": "us"
+          "LEADBAY_REGION": "us",
+          "LEADBAY_TELEMETRY_ENABLED": "true"
         }
       }
     }
@@ -1662,7 +1958,7 @@ async function runLogin(args) {
   let result;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-X5AOPZ2V.js");
+      const { REGIONS } = await import("./dist-BHLIJAIH.js");
       const baseUrl = REGIONS[pinnedRegion];
       const c = createClient({ region: pinnedRegion });
       const token = await loginAt(baseUrl, email, password);
@@ -1989,7 +2285,7 @@ async function readChoice(prompt, def = true) {
     process.stdin.on("data", onData);
   });
 }
-function buildClaudeCodeAddArgs(token, region, includeWrite) {
+function buildClaudeCodeAddArgs(token, region, includeWrite, telemetryEnabled) {
   const args = [
     "mcp",
     "add",
@@ -1999,15 +2295,20 @@ function buildClaudeCodeAddArgs(token, region, includeWrite) {
     "--env",
     `LEADBAY_TOKEN=${token}`,
     "--env",
-    `LEADBAY_REGION=${region}`
+    `LEADBAY_REGION=${region}`,
+    // Always written explicitly (not just when opting out) so MCP-client
+    // config UIs can render it as a toggle the user can flip without
+    // editing the file by hand.
+    "--env",
+    `LEADBAY_TELEMETRY_ENABLED=${telemetryEnabled ? "true" : "false"}`
   ];
   if (!includeWrite) args.push("--env", `LEADBAY_MCP_WRITE=0`);
   args.push("--", "npx", "-y", "@leadbay/mcp@0.3");
   return args;
 }
-async function installInClaudeCode(token, region, includeWrite) {
+async function installInClaudeCode(token, region, includeWrite, telemetryEnabled) {
   const cp = await import("child_process");
-  const args = buildClaudeCodeAddArgs(token, region, includeWrite);
+  const args = buildClaudeCodeAddArgs(token, region, includeWrite, telemetryEnabled);
   return await new Promise((resolve) => {
     const child = cp.spawn("claude", args, { stdio: ["ignore", "pipe", "pipe"] });
     let stderr = "";
@@ -2025,7 +2326,7 @@ async function installInClaudeCode(token, region, includeWrite) {
     );
   });
 }
-async function installInJsonConfig(configPath, token, region, includeWrite) {
+async function installInJsonConfig(configPath, token, region, includeWrite, telemetryEnabled) {
   try {
     const { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } = await import("fs");
     const { dirname } = await import("path");
@@ -2045,7 +2346,9 @@ async function installInJsonConfig(configPath, token, region, includeWrite) {
     parsed.mcpServers = parsed.mcpServers ?? {};
     const env = {
       LEADBAY_TOKEN: token,
-      LEADBAY_REGION: region
+      LEADBAY_REGION: region,
+      // Always written so MCP-client config UIs can render it as a toggle.
+      LEADBAY_TELEMETRY_ENABLED: telemetryEnabled ? "true" : "false"
     };
     if (!includeWrite) env.LEADBAY_MCP_WRITE = "0";
     parsed.mcpServers.leadbay = {
@@ -2073,7 +2376,7 @@ async function runInstall(args) {
   const email = parseFlag(args, "email");
   if (!email) {
     process.stderr.write(
-      "Usage: leadbay-mcp install --email you@example.com [--region us|fr]\n                          [--allow-region-fallback] [--no-write]\n                          [--target claude-code,claude-desktop,cursor]\n                          [--yes] [--force-legacy]\n  Mints a token AND registers the MCP server with your installed clients (at user scope).\n  --target            Comma-separated subset; default = all detected.\n  --no-write          Disable composite write tools (refine_prompt, report_outreach,\n                      adjust_audience, etc.). They are ON by default since 0.3.0;\n                      pass --no-write for read-only agents.\n  --include-write     (deprecated since 0.3.0; now a no-op \u2014 writes are on by default).\n  --yes               Don't ask before installing into each detected client.\n  --force-legacy      Write to claude_desktop_config.json even when Claude Desktop 2026\n                      DXT is detected. Not recommended \u2014 the app overwrites that file.\n                      Use the .dxt bundle instead: https://github.com/leadbay/leadclaw/releases\n"
+      "Usage: leadbay-mcp install --email you@example.com [--region us|fr]\n                          [--allow-region-fallback] [--no-write] [--no-telemetry]\n                          [--target claude-code,claude-desktop,cursor]\n                          [--yes] [--force-legacy]\n  Mints a token AND registers the MCP server with your installed clients (at user scope).\n  --target            Comma-separated subset; default = all detected.\n  --no-write          Disable composite write tools (refine_prompt, report_outreach,\n                      adjust_audience, etc.). They are ON by default since 0.3.0;\n                      pass --no-write for read-only agents.\n  --no-telemetry      Opt out of product usage events (PostHog + Sentry).\n                      Defaults to ON: helps Leadbay improve the MCP. Events are\n                      tied to your Leadbay email; tool args, response bodies,\n                      and lead PII are NEVER captured.\n  --include-write     (deprecated since 0.3.0; now a no-op \u2014 writes are on by default).\n  --yes               Don't ask before installing into each detected client.\n  --force-legacy      Write to claude_desktop_config.json even when Claude Desktop 2026\n                      DXT is detected. Not recommended \u2014 the app overwrites that file.\n                      Use the .dxt bundle instead: https://github.com/leadbay/leadclaw/releases\n"
     );
     return 2;
   }
@@ -2154,7 +2457,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-X5AOPZ2V.js");
+      const { REGIONS } = await import("./dist-BHLIJAIH.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;
@@ -2181,6 +2484,16 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
       "Composite write tools DISABLED (read-only agent). Re-run without --no-write to enable.\n\n"
     );
   }
+  const telemetryEnabled = !hasFlag(args, "no-telemetry");
+  if (telemetryEnabled) {
+    process.stderr.write(
+      "Product usage events ENABLED \u2014 helps Leadbay improve the MCP. We capture\n  per-tool-call metrics (name, duration, ok/error code) and unexpected exceptions.\n  Events are tied to your Leadbay email (so MCP usage consolidates with web-app\n  usage in our analytics) \u2014 they are NOT anonymous. Tool arguments, response\n  bodies, and lead PII are NEVER sent. Flip the toggle\n  LEADBAY_TELEMETRY_ENABLED=false in your client's env block to opt out anytime.\n\n"
+    );
+  } else {
+    process.stderr.write(
+      "Product usage events DISABLED. Re-run without --no-telemetry to enable.\n\n"
+    );
+  }
   const skipPrompts = hasFlag(args, "yes");
   const results = [];
   for (const c of chosen) {
@@ -2200,10 +2513,10 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
     }
     let res;
     if (c.id === "claude-code") {
-      res = await installInClaudeCode(token, region, includeWrite);
+      res = await installInClaudeCode(token, region, includeWrite, telemetryEnabled);
     } else {
       const path = c.detail.split(" ")[0];
-      res = await installInJsonConfig(path, token, region, includeWrite);
+      res = await installInJsonConfig(path, token, region, includeWrite, telemetryEnabled);
     }
     results.push({ id: c.id, label: c.label, ...res });
   }
@@ -2290,7 +2603,9 @@ async function main() {
     process.exit(await runDoctor());
   }
   const logger = makeStderrLogger(parseLogLevel(process.env.LEADBAY_LOG_LEVEL));
+  const telemetry = initTelemetry({ version: VERSION, logger });
   const client = await resolveClientFromEnv(logger);
+  telemetry.identify(client);
   const includeAdvanced = process.env.LEADBAY_MCP_ADVANCED === "1";
   const includeWrite = parseWriteEnv();
   const bulkTracker = await createDefaultBulkStore({ logger });
@@ -2299,13 +2614,24 @@ async function main() {
     includeWrite,
     logger,
     bulkTracker,
-    version: VERSION
+    version: VERSION,
+    telemetry
   });
   const transport = new StdioServerTransport();
   logger.info?.(
     `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability})`
   );
   await server.connect(transport);
+  const shutdown = async (code) => {
+    try {
+      await telemetry.shutdown();
+    } finally {
+      process.exit(code);
+    }
+  };
+  process.once("SIGINT", () => void shutdown(130));
+  process.once("SIGTERM", () => void shutdown(143));
+  process.stdin.once("end", () => void shutdown(0));
 }
 var isEntrypoint = (() => {
   try {
@@ -2318,9 +2644,15 @@ var isEntrypoint = (() => {
   }
 })();
 if (isEntrypoint) {
-  main().catch((err) => {
+  main().catch(async (err) => {
     process.stderr.write(`leadbay-mcp: ${err?.message ?? err}
 `);
+    try {
+      const bootTelemetry = initTelemetry({ version: VERSION });
+      bootTelemetry.captureException(err, { tool: "__bootstrap__" });
+      await bootTelemetry.shutdown();
+    } catch {
+    }
     process.exit(1);
   });
 }