argorant 0.10.0 → 0.12.0

package/bin/argorant.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 "use strict";
 
-// Argorant CLI — a thin, dependency-free wrapper over the Argorant REST API.
-// Search, count, reveal, export, and verify B2B contacts from the terminal.
+// Argorant CLI - a thin, dependency-free wrapper over the Argorant REST API.
+// Search, count, reveal, export, and verify B2B contacts, and find work emails, from the terminal.
 // Auth: an Argorant API key (ag_live_*) via `argorant login`, or ARGORANT_API_KEY.
 
 const crypto = require("crypto");
@@ -83,7 +83,7 @@ const VALUE_FLAGS = {
 };
 // Boolean filter flags (presence => "true"). --verified-only is positive intent
 // only (deliverable contacts); there is deliberately NO flag to query invalid or
-// any raw verification status — that is never exposed on any surface.
+// any raw verification status - that is never exposed on any surface.
 const BOOL_FLAGS = {
   "--has-phone": "has_phone",
   "--has-linkedin": "has_linkedin",
@@ -124,7 +124,7 @@ function warnGradeGap(scope) {
 // A value flag must be followed by an actual value. Silently swallowing the
 // NEXT FLAG (`search "CFO" --title --base http://…` → title="--base") or a
 // missing trailing value (→ undefined, dropped by request()) sends a request
-// the user never asked for — against the wrong host, with the wrong filters.
+// the user never asked for - against the wrong host, with the wrong filters.
 // Fail loud instead. "-" stays legal: it is the documented stdin sentinel.
 function flagValue(argv, i, flag) {
   const v = argv[i + 1];
@@ -134,7 +134,7 @@ function flagValue(argv, i, flag) {
   }
   return v;
 }
-// -n/--limit drives billed row counts on reveal/export — a typo must never
+// -n/--limit drives billed row counts on reveal/export - a typo must never
 // fall through to the default (a mistyped `-n` used to become a 1000-row
 // billed export).
 function parseLimit(raw, flag) {
@@ -146,7 +146,7 @@ function parseLimit(raw, flag) {
 }
 
 function parseArgs(argv) {
-  const out = { _: [], filters: {}, limit: null, output: null, file: null, column: null, json: false, yes: false, base: DEFAULT_BASE, baseExplicit: false, batch: false, name: null, includeExported: false, grade: "valid", gradeExplicit: false };
+  const out = { _: [], filters: {}, limit: null, output: null, file: null, column: null, json: false, yes: false, base: DEFAULT_BASE, baseExplicit: false, batch: false, name: null, includeExported: false, grade: "valid", gradeExplicit: false, phones: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--json") out.json = true;
@@ -158,6 +158,9 @@ function parseArgs(argv) {
     else if (a === "--base") { out.base = flagValue(argv, i++, a); out.baseExplicit = true; }
     else if (a === "--name") out.name = flagValue(argv, i++, a);
     else if (a === "--include-exported") out.includeExported = true;
+    // Phone numbers are opt-in on every surface (2026-10-07): only with --phones, 10 credits per
+    // number actually returned, nothing when none is found or the account already has it.
+    else if (a === "--phones" || a === "--include-phones") out.phones = true;
     else if (a === "--batch") out.batch = true;
     else if (a === "--grade") setGrade(out, flagValue(argv, i++, a));
     else if (a in VALUE_FLAGS) out.filters[VALUE_FLAGS[a]] = flagValue(argv, i++, a);
@@ -252,7 +255,7 @@ function downloadTo(base, urlPath, key, dest) {
 // `detail` is a plain string on most endpoints, a structured object on some
 // (plan_required, campaign launch blockers, native-delivery readiness) and a
 // LIST of validation errors on any FastAPI 422. All three have to render as
-// something a human or an agent can read — never "[object Object]".
+// something a human or an agent can read - never "[object Object]".
 function detailMsg(detail) {
   if (detail == null) return null;
   if (typeof detail === "string") return detail;
@@ -292,7 +295,7 @@ function need(res, what) {
     const url = d.upgrade_url || d.url || "https://argorant.com/pricing";
     die(`${msg}${msg.includes(url) ? "" : `\nUpgrade: ${url}`}`, EXIT.UPGRADE);
   }
-  if (res.status === 403) die(detailMsg(detail) || `forbidden — your key lacks the scope for ${what}.`, EXIT.FORBIDDEN);
+  if (res.status === 403) die(detailMsg(detail) || `forbidden - your key lacks the scope for ${what}.`, EXIT.FORBIDDEN);
   if (res.status === 429) die(detailMsg(detail) || "rate limit / daily quota reached.", EXIT.RATE_LIMIT);
   if (res.status >= 400) die(detailMsg(detail) || `${what} failed (HTTP ${res.status}).`);
   return res.json || {};
@@ -351,7 +354,7 @@ async function cmdLogin(args) {
   let key = args._[0];
   if (!key) key = await prompt("Paste your Argorant API key (ag_live_…): ", { hidden: true });
   if (!key) die("no key provided.");
-  if (!/^ag_(live|test)_/.test(key)) process.stderr.write(dim("note: keys normally start with ag_live_ — continuing anyway.\n"));
+  if (!/^ag_(live|test)_/.test(key)) process.stderr.write(dim("note: keys normally start with ag_live_ - continuing anyway.\n"));
   const res = await request("GET", args.base, "/api/mcp/account", { key });
   if (res.status === 428 && res.json?.detail?.error === "access_key_activation_required") {
     const url = res.json.detail.claim_url;
@@ -370,7 +373,7 @@ async function cmdLogin(args) {
 
 async function cmdLogout() {
   if (!fs.existsSync(CONFIG_PATH)) {
-    console.log(dim(`Nothing to do — no saved credentials at ${CONFIG_PATH}.`));
+    console.log(dim(`Nothing to do - no saved credentials at ${CONFIG_PATH}.`));
   } else {
     try {
       fs.unlinkSync(CONFIG_PATH);
@@ -380,7 +383,7 @@ async function cmdLogout() {
     console.log(green("✓") + ` Removed saved key and base from ${bold(CONFIG_PATH)}`);
   }
   if (process.env.ARGORANT_API_KEY) {
-    warn("ARGORANT_API_KEY is still set in this environment and takes precedence — unset it too.");
+    warn("ARGORANT_API_KEY is still set in this environment and takes precedence - unset it too.");
   }
 }
 
@@ -389,8 +392,8 @@ async function cmdWhoami(args) {
   const res = await request("GET", args.base, "/api/mcp/account", { key });
   const a = need(res, "whoami");
   if (args.json) return console.log(JSON.stringify(a, null, 2));
-  console.log(`${bold("Account")}  ${a.email || "—"} ${dim("(" + (a.role || "member") + ")")}`);
-  console.log(`${bold("Scopes")}   ${(a.scopes || []).join(", ") || "—"}`);
+  console.log(`${bold("Account")}  ${a.email || "-"} ${dim("(" + (a.role || "member") + ")")}`);
+  console.log(`${bold("Scopes")}   ${(a.scopes || []).join(", ") || "-"}`);
   const u = a.usage || {};
   // Keys/fields must match _mcp_usage_summary: actions are count_requests /
   // preview_rows / reveal_rows / export_rows and each entry carries
@@ -471,7 +474,7 @@ async function cmdCompany(args) {
     for (const person of r.results) {
       const who = [person.preview, person.title].filter(Boolean).join(" · ");
       const where = [person.country].filter(Boolean).join(", ");
-      console.log(`    ${bold(who || "—")}${where ? dim("  " + where) : ""}`);
+      console.log(`    ${bold(who || "-")}${where ? dim("  " + where) : ""}`);
     }
   }
 }
@@ -484,13 +487,13 @@ async function cmdSearch(args) {
   const res = await request("GET", args.base, "/api/mcp/people/preview", { key, query });
   const r = need(res, "search");
   if (args.json) return console.log(JSON.stringify(r, null, 2));
-  console.log(dim(`${Number(r.total).toLocaleString()} total · showing ${r.returned} (details redacted — use \`reveal\` or \`export\`)`));
+  console.log(dim(`${Number(r.total).toLocaleString()} total · showing ${r.returned} (details redacted - use \`reveal\` or \`export\`)`));
   for (const p of r.results || []) {
     // _redacted_preview returns the masked identity as `preview` (e.g. "A* P"),
-    // never `name` — without this the row rendered as title-only.
+    // never `name` - without this the row rendered as title-only.
     const who = [p.preview || p.name, p.title].filter(Boolean).join(" · ");
     const where = [p.company || p.company_name, p.country].filter(Boolean).join(", ");
-    console.log(`  ${bold(who || "—")}${where ? dim("  " + where) : ""}`);
+    console.log(`  ${bold(who || "-")}${where ? dim("  " + where) : ""}`);
   }
 }
 
@@ -546,40 +549,132 @@ async function cmdSample(args) {
       `${bold(Number(job.total_companies || 0).toLocaleString())} matching companies`
   );
   for (const lead of job.results || []) {
-    console.log(`  ${bold(lead.full_name || "—")} ${dim("· " + (lead.title || "—"))}`);
-    console.log(`    ${(lead.company || "—")} ${dim("· " + (lead.company_domain || "—"))}`);
-    console.log(`    ${cyan(lead.email || "—")} ${green("✓ Valid")}`);
+    console.log(`  ${bold(lead.full_name || "-")} ${dim("· " + (lead.title || "-"))}`);
+    console.log(`    ${(lead.company || "-")} ${dim("· " + (lead.company_domain || "-"))}`);
+    console.log(`    ${cyan(lead.email || "-")} ${green("✓ Valid")}`);
   }
   if (args.output) console.log(green("✓") + ` Saved CSV → ${bold(args.output)}`);
   console.log(dim(`These 25 are the sample; the full pool contains ${Number(job.total_companies || 0).toLocaleString()} companies.`));
 }
 
+// ---- phone numbers (opt-in, --phones) ----
+const PHONE_FIELDS = ["phone", "phone_1", "phone_2", "phones_all", "additional_phones", "phone_masked"];
+function stripPhones(rec) {
+  if (rec && typeof rec === "object") for (const k of PHONE_FIELDS) delete rec[k];
+  return rec;
+}
+
+// The price and whether the plan includes phone numbers, before anything is spent. An older server
+// without the pricing route falls back to the published price.
+async function phonePricing(args, key) {
+  try {
+    const res = await request("GET", args.base, "/api/v1/people/phones/pricing", { key });
+    if (res.status === 200 && res.json) return res.json;
+  } catch {
+    /* fall back below */
+  }
+  return { price_per_phone: 10, plan_includes_phones: null };
+}
+
+function phonePriceText(pricing) {
+  const price = Number((pricing && pricing.price_per_phone) || 10);
+  return `Phone numbers cost ${price} credits each, only when a number is found. Numbers you already have are free.`;
+}
+
+// Phone numbers for people already revealed (POST /api/v1/people/phones). A refusal never undoes the
+// emails that were just revealed: it comes back as {included:false, message}.
+async function addPhones(args, key, records) {
+  const ids = [];
+  for (const r of records) {
+    const id = String(r.person_id || r.record_id || "").trim();
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  records.forEach(stripPhones);
+  if (!ids.length) return { included: true, phones_returned: 0, credits_charged: 0, summary: "No people to look up phone numbers for, so nothing was charged." };
+  const res = await request("POST", args.base, "/api/v1/people/phones", {
+    key,
+    body: { record_ids: ids.slice(0, 100), channel: "cli" },
+    headers: { "X-Argorant-Channel": "cli" },
+  });
+  if (res.status !== 200 || !res.json) {
+    const detail = res.json && res.json.detail;
+    const code = detail && typeof detail === "object" ? detail.error : null;
+    let message = detailMsg(detail) || `phone numbers failed (HTTP ${res.status}).`;
+    if (code === "phones_not_in_plan") message = "Your plan does not include phone numbers, so none were added and nothing was charged for them.";
+    else if (code === "insufficient_credits") message = "Not enough credits for a phone number, so none were added and nothing was charged for them.";
+    else if (code === "mcp_quota_exceeded") message = "Today's reveal limit is used up, so no phone numbers were added. It resets at midnight UTC.";
+    for (const r of records) r.phone_status = "not_added";
+    return { included: false, status: res.status, error: code || "error", message, summary: message };
+  }
+  const byId = new Map((res.json.results || []).map((row) => [String(row.record_id), row]));
+  for (const r of records) {
+    const row = byId.get(String(r.person_id || r.record_id || "")) || {};
+    r.phone = row.phone || null;
+    if (row.additional_phones && row.additional_phones.length) r.additional_phones = row.additional_phones;
+    r.phone_status = row.phone_status || "not_found";
+    r.phone_credits_charged = Number(row.credits_charged || 0);
+  }
+  return { included: true, ...res.json, results: undefined };
+}
+
+function phoneLine(p) {
+  if (!p || !p.phone_status) return null;
+  if (p.phone) {
+    const extra = p.additional_phones && p.additional_phones.length ? dim(` (+${p.additional_phones.length} more)`) : "";
+    const cost = p.phone_credits_charged ? dim(` · ${p.phone_credits_charged} credits`) : p.phone_status === "already_unlocked" ? dim(" · already yours") : "";
+    return `${p.phone}${extra}${cost}`;
+  }
+  if (p.phone_status === "none_found" || p.phone_status === "not_found") return dim("no phone number on record · not charged");
+  if (p.phone_status === "not_enough_credits") return dim("phone not added · not enough credits");
+  if (p.phone_status === "not_in_plan") return dim("phone not added · not in your plan");
+  if (p.phone_status === "daily_limit_reached") return dim("phone not added · daily limit reached");
+  return null;
+}
+
 async function cmdReveal(args) {
   const key = requireKey();
   warnExcludeTitleGap(args.filters);
   if (args.gradeExplicit) warnGradeGap("reveal");
   const limit = args.limit || 10;
+  const pricing = args.phones ? await phonePricing(args, key) : null;
+  if (pricing && pricing.plan_includes_phones === false) {
+    warn("Your plan does not include phone numbers. Emails are revealed as usual; no phone numbers will be added or charged.");
+  }
   // Confirmation is interactive-only by design: with --yes, --json, or a
   // non-TTY stdin (CI, agents, pipes) this spends credits with no prompt.
   if (!args.yes && !args.json && process.stdin.isTTY) {
-    const ans = await prompt(`Reveal up to ${bold(limit)} contacts? This uses your quota/credits. [y/N] `);
+    const phonesText = args.phones ? ` ${phonePriceText(pricing)}` : "";
+    const ans = await prompt(`Reveal up to ${bold(limit)} contacts${args.phones ? " with phone numbers" : ""}? Each new working email costs 1 credit.${phonesText} [y/N] `);
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  } else if (args.phones && !args.json) {
+    process.stderr.write(dim(phonePriceText(pricing) + "\n"));
   }
   // Sent for forward-compatibility: the platform has no per-request grade
   // control on reveal yet (see GODMODE-PLAN.md), so this is a no-op today.
   const query = { ...args.filters, limit, grade: args.grade === "valid-plus-catchall" ? "valid_plus_catchall" : "valid" };
   const res = await request("GET", args.base, "/api/mcp/people/reveal", { key, query });
   const r = need(res, "reveal");
+  const people = (r.results || []).filter((x) => x && typeof x === "object");
+  if (args.phones && people.length) r.phones = await addPhones(args, key, people);
+  else people.forEach(stripPhones);
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   console.log(dim(`${Number(r.total).toLocaleString()} total · revealed ${r.returned}`));
   for (const p of r.results || []) {
-    // _revealed_contact returns full_name / first_name / last_name — there is
+    // _revealed_contact returns full_name / first_name / last_name - there is
     // no `name` key. The customer just paid for this row; print who it is.
     const name = p.full_name || [p.first_name, p.last_name].filter(Boolean).join(" ") || p.name;
     const who = [name, p.title].filter(Boolean).join(" · ");
-    console.log(`  ${bold(who || "—")}`);
-    const bits = [p.email && cyan(p.email), p.phone, p.linkedin_url, [p.company || p.company_name, p.country].filter(Boolean).join(", ")].filter(Boolean);
+    console.log(`  ${bold(who || "-")}`);
+    const bits = [p.email && cyan(p.email), p.linkedin_url, [p.company || p.company_name, p.country].filter(Boolean).join(", ")].filter(Boolean);
     if (bits.length) console.log("    " + bits.join(dim(" · ")));
+    const phone = args.phones ? phoneLine(p) : null;
+    if (phone) console.log("    " + phone);
+  }
+  const charged = Number(r.charged || 0);
+  console.log(dim(`${charged} credit${charged === 1 ? "" : "s"} charged for emails`));
+  if (r.phones) {
+    if (r.phones.included) console.log(dim(r.phones.summary || `${r.phones.credits_charged || 0} credits charged for phone numbers`));
+    else warn(r.phones.message || "No phone numbers were added.");
   }
 }
 
@@ -622,16 +717,30 @@ async function cmdEnrich(args) {
   else if (name) { body.name = name; body.domain = domain; }
   else body.domain = domain;
   const personMode = Boolean(body.email || body.name);
+  if (args.phones && !personMode) warn("Phone numbers are for people. A company lookup returns the company profile only.");
+  const wantPhones = args.phones && personMode;
+  const pricing = wantPhones ? await phonePricing(args, key) : null;
+  if (pricing && pricing.plan_includes_phones === false) {
+    warn("Your plan does not include phone numbers. The email lookup runs as usual; no phone number will be added or charged.");
+  }
   // Company mode is free, so it never asks. Person mode is billed exactly like
   // a reveal, so it gets the same interactive-only confirmation as `reveal`.
   if (personMode && !args.yes && !args.json && process.stdin.isTTY) {
     const ans = await prompt(
-      `Enrich this contact? A match costs 1 credit; a miss and a non-deliverable address are free. [y/N] `
+      `Enrich this contact? A match costs 1 credit; a miss and a non-deliverable address are free.` +
+        (wantPhones ? ` ${phonePriceText(pricing)}` : "") + ` [y/N] `
     );
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  } else if (wantPhones && !args.json) {
+    process.stderr.write(dim(phonePriceText(pricing) + "\n"));
   }
   const res = await request("POST", args.base, "/api/v1/enrich", { key, body });
   const r = need(res, "enrich");
+  if (r && r.type === "person" && r.person && typeof r.person === "object") {
+    if (!r.person.person_id && r.person_id) r.person.person_id = r.person_id;
+    if (wantPhones && r.found) r.phones = await addPhones(args, key, [r.person]);
+    else stripPhones(r.person);
+  }
   if (args.json) {
     console.log(JSON.stringify(r, null, 2));
     if (!r.found) process.exit(EXIT.ERROR);
@@ -653,14 +762,16 @@ async function cmdEnrich(args) {
   }
   const p = r.person || {};
   const who = [p.full_name || [p.first_name, p.last_name].filter(Boolean).join(" "), p.title].filter(Boolean).join(" · ");
-  console.log(`  ${bold(who || "—")}`);
+  console.log(`  ${bold(who || "-")}`);
   const bits = [
     p.email && cyan(p.email),
-    p.phone,
     p.linkedin_url,
     [p.current_company_name, p.current_company_domain, p.country].filter(Boolean).join(", "),
   ].filter(Boolean);
   if (bits.length) console.log("    " + bits.join(dim(" · ")));
+  const phone = wantPhones ? phoneLine(p) : null;
+  if (phone) console.log("    " + phone);
+  if (r.phones && !r.phones.included) warn(r.phones.message || "No phone number was added.");
   if (r.deliverable === false) {
     console.log("    " + dim(r.message || "This address did not pass live verification, so nothing was charged."));
   }
@@ -683,7 +794,7 @@ function partPath(dest, n) {
 }
 
 // >50k rows come back as {type:"batch", batch_id, status_api_path:
-// /api/mcp/export-batches/{id}} with NO job_id and NO download_api_path — the
+// /api/mcp/export-batches/{id}} with NO job_id and NO download_api_path - the
 // old code fell through to /api/mcp/exports/undefined/download, so large
 // exports were simply impossible from the CLI. Poll the batch, then download
 // each completed chunk.
@@ -740,10 +851,10 @@ async function exportStatusCmd(args, key, id) {
   const s = need(res, "export status");
   if (args.json) return console.log(JSON.stringify(s, null, 2));
   if (isBatch) {
-    console.log(`${bold("Batch #" + (s.batch_id ?? id))}  ${dim(s.status || "—")}`);
+    console.log(`${bold("Batch #" + (s.batch_id ?? id))}  ${dim(s.status || "-")}`);
     console.log(`  ${s.completed_chunks || 0}/${s.total_chunks || 0} chunks · ${Number(s.verified_rows || 0).toLocaleString()} rows · ${s.progress_pct || 0}%`);
   } else {
-    console.log(`${bold("Export #" + (s.job_id ?? id))}  ${dim(s.status || "—")}`);
+    console.log(`${bold("Export #" + (s.job_id ?? id))}  ${dim(s.status || "-")}`);
     console.log(`  ${Number(s.verified_rows || 0).toLocaleString()}/${Number(s.total_rows || 0).toLocaleString()} rows · ${s.progress_pct || 0}%${s.downloadable ? green("  · ready to download") : ""}`);
   }
   if (s.error_message) console.log(red("  " + s.error_message));
@@ -756,7 +867,7 @@ async function exportDownloadCmd(args, key, id) {
     const res = await request("GET", args.base, `/api/mcp/export-batches/${id}`, { key });
     const b = need(res, "export batch status");
     if (!EXPORT_TERMINAL_OK.includes(String(b.status || "").toLowerCase())) {
-      die(`export batch #${id} is ${b.status || "not ready"} — run \`argorant export status ${id} --batch\`.`);
+      die(`export batch #${id} is ${b.status || "not ready"} - run \`argorant export status ${id} --batch\`.`);
     }
     const files = await downloadBatchChunks(args, key, b, dest);
     if (args.json) return console.log(JSON.stringify({ ok: true, batch_id: id, files }, null, 2));
@@ -766,7 +877,7 @@ async function exportDownloadCmd(args, key, id) {
   const res = await request("GET", args.base, `/api/mcp/exports/${id}`, { key });
   const s = need(res, "export status");
   if (!s.downloadable && !s.download_api_path) {
-    die(`export #${id} is ${s.status || "not ready"} — run \`argorant export status ${id}\`.`);
+    die(`export #${id} is ${s.status || "not ready"} - run \`argorant export status ${id}\`.`);
   }
   await downloadTo(args.base, s.download_api_path || `/api/mcp/exports/${id}/download`, key, dest);
   if (args.json) return console.log(JSON.stringify({ ok: true, file: dest, job_id: id }, null, 2));
@@ -776,7 +887,7 @@ async function exportDownloadCmd(args, key, id) {
 
 async function cmdExport(args) {
   const key = requireKey();
-  // `export status <id>` / `export download <id>` — recovery subcommands, no
+  // `export status <id>` / `export download <id>` - recovery subcommands, no
   // job is created and nothing is billed.
   const sub = (args._[0] || "").toLowerCase();
   if (sub === "status" || sub === "download") {
@@ -791,9 +902,18 @@ async function cmdExport(args) {
   const dest = ensureWritable(args.output || "argorant-leads.csv");
   // Confirmation is interactive-only by design: with --yes, --json, or a
   // non-TTY stdin (CI, agents, pipes) this spends credits with no prompt.
+  const pricing = args.phones ? await phonePricing(args, key) : null;
+  if (pricing && pricing.plan_includes_phones === false) {
+    die("Your plan does not include phone numbers. Run the export without --phones.", EXIT.UPGRADE);
+  }
   if (!args.yes && !args.json && process.stdin.isTTY) {
-    const ans = await prompt(`Export up to ${bold(limit)} verified contacts to ${bold(dest)}? Uses quota/credits. [y/N] `);
+    const phonesText = args.phones
+      ? ` Phone numbers are included. Each number in the file costs ${Number((pricing && pricing.price_per_phone) || 10)} more credits, and people without one cost nothing extra.`
+      : "";
+    const ans = await prompt(`Export up to ${bold(limit)} verified contacts to ${bold(dest)}? Each person with a working email costs 1 credit.${phonesText} [y/N] `);
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  } else if (args.phones && !args.json) {
+    process.stderr.write(dim(`Phone numbers are included. Each number in the file costs ${Number((pricing && pricing.price_per_phone) || 10)} more credits.\n`));
   }
   // Match the MCP/app defaults so the CLI yields the same rows: business email
   // present by default, and skip rows already exported (override with
@@ -808,7 +928,7 @@ async function cmdExport(args) {
   const grades = args.grade === "valid-plus-catchall" ? ["valid", "catch_all"] : ["valid"];
   const create = await request("POST", args.base, "/api/mcp/exports/create", {
     key,
-    body: { limit, filters: exportFilters, exclude_previously_exported: !args.includeExported, grades },
+    body: { limit, filters: exportFilters, exclude_previously_exported: !args.includeExported, grades, ...(args.phones ? { include_phones: true } : {}) },
   });
   const job = need(create, "export");
   // >EXPORT_MAX_ROWS (50k) → a multi-chunk batch, a different status endpoint
@@ -817,7 +937,7 @@ async function cmdExport(args) {
     const batchPath = job.status_api_path || `/api/mcp/export-batches/${job.batch_id}`;
     if (!args.json) {
       process.stdout.write(
-        dim(`Large export queued as batch #${job.batch_id} — ${job.total_chunks || "?"} chunk(s) of up to ${Number(job.chunk_size || 0).toLocaleString()} rows\n`)
+        dim(`Large export queued as batch #${job.batch_id} - ${job.total_chunks || "?"} chunk(s) of up to ${Number(job.chunk_size || 0).toLocaleString()} rows\n`)
       );
     }
     const batch = await pollExportBatch(args, key, batchPath, { quiet: !!args.json });
@@ -833,7 +953,7 @@ async function cmdExport(args) {
     if (args.json) return console.log(JSON.stringify(job, null, 2));
     return console.log("Export queued. " + JSON.stringify(job));
   }
-  if (!args.json) process.stdout.write(dim("Export queued — verifying & building CSV"));
+  if (!args.json) process.stdout.write(dim("Export queued - verifying & building CSV"));
   let downloadPath = job.download_api_path || null;
   const started = Date.now();
   // Poll until the job reports a terminal state.
@@ -851,7 +971,7 @@ async function cmdExport(args) {
     }
     if (EXPORT_TERMINAL_FAIL.includes(status)) die(`\nexport ${status}${s.error_message ? `: ${s.error_message}` : "."}`);
     if (Date.now() - started > 1000 * 60 * 20) {
-      die(`\nexport timed out after 20 minutes. It is still running server-side — check with \`argorant export status ${job.job_id}\`.`);
+      die(`\nexport timed out after 20 minutes. It is still running server-side - check with \`argorant export status ${job.job_id}\`.`);
     }
   }
   if (!args.json) process.stdout.write("\n");
@@ -862,7 +982,7 @@ async function cmdExport(args) {
   try {
     await downloadTo(args.base, downloadPath, key, dest);
   } catch (e) {
-    // The job is already paid for — always tell the user how to get it back.
+    // The job is already paid for - always tell the user how to get it back.
     die(`${e.message}\nThe export itself completed. Retry the download with \`argorant export download ${job.job_id} -o ${dest}\`.`);
   }
   if (args.json) return console.log(JSON.stringify({ ok: true, file: dest, job_id: job.job_id }, null, 2));
@@ -870,7 +990,7 @@ async function cmdExport(args) {
   console.log(green("✓") + ` Saved ${rows != null ? bold(rows.toLocaleString()) + " rows → " : ""}${bold(dest)}`);
 }
 
-// ---- verify: external email verification (own lists) — the verification pool,
+// ---- verify: external email verification (own lists) - the verification pool,
 // separate from contact credits. 60-day re-checks are free. ----
 const EMAIL_RE = /[^\s,;"']+@[^\s,;"']+\.[^\s,;"']+/;
 
@@ -911,7 +1031,7 @@ async function cmdVerifyFile(args, key) {
   emails = [...new Set(emails)];
   if (!emails.length) die("no email addresses found in file (try --column <name>)");
   const out = ensureWritable(args.output || "argorant-verified.csv");
-  // Interactive-only by design — see reveal/export.
+  // Interactive-only by design - see reveal/export.
   if (!args.yes && !args.json && process.stdin.isTTY) {
     const ans = await prompt(`Verify ${bold(emails.length.toLocaleString())} emails? Fresh checks cost half a credit each; recent re-checks are free. [y/N] `);
     if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
@@ -938,7 +1058,7 @@ async function cmdVerifyFile(args, key) {
 }
 
 // ---- list: save & inspect reusable lead lists (parity with MCP/app). Creating a
-// filtered list is free and does NOT reveal contacts — the server counts the
+// filtered list is free and does NOT reveal contacts - the server counts the
 // matches itself, so the list reports its real size right away. ----
 async function cmdList(args) {
   const key = requireKey();
@@ -952,7 +1072,7 @@ async function cmdList(args) {
     const r = need(res, "list create");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const total = Number(r.snapshot_total || 0);
-    console.log(green("✓") + ` Created list ${bold("#" + r.list_id)} ${dim("“" + r.name + "”")} — ${bold(total.toLocaleString())} matching contacts`);
+    console.log(green("✓") + ` Created list ${bold("#" + r.list_id)} ${dim("“" + r.name + "”")} - ${bold(total.toLocaleString())} matching contacts`);
     console.log(dim(`Export it with:  argorant export ${Object.entries(args.filters).filter(([, v]) => v).map(([k, v]) => `--${k.replace(/_/g, "-")} ${/\s/.test(String(v)) ? `"${v}"` : v}`).join(" ")} -o leads.csv`));
     return;
   }
@@ -960,14 +1080,14 @@ async function cmdList(args) {
     const id = args._[1] || args.name;
     if (!id) die("usage: argorant list status <list_id>");
     // Validate locally: the API path param is an int, so anything else came
-    // back as a FastAPI 422 whose detail is an array — a useless error for a
+    // back as a FastAPI 422 whose detail is an array - a useless error for a
     // plain typo.
     if (!/^\d+$/.test(String(id).trim())) die(`list id must be a number (got "${id}").`);
     const res = await request("GET", args.base, `/api/mcp/lists/${encodeURIComponent(String(id).trim())}`, { key });
     const r = need(res, "list status");
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const total = Number(r.snapshot_total ?? r.item_count ?? 0);
-    console.log(`${bold("List #" + (r.list_id ?? id))}  ${dim("“" + (r.name || "—") + "”")}`);
+    console.log(`${bold("List #" + (r.list_id ?? id))}  ${dim("“" + (r.name || "-") + "”")}`);
     console.log(`  ${bold(total.toLocaleString())} contacts · ${dim((r.selection_mode || "filtered") + " · " + (r.record_type || "person"))}`);
     return;
   }
@@ -977,9 +1097,9 @@ async function cmdList(args) {
 // =============================================================================
 // campaigns: god-mode native outbound campaign control from the terminal.
 //
-// OPERATOR KEYS ONLY. Every command above talks to /api/mcp/* — the
+// OPERATOR KEYS ONLY. Every command above talks to /api/mcp/* - the
 // customer-facing contact-data API, gated by plan scopes. Everything below
-// talks to /api/sequencer/* — the internal Argorant Sequencer that runs live
+// talks to /api/sequencer/* - the internal Argorant Sequencer that runs live
 // outbound sends. It authenticates via the SAME ag_live_ Bearer key, but only
 // works for a key that (a) belongs to an owner/admin account and (b) carries
 // the `argorant:operator` scope (see cli/GODMODE-PLAN.md). Any other key gets
@@ -987,14 +1107,14 @@ async function cmdList(args) {
 // access.
 //
 // Kept on its own tiny flag reader (readFlags) instead of the top-level
-// parseArgs — these subcommands have their own vocabulary (--step, --subject,
+// parseArgs - these subcommands have their own vocabulary (--step, --subject,
 // --count, --pool, --csv, ...) that would otherwise collide with, or be
 // rejected by, the generic filter-flag parser used for search/reveal/export.
 // =============================================================================
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-// Filter flags for `campaigns leads add --query ...` — the same names/mapping
+// Filter flags for `campaigns leads add --query ...` - the same names/mapping
 // as the top-level VALUE_FLAGS/BOOL_FLAGS (minus the ones the sequencer's
 // filter-enroll endpoint doesn't accept, e.g. --verified-only), plus --query
 // as an explicit alias for free-text `q` (clearer than a bare positional in a
@@ -1053,7 +1173,7 @@ function readFlags(argv, valueFlags = {}, boolFlags = {}) {
 // A saved base from `argorant login --base …` only applies when the caller did
 // NOT pass --base. Inferring "no flag given" from the VALUE (=== DEFAULT_BASE)
 // meant `--base https://argorant.com` was silently ignored after a staging
-// login — requests went to the wrong host with no indication.
+// login - requests went to the wrong host with no indication.
 function applySavedBase(args) {
   if (args.baseExplicit || process.env.ARGORANT_API_BASE) return args;
   const saved = loadConfig().base;
@@ -1088,7 +1208,7 @@ async function resolveCampaign(base, key, identifier) {
   }
   if (matches.length > 1) {
     die(
-      `"${identifier}" matches ${matches.length} campaigns — be more specific:\n` +
+      `"${identifier}" matches ${matches.length} campaigns - be more specific:\n` +
         matches.map((c) => `  ${c.name}  ${dim(c.id)}`).join("\n")
     );
   }
@@ -1106,8 +1226,8 @@ async function campaignsList(argv) {
   for (const c of campaigns) {
     const sent = Number(c.sent_count || 0);
     const replied = Number(c.replied_count || 0);
-    const rate = sent > 0 ? `${((replied / sent) * 100).toFixed(1)}%` : "—";
-    console.log(`${bold(c.name || "—")}  ${dim(c.id)}`);
+    const rate = sent > 0 ? `${((replied / sent) * 100).toFixed(1)}%` : "-";
+    console.log(`${bold(c.name || "-")}  ${dim(c.id)}`);
     console.log(
       `  ${c.status}` +
         dim("  ·  leads ") + Number(c.lead_count || 0).toLocaleString() +
@@ -1248,7 +1368,7 @@ async function campaignsSteps(argv) {
   }
   body = (body || "").trim();
   if (!body) die("body is empty");
-  // The CLI never generates copy — the operator/agent writes it; this command
+  // The CLI never generates copy - the operator/agent writes it; this command
   // only upserts what it's given.
   const campaignId = await resolveCampaign(args.base, key, identifier);
   const stepBody = { step_number: stepNumber, subject, body, copy_status: args.approve ? "approved" : "draft" };
@@ -1270,7 +1390,7 @@ async function campaignsInboxes(argv) {
   if (!count || count < 1) die("--count must be a positive integer");
   const campaignId = await resolveCampaign(args.base, key, identifier);
 
-  // Fleet changes only ever happen via this explicit command — never
+  // Fleet changes only ever happen via this explicit command - never
   // implicitly from create/start. Exclude whatever's already attached to THIS
   // campaign (an inbox can serve multiple campaigns; "unattached" is relative
   // to this one), then page through the healthy/usable pool for candidates.
@@ -1405,7 +1525,7 @@ async function campaignsStatus(argv) {
   const r = need(await request("GET", args.base, `/api/v1/campaigns/${campaignId}`, { key }), "campaign");
   if (args.json) return console.log(JSON.stringify(r, null, 2));
   const c = r.campaign || {};
-  console.log(`${bold(c.name || "—")}  ${dim(c.id)}`);
+  console.log(`${bold(c.name || "-")}  ${dim(c.id)}`);
   console.log(`  status ${bold(c.status)}  ·  leads ${Number(c.lead_count || 0).toLocaleString()}  ·  sent ${Number(c.sent_count || 0).toLocaleString()}  ·  replies ${Number(c.replied_count || 0).toLocaleString()}  ·  bounced ${Number(c.bounced_count || 0).toLocaleString()}`);
   console.log(`  emails ${(r.emails || []).length}  ·  senders ${(r.senders || []).length}`);
   printSettings({ settings: r.settings });
@@ -1511,7 +1631,7 @@ async function campaignsReplies(argv) {
   if (!(r.replies || []).length) return console.log(dim("No replies yet."));
   for (const e of r.replies) {
     console.log(`${bold(e.from_email || "")}  ${dim([e.first_name, e.last_name].filter(Boolean).join(" "))}  ${e.classification || ""}  ${dim(e.created_at || "")}`);
-    console.log(dim(`  ${(e.subject || "").slice(0, 80)} — ${(e.body || "").replace(/\s+/g, " ").slice(0, 140)}`));
+    console.log(dim(`  ${(e.subject || "").slice(0, 80)} - ${(e.body || "").replace(/\s+/g, " ").slice(0, 140)}`));
   }
 }
 
@@ -1530,7 +1650,7 @@ async function cmdInboxThreads(argv) {
     for (const e of r.events) {
       console.log(`${dim(e.id)}`);
       console.log(`  ${bold(e.from_email || e.lead_email || "")}  ${e.classification || ""}  ${dim(e.campaign_name || "")}  ${dim(e.created_at || "")}`);
-      console.log(dim(`  ${(e.subject || "").slice(0, 80)} — ${(e.body || e.snippet || "").replace(/\s+/g, " ").slice(0, 140)}`));
+      console.log(dim(`  ${(e.subject || "").slice(0, 80)} - ${(e.body || e.snippet || "").replace(/\s+/g, " ").slice(0, 140)}`));
     }
     return;
   }
@@ -1624,7 +1744,7 @@ async function cmdBlocklist(argv) {
 function campaignsHelp() {
   const p = bold("argorant campaigns");
   console.log(`
-${bold("Argorant Campaigns")} — email outreach from the terminal
+${bold("Argorant Campaigns")} - email outreach from the terminal
 
 Works with any Argorant API key. Nothing is sent until you launch.
 
@@ -1935,6 +2055,434 @@ async function cmdInboxes(argv) {
   die(`unknown inboxes subcommand: ${sub} (list, set, disconnect, connect-google, endings, suggest, quote, order, status, renewal, cancel-bundle)`);
 }
 
+// =============================================================================
+// find: the email finder. A person's name plus a company domain in, a work
+// email out. Priced per outcome by the server (GET /api/v1/email-finder/pricing):
+// an address returned costs 1 credit, a lookup that finds nothing 0.25 credit,
+// and lookups that cannot run (no mail server, try again later, invalid input)
+// are free. Nothing is charged on any error response.
+//
+// Own flag reader (readFlags) like `campaigns`: --first/--last/--max-credits
+// are not search filters, and `--name` means the job name with --file but the
+// person's name on a single lookup (same habit as `enrich --name`).
+// Exit codes: a single lookup exits 1 when no email came back (like `enrich`);
+// a --file job that pauses exits 5 (out of credits) or 4 (daily limit or slowed
+// down), so scripts can branch without parsing output.
+// =============================================================================
+
+const FIND_API = "/api/v1/email-finder";
+const FIND_DEFAULT_OUT = "argorant-found.csv";
+const FIND_POLL_MS = 2500;
+const FIND_VALUE_FLAGS = {
+  "--domain": "domain",
+  "--first": "first",
+  "--first-name": "first",
+  "--last": "last",
+  "--last-name": "last",
+  "--name": "name",
+  "-f": "file",
+  "--file": "file",
+  "-o": "output",
+  "--output": "output",
+  "--max-credits": "maxCredits",
+};
+const FIND_STATUS_LABELS = {
+  valid: "Confirmed",
+  catch_all: "Unconfirmed, catch-all domain",
+  not_found: "Not found",
+  no_mail_domain: "No mail server",
+  retry_later: "Try again later",
+  invalid_input: "Invalid input",
+  pending: "Pending",
+};
+const FIND_PAUSED_REASONS = {
+  insufficient_credits: "your workspace ran out of credits. Add credits, then resume.",
+  spend_limit: "the job reached its credit cap (--max-credits). Resume with a higher cap to continue.",
+  daily_limit: "the daily lookup limit was reached.",
+  miss_rate: "almost none of the recent lookups found an address, so lookups are slowed down for a while.",
+};
+const FIND_TERMINAL = ["done", "cancelled", "canceled", "paused"];
+const FIND_USAGE =
+  'usage: argorant find "<first last>" --domain <company.com>\n' +
+  "       argorant find --first <first> --last <last> --domain <company.com>\n" +
+  '       argorant find --file people.csv [-o found.csv] [--max-credits N] [--name "Q4 list"]\n' +
+  "       argorant find status | download | resume | cancel <job_id>\n" +
+  "       argorant find pricing";
+
+// 1 -> "1 credit", 0.25 -> "0.25 credit", 2 / 0 -> "2 credits" / "0 credits".
+function fmtCredits(n) {
+  const v = Number(n || 0);
+  return `${v.toLocaleString("en-US", { maximumFractionDigits: 2 })} credit${v > 0 && v <= 1 ? "" : "s"}`;
+}
+function fmtCharge(n) {
+  return Number(n || 0) > 0 ? fmtCredits(n) : "not charged";
+}
+function fmtWait(sec) {
+  if (sec < 90) return `${sec} seconds`;
+  if (sec < 5400) return `${Math.round(sec / 60)} minutes`;
+  return `${Math.round(sec / 3600)} hours`;
+}
+
+// The finder answers errors FastAPI-style under `detail`; tolerate a bare
+// {error, message} body too, and turn Retry-After into a plain wait time.
+function findNeed(res, what, { expect } = {}) {
+  const j = res.json;
+  let r = res;
+  // need() lets any status below 400 through. A redirect (http -> https, a
+  // wrong --base) must not read as "no email found" or "job resumed".
+  if (res.status >= 300 && res.status < 400) {
+    const to = res.res && res.res.headers && res.res.headers.location;
+    die(`${what}: the server answered with a redirect (HTTP ${res.status}${to ? ` to ${to}` : ""}). Check --base / ARGORANT_API_BASE.`);
+  }
+  if (res.status >= 400 && j && typeof j === "object" && !Array.isArray(j) && j.detail === undefined && (j.error || j.message)) {
+    r = { ...res, json: { detail: j } };
+  }
+  if (r.status === 429) {
+    const ra = Number((res.res && res.res.headers && res.res.headers["retry-after"]) || 0);
+    const msg = detailMsg(r.json && r.json.detail) || "the email finder limit was reached.";
+    die(Number.isFinite(ra) && ra > 0 ? `${msg} Try again in ${fmtWait(Math.ceil(ra))}. Nothing was charged.` : `${msg} Nothing was charged.`, EXIT.RATE_LIMIT);
+  }
+  let out = need(r, what);
+  // Job endpoints answer {ok, job: {...}}; the commands work on the job itself.
+  if (out && typeof out === "object" && out.job && typeof out.job === "object" && !Array.isArray(out.job)) out = out.job;
+  if (expect && (out === null || typeof out !== "object" || out[expect] === undefined || out[expect] === null)) {
+    die(`${what}: unexpected response from the server (no "${expect}" field). Check --base / ARGORANT_API_BASE.`);
+  }
+  return out;
+}
+
+function parseMaxCredits(raw) {
+  if (raw === undefined || raw === null) return null;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) die(`--max-credits must be a positive number (got "${raw}").`);
+  return n;
+}
+
+function findJobId(args, sub) {
+  const id = String(args._[1] || "").trim();
+  if (!id) die(`usage: argorant find ${sub} <job_id>${sub === "download" ? " [-o found.csv]" : sub === "resume" ? " [--max-credits N]" : ""}`);
+  if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(id)) die(`that does not look like a job id: ${id}`);
+  return id;
+}
+const findJobPath = (id, suffix = "") => `${FIND_API}/jobs/${encodeURIComponent(id)}${suffix}`;
+
+// Server prices, tolerant of a flat or nested shape. Fallbacks are the
+// documented defaults; the server stays the source of truth for charges.
+function findPrices(p) {
+  const pr = (p && (p.prices || p.pricing)) || {};
+  const pick = (...vals) => {
+    for (let v of vals) {
+      if (v && typeof v === "object") v = v.credits;
+      if (v !== undefined && v !== null && v !== "" && Number.isFinite(Number(v))) return Number(v);
+    }
+    return null;
+  };
+  const found = pick(pr.valid, pr.found, p && p.price_found);
+  return {
+    known: found !== null,
+    found: found ?? 1,
+    catchAll: pick(pr.catch_all, p && p.price_catch_all) ?? found ?? 1,
+    notFound: pick(pr.not_found, p && p.price_not_found) ?? 0.25,
+  };
+}
+
+function findCounts(job) {
+  const c = job.counts || {};
+  const confirmed = Number(c.valid || 0);
+  const catchAll = Number(c.catch_all || 0);
+  return {
+    confirmed,
+    catchAll,
+    found: confirmed + catchAll,
+    notFound: Number(c.not_found || 0),
+    free: Number(c.no_mail_domain || 0) + Number(c.retry_later || 0) + Number(c.invalid_input || 0),
+  };
+}
+function findProgress(job) {
+  const k = findCounts(job);
+  return `${job.status || "queued"}  ${Number(job.processed || 0).toLocaleString()}/${Number(job.total || 0).toLocaleString()} processed · ${k.found.toLocaleString()} found · ${fmtCredits(job.credits_charged)} charged`;
+}
+function findSummaryLines(job) {
+  const k = findCounts(job);
+  const lines = [
+    `  ${Number(job.processed || 0).toLocaleString()}/${Number(job.total || 0).toLocaleString()} processed · ` +
+      `${bold(k.found.toLocaleString())} found ${dim(`(${k.confirmed.toLocaleString()} confirmed, ${k.catchAll.toLocaleString()} unconfirmed catch-all)`)} · ` +
+      `${k.notFound.toLocaleString()} not found · ${k.free.toLocaleString()} not charged`,
+    `  ${fmtCredits(job.credits_charged)} charged` + (job.max_credits != null ? dim(` · cap ${fmtCredits(job.max_credits)}`) : ""),
+  ];
+  if (Number(job.duplicates_removed || 0) > 0) lines.push(dim(`  ${Number(job.duplicates_removed).toLocaleString()} duplicate rows removed`));
+  const bad = Array.isArray(job.invalid_rows) ? job.invalid_rows : [];
+  if (bad.length) {
+    lines.push(dim(`  ${bad.length.toLocaleString()} rows skipped as invalid (row ${bad.slice(0, 10).join(", ")}${bad.length > 10 ? ", ..." : ""})`));
+  }
+  return lines;
+}
+function findPausedLines(job, id) {
+  const r = job.paused_reason;
+  const lines = [yellow(`Paused: ${FIND_PAUSED_REASONS[r] || (r ? `reason "${r}".` : "no reason given.")}`)];
+  if (job.resume_after) lines.push(dim(`It can continue after ${job.resume_after}.`));
+  lines.push(`Resume: argorant find resume ${id} ${r === "spend_limit" ? "--max-credits <new cap>" : "[--max-credits N]"}`);
+  return lines;
+}
+function findPausedExit(reason) {
+  if (reason === "insufficient_credits") return EXIT.UPGRADE;
+  if (reason === "daily_limit" || reason === "miss_rate") return EXIT.RATE_LIMIT;
+  return EXIT.OK; // spend_limit: the job stopped at the cap the caller set.
+}
+function findStatusTag(status) {
+  const s = String(status || "").toLowerCase();
+  if (s === "done") return green(s);
+  if (s === "paused") return yellow(s);
+  return dim(s || "unknown");
+}
+
+async function findSingle(args, key) {
+  const raw = String(args.domain || "").trim();
+  const domain = normalizeDomain(raw.includes("@") ? raw.split("@").pop() : raw);
+  const first = String(args.first || "").trim();
+  const last = String(args.last || "").trim();
+  const name = (args._.join(" ") || String(args.name || "")).trim();
+  if (!domain && !first && !last && !name) die(FIND_USAGE);
+  if (!domain) die(`--domain is required (the company the person works at).\n${FIND_USAGE}`);
+  if (!domain.includes(".")) die(`--domain needs a company domain like acme.com (got "${raw}").`);
+  if ((first || last) && name) die("pass either a full name or --first/--last, not both.");
+  if (!first && !last && !name) die(`a name is required.\n${FIND_USAGE}`);
+  if (args.output) warn("-o is for --file jobs; a single lookup prints its result.");
+  if (args.maxCredits !== undefined) warn("--max-credits is for --file jobs; a single lookup costs at most 1 credit.");
+  const body = first || last ? { first_name: first, last_name: last, domain } : { name, domain };
+  const r = findNeed(await request("POST", args.base, `${FIND_API}/find`, { key, body }), "find", { expect: "status" });
+  const gotEmail = Boolean(r.email);
+  if (args.json) {
+    console.log(JSON.stringify(r, null, 2));
+    if (!gotEmail) process.exit(EXIT.ERROR);
+    return;
+  }
+  const label = FIND_STATUS_LABELS[r.status] || r.status || "unknown";
+  const tag = r.status === "valid" ? green(label) : r.status === "catch_all" ? yellow(label) : dim(label);
+  const parts = [gotEmail ? bold(r.email) : dim("no email found"), tag];
+  if (gotEmail && r.confidence !== undefined && r.confidence !== null) parts.push(`confidence ${r.confidence}`);
+  parts.push(fmtCharge(r.credits_charged));
+  console.log(parts.join(dim("  ·  ")));
+  if (!gotEmail) process.exit(EXIT.ERROR);
+}
+
+async function pollFindJob(args, key, job) {
+  const id = job.job_id;
+  const tty = Boolean(process.stdout.isTTY);
+  const recovery = `The job keeps running. Check it with \`argorant find status ${id}\` and download with \`argorant find download ${id} -o ${args.output || FIND_DEFAULT_OUT}\`.`;
+  const onInt = () => {
+    if (tty && !args.json) process.stdout.write("\n");
+    process.stderr.write(dim(`Stopped watching. ${recovery}\n`));
+    process.exit(130);
+  };
+  process.once("SIGINT", onInt);
+  const started = Date.now();
+  let shown = "";
+  let failures = 0;
+  try {
+    for (;;) {
+      if (!args.json) {
+        const line = findProgress(job);
+        if (line !== shown) {
+          if (tty) process.stdout.write(`\r\x1b[K${dim(line)}`);
+          else console.log(line);
+          shown = line;
+        }
+      }
+      if (FIND_TERMINAL.includes(String(job.status || "").toLowerCase())) break;
+      if (Date.now() - started > 1000 * 60 * 60 * 12) die(`\nstopped watching after 12 hours. ${recovery}`);
+      await new Promise((r) => setTimeout(r, FIND_POLL_MS));
+      let res;
+      try {
+        res = await request("GET", args.base, findJobPath(id), { key });
+      } catch (e) {
+        res = { error: e };
+      }
+      // Ride out short network blips and gateway errors; the job is server-side.
+      if (res.error || res.status >= 500) {
+        failures += 1;
+        if (failures > 5) die(`\n${res.error ? res.error.message : `job status failed (HTTP ${res.status})`}. ${recovery}`);
+        continue;
+      }
+      failures = 0;
+      job = findNeed(res, "find job status", { expect: "status" });
+    }
+  } finally {
+    process.removeListener("SIGINT", onInt);
+  }
+  if (tty && !args.json) process.stdout.write("\n");
+  return job;
+}
+
+async function findFile(args, key) {
+  if (args._.length) die("pass either a name or --file, not both.");
+  if (args.domain || args.first || args.last) {
+    die("--domain/--first/--last are for a single lookup; with --file every row carries its own name and domain.");
+  }
+  const maxCredits = parseMaxCredits(args.maxCredits);
+  let text;
+  try {
+    text = fs.readFileSync(args.file, "utf8");
+  } catch {
+    die(`cannot read file: ${args.file}`);
+  }
+  text = text.replace(/^/, "");
+  const lines = text.split(/\r?\n/).filter((l) => l.trim());
+  if (!lines.length) die("file is empty");
+  // Local count for the prompt only; the server parses the file and reports
+  // the real total, duplicates and invalid rows on the job.
+  const rows = lines.length - 1;
+  if (rows < 1) die("file has a header but no rows.");
+  // A paid job must never die on a path problem after it was created.
+  const destArg = args.output || FIND_DEFAULT_OUT;
+  const dest = ensureWritable(destArg);
+  // Interactive-only by design, like reveal/export: with --yes, --json or a
+  // non-TTY stdin this spends credits with no prompt.
+  if (!args.yes && !args.json && process.stdin.isTTY) {
+    const p = findNeed(await request("GET", args.base, `${FIND_API}/pricing`, { key }), "find pricing");
+    const pr = findPrices(p);
+    if (!pr.known) warn("the server did not return prices in a known shape; showing the standard prices.");
+    let max = rows * Math.max(pr.found, pr.catchAll, pr.notFound);
+    if (maxCredits !== null) max = Math.min(max, maxCredits);
+    const ans = await prompt(
+      `Find emails for ${bold(rows.toLocaleString())} rows? ${fmtCredits(pr.found)} per email found, ` +
+        `${fmtCredits(pr.notFound)} when nothing is found (maximum ${fmtCredits(max)}). [y/N] `
+    );
+    if (!/^y(es)?$/i.test(ans)) return console.log(dim("aborted."));
+  }
+  const body = { csv: text };
+  if (args.name) body.name = String(args.name).trim();
+  if (maxCredits !== null) body.max_credits = maxCredits;
+  const created = findNeed(await request("POST", args.base, `${FIND_API}/jobs`, { key, body }), "find job", { expect: "job_id" });
+  const id = created.job_id;
+  if (args.json) {
+    // stdout stays pure JSON; the id still reaches the terminal for recovery.
+    process.stderr.write(dim(`job ${id}\n`));
+  } else {
+    const extra = [];
+    if (Number(created.duplicates_removed || 0) > 0) extra.push(`${created.duplicates_removed} duplicates removed`);
+    if (Array.isArray(created.invalid_rows) && created.invalid_rows.length) extra.push(`${created.invalid_rows.length} invalid rows skipped`);
+    console.log(
+      green("✓") + ` Job ${bold(id)} created: ${Number(created.total ?? rows).toLocaleString()} rows` + (extra.length ? dim(` (${extra.join(", ")})`) : "")
+    );
+    console.log(dim("Ctrl-C stops watching; the job keeps running."));
+  }
+  const job = await pollFindJob(args, key, created);
+  const status = String(job.status || "").toLowerCase();
+  try {
+    await downloadTo(args.base, findJobPath(id, "/results?format=csv"), key, dest);
+  } catch (e) {
+    die(`${e.message}\nThe job itself is saved. Download it again with \`argorant find download ${id} -o ${destArg}\`.`);
+  }
+  const exitCode = status === "paused" ? findPausedExit(job.paused_reason) : EXIT.OK;
+  if (args.json) {
+    console.log(JSON.stringify({ ...job, file: dest }, null, 2));
+    if (exitCode !== EXIT.OK) process.exit(exitCode);
+    return;
+  }
+  const head = status === "done" ? green("✓") + " Done" : status === "paused" ? yellow("Paused") : dim(status || "stopped");
+  console.log(`${head}  ${bold(id)}`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  const saved = countCsvRows(dest);
+  console.log(
+    `  Saved ${saved !== null ? bold(saved.toLocaleString()) + " rows → " : ""}${bold(dest)}` +
+      (status === "done" ? "" : dim("  (rows not processed yet show as pending)"))
+  );
+  if (status === "paused") for (const l of findPausedLines(job, id)) console.log(l);
+  if (exitCode !== EXIT.OK) process.exit(exitCode);
+}
+
+async function findStatus(args, key) {
+  const id = findJobId(args, "status");
+  const job = findNeed(await request("GET", args.base, findJobPath(id), { key }), "find job status", { expect: "status" });
+  if (args.json) return console.log(JSON.stringify(job, null, 2));
+  const status = String(job.status || "").toLowerCase();
+  console.log(`${bold("Job " + (job.job_id || id))}${job.name ? "  " + dim(`"${job.name}"`) : ""}  ${findStatusTag(status)}`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  if (status === "paused") for (const l of findPausedLines(job, id)) console.log("  " + l);
+  if (Number(job.processed || 0) > 0 || FIND_TERMINAL.includes(status)) {
+    console.log(dim(`  Download: argorant find download ${id} -o found.csv`));
+  }
+}
+
+async function findDownload(args, key) {
+  const id = findJobId(args, "download");
+  const dest = ensureWritable(args.output || FIND_DEFAULT_OUT);
+  const job = findNeed(await request("GET", args.base, findJobPath(id), { key }), "find job status", { expect: "status" });
+  await downloadTo(args.base, findJobPath(id, "/results?format=csv"), key, dest);
+  const status = String(job.status || "").toLowerCase();
+  if (args.json) return console.log(JSON.stringify({ ok: true, job_id: id, status, file: dest }, null, 2));
+  const rows = countCsvRows(dest);
+  console.log(green("✓") + ` Saved ${rows !== null ? bold(rows.toLocaleString()) + " rows → " : ""}${bold(dest)}`);
+  if (status !== "done") {
+    console.log(dim(`  Job is ${status || "not finished"}: ${Number(job.processed || 0).toLocaleString()}/${Number(job.total || 0).toLocaleString()} processed, the rest show as pending.`));
+  }
+}
+
+async function findResume(args, key) {
+  const id = findJobId(args, "resume");
+  const maxCredits = parseMaxCredits(args.maxCredits);
+  const body = maxCredits !== null ? { max_credits: maxCredits } : {};
+  const job = findNeed(await request("POST", args.base, findJobPath(id, "/resume"), { key, body }), "find job resume", { expect: "status" });
+  if (args.json) return console.log(JSON.stringify(job, null, 2));
+  console.log(green("✓") + ` Resumed job ${bold(job.job_id || id)}  ${findStatusTag(job.status)}`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  console.log(dim(`  Follow it with: argorant find status ${id}`));
+}
+
+async function findCancel(args, key) {
+  const id = findJobId(args, "cancel");
+  const job = findNeed(await request("POST", args.base, findJobPath(id, "/cancel"), { key }), "find job cancel", { expect: "status" });
+  if (args.json) return console.log(JSON.stringify(job, null, 2));
+  console.log(green("✓") + ` Cancelled job ${bold(job.job_id || id)}. Remaining rows will not be looked up or charged.`);
+  for (const l of findSummaryLines(job)) console.log(l);
+  if (Number(job.processed || 0) > 0) console.log(dim(`  Download what was found: argorant find download ${id} -o found.csv`));
+}
+
+async function findPricing(args, key) {
+  const p = findNeed(await request("GET", args.base, `${FIND_API}/pricing`, { key }), "find pricing");
+  if (args.json) return console.log(JSON.stringify(p, null, 2));
+  const pr = findPrices(p);
+  if (!pr.known) warn("the server did not return prices in a known shape; showing the standard prices (see --json for the raw answer).");
+  console.log(bold("Email finder prices"));
+  console.log(`  Email found and confirmed        ${fmtCredits(pr.found)}`);
+  console.log(`  Catch-all domain, unconfirmed    ${fmtCredits(pr.catchAll)}`);
+  console.log(`  Nothing found                    ${fmtCredits(pr.notFound)}`);
+  console.log(`  No mail server, try again later, invalid input   ${green("free")}`);
+  const b = p.balance || {};
+  const bal = [];
+  if (b.credits !== undefined && b.credits !== null) bal.push(`${bold(Number(b.credits).toLocaleString("en-US", { maximumFractionDigits: 2 }))} credits`);
+  const pre = b.prepaid_no_result_lookups;
+  if (pre !== undefined && pre !== null) bal.push(`${Number(pre).toLocaleString()} prepaid no-result lookup${Number(pre) === 1 ? "" : "s"}`);
+  if (bal.length) console.log(`${bold("Balance")}  ${bal.join(" · ")}`);
+  const l = p.limits || {};
+  const perMin = l.per_minute ?? l.single_per_minute ?? l.minute;
+  const perDay = l.per_day ?? l.daily ?? l.daily_limit;
+  const used = l.used_today;
+  const lim = [];
+  if (perMin !== undefined && perMin !== null) lim.push(`${Number(perMin).toLocaleString()} lookups per minute`);
+  if (perDay !== undefined && perDay !== null) lim.push(`${Number(perDay).toLocaleString()} per day` + (used !== undefined && used !== null ? ` (${Number(used).toLocaleString()} used today)` : ""));
+  if (lim.length) console.log(`${bold("Limits")}   ${lim.join(" · ")}`);
+  if (p.billing_exempt) console.log(dim("Lookups on this account are not charged."));
+  console.log(dim("Nothing is charged when a request fails. A 0.25 charge takes 1 whole credit and keeps the rest for your next no-result lookups."));
+}
+
+async function cmdFind(argv) {
+  const args = readFlags(argv, FIND_VALUE_FLAGS);
+  const sub = String(args._[0] || "").toLowerCase();
+  if (sub === "help" || (!args._.length && !args.file && !args.domain && !args.first && !args.last && !args.name)) {
+    if (sub === "help") return console.log(FIND_USAGE);
+    die(FIND_USAGE);
+  }
+  const subs = { status: findStatus, download: findDownload, resume: findResume, cancel: findCancel, pricing: findPricing, prices: findPricing };
+  const key = requireKey();
+  // A subcommand word only counts as one when no single-lookup flags are set,
+  // so `find "Pricing" --domain x.com` still looks up a person.
+  if (subs[sub] && !args.file && !args.domain && !args.first && !args.last) return subs[sub](args, key);
+  if (args.file) return findFile(args, key);
+  return findSingle(args, key);
+}
+
 function money(cents, currency) {
   if (cents === null || cents === undefined) return "?";
   const sign = String(currency || "usd").toLowerCase() === "eur" ? "€" : "$";
@@ -1944,7 +2492,7 @@ function money(cents, currency) {
 function help() {
   const p = bold("argorant");
   console.log(`
-${bold("Argorant")} — verified B2B contacts from your terminal  ${dim("v" + VERSION)}
+${bold("Argorant")} - verified B2B contacts from your terminal  ${dim("v" + VERSION)}
 
 ${bold("USAGE")}
   ${p} <command> "<query>" [filters]
@@ -1958,16 +2506,24 @@ ${bold("COMMANDS")}
   ${cyan("search")} "<query>" -n 10     Preview matches, details redacted ${dim("(0 contact credits)")}
   ${cyan("sample")} <company.com>        Build 25 distinct, live-valid company leads ${dim("(free sample)")}
   ${cyan("reveal")} "<query>" -n 25     Reveal full contact details    ${dim("(uses credits; live-verified, pay only for deliverable)")}
+  ${cyan("reveal")} ... --phones         Also add phone numbers         ${dim("(10 credits per number found; none found = free)")}
   ${cyan("enrich")} --email <a@b.com>   One address → the full person profile ${dim("(1 credit per match; miss = free)")}
   ${cyan("enrich")} --name "<n>" --domain <d>   Find that person + reveal a verified email ${dim("(1 credit per match)")}
   ${cyan("enrich")} --domain <d>        Company profile                ${dim("(0 contact credits)")}
+  ${cyan("enrich")} ... --phones         Also add the person's phone number ${dim("(10 credits if found)")}
   ${cyan("export")} "<query>" -n 1000 -o leads.csv   Verified CSV export ${dim("(uses credits)")}
+  ${cyan("export")} ... --phones         Include phone numbers in the file ${dim("(10 credits per number in the file)")}
   ${cyan("export status")} <job_id>     Status of an existing export  ${dim("(free; add --batch for >50k)")}
   ${cyan("export download")} <job_id> -o leads.csv   Re-download a finished export ${dim("(free)")}
   ${cyan("list create")} --name "<n>" [filters]      Save a reusable list ${dim("(free)")}
   ${cyan("list status")} <id>           Show a saved list's size       ${dim("(free)")}
   ${cyan("verify")} <email>             Verify one of your own emails  ${dim("(verification pool)")}
   ${cyan("verify")} --file emails.csv -o out.csv      Bulk-verify your own list ${dim("(recent re-checks free)")}
+  ${cyan("find")} "<first last>" --domain <d>   Find a person's work email ${dim("(1 credit found, 0.25 credit nothing found)")}
+  ${cyan("find")} --first <f> --last <l> --domain <d>   Same, with the name in two parts
+  ${cyan("find")} --file people.csv -o found.csv   Find emails for a list ${dim("(same prices; --max-credits caps the job)")}
+  ${cyan("find")} status | download | resume | cancel <job_id>   Manage a find job ${dim("(free)")}
+  ${cyan("find pricing")}               Finder prices, balance, limits ${dim("(free)")}
   ${cyan("campaigns")} ...                Email outreach: create, write, enroll, launch ${dim("(argorant campaigns help)")}
   ${cyan("inboxes")} list | connect-google  Connected mailboxes; connect a Google Workspace
   ${cyan("inboxes")} quote | order | status | renewal  New mailboxes on new domains ${dim("(saved card or payment link)")}
@@ -1991,20 +2547,26 @@ ${bold("OPTIONS")}
       --json         Raw JSON output    -y, --yes             Skip confirmations
       --base <url>   Override API base  (or ARGORANT_API_BASE)
       --batch        Treat the id in \`export status/download\` as a batch id
+      --phones       Include phone numbers (reveal, enrich, export). Off by default.
+                     10 credits per phone number returned, nothing if none is found;
+                     numbers you already unlocked are free. From the Pro plan.
+      --max-credits <n>  Credit cap for a \`find --file\` job (it pauses at the cap)
       --grade <g>    valid (default) or valid-plus-catchall - which deliverable
                      grade to include on reveal/export. You only ever pay for
                      deliverable contacts; this is the one grade distinction
                      exposed anywhere. ${dim("(coming soon - currently a no-op; see docs)")}
 
 ${bold("NON-INTERACTIVE USE")} ${dim("(agents, CI, pipes)")}
-  ${red("reveal, export, and verify --file SPEND CREDITS WITHOUT A PROMPT")} whenever
+  ${red("reveal, export, verify --file, and find SPEND CREDITS WITHOUT A PROMPT")} whenever
   stdin is not a TTY, or when --yes / --json is passed. The confirmation is a
   convenience for humans at a terminal, never a safety net. Check your -n.
+  A single \`find\` never asks: each lookup costs at most 1 credit.
 
 ${bold("EXIT CODES")}
   0 ok   ·   1 error   ·   2 not authenticated   ·   3 forbidden (missing scope)
   4 rate limit / daily quota   ·   5 plan upgrade required
   ${dim("`enrich` exits 1 when nothing matched, so scripts can branch without parsing the payload.")}
+  ${dim("`find` exits 1 when no email came back; a paused `find --file` job exits 5 (out of credits) or 4 (daily limit).")}
 
 ${bold("EXAMPLES")}
   ${p} count "fintech CFOs in germany"
@@ -2015,8 +2577,12 @@ ${bold("EXAMPLES")}
   ${p} enrich --email patrick@stripe.com --json
   ${p} enrich --name "Patrick Collison" --domain stripe.com
   ${p} enrich --domain stripe.com
+  ${p} reveal --title CFO --domain stripe.com -n 5 --phones
+  ${p} export --title CFO --country Germany -n 200 --phones -o cfos.csv
   ${p} verify ceo@stripe.com
   ${p} verify --file my-list.csv -o verified.csv
+  ${p} find "Patrick Collison" --domain stripe.com
+  ${p} find --file people.csv -o found.csv --max-credits 200
 
   Docs: ${cyan("https://argorant.com/docs/cli")}
 `);
@@ -2027,12 +2593,13 @@ async function main() {
   const cmd = argv[0];
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") return help();
   if (cmd === "version" || cmd === "--version" || cmd === "-v") return console.log(VERSION);
-  // `campaigns` has its own flag vocabulary (--step, --count, --pool, --csv, ...)
-  // handled by readFlags — it never goes through the generic filter parser
+  // `campaigns` and `find` have their own flag vocabulary (--step, --count, --first, --max-credits, ...)
+  // handled by readFlags - it never goes through the generic filter parser
   // below, which would reject those flags as unknown.
-  if (cmd === "campaigns" || cmd === "campaign" || cmd === "inboxes" || cmd === "mailboxes" || cmd === "inbox" || cmd === "unibox" || cmd === "blocklist") {
+  if (cmd === "campaigns" || cmd === "campaign" || cmd === "inboxes" || cmd === "mailboxes" || cmd === "inbox" || cmd === "unibox" || cmd === "blocklist" || cmd === "find") {
     try {
       if (cmd.startsWith("campaign")) await cmdCampaigns(argv.slice(1));
+      else if (cmd === "find") await cmdFind(argv.slice(1));
       else if (cmd === "blocklist") await cmdBlocklist(argv.slice(1));
       else if (cmd === "inbox" || cmd === "unibox") await cmdInboxThreads(argv.slice(1));
       else await cmdInboxes(argv.slice(1));