@hasna/experts 0.0.7 → 0.0.8

package/dist/cli/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 // @bun
+var __require = import.meta.require;
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -53,6 +54,36 @@ function authorityScore(e, inputs = {}, weights = DEFAULT_WEIGHTS) {
   const raw = weights.rating * rating + weights.reviews * reviews + weights.followers * followers + weights.featured * featured + weights.verified * verified + weights.recency * recency;
   return Math.round(raw * 1000) / 10;
 }
+function pricePerHour(price, priceUnit) {
+  if (!price || price <= 0)
+    return /free/i.test(priceUnit) ? 0 : null;
+  const u = (priceUnit || "").toLowerCase();
+  const minMatch = u.match(/(\d+)\s*min/);
+  if (minMatch)
+    return Math.round(price * 60 / Number(minMatch[1]));
+  if (/per\s*min|\/\s*min|minute/.test(u))
+    return price * 60;
+  if (/hour|\/\s*hr|per\s*hr/.test(u))
+    return price;
+  if (/free/.test(u))
+    return 0;
+  return null;
+}
+var DEFAULT_BLEND = { semantic: 0.8, authority: 0.2 };
+function blendScore(semantic, authority, w = DEFAULT_BLEND) {
+  const a = Math.max(0, Math.min(1, (authority || 0) / 100));
+  const s = Math.max(0, Math.min(1, semantic));
+  return w.semantic * s + w.authority * a;
+}
+function explainMatch(query, e) {
+  const q = ` ${(query || "").toLowerCase()} `;
+  const hit = (label) => {
+    const l = label.toLowerCase();
+    return q.includes(` ${l} `) || q.includes(`${l},`) || q.includes(`${l}.`) || new RegExp(`\\b${l.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(q);
+  };
+  const matched = [...e.topics, ...e.tags].filter(hit);
+  return [...new Set(matched)].slice(0, 6);
+}
 
 // src/embed.ts
 var STOPWORDS = new Set([
@@ -143,11 +174,40 @@ class OpenAIEmbedder {
     return data.data.map((d) => d.embedding);
   }
 }
-function getEmbedder() {
-  if (process.env.EXPERTS_EMBEDDER === "openai" && process.env.OPENAI_API_KEY) {
+
+class TransformersEmbedder {
+  id = "minilm-l6-v2";
+  dim = 384;
+  model = process.env.EXPERTS_EMBED_MODEL || "Xenova/all-MiniLM-L6-v2";
+  extractor = null;
+  async ensure() {
+    if (this.extractor)
+      return;
+    const { pipeline } = await import("@huggingface/transformers");
+    this.extractor = await pipeline("feature-extraction", this.model);
+  }
+  async embed(texts) {
+    await this.ensure();
+    const out = [];
+    for (const t of texts) {
+      const r = await this.extractor(t || " ", { pooling: "mean", normalize: true });
+      out.push(Array.from(r.data));
+    }
+    return out;
+  }
+}
+async function getEmbedder() {
+  const choice = process.env.EXPERTS_EMBEDDER;
+  if (choice === "openai" && process.env.OPENAI_API_KEY)
     return new OpenAIEmbedder;
+  if (choice === "hash")
+    return new HashingEmbedder;
+  try {
+    await import("@huggingface/transformers");
+    return new TransformersEmbedder;
+  } catch {
+    return new HashingEmbedder;
   }
-  return new HashingEmbedder;
 }
 function cosine(a, b) {
   let dot = 0;
@@ -232,6 +292,48 @@ function clusterPersons(experts) {
   return out;
 }
 
+// src/crypto.ts
+import { createCipheriv, createDecipheriv, createHmac, scryptSync } from "crypto";
+var PREFIX = "enc1:";
+var cachedKey = null;
+var cachedFrom = null;
+function key2() {
+  const secret = process.env.OPEN_EXPERTS_KEY;
+  if (!secret)
+    return null;
+  if (cachedKey && cachedFrom === secret)
+    return cachedKey;
+  cachedKey = scryptSync(secret, "open-experts/contacts/v1", 32);
+  cachedFrom = secret;
+  return cachedKey;
+}
+function maybeEncrypt(plaintext) {
+  const k = key2();
+  if (!k || plaintext == null)
+    return plaintext;
+  if (plaintext.startsWith(PREFIX))
+    return plaintext;
+  const iv = createHmac("sha256", k).update(plaintext).digest().subarray(0, 12);
+  const cipher = createCipheriv("aes-256-gcm", k, iv);
+  const enc = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return PREFIX + Buffer.concat([iv, tag, enc]).toString("base64");
+}
+function maybeDecrypt(stored) {
+  if (stored == null || !stored.startsWith(PREFIX))
+    return stored;
+  const k = key2();
+  if (!k)
+    return stored;
+  const raw = Buffer.from(stored.slice(PREFIX.length), "base64");
+  const iv = raw.subarray(0, 12);
+  const tag = raw.subarray(12, 28);
+  const enc = raw.subarray(28);
+  const decipher = createDecipheriv("aes-256-gcm", k, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(enc), decipher.final()]).toString("utf8");
+}
+
 // src/db.ts
 function defaultDbPath() {
   return process.env.OPEN_EXPERTS_DB || join(homedir(), ".hasna", "experts", "experts.db");
@@ -343,10 +445,11 @@ class ExpertsDB {
       CREATE INDEX IF NOT EXISTS idx_contacts_expert ON contacts(source, source_id);
       CREATE INDEX IF NOT EXISTS idx_contacts_status ON contacts(status);
 
-      -- Semantic search: one embedding vector per expert.
+      -- Semantic search: one embedding vector per expert (text_hash enables
+      -- incremental re-embedding \u2014 skip unchanged experts).
       CREATE TABLE IF NOT EXISTS vectors (
         source TEXT NOT NULL, source_id TEXT NOT NULL,
-        embedder TEXT NOT NULL, dim INTEGER, vec BLOB,
+        embedder TEXT NOT NULL, dim INTEGER, vec BLOB, text_hash TEXT,
         PRIMARY KEY (source, source_id)
       );
 
@@ -368,6 +471,7 @@ class ExpertsDB {
     `);
     this.addColumnIfMissing("experts", "avatar_local", "TEXT");
     this.addColumnIfMissing("experts", "authority", "REAL DEFAULT 0");
+    this.addColumnIfMissing("vectors", "text_hash", "TEXT");
   }
   addColumnIfMissing(table, column, type) {
     const cols = this.db.query(`PRAGMA table_info(${table})`).all();
@@ -454,6 +558,7 @@ class ExpertsDB {
       extra: JSON.parse(r.extra || "{}"),
       avatarLocal: r.avatar_local || undefined,
       authority: r.authority ?? 0,
+      pricePerHour: pricePerHour(r.price ?? 0, r.price_unit ?? ""),
       crawledAt: r.crawled_at
     };
   }
@@ -577,11 +682,11 @@ class ExpertsDB {
     sql += " ORDER BY name";
     return this.db.query(sql).all(...params);
   }
-  setMeta(key2, value) {
-    this.db.query("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(key2, value);
+  setMeta(key3, value) {
+    this.db.query("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(key3, value);
   }
-  getMeta(key2) {
-    const row = this.db.query("SELECT value FROM meta WHERE key = ?").get(key2);
+  getMeta(key3) {
+    const row = this.db.query("SELECT value FROM meta WHERE key = ?").get(key3);
     return row ? row.value : null;
   }
   stats(source) {
@@ -605,12 +710,12 @@ class ExpertsDB {
       const nodeIds = new Map;
       const insertNode = this.db.query("INSERT INTO kg_nodes (type, key, label) VALUES (?, ?, ?) ON CONFLICT(type, key) DO UPDATE SET label=excluded.label RETURNING id");
       const insertEdge = this.db.query("INSERT OR REPLACE INTO kg_edges (src, dst, rel, weight) VALUES (?, ?, ?, ?)");
-      const node = (type, key2, label) => {
-        const ck = `${type}\x00${key2.toLowerCase()}`;
+      const node = (type, key3, label) => {
+        const ck = `${type}\x00${key3.toLowerCase()}`;
         const cached = nodeIds.get(ck);
         if (cached != null)
           return cached;
-        const id = insertNode.get(type, key2.toLowerCase(), label).id;
+        const id = insertNode.get(type, key3.toLowerCase(), label).id;
         nodeIds.set(ck, id);
         return id;
       };
@@ -620,7 +725,7 @@ class ExpertsDB {
         for (const topic of e.topics) {
           insertEdge.run(eId, node("topic", topic, topic), "IN_TOPIC", 1);
         }
-        const tweetText = this.recentTweets(e.source, e.sourceId, 30).map((t) => t.text).join(". ");
+        const tweetText = this.recentTweets(e.source, e.sourceId, 30).filter((t) => !t.isRetweet).map((t) => t.text).join(". ");
         const tags = inferTags(expertText(e) + ". " + tweetText, vocabulary);
         for (const tag of tags) {
           insertEdge.run(eId, node("tag", tag, tag), "HAS_TAG", 1);
@@ -674,11 +779,11 @@ class ExpertsDB {
       lastSeen: r.last_seen || ""
     }));
   }
-  expertFromNodeKey(key2) {
-    const idx = key2.indexOf(":");
+  expertFromNodeKey(key3) {
+    const idx = key3.indexOf(":");
     if (idx < 0)
       return null;
-    return this.get(key2.slice(idx + 1), key2.slice(0, idx));
+    return this.get(key3.slice(idx + 1), key3.slice(0, idx));
   }
   findByNeeds(needs, opts = {}) {
     const cleaned = needs.map((n) => n.trim().toLowerCase()).filter(Boolean);
@@ -805,6 +910,15 @@ class ExpertsDB {
     };
   }
   replaceTweets(source, sourceId, tweets) {
+    const norm = (t) => (t || "").toLowerCase().replace(/^rt @\w+:\s*/, "").replace(/https?:\/\/\S+/g, "").replace(/[^a-z0-9 ]/g, "").replace(/\s+/g, " ").trim();
+    const seen = new Set;
+    const deduped = tweets.filter((t) => {
+      const k = norm(t.text);
+      if (!k || seen.has(k))
+        return false;
+      seen.add(k);
+      return true;
+    });
     const tx = this.db.transaction((rows) => {
       this.db.query("DELETE FROM tweets WHERE source = ? AND source_id = ?").run(source, sourceId);
       const stmt = this.db.query(`
@@ -817,7 +931,7 @@ class ExpertsDB {
         stmt.run(t.source, t.sourceId, t.tweetId, t.text, t.createdAt, t.retweetCount, t.replyCount, t.likeCount, t.quoteCount, t.impressionCount, t.isRetweet ? 1 : 0, t.isReply ? 1 : 0);
       }
     });
-    tx(tweets);
+    tx(deduped);
   }
   recentTweets(source, sourceId, limit = 10) {
     const rows = this.db.query("SELECT * FROM tweets WHERE source = ? AND source_id = ? ORDER BY created_at DESC LIMIT ?").all(source, sourceId, limit);
@@ -935,17 +1049,24 @@ class ExpertsDB {
     const log = opts.onLog ?? (() => {});
     const experts = this.list({ source: opts.source });
     const batch = opts.batch ?? 64;
-    const stmt = this.db.query("INSERT OR REPLACE INTO vectors (source, source_id, embedder, dim, vec) VALUES (?, ?, ?, ?, ?)");
+    const stmt = this.db.query("INSERT OR REPLACE INTO vectors (source, source_id, embedder, dim, vec, text_hash) VALUES (?, ?, ?, ?, ?, ?)");
+    const existing = new Map(this.db.query("SELECT source, source_id, embedder, text_hash FROM vectors").all().map((r) => [`${r.source}:${r.source_id}`, { embedder: r.embedder, hash: r.text_hash || "" }]));
+    const work = experts.map((e) => ({ e, text: expertEmbedText(e), hash: String(Bun.hash(expertEmbedText(e))) })).filter(({ e, hash }) => {
+      if (opts.force)
+        return true;
+      const prev = existing.get(`${e.source}:${e.sourceId}`);
+      return !prev || prev.embedder !== embedder.id || prev.hash !== hash;
+    });
     let done = 0;
-    for (let i = 0;i < experts.length; i += batch) {
-      const slice = experts.slice(i, i + batch);
-      const vecs = await embedder.embed(slice.map((e) => expertEmbedText(e)));
+    for (let i = 0;i < work.length; i += batch) {
+      const slice = work.slice(i, i + batch);
+      const vecs = await embedder.embed(slice.map((w) => w.text));
       const tx = this.db.transaction(() => {
-        slice.forEach((e, j) => stmt.run(e.source, e.sourceId, embedder.id, embedder.dim, packVector(vecs[j])));
+        slice.forEach((w, j) => stmt.run(w.e.source, w.e.sourceId, embedder.id, embedder.dim, packVector(vecs[j]), w.hash));
       });
       tx();
       done += slice.length;
-      log(`  embedded ${done}/${experts.length}`);
+      log(`  embedded ${done}/${work.length} (${experts.length - work.length} unchanged)`);
     }
     this.setMeta("embedder", embedder.id);
     this.setMeta("embedded_at", new Date().toISOString());
@@ -958,7 +1079,13 @@ class ExpertsDB {
     const where = opts.source ? "WHERE v.source = ?" : "";
     const params = opts.source ? [opts.source] : [];
     const rows = this.db.query(`SELECT e.*, v.vec AS _vec FROM vectors v JOIN experts e ON e.source=v.source AND e.source_id=v.source_id ${where}`).all(...params);
-    const scored = rows.map((r) => ({ expert: this.rowToExpert(r), score: cosine(queryVec, unpackVector(r._vec)) }));
+    const blend = opts.blend !== false;
+    const scored = rows.map((r) => {
+      const expert = this.rowToExpert(r);
+      const semantic = cosine(queryVec, unpackVector(r._vec));
+      const score = blend ? blendScore(semantic, expert.authority ?? 0) : semantic;
+      return { expert, score, semantic };
+    });
     scored.sort((a, b) => b.score - a.score);
     return scored.slice(0, opts.limit ?? 25);
   }
@@ -1048,7 +1175,7 @@ class ExpertsDB {
       $source: c.source,
       $source_id: c.sourceId,
       $type: c.type,
-      $value: c.value,
+      $value: maybeEncrypt(c.value),
       $label: c.label,
       $provider: c.provider,
       $confidence: c.confidence,
@@ -1058,7 +1185,7 @@ class ExpertsDB {
     });
   }
   setContactStatus(source, sourceId, type, value, status) {
-    this.db.query("UPDATE contacts SET status = ?, verified_at = ? WHERE source = ? AND source_id = ? AND type = ? AND value = ?").run(status, new Date().toISOString(), source, sourceId, type, value);
+    this.db.query("UPDATE contacts SET status = ?, verified_at = ? WHERE source = ? AND source_id = ? AND type = ? AND value = ?").run(status, new Date().toISOString(), source, sourceId, type, maybeEncrypt(value));
   }
   contacts(source, sourceId) {
     const rows = this.db.query("SELECT * FROM contacts WHERE source = ? AND source_id = ? ORDER BY type, confidence DESC").all(source, sourceId);
@@ -1066,7 +1193,7 @@ class ExpertsDB {
       source: r.source,
       sourceId: r.source_id,
       type: r.type,
-      value: r.value,
+      value: maybeDecrypt(r.value),
       label: r.label || "",
       provider: r.provider || "",
       confidence: r.confidence ?? 0,
@@ -1091,7 +1218,7 @@ class ExpertsDB {
       source: r.source,
       sourceId: r.source_id,
       type: r.type,
-      value: r.value,
+      value: maybeDecrypt(r.value),
       label: r.label || "",
       provider: r.provider || "",
       confidence: r.confidence ?? 0,
@@ -1401,34 +1528,37 @@ async function fetchJson(url, fetchFn, init = {}) {
 }
 
 // src/sources/mentorcruise.ts
+function stripHtml(s) {
+  return (s || "").replace(/<[^>]+>/g, " ").replace(/&[a-z#0-9]+;/gi, " ").replace(/\s+/g, " ").trim();
+}
 function normalizeMentor(m, crawledAt) {
-  const slug = m.slug || slugify(m.name || String(m.id ?? ""));
+  const path = m.get_absolute_url || "";
+  const slug = path.match(/\/mentor\/([^/]+)/)?.[1] || slugify(m.get_full_name || String(m.objectID ?? ""));
   const socials = {};
   if (m.twitter)
     socials.twitter = m.twitter.startsWith("http") ? m.twitter : `https://x.com/${m.twitter}`;
   if (m.linkedin)
     socials.linkedin = m.linkedin;
+  const price = m.all_prices?.length ? Math.min(...m.all_prices) : Math.round(m.avg_price_per_call ?? 0);
   return makeExpert({
     source: "mentorcruise",
-    sourceId: String(m.id ?? slug),
+    sourceId: String(m.objectID ?? slug),
     slug,
-    url: `https://mentorcruise.com/mentor/${slug}/`,
-    fullName: m.name ?? [m.first_name, m.last_name].filter(Boolean).join(" "),
-    firstName: m.first_name ?? "",
-    lastName: m.last_name ?? "",
-    title: m.job_title ?? "",
-    bio: m.bio ?? "",
-    avatar: m.avatar ?? m.photo ?? "",
-    price: m.price ?? 0,
-    priceCurrency: m.currency ?? "USD",
-    priceUnit: m.price ? "per month" : "",
-    rating: m.rating ?? 0,
-    ratingCount: m.reviews_count ?? 0,
-    verified: Boolean(m.verified),
+    url: path ? `https://mentorcruise.com${path}` : `https://mentorcruise.com/mentor/${slug}/`,
+    fullName: m.get_full_name ?? "",
+    title: (m.cleaned_job_title ?? []).join(", "),
+    bio: stripHtml(m.bio_formatted ?? ""),
+    avatar: m.get_profile_picture ?? "",
+    price,
+    priceCurrency: "USD",
+    priceUnit: price ? "per month" : "",
+    rating: m.avg_rating_float_one_decimal ?? 0,
+    ratingCount: m.number_of_reviews ?? 0,
     featured: Boolean(m.is_top_mentor),
-    topics: m.categories ?? [],
-    tags: m.skills ?? [],
+    topics: m.get_industries ?? [],
+    tags: m.get_skills ?? [],
     socials,
+    extra: { company: m.company ?? "", location: m.get_location_display ?? "", avgPricePerCall: m.avg_price_per_call ?? 0 },
     crawledAt
   });
 }
@@ -1438,44 +1568,61 @@ class MentorCruiseSource {
   description = "MentorCruise \u2014 long-term mentorship from vetted mentors";
   website = "https://mentorcruise.com";
   fetchFn;
-  apiBase;
+  appId;
+  apiKey;
+  index;
   pageSize;
   constructor(opts = {}) {
     this.fetchFn = opts.fetchFn ?? fetch;
-    this.apiBase = opts.apiBase ?? process.env.MENTORCRUISE_API_BASE ?? "https://mentorcruise.com/api";
-    this.pageSize = opts.pageSize ?? 50;
+    this.appId = opts.appId ?? process.env.MENTORCRUISE_ALGOLIA_APP_ID ?? "YD3XA4V91L";
+    this.apiKey = opts.apiKey ?? process.env.MENTORCRUISE_ALGOLIA_API_KEY ?? "454b55a2e50bc884225318d99b0dad1a";
+    this.index = opts.index ?? process.env.MENTORCRUISE_ALGOLIA_INDEX ?? "MentorProfile_prod";
+    this.pageSize = opts.pageSize ?? 200;
   }
   async crawl(opts = {}) {
     const log = opts.onLog ?? (() => {});
     const crawledAt = new Date().toISOString();
+    const url = `https://${this.appId}-dsn.algolia.net/1/indexes/${this.index}/query`;
     const experts = [];
     const tags = new Set;
-    let offset = 0;
-    for (;; ) {
-      const data = await fetchJson(`${this.apiBase}/mentors/?limit=${this.pageSize}&offset=${offset}`, this.fetchFn);
-      const items = data?.results ?? data?.data ?? (Array.isArray(data) ? data : []);
-      if (!items.length)
+    let page = 0;
+    let pages = 1;
+    while (page < pages) {
+      let data;
+      try {
+        const res = await this.fetchFn(url, {
+          method: "POST",
+          headers: {
+            "X-Algolia-Application-Id": this.appId,
+            "X-Algolia-API-Key": this.apiKey,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({ params: `hitsPerPage=${this.pageSize}&page=${page}` })
+        });
+        if (!res.ok)
+          break;
+        data = await res.json();
+      } catch {
         break;
-      for (const m of items) {
-        const e = normalizeMentor(m, crawledAt);
+      }
+      pages = data.nbPages ?? 1;
+      for (const hit of data.hits ?? []) {
+        const e = normalizeMentor(hit, crawledAt);
         experts.push(e);
         for (const t of e.tags)
           tags.add(t);
       }
-      offset += items.length;
-      log(`  mentorcruise: ${experts.length}`);
+      log(`  mentorcruise: ${experts.length}/${data.nbHits ?? "?"}`);
+      page++;
       if (opts.max && experts.length >= opts.max)
         break;
-      if (items.length < this.pageSize)
-        break;
     }
     if (experts.length === 0) {
-      log("mentorcruise: no public listing reachable (set MENTORCRUISE_API_BASE or provide a fetchFn).");
+      log("mentorcruise: Algolia returned nothing (set MENTORCRUISE_ALGOLIA_* or inject fetchFn).");
     }
-    const topics = [];
     return {
       experts: opts.max ? experts.slice(0, opts.max) : experts,
-      topics,
+      topics: [],
       tags: [...tags].map((name) => ({ name, topic: "" })),
       total: experts.length
     };
@@ -1696,6 +1843,9 @@ async function crawlSource(db, sourceName, opts = {}) {
     throw new Error(`Unknown source "${sourceName}". Run \`experts sources\` to list options.`);
   }
   const data = await source.crawl(opts);
+  if (data.experts.length === 0 && db.count(source.name) > 0) {
+    opts.onLog?.(`\u26A0 ${source.name} returned 0 experts but ${db.count(source.name)} are stored \u2014 possible API drift; not overwriting.`);
+  }
   const changes = db.recordChanges(source.name, data.experts);
   db.upsertExperts(data.experts);
   if (data.topics.length)
@@ -2496,10 +2646,68 @@ function normalizePhone(v) {
     return "+" + cleaned.slice(1).replace(/\D/g, "");
   return cleaned;
 }
+function looksFakePhone(v) {
+  const d = normalizePhone(v).replace(/\D/g, "");
+  if (/^(\d)\1+$/.test(d))
+    return true;
+  if (d === "1234567890" || d === "0123456789")
+    return true;
+  if (/^(\d{2,3})\1\1+$/.test(d))
+    return true;
+  return false;
+}
 function validatePhone(v) {
   const n = normalizePhone(v);
   const digits = n.replace(/\D/g, "");
-  return digits.length >= 7 && digits.length <= 15 ? "valid" : "invalid";
+  if (digits.length < 7 || digits.length > 15)
+    return "invalid";
+  if (looksFakePhone(v))
+    return "invalid";
+  return "valid";
+}
+function interpretRcptCode(code) {
+  if (code === 250 || code === 251)
+    return "valid";
+  if (code === 550 || code === 551 || code === 553 || code === 554)
+    return "invalid";
+  return "unknown";
+}
+async function smtpProbe(email, mxHost) {
+  const net = await import("net");
+  return new Promise((resolve) => {
+    let step = 0;
+    let settled = false;
+    const done = (r) => {
+      if (settled)
+        return;
+      settled = true;
+      try {
+        sock.end();
+      } catch {}
+      resolve(r);
+    };
+    const sock = net.createConnection({ host: mxHost, port: 25, timeout: 7000 });
+    sock.on("timeout", () => done("unknown"));
+    sock.on("error", () => done("unknown"));
+    sock.on("data", (buf) => {
+      const code = parseInt(buf.toString().slice(0, 3), 10);
+      if (step === 0) {
+        sock.write(`HELO open-experts.local\r
+`);
+        step = 1;
+      } else if (step === 1) {
+        sock.write(`MAIL FROM:<probe@open-experts.local>\r
+`);
+        step = 2;
+      } else if (step === 2) {
+        sock.write(`RCPT TO:<${email}>\r
+`);
+        step = 3;
+      } else if (step === 3) {
+        done(interpretRcptCode(code));
+      }
+    });
+  });
 }
 async function validateEmail(email, resolver = resolveMx) {
   const e = normalizeEmail(email);
@@ -2669,12 +2877,25 @@ async function verifyContacts(db, opts = {}) {
   const delayMs = opts.delayMs ?? 50;
   const targets = db.contactsToVerify({ source: opts.source, limit: opts.max });
   const res = { checked: 0, valid: 0, invalid: 0, unknown: 0 };
+  const resolver = opts.resolver;
+  const prober = opts.prober ?? smtpProbe;
   for (const c of targets) {
     let status;
-    if (c.type === "email")
-      status = await validateEmail(c.value, opts.resolver);
-    else
+    if (c.type === "email") {
+      status = await validateEmail(c.value, resolver);
+      if (opts.smtp && status === "valid") {
+        try {
+          const mx = await (resolver ?? (await import("dns/promises")).resolveMx)(c.value.split("@")[1]);
+          if (mx[0]?.exchange) {
+            const probed = await prober(c.value, mx[0].exchange);
+            if (probed !== "unknown")
+              status = probed;
+          }
+        } catch {}
+      }
+    } else {
       status = validatePhone(c.value);
+    }
     db.setContactStatus(c.source, c.sourceId, c.type, c.value, status);
     res.checked++;
     res[status]++;
@@ -2751,7 +2972,7 @@ async function syncContacts(db, idsOrSlugs, opts = {}) {
 }
 
 // src/cli/index.ts
-var VERSION = "0.0.7";
+var VERSION = "0.0.8";
 function openDb() {
   const opts = program.opts();
   return new ExpertsDB(opts.db || defaultDbPath());
@@ -2768,6 +2989,15 @@ function requireData(db) {
 }
 var program = new Command;
 program.name("experts").description("Crawl and query expert marketplaces (intro.co and more).").version(VERSION, "-v, --version").option("--db <path>", "database file", undefined).option("--json", "output JSON where applicable", false);
+program.addHelpText("after", `
+Command groups:
+  Query      who \xB7 ask \xB7 brief \xB7 find \xB7 search \xB7 related \xB7 show \xB7 list
+  Ingest     crawl \xB7 enrich \xB7 enrich-youtube \xB7 enrich-linkedin \xB7 enrich-sites \xB7 avatars
+  Contacts   find-contacts \xB7 verify-contacts \xB7 contacts \xB7 sync-contacts
+  Insight    topics \xB7 tags \xB7 stats \xB7 graph \xB7 persons \xB7 changes \xB7 stale
+  Admin      embed \xB7 reindex \xB7 export \xB7 sources
+
+Start with:  experts who "someone who can help me scale a B2B AI product"`);
 program.command("crawl [source]").description("Fetch experts from a source into the local store").option("--max <n>", "limit number of experts (quick runs)", (v) => parseInt(v, 10)).option("--no-topics", "skip topic-membership resolution (fewer requests)").option("--delay <ms>", "min delay between requests", (v) => parseInt(v, 10), 500).action(async (source, cmdOpts) => {
   const db = openDb();
   const name = source || "intro";
@@ -2944,12 +3174,13 @@ program.command("find-contacts [source]").description("Discover email + phone fo
   console.log(chalk2.dim("Next: `experts verify-contacts` to set working/not status."));
   db.close();
 });
-program.command("verify-contacts [source]").description("Validate discovered contacts and set working/not status").option("--max <n>", "limit contacts checked", (v) => parseInt(v, 10)).action(async (source, cmdOpts) => {
+program.command("verify-contacts [source]").description("Validate discovered contacts and set working/not status").option("--max <n>", "limit contacts checked", (v) => parseInt(v, 10)).option("--smtp", "also SMTP-probe MX-valid emails (needs outbound port 25)").action(async (source, cmdOpts) => {
   const db = openDb();
   requireData(db);
   const res = await verifyContacts(db, {
     source,
     max: cmdOpts.max,
+    smtp: cmdOpts.smtp,
     onLog: (m) => process.stderr.write(chalk2.dim(m + `
 `))
   });
@@ -3066,14 +3297,15 @@ ${rows.length} experts`));
   }
   db.close();
 });
-program.command("embed [source]").description("Build the semantic search index (embeddings) for stored experts").action(async (source) => {
+program.command("embed [source]").description("Build the semantic search index (incremental \u2014 only new/changed experts)").option("--force", "re-embed every expert even if unchanged").action(async (source, cmdOpts) => {
   const db = openDb();
   requireData(db);
-  const embedder = getEmbedder();
+  const embedder = await getEmbedder();
   console.error(chalk2.dim(`Embedding with ${embedder.id}\u2026`));
   const n = await db.buildEmbeddings(embedder, {
     source,
-    onLog: (m) => process.stderr.write(chalk2.dim(`\r${m}`.padEnd(40)))
+    force: cmdOpts.force,
+    onLog: (m) => process.stderr.write(chalk2.dim(`\r${m}`.padEnd(50)))
   });
   process.stderr.write(`
 `);
@@ -3087,18 +3319,62 @@ program.command("ask <query...>").description("Natural-language semantic search:
     console.error(chalk2.yellow("No semantic index yet. Run ") + chalk2.bold("experts embed") + chalk2.yellow(" first."));
     process.exit(1);
   }
-  const embedder = getEmbedder();
+  const embedder = await getEmbedder();
+  const storedBy = db.getMeta("embedder");
+  if (storedBy && storedBy !== embedder.id) {
+    console.error(chalk2.yellow(`\u26A0 index built with "${storedBy}" but active embedder is "${embedder.id}" \u2014 run \`experts embed\` to re-index.`));
+  }
   const [qv] = await embedder.embed([query.join(" ")]);
-  const results = db.semanticSearch(qv, { source: cmdOpts.source, limit: cmdOpts.limit });
+  const q = query.join(" ");
+  const results = db.semanticSearch(qv, { source: cmdOpts.source, limit: cmdOpts.limit }).map((r) => ({
+    ...r,
+    why: explainMatch(q, r.expert)
+  }));
   if (program.opts().json) {
     console.log(JSON.stringify(results, null, 2));
   } else {
     const multi = new Set(results.map((r) => r.expert.source)).size > 1;
-    for (const { expert, score } of results) {
+    for (const { expert, score, why } of results) {
       console.log(chalk2.dim(score.toFixed(3)) + "  " + formatRow(expert, { showSource: multi }));
+      if (why.length)
+        console.log(`        ${chalk2.dim("why: " + why.join(", "))}`);
     }
     console.log(chalk2.dim(`
-${results.length} matches for "${query.join(" ")}"`));
+${results.length} matches for "${q}"`));
+  }
+  db.close();
+});
+program.command("who <query...>").description("Smart search \u2014 the one command: semantic + authority + person-dedup + why").option("-s, --source <name>", "filter by source").option("-n, --limit <n>", "results", (v) => parseInt(v, 10), 10).action(async (query, cmdOpts) => {
+  const db = openDb();
+  requireData(db);
+  if (db.vectorCount() === 0) {
+    console.error(chalk2.yellow("No semantic index. Run ") + chalk2.bold("experts embed") + chalk2.yellow(" first."));
+    process.exit(1);
+  }
+  const q = query.join(" ");
+  const [qv] = await (await getEmbedder()).embed([q]);
+  const raw = db.semanticSearch(qv, { source: cmdOpts.source, limit: (cmdOpts.limit + 5) * 4 });
+  const seen = new Set;
+  const out = [];
+  for (const r of raw) {
+    const pid = db.personIdOf(r.expert.source, r.expert.sourceId);
+    if (seen.has(pid))
+      continue;
+    seen.add(pid);
+    out.push({ expert: r.expert, score: r.score, why: explainMatch(q, r.expert) });
+    if (out.length >= cmdOpts.limit)
+      break;
+  }
+  if (program.opts().json) {
+    console.log(JSON.stringify(out, null, 2));
+  } else {
+    const multi = new Set(out.map((r) => r.expert.source)).size > 1;
+    out.forEach((r, i) => {
+      console.log(`${chalk2.cyan(`${i + 1}.`)} ${formatRow(r.expert, { showSource: multi })}`);
+      console.log(`     ${chalk2.dim((r.why.length ? "why: " + r.why.join(", ") : "semantic match") + `  (${r.score.toFixed(3)})`)}`);
+    });
+    console.log(chalk2.dim(`
+${out.length} experts for "${q}"`));
   }
   db.close();
 });
@@ -3110,7 +3386,7 @@ program.command("brief <text...>").description("Paste a brief \u2192 ranked, de-
     process.exit(1);
   }
   const brief = text.join(" ");
-  const [qv] = await getEmbedder().embed([brief]);
+  const [qv] = await (await getEmbedder()).embed([brief]);
   const raw = db.semanticSearch(qv, { source: cmdOpts.source, limit: (cmdOpts.limit + 5) * 4 });
   const seen = new Set;
   const shortlist = [];
@@ -3123,11 +3399,7 @@ program.command("brief <text...>").description("Paste a brief \u2192 ranked, de-
     if (shortlist.length >= cmdOpts.limit)
       break;
   }
-  const briefLc = brief.toLowerCase();
-  const annotated = shortlist.map((r) => ({
-    ...r,
-    why: r.expert.tags.filter((t) => briefLc.includes(t.toLowerCase())).slice(0, 4)
-  }));
+  const annotated = shortlist.map((r) => ({ ...r, why: explainMatch(brief, r.expert) }));
   if (program.opts().json) {
     console.log(JSON.stringify(annotated, null, 2));
   } else {