@leadbay/mcp 0.9.0 → 0.10.0

package/dist/bin.js

@@ -8,7 +8,7 @@ import {
   granularReadTools,
   granularWriteTools,
   resolveRegion
-} from "./chunk-2EGNZRD7.js";
+} from "./chunk-F3EWCHME.js";
 
 // src/bin.ts
 import { realpathSync } from "fs";
@@ -33,11 +33,11 @@ import {
 
 // src/prompts.generated.ts
 var leadbay_daily_check_in = `
-Run the Leadbay daily check-in for me. Treat this prompt the same way for any equivalent ask: "get me leadbay leads", "best leads to prospect today", "what should I work on", "show me my batch".
+Run the Leadbay daily check-in for me. Treat this prompt the same way for any equivalent ask focused on NEW leads from the Discover wishlist: "get me leadbay leads", "best NEW leads to prospect today", "what's new today", "show me my batch", "let's prospect". For follow-up phrasings ("what should I follow up on", "leads I've already worked", "before my trip"), this is the wrong prompt \u2014 route to \`leadbay_followup_check_in\` instead. If the user's intent is ambiguous ("what should I work on?"), ASK once before picking an entry point.
 
 # 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
 
@@ -72,15 +72,99 @@ Call \`leadbay_account_status\` to see what quota I have left and which lens is
 # PHASE 2 \u2014 FRESH BATCH
 Call \`leadbay_pull_leads\` to get today's fresh batch. Capture \`response.lens.id\` (the response nests it under \`lens\`). **Use it as an explicit \`lensId\` argument on every subsequent Leadbay call this session** \u2014 including any re-pulls, bulk qualifies, or research calls that accept it. (See Rule 1 above \u2014 a mid-session lens shift discards your top-10 work.)
 
-# PHASE 3 \u2014 TRIAGE (top 10, motivational framing)
+# PHASE 3 \u2014 TRIAGE (top 10, table + nudges)
 
-Pick the top **10** leads \u2014 prefer leads with a fresh \`ai_agent_lead_score\` (those have been newly AI-qualified); fall back to \`score\` only when \`ai_agent_lead_score\` is absent. For each, write ONE motivational sentence \u2014 framed as *why prospecting this lead today might be a good idea right now* (almost a coach's nudge, not a flat description). Lean on \`qualification_summary\` for the substance, but reframe \u2014 don't paste it verbatim.
+Render the **top 10 leads** using the canonical \`leadbay_pull_leads\` layout:
+
+GATE \u2014 DEFER TO TOOL RENDERING. When you call a Leadbay composite that ships its own RENDERING block (every composite in 0.9.0+ does), render the response using that block's recipe verbatim \u2014 score bars, glyph palette, column order, hide-list, link priorities, all of it. Do NOT substitute prose, a numbered list, or a different column structure even when an orchestrating prompt's body suggests alternate framing. Prompt-specific commentary (motivational nudges, summaries, next-action recommendations) belongs ABOVE or BELOW the canonical table, never in place of it.
+
+If the prompt's body and the tool's RENDERING appear to conflict, the tool's RENDERING wins for the structural layout; the prompt's voice wins for the commentary that surrounds it.
+
+
+## RENDERING \u2014 markdown table, three columns, score-bar driven
+
+Present the response as a markdown table sorted by \`score\` descending, with exactly three columns. Do not summarize in prose. Do not show the numeric score anywhere.
+
+## Score-bar (10-segment, inline-code wrapped)
+
+Wrap a 10-glyph bar in a SINGLE inline-code span (backticks). The inline-code styling is what gives the bar contrast in most chat renderers \u2014 HTML \`<span>\` is stripped inside table cells.
+
+Glyphs (use these exact characters; do not substitute):
+
+- \`\u25B0\` \u2014 firmographic-only fill
+- \`\u2756\` \u2014 AI-booster cap (placed at the RIGHT END of the filled run, never the front)
+- \`\u25B1\` \u2014 empty
+
+Computation:
+
+\`\`\`
+total_filled  = round(score / 10), clamped to 0..10
+ai_segments   = round(qualification_summary.avg_qualification_boost / 3.3),
+                clamped to [0, total_filled]
+normal_filled = total_filled \u2212 ai_segments
+bar = "\u25B0" \xD7 normal_filled
+    + "\u2756" \xD7 ai_segments
+    + "\u25B1" \xD7 (10 \u2212 total_filled)
+\`\`\`
+
+If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is null, set \`ai_segments = 0\` (no \u2756). Always wrap the bar in backticks. Print the legend \`\` \`\u25B0\` firmographic \xB7 \`\u2756\` AI booster cap \xB7 \`\u25B1\` unfilled \`\` once below the table.
+
+
+**Column 1 \u2014 Company**
+
+- Line 1: the 10-segment score bar in inline-code backticks (see the score-bar snippet above for the algorithm).
+- Insert \`<br>\` between lines.
+- Line 2: linked company name + \` \xB7 \` + short location + \` \xB7 \` + compact size.
+  - Link target: \`website\` (prefix \`https://\` if it's a bare hostname). Don't synthesize an app deep-link.
+  - Location: shorten "City of New York" \u2192 "NYC"; otherwise "City ST"; state alone only when city missing.
+  - Size: \`"Xk+"\` when \`size.min >= 1000\`, \`"min\u2013max"\` otherwise.
+
+**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_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.
+
+**Column 3 \u2014 Contact**
+
+\`[Contact name](LINK) \xB7 short job title\`. See linking/contact-linkedin for LINK priority and the \xB0-flag fallback.
+
+**Hide from the user (never include in any cell):** \`id\`, \`location.pos\`, \`location.country\` (unless city/state both missing), \`sector_id\`, \`is_hq\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`highlighted_fields\`, \`custom_fields\`, \`contacts_count\` when 0, \`notes_count\` / \`epilogue_actions_count\` / \`prospecting_actions_count\` when 0, \`stale_at\`, \`deal_insights\`, \`social_presence\` booleans (except as the \xB0-flag signal), \`need_attention\` flags, any field whose value is the string \`"null"\`.
+
+## Linking a contact's name
+
+Two LinkedIn URLs exist and must never be conflated: the **company's** LinkedIn page and an **individual person's** profile.
+
+When the response carries a real contact LinkedIn URL \u2014 \`contact.linkedin_page\` is a string that starts with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it) \u2014 link the contact's name to that URL.
+
+Otherwise fall back to a LinkedIn people-search URL:
+
+\`\`\`
+https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
+\`\`\`
+
+URL-encode the params. Strip Inc / LLC / Corp / Ltd / GmbH suffixes from the company name. Append a trailing \` \xB0\` to the rendered name ONLY when the fallback is in use AND \`social_presence.linkedin == false\` (no company LinkedIn \u2192 search may not resolve). Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa). The two surfaces are different \u2014 conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+ABOVE the table, add a 2\u20134 sentence "Today's nudges" paragraph for the 3 most-promising rows. The nudges speak to urgency / opportunity / freshness \u2014 what makes acting on these RIGHT NOW the right call. Do NOT repeat the "why it fits" column from the table; the nudges should add fresh framing the table doesn't carry (e.g., recent news from the \`qualification_summary\` excerpt, a window closing, a competitor activity the user mentioned earlier in the session). One sentence per nudge, salesperson voice, not coachspeak.
 
 If the batch returns fewer than 10 qualified leads, top it up: call \`leadbay_bulk_qualify_leads\` with \`lensId:<captured>\`, \`count:<1.5x deficit, capped at 25>\`, and **\`wait_for_completion:false\`**. Capture \`qualify_id\` from the response and poll \`leadbay_qualify_status\` every ~10s until \`status:'done'\`. Then re-pull with the same \`lensId\` to pick up the newly qualified leads. **Never re-pull without \`lensId\` \u2014 you will lose your batch to a lens shift.** (The \`leadbay_qualify_top_n\` slash-prompt wraps this same tool with a friendlier surface for users; agents should call the underlying tool directly here.)
 
 # 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)
@@ -114,6 +198,11 @@ A job well done has TWO deliverables:
 IRON LAW \u2014 NO FABRICATION. Every lead id, contact email, custom field id, mapping decision, and tool argument must trace to a value you read from the file the user attached or to an output from a leadbay_* tool call in this session. Do not invent values. Do not "fill in" a missing leadId with a name match. Do not synthesize a CRM id from a guess. If a value is missing, leave the field blank and say so.
 
 
+GATE \u2014 DEFER TO TOOL RENDERING. When you call a Leadbay composite that ships its own RENDERING block (every composite in 0.9.0+ does), render the response using that block's recipe verbatim \u2014 score bars, glyph palette, column order, hide-list, link priorities, all of it. Do NOT substitute prose, a numbered list, or a different column structure even when an orchestrating prompt's body suggests alternate framing. Prompt-specific commentary (motivational nudges, summaries, next-action recommendations) belongs ABOVE or BELOW the canonical table, never in place of it.
+
+If the prompt's body and the tool's RENDERING appear to conflict, the tool's RENDERING wins for the structural layout; the prompt's voice wins for the commentary that surrounds it.
+
+
 # PHASE 1 \u2014 SCAN
 
 Read the file yourself. Inspect every header, sample values from multiple rows, row count, duplicate/blank columns, and obvious dirty data. Build a column preservation plan before importing: for each meaningful column decide standard field, CONTACT_* field, Leadbay note, custom field, derived helper, or skip with a reason. Default to preserving client-provided business data; skip only blank placeholders, duplicate plumbing, raw unparsed blobs after extracting their useful values, or values that would actively harm data quality.
@@ -283,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
 
@@ -293,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
 
@@ -315,13 +404,16 @@ Leadbay supports two parallel ways to find leads to act on. Detect which entry t
 \`\`\`
 Discovery entry              Follow-up entry
 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500            \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-leadbay_pull_leads           (re-engagement on the Monitor view \u2014
-(new from the Discover        currently surfaced via the Leadbay app
- wishlist, lens-driven)       UI; MCP-side composite forthcoming)
+leadbay_pull_leads           leadbay_pull_followups
+(new from the Discover        (re-engagement on the
+ wishlist, lens-driven)        Monitor view of known leads)
+        \u2502                            \u2502
+   wrapped by:                   wrapped by:
+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
@@ -343,6 +435,14 @@ leadbay_pull_leads           (re-engagement on the Monitor view \u2014
 
 When in doubt, ask. The two paths return overlapping but differently-ranked data; presenting the wrong one wastes the user's time.
 
+**Routing the user's first message to an entry point (orchestrator prompts):**
+
+- "give me leads", "what's new", "let's prospect", "today's batch", "best NEW leads" \u2192 \`leadbay_daily_check_in\` (Discovery orchestrator \u2014 wraps \`leadbay_pull_leads\`)
+- "follow up", "already known", "leads I should contact", "before my trip", "this week", "what's overdue", "re-engage" \u2192 \`leadbay_followup_check_in\` (Follow-up orchestrator \u2014 wraps \`leadbay_pull_followups\`)
+- Ambiguous ("what should I work on?") \u2192 ASK once: "Looking for NEW leads from your wishlist, or follow-ups on leads you've already worked?"
+
+Never call \`leadbay_pull_leads\` directly for a follow-up query. Never call \`leadbay_pull_followups\` for a discovery query. The two tools read from different backend tables; iterating pages of one to fake the other is a known failure mode (see the anti-confusion guardrail in \`pull_followups\`'s description).
+
 ## The outreach loop
 
 After \`leadbay_prepare_outreach\` returns a brief, the agent drafts. Adapt to the user's connected outreach tools \u2014 these change the draft idiom:
@@ -397,25 +497,128 @@ After your first \`leadbay_pull_leads\` call, capture \`response.lens.id\` (the
 ## What to read once you've matched intent
 
 You don't need to memorize every tool here \u2014 each tool's own description carries a RENDERING block (how to present the response) and a NEXT STEPS block (observation \u2192 suggestion table). Read the relevant tool's description in full when the user picks an entry point. This overview just gets you to the right starting tool.
+
+GATE \u2014 DEFER TO TOOL RENDERING. When you call a Leadbay composite that ships its own RENDERING block (every composite in 0.9.0+ does), render the response using that block's recipe verbatim \u2014 score bars, glyph palette, column order, hide-list, link priorities, all of it. Do NOT substitute prose, a numbered list, or a different column structure even when an orchestrating prompt's body suggests alternate framing. Prompt-specific commentary (motivational nudges, summaries, next-action recommendations) belongs ABOVE or BELOW the canonical table, never in place of it.
+
+If the prompt's body and the tool's RENDERING appear to conflict, the tool's RENDERING wins for the structural layout; the prompt's voice wins for the commentary that surrounds it.
 `;
 var leadbay_qualify_top_n = `
 Qualify the top {{arg:count_or_default}} un-qualified leads in the active Leadbay lens.
 
+GATE \u2014 DEFER TO TOOL RENDERING. When you call a Leadbay composite that ships its own RENDERING block (every composite in 0.9.0+ does), render the response using that block's recipe verbatim \u2014 score bars, glyph palette, column order, hide-list, link priorities, all of it. Do NOT substitute prose, a numbered list, or a different column structure even when an orchestrating prompt's body suggests alternate framing. Prompt-specific commentary (motivational nudges, summaries, next-action recommendations) belongs ABOVE or BELOW the canonical table, never in place of it.
+
+If the prompt's body and the tool's RENDERING appear to conflict, the tool's RENDERING wins for the structural layout; the prompt's voice wins for the commentary that surrounds it.
+
+
 # PHASE 1 \u2014 LAUNCH
 Call \`leadbay_bulk_qualify_leads\` with \`count={{arg:count_or_default}}\`.
 
 # PHASE 2 \u2014 POLL
-While it polls, expect notifications / progress events showing per-lead transitions. Surface meaningful ones (e.g. "lead X just finished") to me as they arrive.
+While it polls, expect notifications / progress events showing per-lead transitions. Surface meaningful ones (e.g. "lead X just finished") to me as they arrive \u2014 one inline status sentence per check, never expanded into a card:
+
+## Status / scalar \u2014 single-sentence shape
+
+The response is a status confirmation or scalar \u2014 render exactly one sentence inline. Do NOT emit a card or a table. Do NOT enumerate the affected records (that's the next tool's job).
+
+Template patterns to follow:
+
+- Job kicked off \u2192 \`"\u2713 <Verb> N <noun(s)> \u2014 typically ~M minutes. I'll refresh when it's done."\`
+- No work needed \u2192 \`"All N <noun(s)> already <state> \u2014 no work to do."\`
+- Long-running \u2192 \`"\u23F3 <Verb> still running \u2014 N% complete; check back in ~M minutes."\`
+- Failure \u2192 \`"\u26A0 <Verb> failed: <error>. <recovery hint>"\`
+
+After the status line, propose the obvious refresh / progress-check / recovery action in the NEXT STEPS block. Never expand the status into a card.
+
 
 # PHASE 3 \u2014 SUMMARIZE
 
-When \`bulk_qualify_leads\` returns, summarize:
-- How many qualified (name the count)
-- How many are still running (name them, by lead_id + lead name if available, so I can poll again later)
-- The 3 highest-\`ai_agent_lead_score\` leads from THIS batch, with their \`qualification_summary\` (one sentence each)
+When \`bulk_qualify_leads\` returns, surface results in two parts.
+
+**Status line first** \u2014 one sentence using the status-inline shape above: how many qualified, how many are still running (name them by lead_id + lead name if available so the user can poll later).
+
+**Then a refreshed table** \u2014 re-pull the newly-qualified leads via \`leadbay_pull_leads\` with the same \`lensId\` and render them using the canonical pull_leads layout:
+
+## RENDERING \u2014 markdown table, three columns, score-bar driven
+
+Present the response as a markdown table sorted by \`score\` descending, with exactly three columns. Do not summarize in prose. Do not show the numeric score anywhere.
+
+## Score-bar (10-segment, inline-code wrapped)
+
+Wrap a 10-glyph bar in a SINGLE inline-code span (backticks). The inline-code styling is what gives the bar contrast in most chat renderers \u2014 HTML \`<span>\` is stripped inside table cells.
+
+Glyphs (use these exact characters; do not substitute):
+
+- \`\u25B0\` \u2014 firmographic-only fill
+- \`\u2756\` \u2014 AI-booster cap (placed at the RIGHT END of the filled run, never the front)
+- \`\u25B1\` \u2014 empty
+
+Computation:
+
+\`\`\`
+total_filled  = round(score / 10), clamped to 0..10
+ai_segments   = round(qualification_summary.avg_qualification_boost / 3.3),
+                clamped to [0, total_filled]
+normal_filled = total_filled \u2212 ai_segments
+bar = "\u25B0" \xD7 normal_filled
+    + "\u2756" \xD7 ai_segments
+    + "\u25B1" \xD7 (10 \u2212 total_filled)
+\`\`\`
+
+If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is null, set \`ai_segments = 0\` (no \u2756). Always wrap the bar in backticks. Print the legend \`\` \`\u25B0\` firmographic \xB7 \`\u2756\` AI booster cap \xB7 \`\u25B1\` unfilled \`\` once below the table.
+
+
+**Column 1 \u2014 Company**
+
+- Line 1: the 10-segment score bar in inline-code backticks (see the score-bar snippet above for the algorithm).
+- Insert \`<br>\` between lines.
+- Line 2: linked company name + \` \xB7 \` + short location + \` \xB7 \` + compact size.
+  - Link target: \`website\` (prefix \`https://\` if it's a bare hostname). Don't synthesize an app deep-link.
+  - Location: shorten "City of New York" \u2192 "NYC"; otherwise "City ST"; state alone only when city missing.
+  - Size: \`"Xk+"\` when \`size.min >= 1000\`, \`"min\u2013max"\` otherwise.
+
+**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_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.
+
+**Column 3 \u2014 Contact**
+
+\`[Contact name](LINK) \xB7 short job title\`. See linking/contact-linkedin for LINK priority and the \xB0-flag fallback.
+
+**Hide from the user (never include in any cell):** \`id\`, \`location.pos\`, \`location.country\` (unless city/state both missing), \`sector_id\`, \`is_hq\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`highlighted_fields\`, \`custom_fields\`, \`contacts_count\` when 0, \`notes_count\` / \`epilogue_actions_count\` / \`prospecting_actions_count\` when 0, \`stale_at\`, \`deal_insights\`, \`social_presence\` booleans (except as the \xB0-flag signal), \`need_attention\` flags, any field whose value is the string \`"null"\`.
+
+## Linking a contact's name
+
+Two LinkedIn URLs exist and must never be conflated: the **company's** LinkedIn page and an **individual person's** profile.
+
+When the response carries a real contact LinkedIn URL \u2014 \`contact.linkedin_page\` is a string that starts with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it) \u2014 link the contact's name to that URL.
+
+Otherwise fall back to a LinkedIn people-search URL:
+
+\`\`\`
+https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
+\`\`\`
+
+URL-encode the params. Strip Inc / LLC / Corp / Ltd / GmbH suffixes from the company name. Append a trailing \` \xB0\` to the rendered name ONLY when the fallback is in use AND \`social_presence.linkedin == false\` (no company LinkedIn \u2192 search may not resolve). Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa). The two surfaces are different \u2014 conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+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}}
@@ -434,46 +637,153 @@ var leadbay_research_a_domain = `
 IRON LAW \u2014 NO FABRICATION. Every lead id, contact email, custom field id, mapping decision, and tool argument must trace to a value you read from the file the user attached or to an output from a leadbay_* tool call in this session. Do not invent values. Do not "fill in" a missing leadId with a name match. Do not synthesize a CRM id from a guess. If a value is missing, leave the field blank and say so.
 
 
+GATE \u2014 DEFER TO TOOL RENDERING. When you call a Leadbay composite that ships its own RENDERING block (every composite in 0.9.0+ does), render the response using that block's recipe verbatim \u2014 score bars, glyph palette, column order, hide-list, link priorities, all of it. Do NOT substitute prose, a numbered list, or a different column structure even when an orchestrating prompt's body suggests alternate framing. Prompt-specific commentary (motivational nudges, summaries, next-action recommendations) belongs ABOVE or BELOW the canonical table, never in place of it.
+
+If the prompt's body and the tool's RENDERING appear to conflict, the tool's RENDERING wins for the structural layout; the prompt's voice wins for the commentary that surrounds it.
+
+
 Research the company with domain '{{arg:domain}}' for me using Leadbay.
 
 # PHASE 1 \u2014 IMPORT + QUALIFY
-Call \`leadbay_import_and_qualify\` with \`domains=[{domain:'{{arg:domain}}'}]\`. This imports the lead AND runs AI qualification in one call. If the response indicates \`quota_blocked\` or \`still_running\`, say so explicitly.
+Call \`leadbay_import_and_qualify\` with \`domains=[{domain:'{{arg:domain}}'}]\`. This imports the lead AND runs AI qualification in one call. If the response indicates \`quota_blocked\` or \`still_running\`, say so explicitly. Render the import status using the canonical terse single-record summary (never an enumeration of every imported lead):
+
+## RENDERING \u2014 import result summary (single-record, terse)
+
+The response carries either a completed result or an async handle. Render a brief summary; do NOT enumerate every imported lead.
+
+**Header \u2014 single line, choose by status:**
+
+- Completed: \`"\u2713 Import complete \u2014 N leads imported \xB7 M failed \xB7 P resolved-with-ambiguity"\`
+- Running: \`"\u23F3 Import running \u2014 handle_id <id>; poll leadbay_import_status"\`
+- Pending qualification (\`leadbay_import_and_qualify\`): \`"\u2713 Imported N leads \xB7 qualifying M of them \u2014 qualify_id <id>"\`
+
+**When failures or ambiguous rows are non-empty**, follow the header with a small bulleted list (\u2264 5 items): \`<row identifier or domain> \xB7 <reason>\`. Then \`"*+N more \u2014 leadbay_import_status for full detail*"\`.
+
+**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_by_id\` in NEXT STEPS.
+
 
 # PHASE 2 \u2014 DEEP DIVE
-When the import resolves, call \`leadbay_research_lead\` on the new leadId.
+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_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\`.
+
+Default to MODE A when uncertain. Always offer the cross-mode pivot at the end so the user can redirect if you guessed wrong.
+
+### Common structure (both modes)
+
+- **Header** (H4 or H5): \`<10-segment score bar>\` \`[Company name](website)\`. Use the score-bar algorithm; the bar lives in a single inline-code span. Prefix \`https://\` to website if it's a bare hostname.
+- **Pill row** (immediately below the header): short location \xB7 compact size \xB7 social pill chips iterated over \`social_urls\` (each non-null platform becomes \`[<platform-label>](<url>)\`) \xB7 \`[website-domain](website)\` \xB7 \`\u260E phone\` when \`phone_numbers[]\` is non-empty (use the first number). All \` \xB7 \`-separated.
+- **Blurb**: render \`description\` (preferred) or \`short_description\` as a single blockquoted paragraph.
+- **Staleness line**: italic, \`"Researched <relative time>"\` from \`web_insights_fetched_at\`. Use \`"today"\` / \`"yesterday"\` / \`"N days ago"\` up to 30 days, then absolute date. Prefix with \`\u26A0\` if older than 30 days.
+- **Contacts table** (always at the bottom):
+  \`\`\`
+  |   | Name | Title | LinkedIn |
+  \`\`\`
+  Markers in column 1:
+  - \`\u2605\` \u2014 \`recommended_contact\` match.
+  - \`\u{1F48E}\` \u2014 name fuzzy-matches a \`hot: true\` entry in \`web_insights\` key_people. (Use \`\u{1F48E}\`, not \`\u{1F525}\`, to avoid glyph collision with the follow-up status badge.)
+  Sort \`\u2605\` first, then \`\u{1F48E}\`-only rows, then API order. Link the name via \`linkedin_page\` first; fall back to LinkedIn people-search with \`<First>+<Last>+<Company>\`. Append \`\xB0\` only when the fallback is in use AND \`social_presence.linkedin == false\`. Cap to 6 rows; if \`contacts_count > shown\`, end with \`"+N more \u2014 ask to see the full list"\`.
+
+### MODE A body (Discovery, fuller, scannable)
+
+Render each non-empty \`web_insights\` section as H5 with the emoji + label intact. Section order: \`\u{1F3E2} company profile\` \u2192 \`\u{1F4C8} business signals\` \u2192 \`\u{1F4A1} prospecting clues\` \u2192 \`\u{1F9E9} strategic positioning\` \u2192 \`\u{1F50E} technologies & innovation\`. Inside each, bullet 3\u20135 items. Sort \`hot: true\` items first. **Bold** the description text of hot items; leave cold items plain. Render \`source\` as \`[source](url)\` at the end; include \`date\` when present. Omit empty sections. Skip \`\u{1F517} social links\` (already in the pill row) and \`\u{1F464} key people\` (already in the contacts table).
+
+### MODE B body (Contact preparation, tighter)
+
+Render exactly two H5 sections:
+
+##### \u{1F3AF} Conversation hooks
+
+Distill the 3 most recent / most hot signals from \`\u{1F4C8} business signals\` and \`\u{1F4A1} prospecting clues\` into one-sentence talking points in salesperson voice. Strip the academic framing. Cite the source inline.
+
+##### \u{1F464} About the person *(only when recommended_contact is non-empty)*
+
+2-line summary: their title + any context from \`web_insights\` key_people. If they appear in a hot signal ("X appointed CEO"), surface that prominently.
+
+Skip \u{1F3E2} profile, \u{1F9E9} strategic positioning, \u{1F50E} technologies in MODE B \u2014 context the user doesn't need for the next 30 seconds.
+
+If \`qualification[]\` is non-empty, append one collapsed line: \`"Qualification: N questions answered, avg boost X"\` and offer to expand in NEXT STEPS.
+
+**Hide:** \`id\`, \`lead.id\`, \`contact.id\`, \`lead.location.pos\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`recommended_contact_title\` (duplicates \`recommended_contact.job_title\`), empty arrays, fields whose value is the string \`"null"\`, \`contact.source\` (internal), insights whose \`source\` is empty.
+
+**Legend (print once below the card):** \`\` \`\u25B0\` firmographic \xB7 \`\u2756\` AI booster \xB7 \`\u25B1\` unfilled \xB7 \u2605 recommended \xB7 \u{1F48E} hot in web_insights \xB7 \xB0 = no company LinkedIn (fallback link only) \`\`
+
+## Linking a contact's name
+
+Two LinkedIn URLs exist and must never be conflated: the **company's** LinkedIn page and an **individual person's** profile.
+
+When the response carries a real contact LinkedIn URL \u2014 \`contact.linkedin_page\` is a string that starts with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it) \u2014 link the contact's name to that URL.
+
+Otherwise fall back to a LinkedIn people-search URL:
+
+\`\`\`
+https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
+\`\`\`
+
+URL-encode the params. Strip Inc / LLC / Corp / Ltd / GmbH suffixes from the company name. Append a trailing \` \xB0\` to the rendered name ONLY when the fallback is in use AND \`social_presence.linkedin == false\` (no company LinkedIn \u2192 search may not resolve). Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa). The two surfaces are different \u2014 conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
 
 # PHASE 3 \u2014 SUMMARY
-Summarize:
+Place a 2\u20133 sentence summary ABOVE the card with:
 - Who is this company (1 sentence)
 - Their fit (cite specific \`qualification_answers\` from the qualification response)
-- What signals stand out (cite specific research findings)
-- Which contact would I email first (name, role, source)
+- Which contact would I email first (one short clause \u2014 the card's contacts table carries the rest)
 
-Be honest about uncertainty: if any field above is missing from tool responses, say "not surfaced by qualification" rather than guessing.
+The card itself handles the signal callouts (\`\u{1F4C8} business signals\`, \`\u{1F4A1} prospecting clues\`). Do NOT re-narrate signals in prose above the card \u2014 that's what the card sections are for. Be honest about uncertainty: if any field is missing from tool responses, say "not surfaced by qualification" rather than guessing.
 `;
 var PROMPT_META = {
-  leadbay_daily_check_in: { "name": "leadbay_daily_check_in", "short_description": `Run the canonical daily check-in: see account state, pull a fresh batch,
-triage the top 10, deep-dive on every promising one, and offer contact
-enrichment. The user's typical morning workflow. Trigger when the user
-asks for "leadbay leads", "best leads to prospect today", "what should
-I work on", or anything resembling "show me the day's batch".
-`, "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", 'Writes flat one-line summaries instead of motivational "why prospect this today" framing', "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'] },
+  leadbay_daily_check_in: { "name": "leadbay_daily_check_in", "short_description": `Run the canonical daily check-in: account state, fresh batch, triage
+top 10, deep-dive every promising one, offer contact enrichment. The
+morning DISCOVERY workflow (new leads from the lens wishlist). Trigger
+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_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
+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_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"] },
-  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_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"] },
+`, "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"] }
+  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 = {
-  leadbay_daily_check_in: `- \`leadbay_daily_check_in\`: Run the canonical daily check-in: see account state, pull a fresh batch, triage the top 10, deep-dive on every promising one, and offer contact enrichment. The user's typical morning workflow. Trigger when the user asks for "leadbay leads", "best leads to prospect today", "what should I work on", or anything resembling "show me the day's batch".`,
+  leadbay_daily_check_in: `- \`leadbay_daily_check_in\`: Run the canonical daily check-in: account state, fresh batch, triage top 10, deep-dive every promising one, offer contact enrichment. The morning DISCOVERY workflow (new leads from the lens wishlist). Trigger 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\`.`,
+  leadbay_followup_check_in: `- \`leadbay_followup_check_in\`: 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 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.`,
   leadbay_import_file: `- \`leadbay_import_file\` (optional args: file, instruction): Import a user-supplied CSV/file into Leadbay through five phases with evidence gates \u2014 scan, derive, resolve identities, preserve & commit, then optionally qualify and report. The job is to maximize how many rows the Leadbay system actually ingests and matches.`,
   leadbay_log_outreach: `- \`leadbay_log_outreach\` (required args: lead_id, summary): Log outreach (an email I sent, a call I made, a meeting I had) on a specific lead. Captures verification so the SDR pipeline trusts the entry.`,
   leadbay_prospecting_overview: `- \`leadbay_prospecting_overview\`: 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".`,
@@ -572,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
       },
       {
@@ -655,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"
     },
     {
@@ -706,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 = [];
@@ -720,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.`;
@@ -734,6 +1256,7 @@ function buildRhythmParagraph(has) {
   return "Suggested rhythm: a healthy agent pattern is a daily check-in \u2014 pull fresh leads, skim the auto-qualified top, deepen 1-3 promising ones, propose outreach to the user. If your host supports scheduling, offer to set up a daily run.";
 }
 var TOOL_REFERENCE_PATTERN = /\bleadbay_[a-z][a-z0-9_]*\b/g;
+var PROMPT_NAMES = new Set(Object.keys(PROMPT_CATALOG_BULLETS));
 function buildPromptsCatalogParagraph(has) {
   const safeBullets = [];
   for (const [promptName, bullet] of Object.entries(PROMPT_CATALOG_BULLETS)) {
@@ -741,6 +1264,7 @@ function buildPromptsCatalogParagraph(has) {
     for (const match of bullet.matchAll(TOOL_REFERENCE_PATTERN)) {
       const name = match[0];
       if (name === promptName) continue;
+      if (PROMPT_NAMES.has(name)) continue;
       referencedTools.add(name);
     }
     const allExposed = [...referencedTools].every((n) => has(n));
@@ -801,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));
@@ -808,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) {
@@ -938,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) {
@@ -995,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
         };
@@ -1011,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
 `
           );
         }
@@ -1029,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
       };
@@ -1061,7 +1661,7 @@ function buildServer(client, opts = {}) {
 
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.9.0";
+var VERSION = "0.10.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -1097,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)
   {
@@ -1106,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"
         }
       }
     }
@@ -1350,7 +1958,7 @@ async function runLogin(args) {
   let result;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-IIPWWDS5.js");
+      const { REGIONS } = await import("./dist-BHLIJAIH.js");
       const baseUrl = REGIONS[pinnedRegion];
       const c = createClient({ region: pinnedRegion });
       const token = await loginAt(baseUrl, email, password);
@@ -1677,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",
@@ -1687,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 = "";
@@ -1713,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");
@@ -1733,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 = {
@@ -1761,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;
   }
@@ -1842,7 +2457,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-IIPWWDS5.js");
+      const { REGIONS } = await import("./dist-BHLIJAIH.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;
@@ -1869,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) {
@@ -1888,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 });
   }
@@ -1978,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 });
@@ -1987,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 {
@@ -2006,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);
   });
 }