@leadbay/mcp 0.11.0 → 0.12.0

package/dist/{chunk-MZZMIZXA.js → chunk-J2Y4LCFM.js}

@@ -586,6 +586,50 @@ WHEN TO USE: at the start of a session to know what the agent can/can't do, afte
 
 WHEN NOT TO USE: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating. And: a recent quota snapshot showing "exhausted" is NOT a reason to refuse a write call when the user has just topped up \u2014 re-call this tool first, then proceed.
 `;
+var leadbay_add_leads_to_campaign = `## WHEN TO USE
+
+Trigger phrases: "add these leads to my <name> campaign", "attach these to <campaign>", "put these 5 in the Q2 Push campaign", "add to existing campaign".
+
+Do NOT use for: "create a new campaign (not attach to an existing one)" \u2192 \`leadbay_create_campaign\`; "remove a lead from a campaign" \u2192 \`leadbay_create_campaign\`; "list which campaigns I have" \u2192 \`leadbay_list_campaigns\`.
+
+Prefer when: user names an existing campaign (or supplies a campaign_id) AND a set of leads to attach. If they want a new campaign, use create_campaign with seed lead_ids instead
+
+Examples that SHOULD invoke this tool:
+- "Add the three new Tulsa leads to my 'OK Sweep' campaign."
+- "Attach these qualified leads to campaign id 1f12...?"
+- "Put the top 5 of today's batch into my Q2 Push."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Create a new campaign with these 9 leads."
+- "What campaigns do I have?"
+- "Show progression on my Limoges Tour."
+
+## RENDER (quick)
+
+One-line confirmation: \u2705 Added N leads to <campaign-name>
+(M already present). If \`added === 0 && already_present > 0\` ("all
+already in"), surface that as a no-op note instead of a success
+banner. Offer NEXT STEPS chip for "View progression"
+(campaign_progression) or "Add more".
+
+---
+
+Attach a list of \`lead_ids\` to an existing campaign. Wraps \`POST /campaigns/{id}/leads\`. The backend dedups against \`campaign_leads\`, so callers can safely retry without creating duplicates \u2014 the response separates \`added\` (newly attached) from \`already_present\` (no-op).
+
+**Lead UUID source**: pass UUIDs returned from \`leadbay_pull_leads\` (\`lead.id\`), \`leadbay_pull_followups\` (\`lead.id\`), \`leadbay_tour_plan\` (\`monitor_leads[].id\` / \`discover_leads[].id\`), \`leadbay_research_lead_by_id\` / \`_by_name_fuzzy\` (\`lead.id\`). Backend \`ensureLeadsExist\` rejects unknown UUIDs with 404 \u2014 typo'd or fabricated IDs throw \`NOT_FOUND\`.
+
+**Why batch vs. one-at-a-time**: every call rebuilds membership server-side and may regenerate the AI-suggested name (\`maybeRegenerateAiName\`). Prefer one call with N leads over N calls with one lead each.
+
+**Side effect**: \`ensureLeadsInMonitor(orgId, leadIds)\` is called after a successful add \u2014 leads not already in the Monitor view get added there. This means adding a "fresh Discover" lead to a campaign moves it into the user's known-pipeline view.
+
+---
+
+WHEN TO USE: the user has an existing campaign (created earlier in the session or visible via \`leadbay_list_campaigns\`) and wants to attach more leads to it.
+
+WHEN NOT TO USE: to create a NEW campaign (use \`leadbay_create_campaign\` with \`lead_ids\` seeded); to list campaigns (\`leadbay_list_campaigns\`); to view per-lead progression (\`leadbay_campaign_progression\`); to remove leads (not currently exposed in the MCP \u2014 direct backend \`DELETE /campaigns/{id}/leads\` would be needed).
+
+**Response**: \`{added: number, already_present: number}\`. Use both counts in the confirmation \u2014 silent dedup hides useful information from the user.
+`;
 var leadbay_add_note = `Add a note to a lead. Notes are visible to the whole organization in Leadbay.
 
 WHEN TO USE: low-level \u2014 for free-form notes not tied to outreach actions, including meaningful per-lead notes/context preserved from an imported file after the import returns lead IDs.
@@ -691,6 +735,214 @@ Exactly two offers \u2014 keep it terse, this is a status tool:
 | Qualification kicked off (async)     | "Check progress in ~30s"                      | leadbay_qualify_status         |
 | Job is done / blocking call returned | "Refresh leads view \u2014 the new qualifications should be on the top"  | leadbay_pull_leads(lensId = pinned) |
 `;
+var leadbay_campaign_call_sheet = `## WHEN TO USE
+
+Trigger phrases: "show me my campaign as a call sheet", "list of people to call in <campaign>", "cold-calling cheat sheet", "work this campaign", "let's call through my <campaign>", "calling session for <campaign>".
+
+Do NOT use for: "campaign progression pulse only (no contacts)" \u2192 \`leadbay_campaign_progression\`; "create a new campaign" \u2192 \`leadbay_create_campaign\`; "list all my campaigns" \u2192 \`leadbay_list_campaigns\`.
+
+Prefer when: user wants an actionable call-ready view of ONE campaign with phones + LinkedIn ready to click. Pair with the \`leadbay_work_campaign\` prompt for the full dictation+epilogue loop
+
+Examples that SHOULD invoke this tool:
+- "Show me my Limoges Tour campaign as a call sheet."
+- "I'm about to do a calling session \u2014 render the Q2 Push campaign."
+- "Give me phones + LinkedIn for everyone in my OK Sweep campaign."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Quick pulse on how my campaigns are doing."
+- "Save these 9 leads as a new campaign."
+- "Tell me about Acme Corp."
+
+## RENDER (quick)
+
+Per-lead CARD sorted by AI score desc. Heading \`### \u26A1 **<Company>**
+\u2014 <City>, <State>\`; one-line "\u2605 Next step: \u2026" from
+split_ai_summary; then a 4-col table of contacts:
+Contact / Phone / Role / Recent. Cell 1 stacks linked name + email
++ (if constructed) LinkedIn marker \xB0. Phone is \`[bare](tel:URL)\`.
+Recent stacks last note + lead headline. Top of page = summary chip
+from \`summary\` + readiness flags.
+
+---
+
+Build a cold-calling cheat sheet for one campaign. The composite joins two backend reads \u2014 \`/campaigns/{id}/contacts\` (per-contact phones, LinkedIn URLs, emails, job titles, recent notes) and \`/campaigns/{id}/leads\` (per-lead AI next-step, location, score, progress) \u2014 into a single call-ready payload aligned to the lead's page order.
+
+**Per-lead block** carries:
+
+- \`lead_id\`, \`lead_name\`, \`score\`, \`ai_agent_lead_score\`
+- \`location\` (\`city\`, \`state\`, \`country\`, \`full\`, \`pos[lat,lng]\`)
+- \`website\`, \`company_phone_numbers[]\` (often empty; use per-contact phones)
+- \`next_step\` / \`approach_angle\` / \`worth_pursuing\` (from \`split_ai_summary\` \u2014 the structured calling angle)
+- \`progress\` (\`total_contacts\` = reachable contact coverage; \`in_progress\` / \`declined\` / \`headline\` = outreach state \u2014 use those, not \`total_contacts\`, to tell whether the lead has been touched)
+- \`affiliation.own_campaigns[]\` + \`other_users_campaign_count\` (overlap warning \u2014 avoid double-touching)
+- \`contacts[]\` \u2014 every reachable contact for this lead, sorted: AI-pinned first, then recommended, then by phone availability. Each contact has:
+  - \`first_name\`, \`last_name\`, \`full_name\`, \`job_title\`
+  - \`phone_number\` (bare, e.g. \`"+1 512-792-7708"\`), \`phone_tel_url\` (canonical, e.g. \`"tel:+15127927708"\`)
+  - \`email\`, \`mailto_url\`
+  - \`linkedin_url\` + \`linkedin_url_source\` (\`"leadbay"\` when the backend has it, \`"constructed"\` when fallback-built from name + company)
+  - \`recent_notes[]\` \u2014 recent notes about this contact (often empty on cold campaigns)
+
+**Map mode**: the response also carries \`map_locations[]\` \u2014 already-shaped entries for \`places_map_display_v0\` (\`{name, address, latitude, longitude, notes}\`). When the user wants a route ("plot my call list on a map"), pass \`map_locations\` directly into the widget without reshaping.
+
+**Cross-campaign overlap warning**: when a contact's lead shows \`affiliation.other_users_campaign_count > 0\`, surface that ("\u26A0 2 teammates also have this lead in their own campaigns") so the rep can coordinate before calling.
+
+---
+
+## RENDER \u2014 call-sheet markdown (PRIMARY)
+
+This is a cold-calling surface. The user wants to scan \u2192 pick \u2192 tap-to-call \u2192 dictate outcome \u2192 next. Render one CARD per lead, sorted by AI score:
+
+\`\`\`
+### \u26A1 **<Company Name>** \u2014 <City>, <State>
+
+**Score <ai_agent_lead_score or score>** \xB7 \u2605 Next step: <next_step>
+
+| Contact | Phone | Role | Recent |
+|---|---|---|---|
+| **[<First Last>](<linkedin_url>)**<br>\u2709 [<email>](<mailto_url>) | [<phone bare>](<phone_tel_url>) | <job_title> | \u{1F4DD} "<last_note truncated>" (<rel_date>)<br>\u{1F4DE} <last_action_headline> |
+| **[<First Last>](<linkedin_url>)** | [<phone bare>](<phone_tel_url>) | <job_title> | _(no notes)_ |
+
+<short callout \u2014 "\u{1F4DE} 0 prior touches" / "\u26A0 Also in 2 teammates' campaigns" if applicable>
+
+---
+\`\`\`
+
+**Cell 1 \u2014 Contact (stacked content)**:
+- Line 1: \`**[<First Last>](<linkedin_url>)**\` \u2014 MUST always be a markdown link. Use \`contact.linkedin_url\` from the response (the composite already falls back to a \`linkedin.com/search/results/people/?keywords=\u2026\` URL when \`linkedin_page\` is missing \u2014 never render a bare name). When \`linkedin_url_source === "constructed"\`, append a trailing \` \xB0\` to the contact name to mark the fallback path.
+- Line 2 (if email present): \`\u2709 [<email>](<mailto_url>)\` \u2014 \`mailto:\` link, auto-linkifies and opens the user's default mail app. Omit the line entirely if \`email === null\` rather than rendering "_no email_".
+
+**Cell 2 \u2014 Phone (load-bearing for one-tap calling on mobile)**:
+- Always render as a markdown link \`[bare](tel:URL)\`. The bare text auto-linkifies on most hosts; the explicit \`tel:\` link guarantees one-tap dialing on macOS / iOS / Android.
+- Use the \`phone_tel_url\` from the response (already canonicalized to \`tel:+<digits>\`); do NOT reconstruct.
+- When \`phone_number\` is null but the lead has \`company_phone_numbers[]\`, fall back to the company switchboard with a "(company line)" suffix.
+- When neither contact phone nor company phone is present, render \`_no phone_\` \u2014 the rep will know this contact needs enrichment.
+
+**Cell 3 \u2014 Role**: \`contact.job_title\`. Render \`\u2014\` when null.
+
+**Cell 4 \u2014 Recent (stacked content, history surface)**:
+- Line 1 (if \`contact.recent_notes[0]\` present): \`\u{1F4DD} "<note text, truncated to ~60 chars>" (<relative date>)\`. The relative date uses the note's \`created_at\` ISO timestamp \u2014 render as \`3d ago\`, \`2w ago\`, etc. Omit the line entirely if no notes.
+- Line 2 (if \`last_action_headline\` on the lead-level block present): \`\u{1F4DE} <headline>\` \u2014 e.g. \`\u{1F4DE} CONTACTED\`, \`\u{1F4DE} MEETING_BOOKED\`. This is the LEAD's most recent interaction headline, not the contact's. Helpful for context but the per-contact note above is more specific.
+- When both are absent, omit the cell content entirely \u2014 don't render \`_(no activity)_\` for every cold contact; it's noise.
+
+**Sort + filter**:
+- Top of the page: ONE-line summary chip from \`summary\` \u2014 \`\u{1F4CB} 12 leads \xB7 23 contacts \xB7 9 with a phone \xB7 7 with an email \xB7 3 already touched\`.
+- Lead cards sorted by AI score desc; contacts within each card sorted AI-pinned > recommended > has-phone.
+- If \`last_action_headline\` is present OR \`progress.in_progress > 0\` OR \`progress.declined > 0\`, render the card with a \u{1F4DE} prefix instead of \u26A1 \u2014 at-a-glance "already touched" vs "still cold". Do not use \`progress.total_contacts\`; that is contact coverage, not outreach history.
+
+## RENDER \u2014 map widget (SECONDARY, when user asks for a route)
+
+When the user says "plot my call list on a map" / "where are these leads" / "route my calling tour", route to \`places_map_display_v0\` using the \`map_locations\` array verbatim:
+
+\`\`\`
+places_map_display_v0({
+  locations: response.map_locations,
+  travel_mode: "driving"
+})
+\`\`\`
+
+The composite has already built the notes string per place card (one sentence with the top contact's phone inline). After the widget, emit the standard call-sheet card list below it for the rich detail \u2014 the carousel renders bare phones as \`tel:\` but strips markdown.
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
+
+---
+
+## NEXT STEPS \u2014 wire the dictation+epilogue loop
+
+After the user reports a call ("Called Bree, she wants pricing"), route to \`leadbay_report_outreach\` with BOTH \`note\` (the call summary) AND \`epilogue_status\` in one call. The four epilogue values:
+
+- \`STILL_CHASING\` \u2014 still pursuing, no decision yet.
+- \`COULD_NOT_REACH_STILL_TRYING\` \u2014 voicemail / no answer.
+- \`INTEREST_VALIDATED_OR_MEETING_PLANED\` \u2014 qualified / meeting booked.
+- \`NOT_INTERESTED_LOST\` \u2014 declined / not a fit.
+
+The \`verification\` field is REQUIRED \u2014 pass \`{source: "user_confirmed", ref: <user's exact words>}\` since calls don't have message-ids.
+
+WHEN TO USE: the user wants to actually WORK a campaign \u2014 calling session, dictation loop, follow-up sequence. Pair with the \`leadbay_work_campaign\` prompt for the end-to-end orchestrator (pick campaign \u2192 render \u2192 call \u2192 record loop).
+
+WHEN NOT TO USE: for cross-campaign pulse (use \`leadbay_list_campaigns\`); for the slim progression view without contacts (\`leadbay_campaign_progression\` \u2014 same per-lead progress but no phone/LinkedIn fan-out); to log outreach AFTER a call (chain into \`leadbay_report_outreach\`).
+
+**Response envelope**: \`{campaign_id, leads[], map_locations[], summary, pagination, _meta}\`.
+
+## Linking a contact's name
+
+**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.**
+
+URL priority (first applicable wins):
+
+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) \u2014 the two surfaces are different and conflating them quietly degrades the workflow.
+`;
+var leadbay_campaign_progression = `## WHEN TO USE
+
+Trigger phrases: "how is my <name> campaign doing", "campaign progression", "lead-by-lead status on <campaign>", "who in <campaign> have I contacted", "what's stuck in my campaign".
+
+Do NOT use for: "pulse across all campaigns (not one)" \u2192 \`leadbay_list_campaigns\`; "log an outreach event" \u2192 \`leadbay_report_outreach\`.
+
+Prefer when: user named (or just selected from list_campaigns) ONE campaign and wants per-lead status. Use list_campaigns for the cross-campaign overview
+
+Examples that SHOULD invoke this tool:
+- "Walk me through the Limoges Tour campaign \u2014 who have I touched?"
+- "Show progression on campaign 1f12...?"
+- "What's stuck in my Q2 Push?"
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Show me all my campaigns."
+- "Create a new campaign."
+- "Log that I emailed Acme."
+
+## RENDER (quick)
+
+Two-tier render. Top: one-line summary
+("Limoges Tour: 9 leads \xB7 4 contacted \xB7 1 meeting \xB7 0 declined").
+Then a markdown table per lead:
+| Lead | Score | Contacts | Last action | Also in |
+Each row's "Also in" column lists \`affiliation.own_campaigns[]\`
+names (with a \u26A0 suffix if \`other_users_campaign_count > 0\`,
+indicating teammates also have it). Sort by progress.headline
+recency or by score desc \u2014 pick whichever surfaces "needs
+attention" leads first.
+
+---
+
+Per-lead progression view for one campaign. Wraps \`GET /campaigns/{id}/leads\` (paginated). For every lead in the campaign:
+
+- **lead** \u2014 full \`LeadPayload\` (same shape \`pull_leads\` / \`pull_followups\` return), so the agent has score, contacts, ai_summary, location, etc. without an extra round trip.
+- **progress** \u2014 \`{total_contacts, in_progress, declined, headline}\`. \`total_contacts\` is reachable contact coverage; do not treat it as prior outreach. \`headline\` is the most recent \`InteractionType\` (CONTACTED / MEETING_BOOKED / DECLINED / etc.) and is the load-bearing field for "what stage is this lead at".
+- **affiliation** \u2014 \`{own_campaigns: CampaignRefPayload[], other_users_campaign_count}\`. \`own_campaigns\` lists OTHER campaigns of yours this lead is in (overlap detection \u2014 avoids the rep doubling outreach across two of their own campaigns). \`other_users_campaign_count\` is how many teammates also have this lead in one of THEIR campaigns. This is the only cross-user signal the campaign API exposes.
+
+The composite also adds a \`summary\` block computed across the current page (\`{page_size, contacted, in_progress, declined}\`) so a quick "how is this campaign doing" prompt doesn't need to roll up the items array itself.
+
+**Pagination**: \`count\` defaults to 50; \`page\` is 0-indexed. For campaigns with hundreds of leads, page through and concatenate the summary counts.
+
+---
+
+WHEN TO USE: after \`leadbay_list_campaigns\` (or when the user named a specific campaign): the manager wants per-lead status to spot leads needing re-engagement, leads stuck, or leads that progressed to a meeting.
+
+WHEN NOT TO USE: for cross-campaign pulse (use \`leadbay_list_campaigns\`); to drill into a lead's full timeline (use \`leadbay_get_lead_activities\` or \`leadbay_research_lead_by_id\`); to log outreach (\`leadbay_report_outreach\`).
+
+**Response**: \`{items, pagination, summary, _meta}\`. Use the \`summary\` for the one-line headline; use \`items\` for the per-lead table.
+`;
 var leadbay_clear_selection = `Clear the user's transient selection.
 
 WHEN TO USE: cleanup after manual selection work, or recovery from a stuck composite.
@@ -707,6 +959,55 @@ WHEN NOT TO USE: to replace with a different prompt \u2014 just call leadbay_ref
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
+var leadbay_create_campaign = `## WHEN TO USE
+
+Trigger phrases: "create a campaign called <name>", "save these leads as a campaign", "make a campaign for my <city> trip", "track these leads together", "group these leads into a named campaign", "persist these leads".
+
+Do NOT use for: "list my existing campaigns" \u2192 \`leadbay_list_campaigns\`; "add leads to an existing campaign" \u2192 \`leadbay_add_leads_to_campaign\`; "log an outreach event" \u2192 \`leadbay_report_outreach\`.
+
+Prefer when: user wants to persist a hand-picked set of leads as a named cohort they'll work through. Often follows leadbay_pull_leads / leadbay_tour_plan / leadbay_research_lead_by_id
+
+Examples that SHOULD invoke this tool:
+- "Save these 9 leads as a campaign called 'Limoges Tour \u2013 May 24'."
+- "Create a campaign for the qualified leads I just picked."
+- "Make a campaign for my SF visit and add those three accounts."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "What campaigns do I have?"
+- "Add three more leads to my 'Q2 Push' campaign."
+- "I just emailed Acme \u2014 log it."
+
+## RENDER (quick)
+
+One-line confirmation: \u2705 Created **<name>** with N leads \xB7 <id-short>.
+If the backend AI-generated the name (no \`name\` passed), surface that:
+"AI-suggested name: <name>". Offer a NEXT STEPS chip for "Add more
+leads" or "Open in web UI". Don't dump the full campaign payload as a
+table \u2014 the user only needs the confirmation + the id for follow-up.
+
+---
+
+Create a new campaign \u2014 a server-persisted grouping of leads the user (or their manager) plans to work systematically. Wraps \`POST /campaigns\` (see \`.context/campaigns-probe/API.md\` for the discovered shape). Body is snake_case (the backend's \`apiJson\` uses \`JsonNamingStrategy.SnakeCase\`); this composite handles that translation \u2014 agents pass camelCase via the input schema but the wire is snake_case.
+
+**Name behavior**:
+- Pass \`name\` explicitly when the user named it ("Limoges Tour \u2013 May 24"). Max 255 chars.
+- Omit \`name\` AND pass non-empty \`lead_ids\` \u2192 backend calls \`SuggestCampaignName.generate()\` to AI-pick a name from the seed leads. Returned as both \`name\` (final) and \`ai_generated_name\` (the suggestion, in case the user wants to rename later).
+- Omit both \u2192 backend assigns a default (e.g. "Untitled campaign").
+
+**Seed leads vs. empty**:
+- Seed with \`lead_ids: [...]\` when the user already picked the leads (chain after \`leadbay_tour_plan\`, \`leadbay_pull_leads\`, \`leadbay_research_lead_by_id\`).
+- Create empty (\`lead_ids: []\`, default) and add later via \`leadbay_add_leads_to_campaign\` \u2014 useful when the user named the campaign first and wants to populate it incrementally.
+
+**Scope**: campaigns are created in the caller's organization and \`created_by = caller_user_id\`. The list endpoint (\`leadbay_list_campaigns\`) is filtered to the creator \u2014 campaigns ARE NOT shared with teammates by default. For #3630 US3 "manager creates a campaign for a rep", today's MCP workaround is to name campaigns descriptively ("North-East \u2013 John") and have the rep visit /app to access via the web UI; cross-user assignment would need backend work.
+
+---
+
+WHEN TO USE: the user wants to persist a hand-picked set of leads as a named cohort they'll work through systematically. Typical chains: \`tour_plan \u2192 create_campaign(lead_ids=[...selected])\` for trip planning, or \`pull_leads \u2192 research_lead_by_id \u2192 create_campaign\` for incremental promising-lead curation.
+
+WHEN NOT TO USE: to LIST existing campaigns (use \`leadbay_list_campaigns\`); to ADD leads to an existing one (use \`leadbay_add_leads_to_campaign\`); to LOG an outreach event (use \`leadbay_report_outreach\`); to view per-lead campaign progression (use \`leadbay_campaign_progression\`).
+
+**Response**: full \`CampaignPayload\` \u2014 \`{id, name, ai_generated_name?, ai_name_count, archived, created_by, created_at, updated_at, last_accessed_at}\`. Echo \`id\` back to the user as the handle for follow-up tool calls.
+`;
 var leadbay_create_custom_field = `Create an org-level CRM custom field for imports, then use the returned \`mapping_value\` in leadbay_import_leads / leadbay_import_and_qualify mappings. Use when the user's file contains valuable columns that do not fit Leadbay's standard fields, such as source-system deep links, source record IDs, campaign provenance, or user-requested enrichment attributes.
 
 For HubSpot record links, prefer \`type:'EXTERNAL_ID'\` with \`config.url_template\` and import only the stable HubSpot id as the CSV value. Example: create field name 'HubSpot Contact', type 'EXTERNAL_ID', config \`{url_template:'https://app.hubspot.com/contacts/<portal-id>/record/0-1/{value}'}\`; then map \`hubspot_id\` to the returned \`mapping_value\`. If only a full URL column exists and the id cannot be safely extracted, use a TEXT field instead.
@@ -1314,6 +1615,46 @@ WHEN NOT TO USE: the user is just reading or researching a lead without expressi
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
+var leadbay_list_campaigns = `## WHEN TO USE
+
+Trigger phrases: "what campaigns do I have", "list my campaigns", "show me my active campaigns", "campaign overview", "what's in flight", "pulse on my campaigns".
+
+Do NOT use for: "create a new campaign" \u2192 \`leadbay_create_campaign\`; "drill into one specific campaign's progression" \u2192 \`leadbay_campaign_progression\`.
+
+Prefer when: user wants the pulse / overview view across all their campaigns. Use campaign_progression to drill into one
+
+Examples that SHOULD invoke this tool:
+- "What campaigns am I running?"
+- "Show me my active campaigns and how they're doing."
+- "Quick pulse on my campaigns."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Create a 'Q2 Push' campaign."
+- "How are leads progressing in my Limoges Tour?"
+- "Today's fresh leads."
+
+## RENDER (quick)
+
+Render as a compact markdown table sorted by \`updated_at\` desc:
+| Campaign | Leads | Contacted | Meetings | Declined | Updated |
+Each row links to "View progression" via a NEXT STEPS chip that
+passes the campaign_id back into \`leadbay_campaign_progression\`.
+Suppress archived rows unless \`archived: true\` was passed.
+
+---
+
+List the caller's campaigns with roll-up stats. Wraps \`GET /campaigns\` (with \`?archived=true\` to surface archived ones). Each entry is \`CampaignWithStatsPayload\`: the campaign object + \`lead_count\`, \`contact_count\`, \`contacted\` (leads with any logged outreach), \`meeting_booked\` (leads with a recorded meeting outcome), \`declined\` (leads with a recorded decline).
+
+**Scope warning**: this list is filtered server-side to campaigns the calling user CREATED. Other users in the same organization with their own campaigns are not surfaced. The web UI may aggregate differently for admins; the MCP-exposed view is creator-scoped. This matters for #3630 US3 "manager-led prospecting governance" \u2014 a manager can list their own campaigns but not see a rep's. Cross-user visibility would need backend work.
+
+---
+
+WHEN TO USE: the user wants the cross-campaign pulse \u2014 what cohorts are in flight, how active each is, which need attention.
+
+WHEN NOT TO USE: for per-lead progression inside ONE campaign (use \`leadbay_campaign_progression\`); to create a campaign (\`leadbay_create_campaign\`); to add leads to one (\`leadbay_add_leads_to_campaign\`).
+
+**Response**: \`{campaigns: CampaignWithStats[], _meta}\`. Sort by \`updated_at desc\` when rendering \u2014 recency is the manager's natural lens.
+`;
 var leadbay_list_lenses = `List all available Leadbay lenses (saved lead-search configurations). Each lens defines a different target market or buyer segment. The lens with \`is_last_active=true\` is used by default for lead discovery.
 
 WHEN TO USE: when the user wants to switch lens or asks "what lenses do I have".
@@ -2521,6 +2862,101 @@ WHEN NOT TO USE: from agent flow \u2014 use leadbay_refine_prompt, which polls f
 
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
+var leadbay_tour_plan = `## WHEN TO USE
+
+Trigger phrases: "I'm visiting <city> in <N> days", "field tour in <city>", "plan a tour in <city>", "who should I meet in <city>", "mix of customers and prospects in <city>", "tour itinerary", "3 customers + 3 prospects + 3 new in <city>", "field sales tour".
+
+Do NOT use for: "follow-ups only on the map (no new prospects mixed in)" \u2192 \`leadbay_followups_map\`; "new leads only, no geography" \u2192 \`leadbay_pull_leads\`; "research one specific account I picked" \u2192 \`leadbay_research_lead_by_id\`.
+
+Prefer when: user wants both KNOWN accounts AND NEW discovery in one geographic view. If they only want one side, route to followups_map or pull_leads instead
+
+Examples that SHOULD invoke this tool:
+- "I'm flying to Limoges in 4 days \u2014 give me 3 customers, 3 qualified prospects, and 3 new high-potential."
+- "Plan my tour next Tuesday in Lyon: known accounts plus discoveries."
+- "Build a mixed itinerary for Berlin \u2014 I want both follow-ups and fresh leads."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Show me my follow-ups for the SF trip."
+- "What's new in today's batch?"
+- "Tell me about Acme Corp."
+
+## RENDER (quick)
+
+Route the union of monitor_leads + discover_leads into
+\`places_map_display_v0\` \u2014 same recipe as followups_map (lat/lng
+split, full address, short notes). Tag each entry's notes with a
+mode badge: "\u2605 Customer" / "\u2605 Qualified" / "\u2726 New" (split Monitor
+by last_monitor_action; Discover = New). Below the widget: one
+intro sentence + per-group chat-prose list with LinkedIn-linked
+contact names.
+
+---
+
+Build a single-call mixed-mode itinerary for a field sales tour. Combines \`leadbay_pull_followups\` (Monitor leads in the city \u2014 known accounts) with \`leadbay_pull_leads\` (Discover wishlist \u2014 new prospects, then client-side filtered by city) so the agent can answer the canonical #3630 US1 ask: *"I'm visiting Limoges in 4 days \u2014 propose 3 customers + 3 qualified prospects + 3 new high-potential discoveries."*
+
+**Geo resolution** is identical to \`leadbay_followups_map\`: pass \`city\` (any admin level \u2014 city, state, country, region \u2014 the \`/geo/search\` resolver picks the best match), or a pre-resolved \`city_id\`. Ambiguous matches surface as \`status: "ambiguous_locations"\` + \`location_ambiguities[]\`; pick an id and re-call with \`city_id\`.
+
+**Counts**: \`followups_count\` (default 6 \u2014 generous so the agent can split into "customers + qualified" client-side) and \`discover_count\` (default 6 after client-side geo filter). The composite over-pulls Discover (30 raw) because the wishlist endpoint has no server-side geo filter \u2014 it then filters by \`location.city/state/country/full\` substring match against the requested city. The \`discover_filter_note\` string in the response tells the agent the match ratio so it can be honest about coverage ("matched 3/30 by city/state" vs. "matched 12/30").
+
+**What \`tour_plan\` does NOT do**: it doesn't persist the tour as a campaign artifact. To do that \u2014 create a "Limoges Tour \u2013 May 24" campaign and attach the selected accounts \u2014 chain into \`leadbay_create_campaign({lead_ids: [...selected_ids], name: 'Limoges Tour \u2013 <date>'})\` after the user picks. See the \`leadbay_plan_tour_in_city\` prompt for the full end-to-end orchestrator.
+
+---
+
+## RENDER \u2014 host-native map widget (REQUIRED, preferred)
+
+Identical to \`leadbay_followups_map\`. Pass the union \`monitor_leads + discover_leads\` into \`places_map_display_v0\`. The mode information goes in the per-lead \`notes\` string as a **leading badge**:
+
+- \`\u2605 Customer\` \u2014 Monitor lead with an existing \`last_monitor_action\` history (engaged / past interaction).
+- \`\u2605 Qualified\` \u2014 Monitor lead with a high \`ai_agent_lead_score\` or \`score\` but no recent action.
+- \`\u2726 New\` \u2014 Discover lead from \`discover_leads\`.
+
+Then the rest of the notes string follows the standard recipe: ONE sentence, sector/fit + contact ask, bare phone + email auto-linkified. Example:
+
+\`\`\`
+\u2726 New \u2014 Strong mid-size hardware distributor fit. Reach Marie Dupont, Sales Director: +33 5 55 12 34 56, m.dupont@example.fr.
+\`\`\`
+
+Skip any lead whose \`location.pos\` is null (no lat/lng \u2192 no pin) \u2014 list them as a "+ N leads without coordinates" footer below the widget.
+
+## Chat prose AFTER the widget (where markdown DOES render)
+
+Group the leads into THREE sections (Customers / Qualified Prospects / New Discoveries) and emit a short chat-prose list per group with LinkedIn-linked contact name + bare phone/email pills. This is the "Notes from Claude" companion that the carousel can't render. Mirror the \`followups_map\` recipe exactly \u2014 score callout, contact name as markdown link, \`\xB7\`-separated channel pills.
+
+If the user said something like "3+3+3", honor that split. If \`followups_count\` returned fewer Customers than asked, fill from Qualified.
+
+## RENDER \u2014 fallback for hosts without \`places_map_display_v0\`
+
+Emit per-lead markdown blocks grouped by mode, in the standard place-card-friendly format (\`### **Company** \xB7 City, State\`, mode badge + score, contact line, channel lines). Hosts that auto-detect addresses (Claude.ai web, cowork) build their own carousel from these blocks.
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
+
+---
+
+WHEN TO USE: the user signals a *mixed* tour-planning intent \u2014 they want both known accounts AND fresh discoveries on one geographic view, typically for a planned visit.
+
+WHEN NOT TO USE: if the user only wants follow-ups (use \`leadbay_followups_map\`), only wants new leads (use \`leadbay_pull_leads\`), wants research on one specific account (\`leadbay_research_lead_by_id\`), or wants to persist the tour as a campaign artifact (chain into \`leadbay_create_campaign\` after this).
+
+**Response envelope**: \`{city, city_id, monitor_leads, discover_leads, discover_filter_note, _meta}\` on happy path; \`{status: "ambiguous_locations", location_ambiguities, ...}\` when the passed \`city\` matched multiple admin areas.
+`;
 var leadbay_update_lens = `Update lens metadata (name, description, mode flags). Does NOT change the audience filter \u2014 use leadbay_update_lens_filter for that.
 
 WHEN TO USE: rename a lens or toggle \`multi_product_mode\` / \`use_hq_only\`.
@@ -6776,30 +7212,657 @@ var followupsMap = {
   execute: pullFollowups.execute
 };
 
-// ../core/dist/composite/research-lead-by-id.js
-function normalizeLinkedinPage5(v) {
-  if (v == null)
-    return null;
-  if (typeof v !== "string")
-    return null;
-  const trimmed = v.trim();
-  if (!trimmed || trimmed.toLowerCase() === "null")
-    return null;
-  return trimmed;
+// ../core/dist/composite/tour-plan.js
+var DEFAULT_FOLLOWUPS_COUNT = 6;
+var DEFAULT_DISCOVER_COUNT = 6;
+var DISCOVER_OVER_PULL = 30;
+function cityMatches(lead, cityHint) {
+  if (!cityHint)
+    return true;
+  const hint = cityHint.toLowerCase();
+  const loc = lead?.location ?? {};
+  const haystacks = [loc.city, loc.state, loc.country, loc.full].filter((v) => typeof v === "string").map((v) => v.toLowerCase());
+  return haystacks.some((h) => h.includes(hint) || hint.includes(h));
 }
-function renderResearchLeadMarkdown(shape) {
-  const out = [];
-  const firm = shape.firmographics ?? {};
-  const name = firm.name ?? "(unnamed lead)";
-  out.push(`# ${name}`);
-  if (firm.website)
-    out.push(`Website: ${firm.website}`);
-  if (firm.location)
-    out.push(`Location: ${firm.location}`);
-  if (typeof firm.score === "number" || firm.score === null) {
-    const aiScore = firm.ai_agent_lead_score;
-    out.push(`Score: ${firm.score ?? "\u2014"}` + (aiScore != null ? ` \xB7 AI: ${aiScore}` : ""));
-  }
+var tourPlan = {
+  name: "leadbay_tour_plan",
+  annotations: {
+    title: "Plan a mixed-mode tour itinerary (known + fresh leads)",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_tour_plan,
+  inputSchema: {
+    type: "object",
+    properties: {
+      city: {
+        type: "string",
+        description: "Free-text city or region (e.g. 'Limoges', 'Bay Area'). Resolved via the same /geo/search the followups_map uses. Ambiguous matches surface as `status: ambiguous_locations` with location_ambiguities[]; pick a location id and re-call with city_id."
+      },
+      city_id: {
+        type: "string",
+        description: "Pre-resolved admin_area id (numeric string). Bypasses the resolver."
+      },
+      followups_count: {
+        type: "number",
+        description: `Top-N follow-up (Monitor) leads to return. Default ${DEFAULT_FOLLOWUPS_COUNT}.`
+      },
+      discover_count: {
+        type: "number",
+        description: `Top-N Discover leads (active lens wishlist) to return after client-side city filter. Default ${DEFAULT_DISCOVER_COUNT}.`
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      city: { type: ["string", "null"] },
+      city_id: { type: ["string", "null"] },
+      monitor_leads: {
+        type: "array",
+        description: "Follow-up (Monitor) leads in the requested city, sorted by AI / firmographic score. Each lead carries the same shape as pull_followups.",
+        items: { type: "object" }
+      },
+      discover_leads: {
+        type: "array",
+        description: "Fresh Discover leads from the active lens, filtered client-side to match the city. Pulls a larger candidate set internally to compensate for the missing server-side geo filter.",
+        items: { type: "object" }
+      },
+      discover_filter_note: {
+        type: "string",
+        description: "Human-readable summary of the client-side geo filter applied to Discover leads (e.g. 'matched 3/30 by city/state')."
+      },
+      status: {
+        type: "string",
+        description: "'ambiguous_locations' when the passed `city` matched multiple admin areas \u2014 pick an id from location_ambiguities and re-call with city_id."
+      },
+      location_ambiguities: {
+        type: "array",
+        items: { type: "object" }
+      },
+      _meta: {
+        type: "object",
+        properties: {
+          region: { type: "string" },
+          latency_ms: { type: ["number", "null"] }
+        }
+      }
+    },
+    required: ["monitor_leads", "discover_leads"]
+  },
+  execute: async (client, params, ctx) => {
+    const followupsCount = params.followups_count ?? DEFAULT_FOLLOWUPS_COUNT;
+    const discoverCount = params.discover_count ?? DEFAULT_DISCOVER_COUNT;
+    const [followupsResult, leadsResult] = await Promise.allSettled([
+      pullFollowups.execute(client, {
+        city: params.city,
+        city_id: params.city_id,
+        count: followupsCount
+      }, ctx),
+      pullLeads.execute(client, { count: DISCOVER_OVER_PULL }, ctx)
+    ]);
+    if (followupsResult.status === "fulfilled") {
+      const r = followupsResult.value;
+      if (r?.status === "ambiguous_locations") {
+        return {
+          status: "ambiguous_locations",
+          location_ambiguities: r.location_ambiguities,
+          monitor_leads: [],
+          discover_leads: [],
+          discover_filter_note: "City was ambiguous; pick an id and re-call to proceed.",
+          city: params.city ?? null,
+          city_id: params.city_id ?? null,
+          _meta: {
+            region: client.region,
+            latency_ms: client.lastMeta?.latency_ms ?? null
+          }
+        };
+      }
+    }
+    const monitorLeads = followupsResult.status === "fulfilled" ? followupsResult.value?.leads ?? [] : [];
+    if (followupsResult.status === "rejected") {
+      ctx?.logger?.warn?.(`tour_plan: pull_followups failed: ${followupsResult.reason?.message ?? followupsResult.reason}`);
+    }
+    const rawDiscover = leadsResult.status === "fulfilled" ? leadsResult.value?.leads ?? [] : [];
+    if (leadsResult.status === "rejected") {
+      ctx?.logger?.warn?.(`tour_plan: pull_leads failed: ${leadsResult.reason?.message ?? leadsResult.reason}`);
+    }
+    const filtered = rawDiscover.filter((l) => cityMatches(l, params.city));
+    const discoverLeads2 = filtered.slice(0, discoverCount);
+    const filterNote = params.city ? `Matched ${filtered.length}/${rawDiscover.length} Discover leads to '${params.city}'; returning top ${discoverLeads2.length}.` : `No city filter applied; returning top ${discoverLeads2.length} Discover leads.`;
+    return {
+      city: params.city ?? null,
+      city_id: params.city_id ?? null,
+      monitor_leads: monitorLeads,
+      discover_leads: discoverLeads2,
+      discover_filter_note: filterNote,
+      _meta: {
+        region: client.region,
+        latency_ms: client.lastMeta?.latency_ms ?? null
+      }
+    };
+  }
+};
+
+// ../core/dist/composite/create-campaign.js
+var createCampaign = {
+  name: "leadbay_create_campaign",
+  annotations: {
+    title: "Create a named campaign (optionally seeded with leads)",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  description: leadbay_create_campaign,
+  optional: true,
+  // gated behind LEADBAY_MCP_WRITE=1 in MCP
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "Campaign display name (max 255 chars). Omit to let the backend AI-generate one from the seed lead_ids. If lead_ids is empty AND name is omitted, the backend assigns a default."
+      },
+      lead_ids: {
+        type: "array",
+        description: "Lead UUIDs to attach at creation. Empty array (default) creates an empty campaign \u2014 add leads later via leadbay_add_leads_to_campaign. Non-empty seed enables AI name suggestion.",
+        items: { type: "string" }
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "Campaign UUID." },
+      name: { type: "string" },
+      ai_generated_name: { type: ["string", "null"] },
+      ai_name_count: { type: "number" },
+      archived: { type: "boolean" },
+      created_by: { type: "string" },
+      created_at: { type: "string" },
+      updated_at: { type: "string" },
+      last_accessed_at: { type: "string" }
+    },
+    required: ["id", "name", "created_at"]
+  },
+  execute: async (client, params) => {
+    const body = {
+      lead_ids: params.lead_ids ?? []
+    };
+    if (params.name && params.name.trim().length > 0) {
+      body.name = params.name.slice(0, 255);
+    }
+    const result = await client.request("POST", `/campaigns`, body);
+    return result;
+  }
+};
+
+// ../core/dist/composite/add-leads-to-campaign.js
+var addLeadsToCampaign = {
+  name: "leadbay_add_leads_to_campaign",
+  annotations: {
+    title: "Add leads to an existing campaign",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_add_leads_to_campaign,
+  optional: true,
+  inputSchema: {
+    type: "object",
+    properties: {
+      campaign_id: {
+        type: "string",
+        description: "Campaign UUID (from leadbay_create_campaign or leadbay_list_campaigns)."
+      },
+      lead_ids: {
+        type: "array",
+        description: "Lead UUIDs to add. Backend rejects unknown lead UUIDs with 404 \u2014 pass UUIDs sourced from pull_leads / pull_followups / tour_plan / research.",
+        items: { type: "string" },
+        minItems: 1
+      }
+    },
+    required: ["campaign_id", "lead_ids"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      added: { type: "number", description: "Leads newly attached." },
+      already_present: { type: "number", description: "Leads that were already in this campaign \u2014 no-op." }
+    },
+    required: ["added", "already_present"]
+  },
+  execute: async (client, params) => {
+    if (!params.lead_ids || params.lead_ids.length === 0) {
+      throw client.makeError("INVALID_PARAMS", "lead_ids must be a non-empty array", "Pass at least one lead UUID to add. To create an empty campaign, use leadbay_create_campaign with lead_ids: [].");
+    }
+    const result = await client.request("POST", `/campaigns/${params.campaign_id}/leads`, { lead_ids: params.lead_ids });
+    return result;
+  }
+};
+
+// ../core/dist/composite/list-campaigns.js
+var listCampaigns = {
+  name: "leadbay_list_campaigns",
+  annotations: {
+    title: "List your campaigns (with roll-up stats)",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_list_campaigns,
+  inputSchema: {
+    type: "object",
+    properties: {
+      archived: {
+        type: "boolean",
+        description: "Include archived campaigns only. Default false (active only)."
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      campaigns: {
+        type: "array",
+        description: "Each entry is {campaign, lead_count, contact_count, contacted, meeting_booked, declined}. `contacted` = leads with at least one logged outreach; `meeting_booked` = leads with a recorded meeting outcome; `declined` = leads with a recorded decline outcome.",
+        items: { type: "object" }
+      },
+      _meta: {
+        type: "object",
+        properties: {
+          region: { type: "string" },
+          latency_ms: { type: ["number", "null"] }
+        }
+      }
+    },
+    required: ["campaigns"]
+  },
+  execute: async (client, params) => {
+    const archived = params.archived ?? false;
+    const qs = archived ? "?archived=true" : "";
+    const campaigns = await client.request("GET", `/campaigns${qs}`);
+    return {
+      campaigns,
+      _meta: {
+        region: client.region,
+        latency_ms: client.lastMeta?.latency_ms ?? null
+      }
+    };
+  }
+};
+
+// ../core/dist/composite/campaign-progression.js
+function hasOutreachSignal(progress) {
+  if (!progress)
+    return false;
+  return Boolean(progress.headline || (progress.in_progress ?? 0) > 0 || (progress.declined ?? 0) > 0);
+}
+var campaignProgression = {
+  name: "leadbay_campaign_progression",
+  annotations: {
+    title: "Read per-lead progression inside a campaign",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_campaign_progression,
+  inputSchema: {
+    type: "object",
+    properties: {
+      campaign_id: {
+        type: "string",
+        description: "Campaign UUID (from leadbay_create_campaign or leadbay_list_campaigns)."
+      },
+      count: { type: "number", description: "Leads per page (default 50, server-capped)." },
+      page: { type: "number", description: "0-indexed page (default 0)." }
+    },
+    required: ["campaign_id"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      items: {
+        type: "array",
+        description: "Per-lead progression rows: {lead, progress: {total_contacts, in_progress, declined, headline}, affiliation: {own_campaigns, other_users_campaign_count}}. `headline` is the most recent interaction type (e.g. CONTACTED, MEETING_BOOKED, DECLINED).",
+        items: { type: "object" }
+      },
+      pagination: {
+        type: "object",
+        properties: {
+          page: { type: "number" },
+          pages: { type: "number" },
+          total: { type: "number" }
+        }
+      },
+      summary: {
+        type: "object",
+        description: "Roll-up across the current page: how many leads have any outreach, how many converted to meetings, how many were declined.",
+        properties: {
+          page_size: { type: "number" },
+          contacted: { type: "number" },
+          in_progress: { type: "number" },
+          declined: { type: "number" }
+        }
+      },
+      _meta: {
+        type: "object",
+        properties: {
+          region: { type: "string" },
+          latency_ms: { type: ["number", "null"] }
+        }
+      }
+    },
+    required: ["items", "pagination", "summary"]
+  },
+  execute: async (client, params) => {
+    const count = params.count ?? 50;
+    const page = params.page ?? 0;
+    const result = await client.request("GET", `/campaigns/${params.campaign_id}/leads?count=${count}&page=${page}`);
+    let contacted = 0;
+    let inProgress = 0;
+    let declined = 0;
+    for (const row of result.items) {
+      const p = row.progress;
+      if (hasOutreachSignal(p))
+        contacted++;
+      if ((p?.in_progress ?? 0) > 0)
+        inProgress++;
+      if ((p?.declined ?? 0) > 0)
+        declined++;
+    }
+    return {
+      items: result.items,
+      pagination: result.pagination,
+      summary: {
+        page_size: result.items.length,
+        contacted,
+        in_progress: inProgress,
+        declined
+      },
+      _meta: {
+        region: client.region,
+        latency_ms: client.lastMeta?.latency_ms ?? null
+      }
+    };
+  }
+};
+
+// ../core/dist/composite/campaign-call-sheet.js
+function hasOutreachSignal2(progress) {
+  if (!progress)
+    return false;
+  return Boolean(progress.headline || (progress.in_progress ?? 0) > 0 || (progress.declined ?? 0) > 0);
+}
+function normalizeLinkedin(v) {
+  if (typeof v !== "string")
+    return null;
+  const t = v.trim();
+  if (!t || t.toLowerCase() === "null")
+    return null;
+  return t;
+}
+function constructLinkedinFallback(first, last, company) {
+  if (!first || !last)
+    return null;
+  const cleanedCompany = (company ?? "").replace(/\s+(Inc|LLC|Corp|GmbH|Ltd|Co|S\.A\.|S\.L\.|PLC|AG|SAS|SARL)\.?$/gi, "").trim();
+  const keywords = encodeURIComponent([first, last, cleanedCompany].filter(Boolean).join(" "));
+  return `https://www.linkedin.com/search/results/people/?keywords=${keywords}`;
+}
+var campaignCallSheet = {
+  name: "leadbay_campaign_call_sheet",
+  annotations: {
+    title: "Cold-calling cheat sheet for a campaign",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_campaign_call_sheet,
+  inputSchema: {
+    type: "object",
+    properties: {
+      campaign_id: {
+        type: "string",
+        description: "Campaign UUID (from leadbay_create_campaign or leadbay_list_campaigns)."
+      },
+      count: {
+        type: "number",
+        description: "Leads per page for the underlying /campaigns/{id}/leads fetch (default 50). The contacts endpoint is not paginated; the composite always fetches all contacts and aligns them with the leads page."
+      },
+      page: {
+        type: "number",
+        description: "0-indexed page (default 0)."
+      }
+    },
+    required: ["campaign_id"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      campaign_id: { type: "string" },
+      leads: {
+        type: "array",
+        description: "Per-lead call-ready blocks sorted by score desc. Each block: {lead_id, lead_name, score, ai_agent_lead_score, location, website, next_step, approach_angle, worth_pursuing, progress, affiliation, contacts: [{first_name, last_name, full_name, phone_number, phone_tel_url, email, mailto_url, linkedin_url, linkedin_url_source, job_title, recommended, pinned, recent_notes}]}.",
+        items: { type: "object" }
+      },
+      map_locations: {
+        type: "array",
+        description: "Ready-to-pass entries for `places_map_display_v0` when the user wants a geographic call route: {name, address, latitude, longitude, notes}. One entry per lead that has a valid pos[]. Skip leads without coordinates.",
+        items: { type: "object" }
+      },
+      summary: {
+        type: "object",
+        description: "Roll-up: total_leads, total_contacts, leads_with_phone, leads_with_email, leads_with_coords, leads_without_contacts, leads_already_contacted (headline/in_progress/declined outreach signal present).",
+        properties: {
+          total_leads: { type: "number" },
+          total_contacts: { type: "number" },
+          leads_with_phone: { type: "number" },
+          leads_with_email: { type: "number" },
+          leads_with_coords: { type: "number" },
+          leads_without_contacts: { type: "number" },
+          leads_already_contacted: { type: "number" }
+        }
+      },
+      readiness: {
+        type: "object",
+        description: "Pre-computed booleans the orchestrator prompt uses to decide which session modes to OFFER. ready_for_calling (phone coverage \u226560%), ready_for_emailing (email coverage \u226560%), needs_enrichment (\u226530% no-contact leads OR both phone+email coverage <40%), travel_friendly (\u22655 geocoded leads AND coord coverage \u226560%).",
+        properties: {
+          ready_for_calling: { type: "boolean" },
+          ready_for_emailing: { type: "boolean" },
+          needs_enrichment: { type: "boolean" },
+          travel_friendly: { type: "boolean" }
+        }
+      },
+      pagination: {
+        type: "object",
+        properties: {
+          page: { type: "number" },
+          pages: { type: "number" },
+          total: { type: "number" }
+        }
+      },
+      _meta: {
+        type: "object",
+        properties: {
+          region: { type: "string" },
+          latency_ms: { type: ["number", "null"] }
+        }
+      }
+    },
+    required: ["campaign_id", "leads", "summary"]
+  },
+  execute: async (client, params) => {
+    const count = params.count ?? 50;
+    const page = params.page ?? 0;
+    const [contactsRes, leadsRes] = await Promise.all([
+      client.request("GET", `/campaigns/${params.campaign_id}/contacts`),
+      client.request("GET", `/campaigns/${params.campaign_id}/leads?count=${count}&page=${page}`)
+    ]);
+    const contactsByLeadId = /* @__PURE__ */ new Map();
+    for (const row of contactsRes) {
+      contactsByLeadId.set(row.lead_id, row);
+    }
+    const blocks = leadsRes.items.map((row) => {
+      const lead = row.lead;
+      const contactsRow = contactsByLeadId.get(lead.id);
+      const contacts = (contactsRow?.contacts ?? []).map((c) => {
+        const linkedin = normalizeLinkedin(c.contact.linkedin_page);
+        const fallbackLi = linkedin ? null : constructLinkedinFallback(c.contact.first_name, c.contact.last_name, lead.name);
+        const phone = (c.contact.phone_number ?? "").trim() || null;
+        const telUrl = phone ? `tel:${phone.replace(/[^\d+]/g, "")}` : null;
+        const email = (c.contact.email ?? "").trim() || null;
+        const mailtoUrl = email ? `mailto:${email}` : null;
+        const fullName = [c.contact.first_name, c.contact.last_name].filter(Boolean).join(" ").trim();
+        return {
+          id: c.contact.id,
+          first_name: c.contact.first_name ?? null,
+          last_name: c.contact.last_name ?? null,
+          full_name: fullName || null,
+          job_title: c.contact.job_title ?? null,
+          phone_number: phone,
+          phone_tel_url: telUrl,
+          email,
+          mailto_url: mailtoUrl,
+          linkedin_url: linkedin ?? fallbackLi,
+          linkedin_url_source: linkedin ? "leadbay" : fallbackLi ? "constructed" : null,
+          recommended: c.contact.recommended ?? false,
+          pinned: c.contact.pinned ?? false,
+          pinned_by_ai: c.contact.pinned_by_ai ?? false,
+          recent_notes: c.recent_notes ?? []
+        };
+      });
+      contacts.sort((a, b) => {
+        const aRank = (a.pinned_by_ai ? 4 : 0) + (a.recommended ? 2 : 0) + (a.phone_number ? 1 : 0);
+        const bRank = (b.pinned_by_ai ? 4 : 0) + (b.recommended ? 2 : 0) + (b.phone_number ? 1 : 0);
+        return bRank - aRank;
+      });
+      const splitSummary = lead.split_ai_summary ?? {};
+      const headline = row.progress?.headline ?? null;
+      return {
+        lead_id: lead.id,
+        lead_name: lead.name,
+        score: lead.score ?? null,
+        ai_agent_lead_score: lead.ai_agent_lead_score ?? null,
+        website: lead.website ?? null,
+        location: lead.location ?? null,
+        company_phone_numbers: lead.phone_numbers ?? [],
+        next_step: splitSummary.next_step ?? null,
+        approach_angle: splitSummary.approach_angle ?? null,
+        worth_pursuing: splitSummary.worth_pursuing ?? null,
+        short_description: lead.short_description ?? null,
+        last_action_headline: headline,
+        progress: row.progress ?? null,
+        affiliation: row.affiliation ?? null,
+        contacts
+      };
+    });
+    blocks.sort((a, b) => {
+      const aScore = a.ai_agent_lead_score ?? a.score ?? 0;
+      const bScore = b.ai_agent_lead_score ?? b.score ?? 0;
+      return bScore - aScore;
+    });
+    const mapLocations = blocks.filter((b) => {
+      const pos = b.location?.pos;
+      return Array.isArray(pos) && pos.length === 2 && pos.every((n) => typeof n === "number");
+    }).map((b) => {
+      const topContact = b.contacts[0];
+      const angle = b.next_step ?? b.approach_angle ?? "Worth pursuing";
+      let notes;
+      if (topContact?.phone_number && topContact?.full_name) {
+        notes = `\u2605 ${angle} \u2014 call ${topContact.full_name}, \u260E ${topContact.phone_number}.`;
+      } else if (topContact?.email && topContact?.full_name) {
+        notes = `\u2605 ${angle} \u2014 email ${topContact.full_name} at ${topContact.email}.`;
+      } else if (topContact?.full_name) {
+        notes = `\u2605 ${angle} \u2014 reach ${topContact.full_name} (no channel enriched yet).`;
+      } else {
+        notes = `\u2605 ${angle} \u2014 enrich titles to surface a contact.`;
+      }
+      return {
+        name: b.lead_name,
+        address: b.location?.full ?? [b.location?.city, b.location?.state, b.location?.country].filter(Boolean).join(", "),
+        latitude: b.location.pos[0],
+        longitude: b.location.pos[1],
+        notes: notes.slice(0, 280)
+        // place-card notes truncate visibly past ~30 words
+      };
+    });
+    const totalContacts = blocks.reduce((acc, b) => acc + b.contacts.length, 0);
+    const leadsWithPhone = blocks.filter((b) => b.contacts.some((c) => c.phone_number) || b.company_phone_numbers.length > 0).length;
+    const leadsWithEmail = blocks.filter((b) => b.contacts.some((c) => c.email)).length;
+    const leadsWithoutContacts = blocks.filter((b) => b.contacts.length === 0).length;
+    const leadsAlreadyContacted = blocks.filter((b) => hasOutreachSignal2(b.progress)).length;
+    const leadsWithCoords = blocks.filter((b) => Array.isArray(b.location?.pos) && b.location.pos.length === 2 && b.location.pos.every((n) => typeof n === "number")).length;
+    const total = blocks.length;
+    const phoneRatio = total > 0 ? leadsWithPhone / total : 0;
+    const emailRatio = total > 0 ? leadsWithEmail / total : 0;
+    const coordRatio = total > 0 ? leadsWithCoords / total : 0;
+    const noContactRatio = total > 0 ? leadsWithoutContacts / total : 0;
+    const readiness = {
+      ready_for_calling: phoneRatio >= 0.6,
+      ready_for_emailing: emailRatio >= 0.6,
+      needs_enrichment: noContactRatio >= 0.3 || phoneRatio < 0.4 && emailRatio < 0.4,
+      travel_friendly: leadsWithCoords >= 5 && coordRatio >= 0.6
+    };
+    return {
+      campaign_id: params.campaign_id,
+      leads: blocks,
+      map_locations: mapLocations,
+      summary: {
+        total_leads: blocks.length,
+        total_contacts: totalContacts,
+        leads_with_phone: leadsWithPhone,
+        leads_with_email: leadsWithEmail,
+        leads_with_coords: leadsWithCoords,
+        leads_without_contacts: leadsWithoutContacts,
+        leads_already_contacted: leadsAlreadyContacted
+      },
+      readiness,
+      pagination: leadsRes.pagination,
+      _meta: {
+        region: client.region,
+        latency_ms: client.lastMeta?.latency_ms ?? null
+      }
+    };
+  }
+};
+
+// ../core/dist/composite/research-lead-by-id.js
+function normalizeLinkedinPage5(v) {
+  if (v == null)
+    return null;
+  if (typeof v !== "string")
+    return null;
+  const trimmed = v.trim();
+  if (!trimmed || trimmed.toLowerCase() === "null")
+    return null;
+  return trimmed;
+}
+function renderResearchLeadMarkdown(shape) {
+  const out = [];
+  const firm = shape.firmographics ?? {};
+  const name = firm.name ?? "(unnamed lead)";
+  out.push(`# ${name}`);
+  if (firm.website)
+    out.push(`Website: ${firm.website}`);
+  if (firm.location)
+    out.push(`Location: ${firm.location}`);
+  if (typeof firm.score === "number" || firm.score === null) {
+    const aiScore = firm.ai_agent_lead_score;
+    out.push(`Score: ${firm.score ?? "\u2014"}` + (aiScore != null ? ` \xB7 AI: ${aiScore}` : ""));
+  }
   if (firm.short_description)
     out.push(`
 ${firm.short_description}`);
@@ -11420,6 +12483,10 @@ var compositeReadTools = [
   pullLeads,
   pullFollowups,
   followupsMap,
+  tourPlan,
+  listCampaigns,
+  campaignProgression,
+  campaignCallSheet,
   researchLeadById,
   researchLeadByNameFuzzy,
   recallOrderedTitles,
@@ -11460,7 +12527,11 @@ var compositeWriteTools = [
   // likeLead/dislikeLead are granular-shaped but should always be available
   // to the agent without requiring LEADBAY_MCP_ADVANCED=1.
   likeLead,
-  dislikeLead
+  dislikeLead,
+  // Campaign write composites — persist a hand-picked cohort of leads.
+  // Backend POST endpoints; gated behind LEADBAY_MCP_WRITE=1 in MCP.
+  createCampaign,
+  addLeadsToCampaign
 ];
 var compositeTools = [
   ...compositeReadTools,