@leadbay/mcp 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — @leadbay/mcp
 
+## 0.7.0 — UNRELEASED
+
+**Compile pipeline for prompts and tool descriptions**: every MCP prompt body and every Tool description is now authored as a `.md.tmpl` source file in the new `@leadbay/promptforge` workspace package and compiled into `prompts.generated.ts` / `tool-descriptions.generated.ts` at build time. Authors edit prose in one place; the generated TS modules are the bundle's source of inlined strings. No wire-format change: every consumer (Claude Desktop, Cursor, Claude Code, OpenClaw) sees the same MCP protocol shape — `tools/list`, `prompts/list`, `prompts/get` are unchanged. Backwards-compat: every tool name, every `inputSchema`, every annotation set, every `outputSchema` is preserved byte-for-byte. The descriptions themselves are rewritten (see below) — that is the visible change.
+
+**PHASES + IRON LAWS + GATES in every prompt**: all 6 prompts (`leadbay_daily_check_in`, `leadbay_research_a_domain`, `leadbay_import_file`, `leadbay_refine_audience`, `leadbay_log_outreach`, `leadbay_qualify_top_n`) restructured into explicit phases, with byproduct gates the agent must emit before progressing (`COLUMN PRESERVATION PLAN`, `DECISION LOG`, `FINAL REPORT` for file import; `STOP — awaiting user decision` for daily check-in). IRON LAW lines codify non-negotiables (no fabrication of leadIds; verification source required before `report_outreach`; top-N triage with motivational framing for `daily_check_in`).
+
+**All 60 tool descriptions rewritten through shared snippets**: 21 composite + 37 granular + 2 file-import companion tools migrated. Each description uses shared snippet partials (`{{include:headers/tool-when-to-use}}`, `{{include:headers/tool-when-not-to-use}}`, `{{include:headers/verification-required-if-write}}` for write tools). 58 of 60 fit under 1500 chars; the two longest (`leadbay_import_leads`, `leadbay_list_mappable_fields`) retain their load-bearing detail at ~3100 chars. Audit test enforces a 3500-char per-tool budget.
+
+**Shared snippet library**: 11 partials live in `packages/promptforge/snippets/` (iron-laws, gates, heuristics, headers). Most reusable today: `heuristics/crm-record-link.md` (extends the previous HubSpot guidance to Salesforce, Pipedrive, Close, Attio with per-CRM `url_template` examples for EXTERNAL_ID custom fields) and `heuristics/consumer-email-domains.md` with the explicit "domain extraction is a key factor of match success" framing.
+
+**Daily check-in prompt overhaul** (per user direction): triage scope widened from top-3 to **top-10**, preferring leads with a fresh `ai_agent_lead_score`; each summary now framed motivationally ("why prospecting this lead today might be a good idea"); auto-top-up via `leadbay_bulk_qualify_leads` when the batch is short; PHASE 4 now researches **every** promising lead and surfaces the recommended contacts; the agent ASKS the user before consuming contact-enrichment quota.
+
+**Import-file prompt overhaul** (per user direction): explicit GOAL section at the top — the job is to maximize how many rows the Leadbay system can ingest and match. Two deliverables named: max-coverage column mapping + the user's original file augmented with a `LEADBAY_ID` column populated for confidently disambiguated rows. WHAT GOOD LOOKS LIKE section teaches the disambiguation bar positively; the "never pick from score alone..." guardrail remains as a hard rule.
+
+**Test framework spine** (`packages/mcp/test/eval/`): full eval harness landed. Drives scripted Claude sessions against the in-process MCP Server, captures L1+L2+L3 Evidence (tool calls, transcript, invariants, judge scores), runs a mission-match judge that reads its rubric from the prompt's frontmatter, enforces an Evidence-pyramid completeness rule, supports atomic partial saves to `.context/evals/<run-id>.json`, computes budget-regression flags, ships a worktree-based drift detector for main-vs-branch comparison, and includes a tool-routing classifier eval with 70+ (intent → expected_tool) fixtures. Gated by `EVAL=1`; default `pnpm test` ignores it. Replay-by-default for backend HTTP (`EVAL_RECORD=1` opt-in) keeps the user's Leadbay quota safe by construction.
+
+**Audit tests** (`packages/mcp/test/audit/`): five new T0 meta-properties enforced on every commit — every prompt has eval coverage, tool descriptions imported (never inline in `server.ts`), per-tool char budget, `leadbay_<verb>_<noun>` naming convention, snippet orphans + dead `{{include:...}}` refs. Snapshot regression test catches accidental prose loss in migrated prompts.
+
+**Agentic file import prep** (carryover entry — work landed in the merged 0.6.4 PR but never got a published changelog entry; rolled forward here): `leadbay_resolve_import_rows` — a read-only resolver that calls the backend `/leads/resolve` endpoint for messy CSV-shaped rows, returns matched/ambiguous/unresolved candidates, can hydrate ambiguous candidates with active-lens profile facts, and emits `records_for_import` plus safe identity-only `mappings_for_import` for `leadbay_import_leads` / `leadbay_import_and_qualify`. Import mappings accept `LEADBAY_ID`, `CRM_ID`, and `SIREN` as resolver fields.
+
 ## 0.6.3 — 2026-05-12
 
 **Async import schema fix**: `leadbay_import_leads` now declares both its legacy blocking result shape and its async kickoff shape (`{status: "running", handle_id, importIds, progress}`) in `outputSchema`, so Claude Desktop and other MCP SDK clients accept the fast handle response instead of rejecting `structuredContent`.

package/dist/bin.js

@@ -8,7 +8,7 @@ import {
   granularReadTools,
   granularWriteTools,
   resolveRegion
-} from "./chunk-QAOJARMK.js";
+} from "./chunk-3WNCQ7MP.js";
 
 // src/bin.ts
 import { realpathSync } from "fs";
@@ -31,24 +31,306 @@ import {
   CompleteRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 
+// src/prompts.generated.ts
+var leadbay_daily_check_in = `
+Run the Leadbay daily check-in for me. Treat this prompt the same way for any equivalent ask: "get me leadbay leads", "best leads to prospect today", "what should I work on", "show me my batch".
+
+# PHASE 1 \u2014 STATE
+Call \`leadbay_account_status\` to see what quota I have left and which lens is active. Note the remaining \`ai_rescore_remaining\` and \`web_fetch_remaining\` budgets \u2014 Phase 4 enrichment depends on them.
+
+# PHASE 2 \u2014 FRESH BATCH
+Call \`leadbay_pull_leads\` to get today's fresh batch.
+
+# PHASE 3 \u2014 TRIAGE (top 10, motivational framing)
+
+Pick the top **10** leads \u2014 prefer leads with a fresh \`ai_agent_lead_score\` (those have been newly AI-qualified); fall back to \`score\` only when \`ai_agent_lead_score\` is absent. For each, write ONE motivational sentence \u2014 framed as *why prospecting this lead today might be a good idea right now* (almost a coach's nudge, not a flat description). Lean on \`qualification_summary\` for the substance, but reframe \u2014 don't paste it verbatim.
+
+If the batch returns fewer than 10 qualified leads, top it up by calling \`leadbay_bulk_qualify_leads\` with \`count\` set a bit above what you still need (some leads may get disqualified during qualification \u2014 request 1.5x the deficit, capped at 25). Then re-pull the batch and continue. (The \`leadbay_qualify_top_n\` slash-prompt wraps this same tool with a friendlier surface for users; agents should call the underlying tool directly here.)
+
+# PHASE 4 \u2014 DEEP DIVE (every promising lead)
+
+Call \`leadbay_research_lead\` on **every** lead from your top 10 that the user might realistically prospect today (filter out clearly weak fits if any). Don't pick just one. For each researched lead surface:
+- what makes it promising (1\u20132 sentences citing signals from the research)
+- the **recommended contacts** the research returns \u2014 name, title, why they're the right starting point
+
+Then ASK the user (don't auto-run): "Want me to enrich the contacts on these leads to acquire their emails / phone numbers?" If the user says yes, call \`leadbay_enrich_contacts\` for the relevant lead IDs (this consumes enrichment quota \u2014 that's why we ask first).
+
+# GATE \u2014 STOP
+
+IRON LAW \u2014 DO NOT TAKE OUTBOUND ACTION. Do not call \`leadbay_report_outreach\`. Do not draft an outreach message into a tool argument. Outreach is the user's call after they've reviewed your research.
+
+Render this acknowledgment VERBATIM as the last line of your message:
+
+\`\`\`
+STOP \u2014 awaiting user decision. I will not take any further action until you tell me what to do next.
+\`\`\`
+
+Do not propose a next action. Do not call any more tools. Hand control back to the user.
+`;
+var leadbay_import_file = `
+Import the user's Leadbay file{{arg:file_paren}} and satisfy this instruction: {{arg:instruction_or_default}}.
+
+# GOAL \u2014 what we're actually trying to do
+
+The job is to **prepare the file so the Leadbay system ingests and matches as many rows as possible**. Every choice you make in the phases below \u2014 column mapping, domain derivation, identity resolution, custom-field creation \u2014 exists to maximize that match rate. The user shouldn't have to lose data because a header was unusual, a website was missing, or a CRM column had no obvious counterpart in Leadbay.
+
+A job well done has TWO deliverables:
+1. **Maximum-coverage column mapping**: every meaningful source column is mapped \u2014 to a standard Leadbay field where one exists, to a CONTACT_* field for person columns, to a custom field where no standard fits (including the CRM record link as a special EXTERNAL_ID custom field that's later clickable inside Leadbay), or to a Leadbay note for free-text context. Dropping data is the failure case; finding it a home is the success case.
+2. **An augmented file**: the user's original file enriched with a new \`LEADBAY_ID\` column populated wherever you confidently disambiguated a match. The user keeps this as their audit trail of what got ingested and what didn't.
+
+IRON LAW \u2014 NO FABRICATION. Every lead id, contact email, custom field id, mapping decision, and tool argument must trace to a value you read from the file the user attached or to an output from a leadbay_* tool call in this session. Do not invent values. Do not "fill in" a missing leadId with a name match. Do not synthesize a CRM id from a guess. If a value is missing, leave the field blank and say so.
+
+
+# PHASE 1 \u2014 SCAN
+
+Read the file yourself. Inspect every header, sample values from multiple rows, row count, duplicate/blank columns, and obvious dirty data. Build a column preservation plan before importing: for each meaningful column decide standard field, CONTACT_* field, Leadbay note, custom field, derived helper, or skip with a reason. Default to preserving client-provided business data; skip only blank placeholders, duplicate plumbing, raw unparsed blobs after extracting their useful values, or values that would actively harm data quality.
+
+## GATE 1 \u2014 COLUMN PRESERVATION PLAN
+
+Before calling any leadbay_* tool, render the COLUMN PRESERVATION PLAN byproduct in your response. Do NOT proceed to PHASE 2 until this table is in your output.
+
+Render this block VERBATIM as your byproduct:
+
+\`\`\`
+COLUMN PRESERVATION PLAN
+========================
+| Source column      | Disposition                       | Reason                            |
+|--------------------|-----------------------------------|-----------------------------------|
+| <header from file> | standard:LEAD_NAME                | cleaned company name              |
+| <header>           | standard:LEAD_WEBSITE             | domain agrees with brand          |
+| <header>           | contact:CONTACT_EMAIL             | per-person mailbox                |
+| <header>           | custom:HubSpot record (EXTERNAL_ID)| preserve link via url_template   |
+| <header>           | note                              | meaningful per-lead context       |
+| <header>           | derived:company_domain            | extracted from biz email          |
+| <header>           | skip                              | blank placeholder / dup plumbing  |
+========================
+\`\`\`
+
+One row per meaningful source column. If you have 30+ columns, group blank/duplicate-plumbing columns under a single "skip" row with the count.
+
+
+# PHASE 2 \u2014 DERIVE (especially: company domain)
+
+**Domain extraction is the single biggest lever for match success.** A row with a company website resolves cleanly; a row without one drops to name-based fuzzy matching, which is unreliable. Whenever a row has no \`website\`/\`domain\` column but DOES have a contact email at a real business domain, derive a \`company_domain\` (and treat it as \`LEAD_WEBSITE\` for resolution) \u2014 that one move can turn a 60% match rate into 90%.
+
+**Domain extraction is a key factor of match success.** Build semantic helper columns BEFORE resolving identities. The Leadbay matcher leans heavily on \`LEAD_WEBSITE\`/\`company_domain\`; rows that arrive without one drop to fuzzy name matching, which is unreliable. Whenever a row lacks a website/domain column but contains a contact email at a real business domain, derive a \`company_domain\` from the email and treat it as \`LEAD_WEBSITE\` for resolution \u2014 but ONLY when that domain agrees with the company/deal/brand context (do not blindly use whatever's after the @).
+
+Ignore consumer mailbox domains such as gmail.com, hotmail.com, outlook.com, yahoo.com, icloud.com, proton.me/protonmail.com, aol.com, live.com, msn.com, me.com, gmx.*, and similar personal email providers \u2014 these are NOT company domains. Also ignore POS/vendor/group domains that conflict with the company (e.g. a \`square.com\` email on a coffee-shop row is the POS provider, not the shop). Keep the original email for CONTACT_EMAIL.
+
+When in doubt, sample several rows that share a candidate derived domain and confirm the company names cluster sensibly under it before committing.
+
+
+# PHASE 3 \u2014 RESOLVE IDENTITIES
+
+Decide resolver \`identity_mappings\` from the actual file semantics. Prefer: website/domain/url or **vetted derived business email domain** -> website; cleaned company/account/restaurant/establishment name -> name; CRM/system id -> crm_id; registry/SIREN/SIRET/company number -> registry_number; full address/city/postcode/country/phone/email/socials when present. For HubSpot/deal exports, clean campaign suffixes like BYOC, BYOC only, DD, Uber, trailing separators, and duplicate pipeline labels before using the value as LEAD_NAME. If a column is ambiguous, inspect row values before mapping it. Do not rely on fixed header names.
+
+Call \`leadbay_resolve_import_rows\` with representative or all rows and your explicit \`identity_mappings\`. For large files, batch rows so responses stay readable. Use \`include_candidate_profiles=true\` for small batches or rerun it on ambiguous rows only. If a row is ambiguous and candidate profiles are missing or truncated, rerun just those rows with \`include_candidate_profiles=true\` and a larger \`candidate_profile_limit\` before deciding.
+
+Disambiguate relentlessly. Use matched \`lead_id\` values directly. For ambiguous candidates, first make sure you have enough evidence: rerun the ambiguous rows with \`include_candidate_profiles=true\` and a larger \`candidate_profile_limit\` if profiles are truncated, and include every trustworthy source signal available (website, full address, postcode, city, phone, registry/CRM id, source URL path, neighborhood/location words).
+
+Compare addresses intelligently as a human would: recognize ordinary formatting, abbreviation, spelling, punctuation, casing, direction, ordinal, and suite/unit differences without reducing the decision to rigid rules.
+
+Write LEADBAY_ID when candidate facts uniquely agree with strong source evidence: exact registry/CRM id, exact phone, exact canonical website/domain with only one candidate, or name plus clear same-place address match with postcode/city and no conflict. If several candidates share the same website/domain, treat it as a chain/multi-location problem and use street address, postcode, city/neighborhood, phone, source URL path/location slug, and location words in the source name to pick the specific place when exactly one candidate matches.
+
+
+# WHAT GOOD LOOKS LIKE \u2014 the disambiguation bar
+
+A "good" run produces an **augmented file** (input file + a new LEADBAY_ID column) where every row that COULD be confidently matched IS matched, and every row that couldn't is honestly left blank with the reason. Concretely:
+
+- Write LEADBAY_ID when candidate facts uniquely agree with strong source evidence: exact registry/CRM id, exact phone, exact canonical website/domain with only one candidate, or name plus clear same-place address match with postcode/city and no conflict.
+- For chain/multi-location problems (several candidates share the same website/domain), use street address, postcode, city/neighborhood, phone, source URL path/location slug, and location words in the source name to pick the specific place when exactly one candidate matches.
+- **Never** pick LEADBAY_ID from score alone, name-only, fuzzy-name-only, generic directory websites, root-domain-only, brand-only, postcode-only, or city-only evidence.
+- Leave LEADBAY_ID blank only after those checks still leave real ambiguity, and record why in the DECISION LOG.
+
+A row left blank with a clear reason is a SUCCESS, not a failure \u2014 it gives the user an honest audit trail. Fabricating an ID is a critical failure.
+
+## GATE 3 \u2014 DECISION LOG
+
+Before writing LEADBAY_ID for any ambiguous row, render the DECISION LOG byproduct in your response. One line per row that was not a deterministic match.
+
+Append one line per ambiguous-or-resolved row to the DECISION LOG block:
+
+\`\`\`
+DECISION LOG
+============
+row <N>: LEADBAY_ID=<id|blank>  evidence=<which signals agreed>  rejected=<why other candidates were not chosen>
+row <N>: LEADBAY_ID=<id|blank>  evidence=<...>                   rejected=<...>
+============
+\`\`\`
+
+For rows where no resolution was possible, write \`LEADBAY_ID=blank evidence=insufficient\` and explain in \`rejected=\` why the available signals were not enough.
+
+
+# PHASE 4 \u2014 PRESERVE & COMMIT
+
+Build a clean records array for import from the preservation plan. Preserve user-requested and semantically meaningful business fields, add LEADBAY_ID where resolved, normalize obvious scalar fields, and split JSON/list blobs into useful scalar columns when they contain real business data. For meaningful columns with no standard Leadbay field, call \`leadbay_list_mappable_fields\` and create/reuse custom fields rather than dropping the data. Drop blank-header columns and placeholder values like \`couldn't find\`, \`yes\`, empty arrays, and raw JSON after useful values have been extracted. Do not preserve scraper plumbing, duplicate blank columns, or long reasoning text, but do preserve meaningful client notes, data-quality warnings that affect outreach, source record links, and evidence URLs when they help the user's workflow.
+
+Treat contact exports and embedded owner/contact data as lead+contact imports. Map the parent company identity columns (LEADBAY_ID/LEAD_WEBSITE/LEAD_NAME/CRM_ID/SIREN) and also map person columns to CONTACT_FIRST_NAME, CONTACT_LAST_NAME, CONTACT_EMAIL, CONTACT_PHONE_NUMBER, CONTACT_TITLE, CONTACT_LINKEDIN. If a restaurant/company row contains structured owners, decision makers, or contact lists, expand those people into additional import rows that repeat the parent lead identity and contain one CONTACT_* person per row. Multiple rows may share the same LEADBAY_ID/company; import each row as a contact for that lead.
+
+**Preserve the source CRM record as a clickable link.** Source CRM URLs/ids \u2014 HubSpot, Salesforce, Pipedrive, Close, Attio, or anything similar \u2014 are high-value: they let the user click straight from a Leadbay lead back to the original record in their CRM. Don't drop them.
+
+Workflow:
+1. Call \`leadbay_list_mappable_fields\` first; if a suitable EXTERNAL_ID-style field already exists for the source CRM, reuse it.
+2. If no suitable field exists, call \`leadbay_create_custom_field\` with \`kind=EXTERNAL_ID\` and a \`config.url_template\` for the specific CRM. Pass the stable object id (not the URL) as the value.
+
+Per-CRM templates \u2014 pass the CRM's stable object id as \`{value}\`:
+- **HubSpot**: \`https://app.hubspot.com/contacts/<portal-id>/record/0-1/{value}\` (companies) or \`.../record/0-2/{value}\` (contacts) or \`.../record/0-3/{value}\` (deals)
+- **Salesforce**: \`https://<your-instance>.lightning.force.com/lightning/r/Account/{value}/view\` (Accounts) or \`.../Lead/{value}/view\`, \`.../Contact/{value}/view\`, \`.../Opportunity/{value}/view\`
+- **Pipedrive**: \`https://<your-domain>.pipedrive.com/organization/{value}\` or \`.../person/{value}\` or \`.../deal/{value}\`
+- **Close**: \`https://app.close.com/lead/{value}/\`
+- **Attio**: \`https://app.attio.com/<workspace-slug>/company/{value}\`
+- **Other CRMs**: ask the user for the URL template; if they don't know, fall back to a TEXT custom field for the full URL.
+
+Preserve raw source identifiers (e.g. \`hubspot_id\`, \`salesforce_account_id\`, \`associated_deal\`, \`pipedrive_org_id\`) in custom fields when they aren't already represented by a better standard/custom field. If only a full URL exists and no stable id/template can be recovered, create/use a TEXT custom field for the URL.
+
+Leadbay has CONTACT_PHONE_NUMBER but no standard LEAD_PHONE in this tool surface; preserve establishment/company phone only via an intentional custom field.
+
+
+Preserve notes intentionally. If the file contains meaningful per-lead notes/context that should live as Leadbay notes, keep them aside during import and, after the import returns lead IDs, call \`leadbay_add_note\` for the relevant imported/resolved leads when that tool is available. For dry runs, report which notes would be written. If lead notes are not available and the user asked to preserve the text, create/reuse an import-notes custom field instead of dropping it.
+
+Build the final mappings yourself. Start from \`leadbay_resolve_import_rows.mappings_for_import\`, then map semantically: LEADBAY_ID, LEAD_WEBSITE, LEAD_NAME, CRM_ID, SIREN, LEAD_LOCATION*, LEAD_SECTOR, LEAD_SIZE, contact fields, and useful \`CUSTOM.<id>\` fields. Call \`leadbay_list_mappable_fields\` before using custom fields.
+
+# PHASE 5 \u2014 QUALIFY (optional) + REPORT
+
+Prefer \`leadbay_import_and_qualify\` when the user asks to qualify/research after import; otherwise use \`leadbay_import_leads\`. For large files or short client timeouts, pass \`wait_for_completion=false\` and poll \`leadbay_import_status\`. After import, qualify only lead IDs returned by the import; late website matches may appear later via \`import_status\`.
+
+**Deliver the augmented file back to the user**: the original file plus a new \`LEADBAY_ID\` column populated from the resolution step. This is the second deliverable of a job well done.
+
+## GATE 5 \u2014 FINAL REPORT
+
+Before ending the session, render the FINAL REPORT byproduct in your response.
+
+Render the FINAL REPORT block VERBATIM as your byproduct:
+
+\`\`\`
+FINAL REPORT
+============
+rows read:                 <n>
+rows skipped (blank/dup):  <n>
+deterministic matches:     <n>
+ambiguous left unresolved: <n>
+contacts imported:         <n>
+notes written or staged:   <n>
+custom fields created:     <n>
+custom fields reused:      <n>
+import IDs / handle IDs:   <list>
+leads imported now:        <list-or-count>
+needs later polling:       <yes/no, via leadbay_import_status>
+============
+\`\`\`
+
+If any field is N/A for this run, render the row with \`n/a\` instead of dropping it.
+`;
+var leadbay_log_outreach = `
+IRON LAW \u2014 VERIFICATION REQUIRED. Before calling leadbay_report_outreach, you MUST collect one of: a gmail message id (verification.source = 'gmail_message_id'), a calendar event id (verification.source = 'calendar_event_id'), or a literal one-sentence user confirmation (verification.source = 'user_confirmed', verification.ref = the user's exact words). Skipping or fabricating verification poisons the human team's pipeline.
+
+
+Log this outreach on Leadbay lead {{arg:lead_id}}:
+Summary: {{arg:summary}}
+
+# PHASE 1 \u2014 COLLECT VERIFICATION (ask the user EXACTLY once)
+
+Before calling \`leadbay_report_outreach\`, ask me ONCE which of these applies:
+
+- I sent an **email** \u2192 ask for the Gmail message id (\`verification.source = 'gmail_message_id'\`, \`verification.ref = <the id>\`).
+- I booked a **meeting** \u2192 ask for the calendar event id (\`verification.source = 'calendar_event_id'\`, \`verification.ref = <the id>\`).
+- **Other** \u2192 ask me for a literal one-sentence confirmation that the outreach happened (\`verification.source = 'user_confirmed'\`, \`verification.ref = my exact words\`).
+
+# PHASE 2 \u2014 RECORD
+
+After I answer, call \`leadbay_report_outreach({lead_id: '{{arg:lead_id}}', note: <summary>, verification: {source, ref}})\`. Optionally pass \`dry_run:true\` first to confirm exactly what would be sent \u2014 recommended if I described the outreach but you're not 100% sure how to phrase the 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_qualify_top_n = `
+Qualify the top {{arg:count_or_default}} un-qualified leads in the active Leadbay lens.
+
+# PHASE 1 \u2014 LAUNCH
+Call \`leadbay_bulk_qualify_leads\` with \`count={{arg:count_or_default}}\`.
+
+# PHASE 2 \u2014 POLL
+While it polls, expect notifications / progress events showing per-lead transitions. Surface meaningful ones (e.g. "lead X just finished") to me as they arrive.
+
+# PHASE 3 \u2014 SUMMARIZE
+
+When \`bulk_qualify_leads\` returns, summarize:
+- How many qualified (name the count)
+- How many are still running (name them, by lead_id + lead name if available, so I can poll again later)
+- The 3 highest-\`ai_agent_lead_score\` leads from THIS batch, with their \`qualification_summary\` (one sentence each)
+
+# PHASE 4 \u2014 RECOMMEND
+Recommend the single most-promising lead from this batch and offer to research it deeply with \`leadbay_research_lead\`. Do not actually call \`research_lead\` yet \u2014 wait for my go.
+`;
+var leadbay_refine_audience = `
+Refine the Leadbay audience prompt to: {{arg:instruction}}
+
+# PHASE 1 \u2014 REFINE
+Call \`leadbay_refine_prompt\` with \`prompt=<the instruction above>\`.
+
+# PHASE 2 \u2014 CLARIFICATION ROUND-TRIP (if needed)
+
+IRON LAW \u2014 DO NOT ANSWER CLARIFICATIONS ON THE USER'S BEHALF. If the response includes a \`clarification\` block, surface the question and options to me VERBATIM and wait. Do NOT call \`leadbay_answer_clarification\`. I want to choose.
+
+# PHASE 3 \u2014 APPLIED OR NOT
+If the response status is \`applied\`, tell me Leadbay is regenerating intelligence and recommend I check back in a few minutes via \`leadbay_account_status\` (\`computing_intelligence\` flips to false when ready). If the status is anything else, name it explicitly.
+`;
+var leadbay_research_a_domain = `
+IRON LAW \u2014 NO FABRICATION. Every lead id, contact email, custom field id, mapping decision, and tool argument must trace to a value you read from the file the user attached or to an output from a leadbay_* tool call in this session. Do not invent values. Do not "fill in" a missing leadId with a name match. Do not synthesize a CRM id from a guess. If a value is missing, leave the field blank and say so.
+
+
+Research the company with domain '{{arg:domain}}' for me using Leadbay.
+
+# PHASE 1 \u2014 IMPORT + QUALIFY
+Call \`leadbay_import_and_qualify\` with \`domains=[{domain:'{{arg:domain}}'}]\`. This imports the lead AND runs AI qualification in one call. If the response indicates \`quota_blocked\` or \`still_running\`, say so explicitly.
+
+# PHASE 2 \u2014 DEEP DIVE
+When the import resolves, call \`leadbay_research_lead\` on the new leadId.
+
+# PHASE 3 \u2014 SUMMARY
+Summarize:
+- Who is this company (1 sentence)
+- Their fit (cite specific \`qualification_answers\` from the qualification response)
+- What signals stand out (cite specific research findings)
+- Which contact would I email first (name, role, source)
+
+Be honest about uncertainty: if any field above is missing from tool responses, say "not surfaced by qualification" rather than guessing.
+`;
+var PROMPT_META = {
+  leadbay_daily_check_in: { "name": "leadbay_daily_check_in", "short_description": `Run the canonical daily check-in: see account state, pull a fresh batch,
+triage the top 10, deep-dive on every promising one, and offer contact
+enrichment. The user's typical morning workflow. Trigger when the user
+asks for "leadbay leads", "best leads to prospect today", "what should
+I work on", or anything resembling "show me the day's batch".
+`, "arguments": [], "expected_calls": ["leadbay_account_status", "leadbay_pull_leads", "leadbay_research_lead", "leadbay_bulk_qualify_leads", "leadbay_enrich_contacts"], "failure_modes": ["Calls leadbay_report_outreach without explicit user authorization", "Surfaces fewer than 10 leads when more are available, or fails to top up via leadbay_qualify_top_n when the batch is short", 'Writes flat one-line summaries instead of motivational "why prospect this today" framing', "Skips deep research on promising leads (Phase 4) \u2014 the agent must call leadbay_research_lead on each, not just one", "Triggers contact enrichment without asking the user first (it consumes quota)", "Skips the STOP byproduct and proposes next actions on its own"] },
+  leadbay_import_file: { "name": "leadbay_import_file", "short_description": "Import a user-supplied CSV/file into Leadbay through five phases with\nevidence gates \u2014 scan, derive, resolve identities, preserve & commit,\nthen optionally qualify and report. The job is to maximize how many\nrows the Leadbay system actually ingests and matches.\n", "arguments": [{ "name": "file", "description": "Path or user-visible name of the CSV/file to import. If omitted, use the file the user attached or referenced.", "required": false }, { "name": "instruction", "description": 'Additional user goal, e.g. "then qualify the leads", "preserve owner phone as a custom field", or "only import restaurants in Manhattan".', "required": false }], "expected_calls": ["leadbay_resolve_import_rows", "leadbay_list_mappable_fields", "leadbay_create_custom_field", "leadbay_import_leads", "leadbay_import_and_qualify", "leadbay_add_note", "leadbay_import_status"], "failure_modes": ["Picks LEADBAY_ID from score alone, name-only, fuzzy-name-only, root-domain-only, brand-only, postcode-only, or city-only evidence", "Drops meaningful business notes or CRM record links instead of preserving them as custom fields or lead notes", "Treats a consumer mailbox domain (gmail.com, hotmail.com, ...) as the company domain", "Skips deriving company_domain from a business email when no website column exists (this kills match rate)", "Skips the COLUMN PRESERVATION PLAN byproduct before importing", "Skips the DECISION LOG byproduct before writing LEADBAY_ID", "Returns the imported records WITHOUT writing LEADBAY_ID values back into the user's file (leaves the user no audit trail of what matched)", "Fabricates leadIds, contact emails, or mapping IDs not present in the file or a tool response"] },
+  leadbay_log_outreach: { "name": "leadbay_log_outreach", "short_description": "Log outreach (an email I sent, a call I made, a meeting I had) on a\nspecific lead. Captures verification so the SDR pipeline trusts the entry.\n", "arguments": [{ "name": "lead_id", "description": "The lead UUID. Get it from leadbay_pull_leads or leadbay_research_lead.", "required": true }, { "name": "summary", "description": "1-2 sentences describing what I did (e.g. 'Sent intro email to CTO citing recent Hornsea contract').", "required": true }], "expected_calls": ["leadbay_report_outreach"], "failure_modes": ["Calls leadbay_report_outreach without first collecting a verification source", "Fabricates a gmail_message_id or calendar_event_id (the human team treats verification as canonical)", "Records outreach to a different lead_id than the one the user supplied", "Skips the dry_run step when the user is unsure what would be sent"] },
+  leadbay_qualify_top_n: { "name": "leadbay_qualify_top_n", "short_description": "Bulk-qualify the top N un-qualified leads in the active lens. Uses\nleadbay_bulk_qualify_leads with a sensible default budget.\n", "arguments": [{ "name": "count", "description": "How many leads to qualify (default 10, max 25). Higher counts may take 5+ minutes.", "required": false }], "expected_calls": ["leadbay_bulk_qualify_leads", "leadbay_research_lead"], "failure_modes": ["Picks a count larger than the user asked for (or larger than the max 25)", "Glosses over still-running leads in the summary instead of naming them", "Recommends a lead from the existing qualified pool instead of one from this batch's actual results"] },
+  leadbay_refine_audience: { "name": "leadbay_refine_audience", "short_description": "Refine the kind of leads Leadbay surfaces beyond firmographics, with a\nfree-text instruction. Handles the clarification round-trip if the new\nprompt is ambiguous.\n", "arguments": [{ "name": "instruction", "description": "The refinement (e.g. 'focus on hospitals running their own IT'). Set to plain English.", "required": true }], "expected_calls": ["leadbay_refine_prompt", "leadbay_account_status"], "failure_modes": ["Calls leadbay_answer_clarification on the user's behalf instead of surfacing the clarification verbatim", "Glosses over the clarification options instead of presenting them as offered", "Promises immediate effect when status='applied' actually triggers an async intelligence recompute"] },
+  leadbay_research_a_domain: { "name": "leadbay_research_a_domain", "short_description": "Import a company by domain and run deep qualification + research in one\npass. Use when a colleague mentions a name and you want everything Leadbay\nknows about it.\n", "arguments": [{ "name": "domain", "description": "The company's primary domain (e.g. 'acme.com'). Protocol/path are stripped.", "required": true }], "expected_calls": ["leadbay_import_and_qualify", "leadbay_research_lead"], "failure_modes": ["Fabricates qualification answers not present in any tool response", "Reports certainty about fit when qualification didn't actually run (e.g. quota_blocked)", "Skips the research step after import completes"] }
+};
+
 // src/prompts.ts
 function userMessage(text) {
   return { role: "user", content: { type: "text", text } };
 }
+function substitutePlaceholders(body, substitutions) {
+  let out = body;
+  for (const [placeholder, value] of Object.entries(substitutions)) {
+    out = out.split(`{{arg:${placeholder}}}`).join(value);
+  }
+  return out;
+}
 var CATALOG = [
   {
     name: "leadbay_daily_check_in",
-    description: "Run the canonical daily check-in: see account state, pull fresh leads, and surface the most-promising one for review. The user's typical morning workflow.",
+    description: PROMPT_META.leadbay_daily_check_in.short_description,
     arguments: [],
-    render: () => [
-      userMessage(
-        "Run the Leadbay daily check-in for me:\n1. Call leadbay_account_status to see what quota I have left and which lens is active.\n2. Call leadbay_pull_leads to get today's fresh batch.\n3. Show me the top 3 \u2014 by ai_agent_lead_score when present, otherwise by score. For each, summarize qualification_summary in one sentence.\n4. Recommend ONE lead to research deeply, and call leadbay_research_lead on it. Tell me what makes it promising, what signals stand out, and what would be the right outreach move.\n5. Stop. Wait for me to decide what to do next. Do not call leadbay_report_outreach unless I explicitly say so."
-      )
-    ]
+    render: () => [userMessage(leadbay_daily_check_in)]
   },
   {
     name: "leadbay_research_a_domain",
-    description: "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.",
+    description: PROMPT_META.leadbay_research_a_domain.short_description,
     arguments: [
       {
         name: "domain",
@@ -58,16 +340,39 @@ var CATALOG = [
     ],
     render: (args) => [
       userMessage(
-        `Research the company with domain '${args.domain ?? "<missing>"}' for me using Leadbay:
-1. Call leadbay_import_and_qualify with domains=[{domain:'${args.domain ?? ""}'}]. This imports the lead AND runs AI qualification.
-2. When the import resolves, call leadbay_research_lead on the new leadId.
-3. Summarize: who is this company, what's their fit (qualification answers), what signals stand out, and which contact would I email first. Be honest about uncertainty.`
+        substitutePlaceholders(leadbay_research_a_domain, {
+          domain: args.domain ?? "<missing>"
+        })
+      )
+    ]
+  },
+  {
+    name: "leadbay_import_file",
+    description: PROMPT_META.leadbay_import_file.short_description,
+    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
+      }
+    ],
+    render: (args) => [
+      userMessage(
+        substitutePlaceholders(leadbay_import_file, {
+          file_paren: args.file ? ` (${args.file})` : "",
+          instruction_or_default: args.instruction ?? "import the rows, resolve identities, and qualify leads if the user asked for qualification"
+        })
       )
     ]
   },
   {
     name: "leadbay_refine_audience",
-    description: "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.",
+    description: PROMPT_META.leadbay_refine_audience.short_description,
     arguments: [
       {
         name: "instruction",
@@ -77,17 +382,15 @@ var CATALOG = [
     ],
     render: (args) => [
       userMessage(
-        `Refine the Leadbay audience prompt to: ${args.instruction ?? "<missing>"}
-
-1. Call leadbay_refine_prompt with prompt=<the instruction above>.
-2. If the response includes a 'clarification' block, surface the question + options to me VERBATIM and wait. Do NOT call leadbay_answer_clarification on my behalf \u2014 I want to choose.
-3. If the response status is 'applied', tell me Leadbay is regenerating intelligence and recommend I check back in a few minutes via leadbay_account_status (computing_intelligence flips to false when ready).`
+        substitutePlaceholders(leadbay_refine_audience, {
+          instruction: args.instruction ?? "<missing>"
+        })
       )
     ]
   },
   {
     name: "leadbay_log_outreach",
-    description: "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.",
+    description: PROMPT_META.leadbay_log_outreach.short_description,
     arguments: [
       {
         name: "lead_id",
@@ -102,21 +405,16 @@ var CATALOG = [
     ],
     render: (args) => [
       userMessage(
-        `Log this outreach on Leadbay lead ${args.lead_id ?? "<missing>"}:
-Summary: ${args.summary ?? "<missing>"}
-
-Before calling leadbay_report_outreach, ask me ONCE for verification:
-- If I sent an email: ask for the Gmail message id (verification.source = 'gmail_message_id').
-- If I booked a meeting: ask for the calendar event id (verification.source = 'calendar_event_id').
-- Otherwise: ask me for a literal one-sentence confirmation that the outreach happened (verification.source = 'user_confirmed', verification.ref = my exact words).
-
-After I answer, call leadbay_report_outreach({lead_id, note: <summary>, verification: {source, ref}}). Optionally pass dry_run:true first to confirm what would be sent.`
+        substitutePlaceholders(leadbay_log_outreach, {
+          lead_id: args.lead_id ?? "<missing>",
+          summary: args.summary ?? "<missing>"
+        })
       )
     ]
   },
   {
     name: "leadbay_qualify_top_n",
-    description: "Bulk-qualify the top N un-qualified leads in the active lens. Uses leadbay_bulk_qualify_leads with a sensible default budget.",
+    description: PROMPT_META.leadbay_qualify_top_n.short_description,
     arguments: [
       {
         name: "count",
@@ -128,11 +426,9 @@ After I answer, call leadbay_report_outreach({lead_id, note: <summary>, verifica
       const n = args.count ?? "10";
       return [
         userMessage(
-          `Qualify the top ${n} un-qualified leads in the active Leadbay lens:
-1. Call leadbay_bulk_qualify_leads with count=${n}.
-2. While it polls, expect notifications/progress events showing per-lead transitions.
-3. When it returns, summarize: how many qualified, how many still running, and the 3 highest-boost-score leads with their qualification_summary.
-4. Recommend the single most promising lead and offer to research it deeply with leadbay_research_lead.`
+          substitutePlaceholders(leadbay_qualify_top_n, {
+            count_or_default: n
+          })
         )
       ];
     }
@@ -264,6 +560,7 @@ function buildSlashCommandsParagraph(has) {
   commands.push("`/leadbay daily-check-in` (chains account_status \u2192 pull_leads \u2192 research_lead on the top hit)");
   if (has("leadbay_import_and_qualify")) {
     commands.push("`/leadbay research-a-domain {domain}` (import_and_qualify \u2192 research_lead)");
+    commands.push("`/leadbay import-file {file}` (resolve_import_rows \u2192 import_leads/import_and_qualify \u2192 status)");
   }
   if (has("leadbay_refine_prompt")) {
     commands.push("`/leadbay refine-audience {instruction}` (refine_prompt with clarification handling)");
@@ -587,7 +884,7 @@ function buildServer(client, opts = {}) {
 
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.6.3";
+var VERSION = "0.7.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -876,7 +1173,7 @@ async function runLogin(args) {
   let result;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-KHXRELXF.js");
+      const { REGIONS } = await import("./dist-2RTYPHB3.js");
       const baseUrl = REGIONS[pinnedRegion];
       const c = createClient({ region: pinnedRegion });
       const token = await loginAt(baseUrl, email, password);
@@ -1368,7 +1665,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-KHXRELXF.js");
+      const { REGIONS } = await import("./dist-2RTYPHB3.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;