@leadbay/mcp 0.10.1 → 0.12.0

package/dist/bin.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  LeadbayClient,
   compositeReadTools,
   compositeWriteTools,
   createClient,
@@ -8,7 +9,7 @@ import {
   granularReadTools,
   granularWriteTools,
   resolveRegion
-} from "./chunk-F3EWCHME.js";
+} from "./chunk-J2Y4LCFM.js";
 
 // src/bin.ts
 import { realpathSync } from "fs";
@@ -128,25 +129,20 @@ If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is nul
 
 **Column 3 \u2014 Contact**
 
-\`[Contact name](LINK) \xB7 short job title\`. See linking/contact-linkedin for LINK priority and the \xB0-flag fallback.
+\`[Contact name](LINK) \xB7 short job title\`. The \`[Contact name](LINK)\` markdown link wrapping is mandatory \u2014 never render the name as plain text. See linking/contact-linkedin for the URL priority (real profile \u2192 constructed people-search) 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.
+**MANDATORY: every contact name in your output \u2014 table cells, prose, headers, "Reach <Name>" callouts \u2014 MUST be wrapped in markdown link syntax \`[Name](URL)\`. Never render a contact name as bare text. A plain-text name is a broken contact card; the underlined name is the user's primary affordance for "take me to this person's profile". No "no URL available" exception \u2014 the search URL below is always constructable from name + company.**
 
-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.
+URL priority (first applicable wins):
 
-Otherwise fall back to a LinkedIn people-search URL:
+1. **Real profile** \u2014 \`contact.linkedin_page\` when it's a string starting with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it).
+2. **Constructed people-search** \u2014 \`https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>\`. URL-encode params. Strip Inc / LLC / Corp / Ltd / GmbH / Co / S.A. / S.L. / PLC / AG / SAS / SARL suffixes from the company. Append a trailing \` \xB0\` to the rendered name ONLY when this fallback is in use AND \`social_presence.linkedin == false\`. Never append \`\xB0\` when a real \`linkedin_page\` was used.
 
-\`\`\`
-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.
+Never link a person's name to the company's LinkedIn page (and vice versa) \u2014 the two surfaces are different and conflating them quietly degrades the workflow.
 
 ## Linking the company
 
@@ -365,6 +361,55 @@ After I answer, call \`leadbay_report_outreach({lead_id: '{{arg:lead_id}}', note
 # PHASE 3 \u2014 CONFIRM
 Tell me the outreach was logged, name the verification.source used, and surface the response's \`outreach_id\` if present so I can refer back to it.
 `;
+var leadbay_plan_tour_in_city = `
+Plan a field sales tour for me in **{{arg:city}}**{{arg:date_paren}}.
+
+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 BUILD THE ITINERARY
+
+Call \`leadbay_tour_plan({city: "{{arg:city}}"})\` with the default counts (6 follow-ups + 6 discover). If the response is \`status: "ambiguous_locations"\`, surface the candidates and ask me to pick one, then re-call with \`city_id\`.
+
+Split the returned \`monitor_leads\` into two buckets client-side using \`last_monitor_action\`:
+
+- **Customers** \u2014 leads with any \`last_monitor_action\` history (CONTACTED, MEETING_BOOKED, etc.). Treat as known accounts with prior engagement.
+- **Qualified prospects** \u2014 leads with high \`ai_agent_lead_score\` (or \`score\`) but no recent action.
+
+\`discover_leads\` are the **New** bucket.
+
+Aim for a 3+3+3 split if possible. If the customers bucket has fewer than 3, fill from qualified. If discover_filter_note indicates a low match ratio for the city, mention it: "Only N/30 fresh leads matched your city" \u2014 better honest than padded.
+
+# PHASE 2 \u2014 RENDER THE MAP
+
+Route the union of \`monitor_leads + discover_leads\` into \`places_map_display_v0\` (when the host exposes it). Per-lead \`notes\` string:
+
+- \`\u2605 Customer \u2014 <one-sentence sector + why-now>. Reach <name>, <role>: <bare phone>, <bare email>.\`
+- \`\u2605 Qualified \u2014 <one-sentence>. Reach <name>...\`
+- \`\u2726 New \u2014 <one-sentence>. Reach <name>...\`
+
+Skip leads with \`location.pos === null\` (no coordinates \u2192 no pin) \u2014 list them as "+ N leads without coordinates" below the widget.
+
+Below the widget, emit a chat-prose summary grouped by mode (Customers / Qualified / New), with LinkedIn-linked contact name + bare phone/email pills per lead. Use the canonical \`linking/contact-linkedin\` rules.
+
+# PHASE 3 \u2014 DRAFT IN-AREA OUTREACH (optional, ask first)
+
+After the map, ask me ONCE: "Want me to draft 'I'll be in {{arg:city}}{{arg:date_paren}}' outreach for the top accounts?" If I say yes, for each of the top 3 leads (1 Customer / 1 Qualified / 1 New), call \`leadbay_prepare_outreach(leadId)\` and route the draft through \`message_compose_v1\` with a single variant labeled "In-area visit" \u2014 body opens with the visit context, references the AI-summary angle, ends with a clear ask (15-min coffee / on-site stopover).
+
+Serialize the prepare_outreach calls (max 3 in parallel \u2014 see the long-running-tools rule).
+
+# PHASE 4 \u2014 PERSIST AS A CAMPAIGN (optional, ask first)
+
+After drafts, ask me ONCE: "Save these 9 accounts as a campaign called '**{{arg:city}} Tour{{arg:date_dash}}**'?" If I say yes, call \`leadbay_create_campaign({lead_ids: [...all_nine_lead_ids], name: "{{arg:city}} Tour{{arg:date_dash}}"})\`. Surface the returned \`id\` + \`name\` as a confirmation line, and offer the NEXT STEPS chip "View progression" (which routes to \`leadbay_campaign_progression\`).
+
+If I declined the campaign step, end the turn \u2014 the map + drafts are enough for an ad-hoc trip.
+
+# PHASE 5 \u2014 STOP
+
+Done. The map is the surface; the drafts are the action; the campaign is the persistence layer for managerial follow-up after the trip.
+`;
 var leadbay_prospecting_overview = `
 # Leadbay Prospecting \u2014 Orientation
 
@@ -585,25 +630,20 @@ If \`qualification_summary.answered == 0\` or \`avg_qualification_boost\` is nul
 
 **Column 3 \u2014 Contact**
 
-\`[Contact name](LINK) \xB7 short job title\`. See linking/contact-linkedin for LINK priority and the \xB0-flag fallback.
+\`[Contact name](LINK) \xB7 short job title\`. The \`[Contact name](LINK)\` markdown link wrapping is mandatory \u2014 never render the name as plain text. See linking/contact-linkedin for the URL priority (real profile \u2192 constructed people-search) 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:
+**MANDATORY: every contact name in your output \u2014 table cells, prose, headers, "Reach <Name>" callouts \u2014 MUST be wrapped in markdown link syntax \`[Name](URL)\`. Never render a contact name as bare text. A plain-text name is a broken contact card; the underlined name is the user's primary affordance for "take me to this person's profile". No "no URL available" exception \u2014 the search URL below is always constructable from name + company.**
 
-\`\`\`
-https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>
-\`\`\`
+URL priority (first applicable wins):
 
-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.
+1. **Real profile** \u2014 \`contact.linkedin_page\` when it's a string starting with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it).
+2. **Constructed people-search** \u2014 \`https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>\`. URL-encode params. Strip Inc / LLC / Corp / Ltd / GmbH / Co / S.A. / S.L. / PLC / AG / SAS / SARL suffixes from the company. Append a trailing \` \xB0\` to the rendered name ONLY when this fallback is in use AND \`social_presence.linkedin == false\`. 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.
+Never link a person's name to the company's LinkedIn page (and vice versa) \u2014 the two surfaces are different and conflating them quietly degrades the workflow.
 
 ## Linking the company
 
@@ -718,19 +758,14 @@ If \`qualification[]\` is non-empty, append one collapsed line: \`"Qualification
 
 ## 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.
+**MANDATORY: every contact name in your output \u2014 table cells, prose, headers, "Reach <Name>" callouts \u2014 MUST be wrapped in markdown link syntax \`[Name](URL)\`. Never render a contact name as bare text. A plain-text name is a broken contact card; the underlined name is the user's primary affordance for "take me to this person's profile". No "no URL available" exception \u2014 the search URL below is always constructable from name + company.**
 
-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.
+URL priority (first applicable wins):
 
-Otherwise fall back to a LinkedIn people-search URL:
+1. **Real profile** \u2014 \`contact.linkedin_page\` when it's a string starting with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it).
+2. **Constructed people-search** \u2014 \`https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>\`. URL-encode params. Strip Inc / LLC / Corp / Ltd / GmbH / Co / S.A. / S.L. / PLC / AG / SAS / SARL suffixes from the company. Append a trailing \` \xB0\` to the rendered name ONLY when this fallback is in use AND \`social_presence.linkedin == false\`. Never append \`\xB0\` when a real \`linkedin_page\` was used.
 
-\`\`\`
-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.
+Never link a person's name to the company's LinkedIn page (and vice versa) \u2014 the two surfaces are different and conflating them quietly degrades the workflow.
 
 ## Linking the company
 
@@ -750,6 +785,160 @@ Place a 2\u20133 sentence summary ABOVE the card with:
 
 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 leadbay_setup_team_prospecting = `
+Set up manager-led prospecting for me: turn the audience into a lens, validate candidates, then persist as named campaigns.
+
+Audience: **{{arg:audience}}**
+{{arg:rep_split_block}}
+
+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 INTERPRET INTENT INTO A LENS
+
+Call \`leadbay_refine_prompt({user_prompt: "{{arg:audience}}"})\`. This handles the clarification protocol natively \u2014 if the system needs more info (e.g. industry disambiguation, geography precision), it returns \`status: "clarification_needed"\` with options. Surface those to me; on my answer, re-call \`leadbay_refine_prompt\` until the prompt converges.
+
+When the prompt has converged, call \`leadbay_create_lens({user_prompt: <refined>, name: "<short descriptive name>"})\` to create a draft lens, then \`leadbay_promote_lens({lensId})\` to make it the active lens.
+
+# PHASE 2 \u2014 PULL + VALIDATE CANDIDATES
+
+Call \`leadbay_pull_leads({count: 20, lensId: <the new lens id>})\` to surface the top 20 candidates from the freshly-created lens. Render with the canonical \`pull_leads\` table layout.
+
+Ask me ONCE: "Want me to deep-research the top N for validation?" If yes, call \`leadbay_research_lead_by_id\` serialized over the top 3-5 (one at a time, max 3 in parallel per the long-running-tools rule). Surface a research summary per lead.
+
+Then ask me ONCE: "Which of these should we drop?" If I name leads to drop, exclude them from the working set. The remaining is the validated set.
+
+# PHASE 3 \u2014 DECIDE THE CAMPAIGN SHAPE
+
+If I provided a \`rep_split\` ("one campaign per rep: John gets Tulsa, Sarah gets OKC"), partition the validated leads accordingly. If I didn't, ask ONCE: "Create one campaign for the whole batch, or split per rep / region / sector?" \u2014 surface 2-4 options via \`ask_user_input_v0\` when available, else as a bulleted list.
+
+For each campaign-shape decision, derive a name. Templates:
+- Whole batch: \`"<lens-name> \u2013 <YYYY-MM-DD>"\`
+- Per rep: \`"<lens-name> \u2013 <RepName>"\`
+- Per region: \`"<lens-name> \u2013 <RegionName>"\`
+
+# PHASE 4 \u2014 PERSIST
+
+For each campaign-shape partition, call \`leadbay_create_campaign({lead_ids: [...partition], name: "<derived>"})\`. Surface the returned \`id\` + \`name\` per campaign as a confirmation line.
+
+# PHASE 5 \u2014 BE HONEST ABOUT SCOPE
+
+Once the campaigns are created, surface this caveat in plain prose:
+
+> Campaign visibility is currently scoped to the user who CREATED the campaign \u2014 the reps won't see these in their own MCP \`leadbay_list_campaigns\` calls. They CAN see them in the web UI at app.leadbay.ai \u2192 Campaigns. Cross-user MCP visibility would need backend work; flag this as a #3630 US3 product gap if your reps work primarily through MCP.
+
+End with a NEXT STEPS chip via \`ask_user_input_v0\`: "View progression on one of these now?" \u2192 routes to \`leadbay_campaign_progression\`.
+
+# PHASE 6 \u2014 STOP
+
+Done. The lens is live, the validated cohort is persisted as named campaigns, and the manager knows where the cross-user-visibility gap is.
+`;
+var leadbay_work_campaign = `
+Work my **{{arg:campaign_or_default}}** campaign as an outreach session{{arg:mode_paren}}.
+
+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 0 \u2014 PICK THE CAMPAIGN
+
+If I gave you a name or id, resolve it. Otherwise call \`leadbay_list_campaigns()\` and surface the active campaigns as a \`single_select\` via \`ask_user_input_v0\` (cap at 4 \u2014 sort by \`updated_at\` desc, archived hidden):
+
+> Which campaign do you want to work?
+> - <Name 1> \xB7 <N leads> \xB7 last touched <date>
+> - <Name 2> \xB7 <N leads> \xB7 last touched <date>
+> - \u2026
+
+When the user picks, capture the \`campaign_id\`. If \`{{arg:campaign}}\` is a name, fuzzy-match against \`campaigns[].campaign.name\`. On ambiguous matches, surface a \`single_select\` instead of guessing.
+
+# PHASE 1 \u2014 FETCH + ASSESS READINESS (the load-bearing phase)
+
+Call \`leadbay_campaign_call_sheet({campaign_id})\`. The response carries \`summary\` + \`readiness\` \u2014 use them to figure out what the user CAN actually do today, then PROPOSE the right session mode rather than auto-rendering.
+
+**Read the summary numbers**:
+- \`total_leads\`, \`total_contacts\`
+- \`leads_with_phone\` \u2014 can call from this many leads
+- \`leads_with_email\` \u2014 can email this many
+- \`leads_with_coords\` \u2014 can map this many
+- \`leads_without_contacts\` \u2014 these need enrichment before any outreach is possible
+- \`leads_already_contacted\` \u2014 these have prior touches; the rep may want to skip them for cold work
+
+**Read the \`readiness\` booleans** (pre-computed thresholds):
+- \`ready_for_calling\` (phone coverage \u226560%) \u2014 call session viable
+- \`ready_for_emailing\` (email coverage \u226560%) \u2014 email session viable
+- \`needs_enrichment\` (\u226530% no-contacts OR both phone+email coverage <40%) \u2014 enrichment recommended first
+- \`travel_friendly\` (\u22655 geocoded leads AND coord coverage \u226560%) \u2014 map mode worth proposing
+
+**One-line situation report** (always emit BEFORE the proposal):
+
+\`\`\`
+\u{1F4CB} <total_leads> leads \xB7 \u{1F4DE} <leads_with_phone> with a phone \xB7 \u2709 <leads_with_email> with an email \xB7 \u{1F5FA} <leads_with_coords> with coords \xB7 \u{1F534} <leads_without_contacts> need enrichment \xB7 \u2705 <leads_already_contacted> already touched
+\`\`\`
+
+**Then PROPOSE the right modes via \`ask_user_input_v0\`** (2-4 options, sorted by what makes the most sense for THIS campaign's data):
+
+- "\u{1F4DE} Start calling now" \u2014 IF \`ready_for_calling\`. Top option when phones are there.
+- "\u2709 Email session instead" \u2014 IF \`ready_for_emailing\` AND \`email_ratio > phone_ratio\`. Don't surface this when calling is more obvious.
+- "\u{1F527} Enrich titles first" \u2014 IF \`needs_enrichment\`. Top option when most leads have no contacts. Phrase as "<N> leads have no reachable contact yet \u2014 enrich titles before we start?" so the user understands the cost.
+- "\u{1F5FA} View on a map" \u2014 IF \`travel_friendly\` **AND** the user hasn't previously signaled disinterest in maps (check your conversation memory; if you've seen the user dismiss map renders before in this session or saved a "no maps" preference, drop this option).
+
+If the MCP prompt argument \`mode\` was actually supplied, skip the proposal and jump to the matching mode below. If \`mode\` was omitted, do not treat \`call_sheet\` as implicit user consent \u2014 propose first.
+
+# PHASE 2A \u2014 CALL-SHEET MODE (default after "\u{1F4DE} Start calling now")
+
+Render per the \`leadbay_campaign_call_sheet\` RENDERING block \u2014 one CARD per lead with the 4-col contact table (Contact / Phone / Role / Recent). The phone in column 2 MUST be \`[bare](tel:URL)\` (use \`contact.phone_tel_url\` verbatim \u2014 the composite has already canonicalized it). The contact name in column 1 MUST be \`[Name](linkedin_url)\`. Email stacks under the name when present (\`\u2709 [email](mailto_url)\`). Recent stacks \`\u{1F4DD} last note\` + \`\u{1F4DE} last_action_headline\`.
+
+End the turn with the standby line:
+
+> Ready to start calling. Tell me what happened after each call \u2014 I'll record the note + outcome.
+
+# PHASE 2B \u2014 EMAIL-SHEET MODE (after "\u2709 Email session instead")
+
+Same data, slightly different render emphasis: drop the Phone column, put \`\u2709 [email](mailto_url)\` as column 2. Below each lead's table, generate a SUGGESTED short email draft per the next-step \u2014 but DON'T send. Drafts are for the user to copy-paste / send themselves.
+
+# PHASE 2C \u2014 ENRICH-FIRST MODE (after "\u{1F527} Enrich titles first")
+
+Extract \`leadIds\` from \`sheet.leads[].lead_id\`, then call \`leadbay_enrich_titles({leadIds, \u2026})\` (consult its description for titles / email / phone selection; do not pass \`campaign_id\`, because that is not part of the tool schema). Surface progress to the user. When complete, automatically loop back to Phase 1 (re-fetch the call sheet, re-assess readiness, re-propose).
+
+# PHASE 2D \u2014 MAP MODE (after "\u{1F5FA} View on a map")
+
+Pass \`response.map_locations\` directly to \`places_map_display_v0\` \u2014 the composite has already built the per-pin notes string with the top contact's phone inline. After the widget, emit the standard 4-col card list anyway so the rich detail is still scannable.
+
+# PHASE 3 \u2014 RECORD OUTCOMES, ONE AT A TIME (after the user starts dictating)
+
+When the user says something like *"Called Bree, voicemail, trying again Tuesday"* or *"Talked to John, wants pricing sent next week"*, parse:
+
+1. **Which lead** \u2014 by company name OR contact name (cross-reference with the cards you just rendered).
+2. **The note** \u2014 the user's exact words about what happened (the SDR's voice \u2014 don't paraphrase).
+3. **The outcome** \u2014 pick ONE of these four epilogue values based on what the user said:
+   - \`STILL_CHASING\` \u2014 pursuing, no decision yet ("trying again", "they'll get back to me")
+   - \`COULD_NOT_REACH_STILL_TRYING\` \u2014 voicemail, no answer, wrong number, gatekeeper blocked
+   - \`INTEREST_VALIDATED_OR_MEETING_PLANED\` \u2014 meeting booked, quote requested, "send me more info"
+   - \`NOT_INTERESTED_LOST\` \u2014 declined, "not now", "not a fit", "remove from list"
+
+Call \`leadbay_report_outreach({lead_id, note: <user's words>, epilogue_status: <picked>, verification: {source: "user_confirmed", ref: <user's exact words verbatim>}})\`. Confirm in ONE line: *"\u2705 Logged: <Company> \u2192 <epilogue>. Next?"*
+
+Then wait for the next dictation. Don't ask "anything else?" \u2014 just acknowledge and wait.
+
+# PHASE 4 \u2014 STOP
+
+When the user says "done" / "that's it" / "wrapping up" / similar, surface a session summary chip:
+
+> Session complete \u2014 N calls logged: X meetings booked \xB7 Y still chasing \xB7 Z couldn't reach \xB7 W declined.
+
+Optional: offer to review the \`leadbay_campaign_progression\` for the same campaign to see the updated counts.
+
+# Iron laws
+
+- The \`verification\` field on \`leadbay_report_outreach\` is REQUIRED. For calls (no message id), always use \`{source: "user_confirmed", ref: <user's verbatim words>}\`. Skipping it is forbidden; fabricating a gmail_message_id for a call is forbidden.
+- ONE call \u2192 ONE \`leadbay_report_outreach\` invocation. Don't batch; each call has its own note + outcome.
+- Map mode is OPT-IN, never automatic. The user invokes it via the proposal options or by passing \`mode=map\`.
+- If you've seen the user dismiss / dislike map renders earlier in the session, don't propose map mode again.
+- If the user dictates an outcome that doesn't cleanly map to one of the four epilogue values, ASK ONCE before guessing.
+`;
 var PROMPT_META = {
   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
@@ -769,6 +958,7 @@ 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_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_plan_tour_in_city: { "name": "leadbay_plan_tour_in_city", "short_description": "Plan a field sales tour: in one flow, surface follow-ups + fresh\nDiscover leads in the target city via `leadbay_tour_plan`, render\nto a map, draft in-area outreach via `leadbay_prepare_outreach`,\nand optionally persist the selected accounts as a named campaign\nvia `leadbay_create_campaign`. Closes #3630 US1 end-to-end.\n", "arguments": [{ "name": "city", "description": "City or region the user is visiting (e.g. 'Limoges', 'Bay Area'). Used as the geo filter for both Monitor and Discover lookups.", "required": true }, { "name": "date", "description": "When the visit is (e.g. 'May 24', 'next Thursday'). Surfaced in the outreach drafts as 'I'll be in <city> on <date>'.", "required": false }], "expected_calls": ["leadbay_tour_plan", "leadbay_research_lead_by_id", "leadbay_prepare_outreach", "leadbay_create_campaign"], "failure_modes": ["Calls leadbay_followups_map (Monitor-only) instead of leadbay_tour_plan \u2014 loses the Discover (fresh-lead) half that the user explicitly asked for", "Calls leadbay_pull_leads then drops the geo filter \u2014 returns the lens-wide wishlist instead of city-relevant fresh leads", 'Skips the campaign-persist step ("would you like to save these as a tour?") \u2014 leaves the rep with a one-shot map but no follow-up artifact', "Creates a campaign WITHOUT asking the user first \u2014 the persist step is high-intent; offer it, don't assume", "Fabricates lead_ids when seeding the campaign instead of using the ids returned by tour_plan"] },
   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
@@ -778,7 +968,9 @@ 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_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_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"] }
+  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"] },
+  leadbay_setup_team_prospecting: { "name": "leadbay_setup_team_prospecting", "short_description": "Manager-led prospecting setup: conversationally turn a natural-language\naudience ask into a Leadbay lens, validate the candidate leads, and\npersist them as one or more named campaigns the rep(s) can work\nthrough. Closes #3630 US3 end-to-end (within the current\ncreator-scoped campaign visibility model).\n", "arguments": [{ "name": "audience", "description": "Natural-language audience description (e.g. 'plumbing companies with 10-50 employees in Seine-Maritime'). The lens-creation step (`leadbay_refine_prompt` \u2192 `leadbay_create_lens`) interprets it.", "required": true }, { "name": "rep_split", "description": "Optional: how to split the validated leads into per-rep campaigns. Free text \u2014 e.g. 'split by city' or 'one campaign per rep: John gets Tulsa, Sarah gets OKC'.", "required": false }], "expected_calls": ["leadbay_refine_prompt", "leadbay_create_lens", "leadbay_promote_lens", "leadbay_pull_leads", "leadbay_research_lead_by_id", "leadbay_create_campaign", "leadbay_add_leads_to_campaign"], "failure_modes": ["Skips the validation step \u2014 creates a campaign of unvetted leads from a freshly-created lens without giving the manager a chance to drop weak fits", "Creates ONE campaign for all reps without asking about the split \u2014 the user explicitly mentioned per-rep distribution and the prompt should honor it", "Pretends the backend supports cross-user assignment \u2014 campaigns are owned by the caller (creator-scoped). Surface this honestly instead of fabricating an assignment model", "Asks ALL clarifying questions inline before tool calls \u2014 instead, run the lens refinement loop with `leadbay_refine_prompt` which handles the clarification protocol natively"] },
+  leadbay_work_campaign: { "name": "leadbay_work_campaign", "short_description": "Work a campaign as a real outreach session: pick the campaign,\nassess what the user has (phones / emails / coords), then PROPOSE\nthe right session mode (call sheet, email sheet, enrich titles\nfirst, map). After they pick, render \u2014 and as they dictate\noutcomes per lead, record both note + epilogue via\n`leadbay_report_outreach` in one round trip.\n", "arguments": [{ "name": "campaign", "description": "Campaign name (fuzzy match against your own campaigns) or campaign UUID. Omit to list and pick interactively.", "required": false }, { "name": "mode", "description": "Optional: skip the readiness-assessment proposal and jump directly into 'call_sheet' / 'email_sheet' / 'map' / 'enrich_first'. Omit (recommended) and let the prompt propose based on the data.", "required": false }], "expected_calls": ["leadbay_list_campaigns", "leadbay_campaign_call_sheet", "leadbay_enrich_titles", "leadbay_report_outreach"], "failure_modes": ["Renders the call sheet immediately without proposing the right mode \u2014 if 60% of leads have no contacts, calling is futile; enrich first. Always assess `readiness` first.", "Auto-renders the map widget without asking \u2014 maps are intrusive when the user just wants to scroll a list. Map mode is a proposed option, not a default.", "Proposes map mode after the user has previously said they don't like maps \u2014 check conversation memory before adding 'View on a map' to the options list.", "Calls `leadbay_campaign_progression` instead of `leadbay_campaign_call_sheet` \u2014 progression has counts but no phones / LinkedIn / call-ready data; the user can't actually dial from progression rows.", "Renders contacts WITHOUT making the phone number a `[bare](tel:URL)` link \u2014 on mobile that breaks one-tap calling, which is the whole point of the cheat sheet.", "Records outreach WITHOUT epilogue_status \u2014 leaves the lead's pipeline state unchanged; the rep then sees the same lead surfaced again next session.", "Records outreach WITHOUT verification \u2014 verification.source/ref is REQUIRED. For calls, pass `{source: 'user_confirmed', ref: <user's exact words>}`.", "Loops through ALL leads in a 50-lead campaign before recording any outreach \u2014 the call-then-record loop must be per-lead, not batched."] }
 };
 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 = {
@@ -786,10 +978,13 @@ var PROMPT_CATALOG_BULLETS = {
   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_plan_tour_in_city: `- \`leadbay_plan_tour_in_city\` (required args: city; optional args: date): Plan a field sales tour: in one flow, surface follow-ups + fresh Discover leads in the target city via \`leadbay_tour_plan\`, render to a map, draft in-area outreach via \`leadbay_prepare_outreach\`, and optionally persist the selected accounts as a named campaign via \`leadbay_create_campaign\`. Closes #3630 US1 end-to-end.`,
   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".`,
   leadbay_qualify_top_n: `- \`leadbay_qualify_top_n\` (optional args: count): Bulk-qualify the top N un-qualified leads in the active lens. Uses leadbay_bulk_qualify_leads with a sensible default budget.`,
   leadbay_refine_audience: `- \`leadbay_refine_audience\` (required args: instruction): Refine the kind of leads Leadbay surfaces beyond firmographics, with a free-text instruction. Handles the clarification round-trip if the new prompt is ambiguous.`,
-  leadbay_research_a_domain: `- \`leadbay_research_a_domain\` (required args: domain): Import a company by domain and run deep qualification + research in one pass. Use when a colleague mentions a name and you want everything Leadbay knows about it.`
+  leadbay_research_a_domain: `- \`leadbay_research_a_domain\` (required args: domain): Import a company by domain and run deep qualification + research in one pass. Use when a colleague mentions a name and you want everything Leadbay knows about it.`,
+  leadbay_setup_team_prospecting: `- \`leadbay_setup_team_prospecting\` (required args: audience; optional args: rep_split): Manager-led prospecting setup: conversationally turn a natural-language audience ask into a Leadbay lens, validate the candidate leads, and persist them as one or more named campaigns the rep(s) can work through. Closes #3630 US3 end-to-end (within the current creator-scoped campaign visibility model).`,
+  leadbay_work_campaign: `- \`leadbay_work_campaign\` (optional args: campaign, mode): Work a campaign as a real outreach session: pick the campaign, assess what the user has (phones / emails / coords), then PROPOSE the right session mode (call sheet, email sheet, enrich titles first, map). After they pick, render \u2014 and as they dictate outcomes per lead, record both note + epilogue via \`leadbay_report_outreach\` in one round trip.`
 };
 
 // src/prompts.ts
@@ -900,6 +1095,80 @@ var CATALOG = [
       )
     ]
   },
+  {
+    name: "leadbay_plan_tour_in_city",
+    description: PROMPT_META.leadbay_plan_tour_in_city.short_description,
+    arguments: [
+      {
+        name: "city",
+        description: "City or region the user is visiting (e.g. 'Limoges', 'Bay Area'). Used as the geo filter for both Monitor and Discover lookups.",
+        required: true
+      },
+      {
+        name: "date",
+        description: "When the visit is (e.g. 'May 24', 'next Thursday'). Surfaced in the outreach drafts as 'I'll be in <city> on <date>'.",
+        required: false
+      }
+    ],
+    render: (args) => [
+      userMessage(
+        substitutePlaceholders(leadbay_plan_tour_in_city, {
+          city: args.city ?? "<missing>",
+          date_paren: args.date ? ` on ${args.date}` : "",
+          date_dash: args.date ? ` \u2013 ${args.date}` : ""
+        })
+      )
+    ]
+  },
+  {
+    name: "leadbay_setup_team_prospecting",
+    description: PROMPT_META.leadbay_setup_team_prospecting.short_description,
+    arguments: [
+      {
+        name: "audience",
+        description: "Natural-language audience description (e.g. 'plumbing companies with 10-50 employees in Seine-Maritime').",
+        required: true
+      },
+      {
+        name: "rep_split",
+        description: "Optional: how to split validated leads into per-rep campaigns. Free text (e.g. 'split by city', 'one campaign per rep').",
+        required: false
+      }
+    ],
+    render: (args) => [
+      userMessage(
+        substitutePlaceholders(leadbay_setup_team_prospecting, {
+          audience: args.audience ?? "<missing>",
+          rep_split_block: args.rep_split ? `Rep split preference: **${args.rep_split}**
+` : ""
+        })
+      )
+    ]
+  },
+  {
+    name: "leadbay_work_campaign",
+    description: PROMPT_META.leadbay_work_campaign.short_description,
+    arguments: [
+      {
+        name: "campaign",
+        description: "Campaign name (fuzzy match) or campaign UUID. Omit to list and pick interactively.",
+        required: false
+      },
+      {
+        name: "mode",
+        description: "Optional: skip readiness proposal and jump to 'call_sheet', 'email_sheet', 'map', or 'enrich_first'. Omit to let the prompt propose based on campaign data.",
+        required: false
+      }
+    ],
+    render: (args) => [
+      userMessage(
+        substitutePlaceholders(leadbay_work_campaign, {
+          campaign_or_default: args.campaign ?? "<pick from the list>",
+          mode_paren: args.mode ? ` (mode: ${args.mode})` : ""
+        })
+      )
+    ]
+  },
   {
     name: "leadbay_qualify_top_n",
     description: PROMPT_META.leadbay_qualify_top_n.short_description,
@@ -1032,6 +1301,12 @@ var EMBEDDED_SENTRY_DSN = "https://301f1c433433b76132956ed5415bea19@o45058744368
 var EV_TOOL_CALL = "mcp tool called";
 var EV_QUOTA_HIT = "mcp quota hit";
 var EV_TOPUP_LINK = "mcp topup link created";
+var EV_STARTUP = "mcp startup";
+var EV_MCP_UPDATE_CHECK = "mcp update check";
+var EV_MCP_UPDATE_PROMPTED = "mcp update prompted";
+var EV_MCP_UPDATE_INSTALL_CLICKED = "mcp update install_clicked";
+var EV_MCP_UPDATE_DISMISSED = "mcp update dismissed";
+var EV_MCP_VERSION_UPDATED = "mcp version updated";
 
 // src/telemetry.ts
 var NOOP_TELEMETRY = {
@@ -1043,8 +1318,20 @@ var NOOP_TELEMETRY = {
   },
   captureTopupLink: () => {
   },
+  captureStartup: () => {
+  },
   captureException: () => {
   },
+  captureUpdateCheck: () => {
+  },
+  captureUpdatePrompted: () => {
+  },
+  captureUpdateInstallClicked: () => {
+  },
+  captureUpdateDismissed: () => {
+  },
+  captureVersionUpdated: () => {
+  },
   shutdown: async () => {
   }
 };
@@ -1088,7 +1375,12 @@ function initTelemetry(opts) {
         profilesSampleRate: 0,
         defaultIntegrations: false,
         integrations: [Sentry.httpIntegration()],
-        sendDefaultPii: false
+        sendDefaultPii: false,
+        // Tag every captured event with the surface so Sentry views can
+        // split MCP issues from web-app issues without per-call work.
+        initialScope: {
+          tags: { source: "mcp" }
+        }
       });
       sentryReady = true;
     }
@@ -1105,6 +1397,11 @@ function initTelemetry(opts) {
   const pendingEvents = [];
   let region = "unknown";
   const baseProps = () => ({
+    // Always tag MCP-originated events so PostHog dashboards can split
+    // MCP usage from the web app and any future surfaces. The value
+    // ("mcp") is the canonical source identifier — match it in any
+    // PostHog filter or insight that should isolate the MCP surface.
+    source: "mcp",
     mcp_version: version,
     node_version: process.versions.node,
     platform: process.platform,
@@ -1204,6 +1501,24 @@ function initTelemetry(opts) {
     captureTopupLink(props) {
       emit(EV_TOPUP_LINK, { ...props });
     },
+    captureStartup(props) {
+      emit(EV_STARTUP, { ...props });
+    },
+    captureUpdateCheck(props) {
+      emit(EV_MCP_UPDATE_CHECK, { ...props });
+    },
+    captureUpdatePrompted(props) {
+      emit(EV_MCP_UPDATE_PROMPTED, { ...props });
+    },
+    captureUpdateInstallClicked(props) {
+      emit(EV_MCP_UPDATE_INSTALL_CLICKED, { ...props });
+    },
+    captureUpdateDismissed(props) {
+      emit(EV_MCP_UPDATE_DISMISSED, { ...props });
+    },
+    captureVersionUpdated(props) {
+      emit(EV_MCP_VERSION_UPDATED, { ...props });
+    },
     captureException(err, ctx) {
       if (!sentryReady) return;
       try {
@@ -1227,6 +1542,327 @@ function initTelemetry(opts) {
   };
 }
 
+// src/update-check.ts
+var cachedInfo = null;
+var checkInFlight = false;
+function getCachedUpdateInfo() {
+  return cachedInfo;
+}
+var RELEASES_LATEST_URL = "https://api.github.com/repos/leadbay/leadclaw/releases/latest";
+var CHECK_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 5e3;
+var USER_AGENT = "leadbay-mcp-update-check";
+function parseTagName(tag) {
+  const stripped = tag.replace(/^mcp-v?/, "").replace(/^v/, "");
+  if (!/^\d+\.\d+\.\d+/.test(stripped)) return null;
+  return stripped;
+}
+function compareSemver(a, b) {
+  const [aCore, aPre] = a.split("-", 2);
+  const [bCore, bPre] = b.split("-", 2);
+  const aParts = aCore.split(".").map((n) => parseInt(n, 10));
+  const bParts = bCore.split(".").map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const av = aParts[i] ?? 0;
+    const bv = bParts[i] ?? 0;
+    if (av > bv) return 1;
+    if (av < bv) return -1;
+  }
+  if (!aPre && !bPre) return 0;
+  if (!aPre && bPre) return 1;
+  if (aPre && !bPre) return -1;
+  const aIds = aPre.split(".");
+  const bIds = bPre.split(".");
+  const len = Math.max(aIds.length, bIds.length);
+  for (let i = 0; i < len; i++) {
+    const ai = aIds[i];
+    const bi = bIds[i];
+    if (ai === void 0) return -1;
+    if (bi === void 0) return 1;
+    const aNum = /^\d+$/.test(ai);
+    const bNum = /^\d+$/.test(bi);
+    if (aNum && bNum) {
+      const d = parseInt(ai, 10) - parseInt(bi, 10);
+      if (d !== 0) return d > 0 ? 1 : -1;
+    } else if (aNum !== bNum) {
+      return aNum ? -1 : 1;
+    } else if (ai !== bi) {
+      return ai > bi ? 1 : -1;
+    }
+  }
+  return 0;
+}
+function pickMcpbAsset(rel) {
+  if (!Array.isArray(rel.assets)) return void 0;
+  const mcpb = rel.assets.find(
+    (a) => typeof a.name === "string" && a.name.endsWith(".mcpb")
+  );
+  if (mcpb?.browser_download_url) return mcpb.browser_download_url;
+  const dxt = rel.assets.find(
+    (a) => typeof a.name === "string" && a.name.endsWith(".dxt")
+  );
+  return dxt?.browser_download_url;
+}
+async function checkForUpdate(opts) {
+  if (checkInFlight) return cachedInfo;
+  checkInFlight = true;
+  try {
+    return await doCheck(opts);
+  } finally {
+    checkInFlight = false;
+  }
+}
+async function doCheck(opts) {
+  const now = opts.now ?? Date.now;
+  const url = opts.releasesUrl ?? RELEASES_LATEST_URL;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const currentVersion = opts.currentVersion;
+  const state = await opts.stateStore.read();
+  const within = now() - state.last_check_time < CHECK_THROTTLE_MS;
+  if (within && state.latest_known_version && state.latest_known_mcpb_url && state.latest_known_release_url) {
+    const cached = buildInfoIfUpgrade(
+      currentVersion,
+      state.latest_known_version,
+      state.latest_known_mcpb_url,
+      state.latest_known_release_url,
+      state.suppressed_versions,
+      state.remind_until,
+      now()
+    );
+    cachedInfo = cached;
+    return cached;
+  }
+  let status;
+  let body = null;
+  let nextEtag;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    let resp;
+    try {
+      resp = await fetchImpl(url, {
+        method: "GET",
+        headers: {
+          Accept: "application/vnd.github+json",
+          "User-Agent": USER_AGENT,
+          ...state.etag ? { "If-None-Match": state.etag } : {}
+        },
+        signal: ctrl.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    status = resp.status;
+    nextEtag = resp.headers.get("etag") ?? state.etag;
+    if (status === 200) {
+      body = await resp.json();
+    }
+  } catch (err) {
+    opts.logger?.warn?.(
+      `update_check.fetch_failed ${err?.message ?? err}`
+    );
+    opts.telemetry.captureUpdateCheck?.({
+      current_version: currentVersion,
+      check_error: String(err?.message ?? err)
+    });
+    await opts.stateStore.update((cur) => ({ ...cur, last_check_time: now() }));
+    return null;
+  }
+  if (status !== 200 && status !== 304) {
+    opts.telemetry.captureUpdateCheck?.({
+      current_version: currentVersion,
+      check_error: `http_${status}`
+    });
+    await opts.stateStore.update((cur) => ({ ...cur, last_check_time: now() }));
+    return null;
+  }
+  let latestVersion;
+  let mcpbUrl;
+  let releaseUrl;
+  if (status === 200 && body) {
+    const parsed = body.tag_name ? parseTagName(body.tag_name) : null;
+    if (parsed) {
+      latestVersion = parsed;
+      mcpbUrl = pickMcpbAsset(body);
+      releaseUrl = body.html_url;
+    }
+  } else {
+    latestVersion = state.latest_known_version;
+    mcpbUrl = state.latest_known_mcpb_url;
+    releaseUrl = state.latest_known_release_url;
+  }
+  const persisted = await opts.stateStore.update((cur) => ({
+    ...cur,
+    last_check_time: now(),
+    etag: nextEtag,
+    latest_known_version: latestVersion ?? cur.latest_known_version,
+    latest_known_mcpb_url: mcpbUrl ?? cur.latest_known_mcpb_url,
+    latest_known_release_url: releaseUrl ?? cur.latest_known_release_url
+  }));
+  opts.telemetry.captureUpdateCheck?.({
+    current_version: currentVersion,
+    latest_version: persisted.latest_known_version
+  });
+  const info = buildInfoIfUpgrade(
+    currentVersion,
+    persisted.latest_known_version,
+    persisted.latest_known_mcpb_url,
+    persisted.latest_known_release_url,
+    persisted.suppressed_versions,
+    persisted.remind_until,
+    now()
+  );
+  cachedInfo = info;
+  return info;
+}
+function buildInfoIfUpgrade(currentVersion, latestVersion, mcpbUrl, releaseUrl, suppressed, remindUntil, nowMs) {
+  if (!latestVersion || !mcpbUrl || !releaseUrl) return null;
+  if (compareSemver(latestVersion, currentVersion) <= 0) return null;
+  if (suppressed.includes(latestVersion)) return null;
+  if (remindUntil && remindUntil > nowMs) return null;
+  return {
+    current_version: currentVersion,
+    latest_version: latestVersion,
+    mcpb_url: mcpbUrl,
+    release_url: releaseUrl
+  };
+}
+async function recordRunningVersion(currentVersion, stateStore, telemetry) {
+  const cur = await stateStore.read();
+  const prev = cur.previous_running_version;
+  if (prev === currentVersion) return;
+  if (prev && compareSemver(currentVersion, prev) > 0) {
+    telemetry.captureVersionUpdated?.({
+      from_version: prev,
+      to_version: currentVersion
+    });
+  }
+  await stateStore.update((s) => ({
+    ...s,
+    previous_running_version: currentVersion,
+    // Clear any prior "remind me tomorrow" for the version we just landed on —
+    // the user has effectively answered the prompt by upgrading.
+    remind_until: void 0,
+    // Drop suppression of versions we've now surpassed.
+    suppressed_versions: s.suppressed_versions.filter(
+      (v) => compareSemver(v, currentVersion) > 0
+    )
+  }));
+}
+
+// src/update-tool.ts
+var TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1e3;
+var DESCRIPTION = "Record the user's choice on an update prompt surfaced via `update_available` on leadbay_account_status. Pass `action: 'install' | 'remind_tomorrow' | 'skip'` and `version` (the `latest_version` from the prompt). On 'install', the server returns `{ mcpb_url, release_url }` \u2014 show the user a clickable link to mcpb_url so Claude Desktop's native installer opens it. On 'remind_tomorrow' the server suppresses the prompt for 24 hours. On 'skip' the version is suppressed permanently. Call this tool EXACTLY ONCE per prompt \u2014 do not loop, and do not call it speculatively when no update_available block is present.";
+function buildAcknowledgeUpdateTool(opts) {
+  const now = opts.now ?? Date.now;
+  return {
+    name: "leadbay_acknowledge_update",
+    annotations: {
+      title: "Acknowledge a Leadbay MCP update prompt",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false
+    },
+    description: DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["install", "remind_tomorrow", "skip"],
+          description: "What the user chose: 'install' (they'll click the link), 'remind_tomorrow' (suppress for 24h), or 'skip' (suppress this version permanently)."
+        },
+        version: {
+          type: "string",
+          description: "The latest_version string from the update_available block. Used for suppression and event correlation."
+        }
+      },
+      required: ["action", "version"],
+      additionalProperties: false
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        ok: { type: "boolean" },
+        action: { type: "string" },
+        version: { type: "string" },
+        message: { type: "string" },
+        mcpb_url: { type: ["string", "null"] },
+        release_url: { type: ["string", "null"] }
+      },
+      required: ["ok", "action", "version", "message"]
+    },
+    execute: async (_client, args, _ctx) => {
+      const action = String(args?.action ?? "");
+      const version = String(args?.version ?? "");
+      if (action !== "install" && action !== "remind_tomorrow" && action !== "skip") {
+        return {
+          error: true,
+          code: "INVALID_ARGUMENT",
+          message: `Unknown action '${action}' for leadbay_acknowledge_update.`,
+          hint: "Pass one of: 'install', 'remind_tomorrow', 'skip'."
+        };
+      }
+      if (!version) {
+        return {
+          error: true,
+          code: "INVALID_ARGUMENT",
+          message: "Missing required `version` argument.",
+          hint: "Pass the latest_version string from the update_available block."
+        };
+      }
+      if (action === "install") {
+        const state = await opts.stateStore.read();
+        opts.telemetry.captureUpdateInstallClicked?.({
+          current_version: opts.currentVersion,
+          latest_version: version
+        });
+        return {
+          ok: true,
+          action,
+          version,
+          mcpb_url: state.latest_known_mcpb_url ?? null,
+          release_url: state.latest_known_release_url ?? null,
+          message: state.latest_known_mcpb_url ? "Show the user the mcpb_url as a clickable link \u2014 opening it in Claude Desktop runs the native installer." : "No .mcpb URL is cached. Direct the user to the release_url to download manually."
+        };
+      }
+      if (action === "remind_tomorrow") {
+        await opts.stateStore.update((cur) => ({
+          ...cur,
+          remind_until: now() + TWENTY_FOUR_HOURS_MS
+        }));
+        opts.telemetry.captureUpdateDismissed?.({
+          current_version: opts.currentVersion,
+          latest_version: version,
+          action: "remind_tomorrow"
+        });
+        return {
+          ok: true,
+          action,
+          version,
+          message: "Reminder snoozed for 24 hours. No further prompts will appear in that window."
+        };
+      }
+      await opts.stateStore.update((cur) => ({
+        ...cur,
+        suppressed_versions: cur.suppressed_versions.includes(version) ? cur.suppressed_versions : [...cur.suppressed_versions, version]
+      }));
+      opts.telemetry.captureUpdateDismissed?.({
+        current_version: opts.currentVersion,
+        latest_version: version,
+        action: "skip"
+      });
+      return {
+        ok: true,
+        action,
+        version,
+        message: `Version ${version} suppressed. Future releases will still prompt.`
+      };
+    }
+  };
+}
+
 // 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.";
@@ -1249,6 +1885,10 @@ function buildStartHereParagraph(has) {
   }
   return base + " When the user asks for refinement, contact enrichment, audience changes, or outreach reporting, tell them: those actions require write tools, currently disabled. Re-enable by removing `LEADBAY_MCP_WRITE=0` from your MCP client config and restarting the client. Also: do not promise to log outreach \u2014 the report_outreach tool is not available in this configuration.";
 }
+function buildUpdateAvailableParagraph(has) {
+  if (!has("leadbay_acknowledge_update")) return null;
+  return "MCP auto-update: when `leadbay_account_status` returns an `update_available` field (`{ current_version, latest_version, mcpb_url, release_url }`), a newer MCP server release is published and the user has NOT suppressed it. Surface a prompt via `ask_user_input_v0` with EXACTLY these three options: \"Install now\", \"Remind me tomorrow\", \"Skip this version\". Map the user's choice to `leadbay_acknowledge_update({ action: 'install' | 'remind_tomorrow' | 'skip', version: latest_version })`. On 'install', the tool returns `mcpb_url` \u2014 render it as a clickable markdown link the user can open in Claude Desktop (the .mcpb extension triggers the native installer). The user does NOT need to restart anything before clicking \u2014 the new server takes effect on the next MCP session. Prompt the user ONCE per session per version \u2014 don't re-prompt within the same chat after they've acknowledged.";
+}
 function buildRhythmParagraph(has) {
   if (has("leadbay_report_outreach")) {
     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, then leadbay_report_outreach on what actually got sent. If your host supports scheduling, offer to set up a daily run.";
@@ -1329,6 +1969,8 @@ function buildServerInstructions(exposed) {
   parts.push(buildScoringParagraph(has));
   parts.push(buildStartHereParagraph(has));
   parts.push(buildRhythmParagraph(has));
+  const updateParagraph = buildUpdateAvailableParagraph(has);
+  if (updateParagraph) parts.push(updateParagraph);
   const promptsCatalog = buildPromptsCatalogParagraph(has);
   if (promptsCatalog) parts.push(promptsCatalog);
   parts.push(RESOURCES_PARAGRAPH);
@@ -1376,6 +2018,16 @@ function buildServer(client, opts = {}) {
       exposedTools.push(...granularWriteTools);
     }
   }
+  if (opts.updateStateStore) {
+    exposedTools.push(
+      buildAcknowledgeUpdateTool({
+        stateStore: opts.updateStateStore,
+        telemetry: opts.telemetry ?? NOOP_TELEMETRY,
+        currentVersion: opts.version ?? "0.0.0-dev",
+        logger: opts.logger
+      })
+    );
+  }
   if (opts.extraTools) {
     exposedTools.push(...opts.extraTools);
   }
@@ -1465,10 +2117,45 @@ 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 promptedVersionsThisSession = /* @__PURE__ */ new Set();
+  const serverVersion = opts.version ?? "0.0.0-dev";
+  const UPDATE_CHECK_DISABLED = process.env.LEADBAY_UPDATE_CHECK_DISABLED === "1";
+  const maybeRefreshUpdate = () => {
+    if (UPDATE_CHECK_DISABLED) return;
+    if (!opts.updateStateStore) return;
+    void checkForUpdate({
+      currentVersion: serverVersion,
+      stateStore: opts.updateStateStore,
+      telemetry,
+      logger: opts.logger
+    }).catch((err) => {
+      opts.logger?.warn?.(
+        `update_check.unexpected ${err?.message ?? err}`
+      );
+    });
+  };
+  const maybeAttachUpdate = (toolName, result) => {
+    if (toolName !== "leadbay_account_status") return;
+    if (!opts.updateStateStore) return;
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+      return;
+    }
+    const info = getCachedUpdateInfo();
+    if (!info) return;
+    result.update_available = info;
+    if (!promptedVersionsThisSession.has(info.latest_version)) {
+      promptedVersionsThisSession.add(info.latest_version);
+      telemetry.captureUpdatePrompted?.({
+        current_version: serverVersion,
+        latest_version: info.latest_version
+      });
+    }
+  };
   const isLeadbayBusinessError = (err) => err != null && typeof err === "object" && err.error === true && typeof err.code === "string";
   server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
     const callStart = Date.now();
     const name = req.params.name;
+    maybeRefreshUpdate();
     const tool = toolByName.get(name);
     if (!tool) {
       return {
@@ -1522,6 +2209,7 @@ function buildServer(client, opts = {}) {
         progress,
         elicit
       });
+      maybeAttachUpdate(name, result);
       if (result && typeof result === "object" && result.error === true) {
         const envText = formatErrorForLLM(result);
         const envDur = Date.now() - callStart;
@@ -1659,9 +2347,202 @@ function buildServer(client, opts = {}) {
   return server;
 }
 
+// src/update-state.ts
+import {
+  mkdir as mkdirAsync,
+  lstat,
+  open as fsOpen,
+  readFile,
+  rename,
+  stat,
+  unlink
+} from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { dirname, resolve as resolvePath } from "path";
+import { homedir } from "os";
+function emptyState() {
+  return {
+    last_check_time: 0,
+    suppressed_versions: []
+  };
+}
+var UpdateStateStore = class {
+  backend;
+  path;
+  logger;
+  allowUnsafePath;
+  now;
+  memory = emptyState();
+  initialized = false;
+  constructor(opts) {
+    this.backend = opts.backend;
+    this.logger = opts.logger;
+    this.allowUnsafePath = !!opts.allowUnsafePath;
+    this.now = opts.now ?? Date.now;
+    if (this.backend === "file") {
+      if (!opts.path) {
+        throw new Error("UpdateStateStore: path is required when backend=file");
+      }
+      this.path = resolvePath(opts.path);
+      this.validatePath(this.path);
+    }
+  }
+  get durability() {
+    return this.backend;
+  }
+  get resolvedPath() {
+    return this.path;
+  }
+  validatePath(p) {
+    if (this.allowUnsafePath) return;
+    const home = resolvePath(homedir());
+    if (p !== home && !p.startsWith(home + "/") && !p.startsWith(home + "\\")) {
+      throw new Error(
+        `UpdateStateStore: path ${p} is outside $HOME (${home}). Set LEADBAY_UPDATE_STATE_PATH_UNSAFE=1 to override.`
+      );
+    }
+  }
+  async ensureInitialized() {
+    if (this.initialized || this.backend !== "file") {
+      this.initialized = true;
+      return;
+    }
+    const dir = dirname(this.path);
+    await mkdirAsync(dir, { recursive: true, mode: 448 });
+    try {
+      const st = await lstat(this.path);
+      if (st.isSymbolicLink()) {
+        throw new Error(
+          `UpdateStateStore: refusing to use ${this.path} \u2014 path is a symlink. Set LEADBAY_UPDATE_STATE_PATH_UNSAFE=1 to override.`
+        );
+      }
+    } catch (err) {
+      if (err?.code !== "ENOENT") throw err;
+    }
+    this.initialized = true;
+  }
+  async read() {
+    if (this.backend === "memory") return { ...this.memory, suppressed_versions: [...this.memory.suppressed_versions] };
+    await this.ensureInitialized();
+    let raw;
+    try {
+      raw = await readFile(this.path, "utf8");
+    } catch (err) {
+      if (err?.code === "ENOENT") return emptyState();
+      throw err;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return this.validate(parsed);
+    } catch (err) {
+      this.logger?.warn?.(
+        `update_state.parse_failed ${err?.message ?? err}; resetting to empty`
+      );
+      return emptyState();
+    }
+  }
+  async write(state) {
+    if (this.backend === "memory") {
+      this.memory = { ...state, suppressed_versions: [...state.suppressed_versions] };
+      return;
+    }
+    await this.ensureInitialized();
+    const tmp = `${this.path}.tmp.${process.pid}.${this.now()}`;
+    const handle = await openTmpFileExclusive(tmp);
+    try {
+      await handle.writeFile(JSON.stringify(state, null, 2));
+    } finally {
+      await handle.close();
+    }
+    await rename(tmp, this.path);
+  }
+  /**
+   * Apply a partial mutation atomically (read → merge → write). Caller
+   * passes a function so concurrent mutators (the startup check + a
+   * tool call landing during it) compose without dropping fields.
+   */
+  async update(mutator) {
+    const cur = await this.read();
+    const next = mutator(cur);
+    await this.write(next);
+    return next;
+  }
+  validate(raw) {
+    if (!raw || typeof raw !== "object") return emptyState();
+    const r = raw;
+    const out = emptyState();
+    if (typeof r.last_check_time === "number" && Number.isFinite(r.last_check_time)) {
+      out.last_check_time = r.last_check_time;
+    }
+    if (typeof r.latest_known_version === "string") {
+      out.latest_known_version = r.latest_known_version;
+    }
+    if (typeof r.latest_known_mcpb_url === "string") {
+      out.latest_known_mcpb_url = r.latest_known_mcpb_url;
+    }
+    if (typeof r.latest_known_release_url === "string") {
+      out.latest_known_release_url = r.latest_known_release_url;
+    }
+    if (typeof r.etag === "string") out.etag = r.etag;
+    if (Array.isArray(r.suppressed_versions)) {
+      out.suppressed_versions = r.suppressed_versions.filter(
+        (v) => typeof v === "string"
+      );
+    }
+    if (typeof r.remind_until === "number" && Number.isFinite(r.remind_until)) {
+      out.remind_until = r.remind_until;
+    }
+    if (typeof r.previous_running_version === "string") {
+      out.previous_running_version = r.previous_running_version;
+    }
+    return out;
+  }
+};
+async function openTmpFileExclusive(path) {
+  try {
+    return await fsOpen(
+      path,
+      fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_EXCL,
+      384
+    );
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      await unlink(path).catch(() => {
+      });
+      return fsOpen(
+        path,
+        fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_EXCL,
+        384
+      );
+    }
+    throw err;
+  }
+}
+async function createDefaultUpdateStateStore(opts = {}) {
+  const env = opts.env ?? process.env;
+  const allowUnsafePath = env.LEADBAY_UPDATE_STATE_PATH_UNSAFE === "1";
+  const path = env.LEADBAY_UPDATE_STATE_PATH ?? resolvePath(homedir(), ".leadbay", "update-state.json");
+  try {
+    const store = new UpdateStateStore({
+      backend: "file",
+      path,
+      logger: opts.logger,
+      allowUnsafePath
+    });
+    await store.ensureInitialized();
+    await stat(dirname(path));
+    return store;
+  } catch (err) {
+    opts.logger?.warn?.(
+      `update_state.fallback_memory path=${path} reason=${err?.message ?? err}`
+    );
+    return new UpdateStateStore({ backend: "memory", logger: opts.logger });
+  }
+}
+
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.10.1";
+var VERSION = "0.12.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -1710,7 +2591,7 @@ EXAMPLE Claude Desktop config (~/Library/Application Support/Claude/claude_deskt
     "mcpServers": {
       "leadbay": {
         "command": "npx",
-        "args": ["-y", "@leadbay/mcp@0.10"],
+        "args": ["-y", "@leadbay/mcp@0.12"],
         "env": {
           "LEADBAY_TOKEN": "lb_...",
           "LEADBAY_REGION": "us",
@@ -1763,9 +2644,47 @@ function exitWithTokenError() {
   );
   process.exit(1);
 }
+var BrokenLeadbayClient = class extends LeadbayClient {
+  stubError;
+  constructor(stubError, baseUrl, region) {
+    super(baseUrl, "broken-token-startup-auth-failure", region);
+    this.stubError = stubError;
+  }
+  async request() {
+    throw this.stubError;
+  }
+  async requestVoid() {
+    throw this.stubError;
+  }
+  async requestRawBinary() {
+    throw this.stubError;
+  }
+};
+function makeBrokenClient(stubError, region) {
+  const baseUrl = region === "fr" ? "https://api-fr.leadbay.app" : "https://api-us.leadbay.app";
+  return new BrokenLeadbayClient(stubError, baseUrl, region);
+}
 async function resolveClientFromEnv(logger) {
   const token = process.env.LEADBAY_TOKEN;
-  if (!token) exitWithTokenError();
+  if (!token) {
+    process.stderr.write(
+      "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Run: npx -y @leadbay/mcp install --email <you> --region <us|fr>\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
+    );
+    const regionEnv2 = process.env.LEADBAY_REGION;
+    const region = regionEnv2 === "fr" ? "fr" : "us";
+    return {
+      client: makeBrokenClient(
+        {
+          error: true,
+          code: "AUTH_MISSING",
+          message: "LEADBAY_TOKEN environment variable is not set.",
+          hint: "Run `npx -y @leadbay/mcp install --email <you> --region <us|fr>` to mint a token, then set LEADBAY_TOKEN in your MCP client config."
+        },
+        region
+      ),
+      authState: "missing"
+    };
+  }
   const regionEnv = process.env.LEADBAY_REGION;
   const explicitRegion = regionEnv === "us" || regionEnv === "fr" ? regionEnv : void 0;
   const baseUrl = process.env.LEADBAY_BASE_URL;
@@ -1773,7 +2692,7 @@ async function resolveClientFromEnv(logger) {
     const config = { token };
     if (baseUrl) config.baseUrl = baseUrl;
     if (explicitRegion) config.region = explicitRegion;
-    return createClient(config);
+    return { client: createClient(config), authState: "ok" };
   }
   process.stderr.write(
     "[leadbay-mcp warn] LEADBAY_REGION is unset; probing api-us and api-fr in parallel.\n  Your bearer token will be sent to BOTH backends. Set LEADBAY_REGION=us|fr in your\n  MCP client config to avoid this.\n"
@@ -1785,7 +2704,8 @@ async function resolveClientFromEnv(logger) {
     return c;
   };
   try {
-    return await Promise.any([probe("us"), probe("fr")]);
+    const client = await Promise.any([probe("us"), probe("fr")]);
+    return { client, authState: "ok" };
   } catch (err) {
     const errors = err?.errors ?? [];
     const firstAuth = errors.find(
@@ -1797,14 +2717,28 @@ async function resolveClientFromEnv(logger) {
 Tip: verify your LEADBAY_TOKEN is valid and, if you know your region, set LEADBAY_REGION=us or LEADBAY_REGION=fr.
 `
       );
-      process.exit(1);
+      return {
+        client: makeBrokenClient(
+          {
+            error: true,
+            code: firstAuth.code,
+            message: firstAuth.message,
+            hint: "Verify your LEADBAY_TOKEN is valid. If you know your region, set LEADBAY_REGION=us or LEADBAY_REGION=fr to skip auto-probing. Mint a fresh token with `leadbay-mcp login --email <you> --region <us|fr>`."
+          },
+          "us"
+        ),
+        authState: "expired"
+      };
     }
     const firstMsg = errors[0]?.message ?? String(err);
     process.stderr.write(
       `leadbay-mcp: region auto-detection failed (${firstMsg}). Defaulting to us; set LEADBAY_REGION to skip probing.
 `
     );
-    return createClient({ token, region: "us" });
+    return {
+      client: createClient({ token, region: "us" }),
+      authState: "probe_failed"
+    };
   }
 }
 async function readPassword() {
@@ -1958,7 +2892,7 @@ async function runLogin(args) {
   let result;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-BHLIJAIH.js");
+      const { REGIONS } = await import("./dist-YYVFSDMH.js");
       const baseUrl = REGIONS[pinnedRegion];
       const c = createClient({ region: pinnedRegion });
       const token = await loginAt(baseUrl, email, password);
@@ -1977,7 +2911,7 @@ async function runLogin(args) {
     mcpServers: {
       leadbay: {
         command: "npx",
-        args: ["-y", "@leadbay/mcp@0.10"],
+        args: ["-y", "@leadbay/mcp@0.12"],
         env: {
           LEADBAY_TOKEN: result.token,
           LEADBAY_REGION: result.region
@@ -2017,7 +2951,7 @@ Or for Claude Code (token included \u2014 same warning applies):
   claude mcp add leadbay --scope user \\
     --env LEADBAY_TOKEN=${result.token} \\
     --env LEADBAY_REGION=${result.region} \\
-    -- npx -y @leadbay/mcp@0.10
+    -- npx -y @leadbay/mcp@0.12
 
 Restart your MCP client to pick up the new server.
 `
@@ -2064,8 +2998,8 @@ Restart your MCP client to pick up the new server.
   let actualMode;
   try {
     const { writeFileSync, chmodSync, mkdirSync, renameSync, statSync, unlinkSync } = await import("fs");
-    const { dirname } = await import("path");
-    mkdirSync(dirname(targetPath), { recursive: true });
+    const { dirname: dirname2 } = await import("path");
+    mkdirSync(dirname2(targetPath), { recursive: true });
     const tmp = targetPath + ".tmp." + process.pid;
     writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", {
       encoding: "utf8",
@@ -2123,7 +3057,7 @@ For Claude Code, run:
   claude mcp add leadbay --scope user \\
     --env LEADBAY_TOKEN=$(jq -r .mcpServers.leadbay.env.LEADBAY_TOKEN ${quotedPath}) \\
     --env LEADBAY_REGION=${result.region} \\
-    -- npx -y @leadbay/mcp@0.10
+    -- npx -y @leadbay/mcp@0.12
 `
     );
   }
@@ -2303,7 +3237,7 @@ function buildClaudeCodeAddArgs(token, region, includeWrite, telemetryEnabled) {
     `LEADBAY_TELEMETRY_ENABLED=${telemetryEnabled ? "true" : "false"}`
   ];
   if (!includeWrite) args.push("--env", `LEADBAY_MCP_WRITE=0`);
-  args.push("--", "npx", "-y", "@leadbay/mcp@0.10");
+  args.push("--", "npx", "-y", "@leadbay/mcp@0.12");
   return args;
 }
 async function installInClaudeCode(token, region, includeWrite, telemetryEnabled) {
@@ -2329,7 +3263,7 @@ async function installInClaudeCode(token, region, includeWrite, telemetryEnabled
 async function installInJsonConfig(configPath, token, region, includeWrite, telemetryEnabled) {
   try {
     const { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } = await import("fs");
-    const { dirname } = await import("path");
+    const { dirname: dirname2 } = await import("path");
     let parsed = {};
     let preserved = {};
     if (existsSync(configPath)) {
@@ -2341,7 +3275,7 @@ async function installInJsonConfig(configPath, token, region, includeWrite, tele
         return { ok: false, message: `existing ${configPath} is not valid JSON; refusing to overwrite` };
       }
     } else {
-      mkdirSync(dirname(configPath), { recursive: true });
+      mkdirSync(dirname2(configPath), { recursive: true });
     }
     parsed.mcpServers = parsed.mcpServers ?? {};
     const env = {
@@ -2353,7 +3287,7 @@ async function installInJsonConfig(configPath, token, region, includeWrite, tele
     if (!includeWrite) env.LEADBAY_MCP_WRITE = "0";
     parsed.mcpServers.leadbay = {
       command: "npx",
-      args: ["-y", "@leadbay/mcp@0.10"],
+      args: ["-y", "@leadbay/mcp@0.12"],
       env
     };
     const tmp = configPath + ".tmp";
@@ -2457,7 +3391,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-BHLIJAIH.js");
+      const { REGIONS } = await import("./dist-YYVFSDMH.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;
@@ -2530,7 +3464,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   process.stderr.write(
     `
 The token was written into client config files but never printed to your terminal.
-Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.10 doctor
+Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.12 doctor
 Restart your MCP client(s) to pick up the new server.
 If you ever leak the token, run \`leadbay-mcp login --email <you> --region <us|fr>\` to mint a fresh one (which invalidates the prior session).
 `
@@ -2581,6 +3515,26 @@ async function runDoctor() {
   );
   return 1;
 }
+var startupSafetyNetsInstalled = false;
+function installStartupSafetyNets(logger) {
+  if (startupSafetyNetsInstalled) return;
+  startupSafetyNetsInstalled = true;
+  const reportAndExit = (label, err) => {
+    const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+    process.stderr.write(`leadbay-mcp: ${label}: ${msg}
+`);
+    logger.error?.(`${label}: ${msg}`);
+    try {
+      const bootTelemetry = initTelemetry({ version: VERSION });
+      bootTelemetry.captureException(err, { tool: "__startup__" });
+      void bootTelemetry.shutdown();
+    } catch {
+    }
+    process.exit(1);
+  };
+  process.on("uncaughtException", (err) => reportAndExit("uncaughtException", err));
+  process.on("unhandledRejection", (err) => reportAndExit("unhandledRejection", err));
+}
 async function main() {
   const arg = process.argv[2];
   if (arg === "--version" || arg === "-v") {
@@ -2603,23 +3557,45 @@ async function main() {
     process.exit(await runDoctor());
   }
   const logger = makeStderrLogger(parseLogLevel(process.env.LEADBAY_LOG_LEVEL));
+  installStartupSafetyNets(logger);
   const telemetry = initTelemetry({ version: VERSION, logger });
-  const client = await resolveClientFromEnv(logger);
+  const { client, authState } = await resolveClientFromEnv(logger);
   telemetry.identify(client);
+  telemetry.captureStartup({
+    auth_state: authState,
+    region: client.region
+  });
   const includeAdvanced = process.env.LEADBAY_MCP_ADVANCED === "1";
   const includeWrite = parseWriteEnv();
   const bulkTracker = await createDefaultBulkStore({ logger });
+  const updateStateStore = await createDefaultUpdateStateStore({ logger });
+  void recordRunningVersion(VERSION, updateStateStore, telemetry).catch((err) => {
+    logger.warn?.(
+      `update_state.record_version_failed ${err?.message ?? err}`
+    );
+  });
+  if (process.env.LEADBAY_UPDATE_CHECK_DISABLED !== "1") {
+    void checkForUpdate({
+      currentVersion: VERSION,
+      stateStore: updateStateStore,
+      telemetry,
+      logger
+    }).catch((err) => {
+      logger.warn?.(`update_check.unexpected ${err?.message ?? err}`);
+    });
+  }
   const server = buildServer(client, {
     includeAdvanced,
     includeWrite,
     logger,
     bulkTracker,
     version: VERSION,
-    telemetry
+    telemetry,
+    updateStateStore
   });
   const transport = new StdioServerTransport();
   logger.info?.(
-    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability})`
+    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability}, auth_state=${authState})`
   );
   await server.connect(transport);
   const shutdown = async (code) => {
@@ -2661,6 +3637,7 @@ export {
   checkLoginCollision,
   computeFreshDefaultPath,
   detectClaudeDesktopMode,
+  makeBrokenClient,
   parseWriteEnv,
   resolveClientFromEnv,
   resolveDefaultCredentialsPath