From dec535d2b16766bd187a98ec17fe0cb221562420 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Tue, 28 Jul 2026 17:23:22 +0000
Subject: [PATCH] feat(leads): alert on intent, and match on what you sell
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds prd/0001, a read of Leadmatically against what we shipped this week.
Their scoring is comparable to ours and in two respects ours is stricter —
we refuse people who wrote "no vendors", and we refuse drafts that state
anything the campaign never claimed. They beat us on everything that
happens after a signal is found, which is where the value of finding it
goes. This implements the two P0s.

We were finding requests and telling nobody. A conversation worth
answering has a useful life measured in hours, and a signal that sits in a
table until somebody opens the Leads page is indistinguishable from one
that was never found. Alerts are batched per campaign per sweep, because
eleven emails for eleven conversations is the fastest way to make the
feature something people filter to a folder. The count and best score go
in the subject so it is triageable from a phone. Dedupe is a column on the
row rather than a time window, and the row is marked only after the send
succeeds — the other order loses a batch to one SMTP hiccup.

And we matched on keywords alone, which drops the requests most worth
having. "Our checkout keeps timing out whenever we run a promo" is exactly
the buyer a load-testing campaign wants and contains none of its
keywords, because people with a problem describe the problem rather than
the product category that solves it. A campaign can now say what it sells
in prose, and a keyword miss becomes a question rather than a verdict.

That path is deliberately narrow. It only judges signals the cheap path
already scored above the bar, it is capped per sweep so an index that
returns three hundred results cannot become three hundred model calls, it
cannot overturn a stated no or rescue somebody advertising their own
services, and it has to quote the words that decided it — a keyword match
is wrong in obvious ways, a model judging relevance is wrong in ways
nobody sees unless it says why.

Two things in their product are deliberately not copied. Facebook and
Instagram monitoring, because neither carries meaningful public buying
intent and neither is readable without access we do not have, so listing
them would be coverage we cannot deliver. And per-keyword subscription
tiers, because bolting a second quota beside credits would make the cost
of a run unpredictable, which is the one thing this week's billing work
was for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .env.bak-2026-07-28                           | 102 +++++++++++++
 app/(app)/projects/[id]/leads/page.tsx        |   2 +-
 app/actions/leads.ts                          |   3 +
 components/leads/campaign-panel.tsx           |  22 +++
 lib/email.ts                                  |  69 +++++++++
 lib/outreach/intent.ts                        |  26 +++-
 lib/outreach/intentRelevance.ts               | 117 +++++++++++++++
 lib/outreach/intentSources.ts                 |  48 +++++-
 lib/outreach/runner.ts                        |  85 ++++++++++-
 prd/0001-intent-lead-monitoring.md            | 141 ++++++++++++++++++
 ...29080000_intent_description_and_alerts.sql |  36 +++++
 tests/intent-description.test.ts              | 123 +++++++++++++++
 12 files changed, 769 insertions(+), 5 deletions(-)
 create mode 100644 .env.bak-2026-07-28
 create mode 100644 lib/outreach/intentRelevance.ts
 create mode 100644 prd/0001-intent-lead-monitoring.md
 create mode 100644 supabase/migrations/20260729080000_intent_description_and_alerts.sql
 create mode 100644 tests/intent-description.test.ts

diff --git a/.env.bak-2026-07-28 b/.env.bak-2026-07-28
new file mode 100644
index 00000000..4d13e940
--- /dev/null
+++ b/.env.bak-2026-07-28
@@ -0,0 +1,102 @@
+# CrawlProof — local environment
+# This file is gitignored. Do not commit.
+
+# ---------- Site ----------
+NEXT_PUBLIC_SITE_URL=https://crawlproof.com
+
+# ---------- Supabase ----------
+# Project ref: ywcizjsgrcmhgyplldac
+# Get keys from: https://supabase.com/dashboard/project/ywcizjsgrcmhgyplldac/settings/api
+NEXT_PUBLIC_SUPABASE_URL=https://ywcizjsgrcmhgyplldac.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_a8SgqPVlemtSVPE1sJb5CQ_oFXlIBPd
+SUPABASE_SERVICE_ROLE_KEY=sb_secret_o5miaAgk7KqxA-PW-s7dRw_rg5N2X1A
+
+# DB password — only needed for direct psql / `supabase db push`.
+SUPABASE_DB_PASSWORD=XXyZIOyha0KSe2zM
+
+# ---------- CoinPay (crypto credit purchases) ----------
+# Merchant + API key supplied by CoinPay dashboard.
+COINPAY_MERCHANT_ID=218c9732-50c0-4542-ad16-1a83f55538c4
+COINPAY_API_KEY=cp_live_36db63b9e87fed4a4baca7f673f4af1c
+# CoinPay HTTP API base; adjust if your CoinPay instance is hosted elsewhere.
+COINPAY_API_URL=https://coinpayportal.com
+# Used to verify webhook signatures (HMAC-SHA256 over raw body).
+COINPAY_WEBHOOK_SECRET=whsecret_43ef7164649e7b3bedf516a1268cce4b9655456740877ca9cad5dba91b727fd0
+
+# ---------- Resend (transactional email) ----------
+RESEND_API_KEY=re_Si92GTEM_33xCWHbnsQ3DhmQgum3XrJam
+RESEND_FROM=CrawlProof <reports@crawlproof.com>
+
+# ---------- Worker ----------
+# In the single-container Railway deploy the worker is on localhost.
+# WORKER_PORT must match the loopback port in WORKER_URL — start.sh used
+# to default to 8080 while WORKER_URL pointed at 9080, which silently
+# broke every worker-bound enqueue (autoblog delivery, audit kick-off).
+WORKER_URL=http://127.0.0.1:9080
+WORKER_PORT=9080
+WORKER_SHARED_SECRET=MqHuZTa9xBhvScyykIjdZZRVGonzA4nhh2V8Ly8nrj0
+
+# ---------- Cron ----------
+CRON_SECRET=jIlEofmw0FBKuUVQewjLugcFn9vcted7tWzeT9G7jFg
+
+# ---------- Anthropic — paid scans run Claude Opus 4.7 ----------
+ANTHROPIC_API_KEY=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
+
+# ---------- Next.js server action closure encryption ----------
+# Stable key so encrypted action closures from one deploy can still be
+# decrypted on the next. Used at build AND runtime — keep it the same.
+NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=IWa/cBI4x6urAes/ZzNTXO38m6VAPRkO+KfRm7jNAv4=
+
+# ---------- Paid engines ----------
+BACKEND_AI_PROVIDER=openai
+BACKEND_AI_OPENAI_MODEL=gpt-5.5
+OPENAI_API_KEY=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
+GEMINI_API_KEY=AIzaSyC5pQVScjttZONatDsAccZTVqcaAFhv9WA
+# Qwen via Alibaba Cloud Model Studio (DashScope).
+DASHSCOPE_API_KEY=sk-2ea2783374594749ac12b561c193d3c7
+# Kimi via Moonshot AI.
+MOONSHOT_API_KEY=sk-1An97Cdeqoluw7avoOa799Q8sIbED6AosRemT7lVUx3GTYgv
+# DeepSeek.
+DEEPSEEK_API_KEY=sk-d40dbce41e2646afb7ee855656f5b06a
+# Z.AI (Zhipu) GLM — OpenAI-compatible. Key format: <id>.<secret>.
+ZAI_API_KEY=e37359a7992b4fa3af4246175b8d2f5f.ml6rLO8RsjVBtHDK
+# Perplexity — Sonar API, OpenAI-compatible.
+PERPLEXITY_API_KEY=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
+# HuggingFace.
+HUGGINGFACE_API_KEY=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
+# DataForSEO — keyword research for Autoblog. Basic auth.
+DATAFORSEO_LOGIN=anthony@profullstack.com
+DATAFORSEO_PASSWORD=116960f7c7a9c393
+
+# ---------- Observability ----------
+SENTRY_DSN=
+SOCIAL_VAULT_KEY=SwbGDG/K/n0IhVnhieE6Ga95sJidRF2GHis93I12Rz0=
+
+# ---------- Social posting — Meta (Facebook / Instagram) ----------
+META_APP_ID=994377213462196
+META_APP_SECRET=411f562235f73f1201e4b51a19592aaa
+
+# ---------- Social posting — Threads ----------
+THREADS_APP_ID=1647193763244473
+THREADS_APP_SECRET=0604eb698c2cf1caf95af644a7dfa37f
+# Kimi (kimi.com endpoint — alt to MOONSHOT_API_KEY which targets api.moonshot.ai)
+KIMI_API_KEY=sk-kimi-zExTu48ugqwJs6JKciFDZUyRsxDhyBCJi3yLQ0IhimtKIwfJltsaRzvaXtxykmdK
+
+# GitHub App — registered on the profullstack org via the App Manifest flow.
+# Don't commit. Re-run /admin/github/setup if these need to be rotated.
+GITHUB_APP_ID=3811357
+GITHUB_APP_SLUG=crawlproof
+GITHUB_APP_CLIENT_ID=Iv23liLyqvYTbh1PMMn8
+GITHUB_APP_CLIENT_SECRET=1644e6db895845636c9a1bb8451ac83ebed4ef52
+GITHUB_APP_WEBHOOK_SECRET=fc97dd7ec199c47d909da7c8d9cf80b7b9643a30
+GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAmaZTM8mshRtWYkvWhmZnLbkf4Z1fafwAwqXj0gBlWSeBv3o5\nBSTM3HLy0bWWAMVO1xdDQoOsmuX3ZCSozY+BgoWOYucCUcSnt7B6zKDKglPZ27jW\neBLshtqhy9l7w5qg2l0OPXdASDHrkBY8e7wXsEZz8tdgqfGB/58iHQJ3nAMw/BgO\nRIwNM+YyGDk8psWYOy44J1oDTslM+ysECXTKlap76GyEiT8vMARsZJsSf3fA1DPc\nkd1SP4zKMdNysC+60YxWrNPGTGoOrSZs6PaZb5Qch/GuN4JKKPzexOoZktFl6tRi\nnLAHKJkL4DKITZTmsXTB7eNwAjrDp5TkOj/M7QIDAQABAoIBAHHCxvmiCTzoN7ZB\npk0ORriAx40ZIsrqzXlQr/QNXPx8lsE5cjxPuepCpWwFgVGCxNPWInN94G8zc07P\nIbhI1z/XOMwbdAksjG0hmloldqq2AKiBGzH9+OgDuiWfGdaChzQGEAQMZijN5TZi\ncFfAtN1L3I9hTe2lpXWo0e4epIZ6ZKnf9eeSsoEGUnhKQr83plH1dI02fmJX+Gtd\nPvspUbyV09jZ3iLR2V9bY7azdxU+6wXoSk5GkfCojdZJlxoqy+8eanMlDT/i0kzx\nEKmLRAeVdp5PfCYQhYSw7O1825+NZV+rw1RnMlVAswecGPd+dR78uYVD0OXaNKtl\n3/zxdpUCgYEAyrBHQjLYN8oaHfl6h/albIeERzaVNP7j+xzciACuKnBDXskxzAO6\n/W/ARpd31noHsZfUNUM7uKiYNdwwZ7ynTmkC1G3q8TlzZ5nUrOXFTuR0YHUKz/yQ\nlOChUSs7ZQGwcA6XFbVqlp94/HAFSLxbfhtUeXv3XK7lcDlVGWQlU1cCgYEAwhAW\n95OFqLUK0P4D1yBPKOxq1YS1Zw3VwzfdqfgMw2OnopY6RxZRQUg0eQWmzgFoL8B2\nok7VF1KOgp/UMiAxiPTXWdXGZ8Ob7EJIc2jCHum4/IeysVsz08f9FfaHKDCztAcl\nr4ovyfV6/kuamQgxQQ1ZvVTca9MI4Eg2dRK3G1sCgYEAjJbtNnuyAjCLIRN07G4m\nnDr7g7HWmOXcGMgSJ7vhEsq/0DVZ9xr3Tud+xPg3RWtrfsHDjhZOjG1U9rb+VFZE\n7lxkfBiqCBxDci7/l9XgoDJSjr1gfJfBaaLOAlEsZ4learuUDJjDkCqZbu/8mlEc\nXUJzu7hDAeTGfKsn3e7a/Q0CgYBKgTTgHjIdgExDypIc4Jmjo4isqwOeKhCcn3Ep\n1ULJLRRp9nUvX6EYiCklIYdV5fJjCuhBDjT/fEGcYtJr4DJEW4PmSI2gvte5EAWS\n0XBdv+u2gD6ZmuM99rTy3rArPO9xOaE9ULdiOS3cPZiAEkYerIp8hv0NJHtu6CqI\nLgRAqwKBgQDFhX5Q0IMGNQbJWT5xwWXfGYvXssZE2LsjUSIjiqDVXU3FkgX6OFWO\nibyh5GwNmZn+LBwHOJ3Cf5WRjllyfJwb78yEU6da33+cyHR5+8KeJ6xVpOMjWU9e\na3tvwJOb8bE5PNwQ5Dg3QoyRUid+LjtId6rO+it3fKx/xhjE0xLUoQ==\n-----END RSA PRIVATE KEY-----\n"
+
+# Peppers sha256 hashes of API tokens (sp_api_token + project_api_keys)
+SP_TOKEN_PEPPER=RqYRUvLiBrqilHqIOOVJHtWl2T2ffK0LLd+VImjzGwY=
+
+# Audience Hub ingest key for this project ("prod" key, revealable in dashboard)
+CRAWLPROOF_PROJECT_KEY=cpk_EhiJth_9UcD_T-X1KqzVkLJEtFc0K_wV-lZ-owHZCZ8
+
+# CrawlProof Alerts — ValueSERP (Google SERP polling)
+VALUESERP_API_KEY=5F0086E0C4D74B4A9113A89A945BA376
+ALERTS_FROM=CrawlProof Alerts <alerts@crawlproof.com>
diff --git a/app/(app)/projects/[id]/leads/page.tsx b/app/(app)/projects/[id]/leads/page.tsx
index 26130eec..bef4d02d 100644
--- a/app/(app)/projects/[id]/leads/page.tsx
+++ b/app/(app)/projects/[id]/leads/page.tsx
@@ -92,7 +92,7 @@ export default async function LeadsPage({
     supabase
       .from("outreach_campaigns")
       .select(
-        "id, name, active, auto_send, daily_send_limit, max_score, queries, seed_urls, last_run_at, last_run_note, auth_required_hosts, pitch_mode, pitch_intro, pitch_ask, pitch_facts, scan_prospects, min_intent, angle, sender_name, reply_to",
+        "id, name, active, auto_send, daily_send_limit, max_score, queries, seed_urls, last_run_at, last_run_note, auth_required_hosts, pitch_mode, pitch_intro, pitch_ask, pitch_facts, scan_prospects, min_intent, sells_description, angle, sender_name, reply_to",
       )
       .eq("project_id", projectId)
       .order("updated_at", { ascending: false })
diff --git a/app/actions/leads.ts b/app/actions/leads.ts
index 9ab0aa0e..c49953cc 100644
--- a/app/actions/leads.ts
+++ b/app/actions/leads.ts
@@ -511,6 +511,8 @@ export async function saveCampaignAction(input: {
    * campaign did before intent existed.
    */
   minIntent?: number | null;
+  /** Plain prose: what this campaign sells. Enables description matching. */
+  sellsDescription?: string;
 }): Promise<Ok<{ note: string }> | Err> {
   const auth = await requireLeadAccess(input.projectId);
   if (!auth.ok) return auth;
@@ -584,6 +586,7 @@ export async function saveCampaignAction(input: {
           input.minIntent === null || input.minIntent === undefined
             ? null
             : Math.max(0, Math.min(100, Math.round(input.minIntent))),
+        sells_description: input.sellsDescription?.trim() || null,
         angle: input.angle?.trim() || null,
         sender_name: input.senderName?.trim() || null,
         reply_to: input.replyTo?.trim() || null,
diff --git a/components/leads/campaign-panel.tsx b/components/leads/campaign-panel.tsx
index e7d089d3..bcaff3dd 100644
--- a/components/leads/campaign-panel.tsx
+++ b/components/leads/campaign-panel.tsx
@@ -37,6 +37,7 @@ export type CampaignSummary = {
   pitch_facts: string[];
   scan_prospects: boolean;
   min_intent: number | null;
+  sells_description: string | null;
   auth_required_hosts: string[];
   runs: CampaignRun[];
 };
@@ -89,6 +90,7 @@ export function CampaignPanel({
   // the failure mode the whole feature exists to avoid, so it should be what
   // you turn off deliberately rather than what you remember to turn on.
   const [minIntent, setMinIntent] = useState<number | null>(DEFAULT_MIN_INTENT);
+  const [sellsDescription, setSellsDescription] = useState("");
   const [goal, setGoal] = useState("");
   const [generating, setGenerating] = useState(false);
   const [pitchNote, setPitchNote] = useState<string | null>(null);
@@ -166,6 +168,7 @@ export function CampaignPanel({
     setPitchFacts((c.pitch_facts ?? []).join("\n"));
     setScanProspects(c.scan_prospects);
     setMinIntent(c.min_intent ?? null);
+    setSellsDescription(c.sells_description ?? "");
     // Every field the form submits has to be loaded, not just the ones that
     // changed recently: save() sends the whole form, so anything left blank
     // here is written back as blank and silently wipes the column.
@@ -199,6 +202,7 @@ export function CampaignPanel({
         pitchFacts,
         scanProspects,
         minIntent,
+        sellsDescription,
       });
       if (result.ok) setEditing(null);
       return result;
@@ -517,6 +521,24 @@ export function CampaignPanel({
             </span>
           </label>
 
+          {minIntent !== null && (
+            <label className="text-sm sm:col-span-2">
+              What you sell, in a sentence or two
+              <textarea
+                className="input mt-1 w-full"
+                rows={2}
+                value={sellsDescription}
+                onChange={(e) => setSellsDescription(e.target.value)}
+                placeholder="Load testing for teams whose checkout falls over under traffic spikes."
+              />
+              <span className="mt-0.5 block text-xs text-[var(--color-muted)]">
+                Optional, and the single highest-value field here. People with a problem describe
+                the problem, not the product category — so the best requests contain none of your
+                keywords. With this, they get found anyway.
+              </span>
+            </label>
+          )}
+
           {minIntent !== null && (
             <label className="text-sm sm:col-span-2">
               Minimum intent score: <span className="font-mono">{minIntent}</span>
diff --git a/lib/email.ts b/lib/email.ts
index 0284bb1d..eb13b99c 100644
--- a/lib/email.ts
+++ b/lib/email.ts
@@ -1057,6 +1057,75 @@ export async function sendAiSpendAlertEmail(input: {
   return { sent: true };
 }
 
+/**
+ * Somebody publicly asked for what you sell.
+ *
+ * Batched per campaign per sweep, never per signal: a sweep that finds eleven
+ * conversations has to produce one email. Eleven would be the fastest way to
+ * make the feature something people filter to a folder, and a filtered alert
+ * is the same as no alert.
+ *
+ * The count and the best score go in the subject so it can be triaged from a
+ * phone notification without opening anything — the whole point is answering
+ * before somebody else does, and a lead worth having has a useful life
+ * measured in hours.
+ */
+export async function sendIntentAlertEmail(input: {
+  to: string;
+  campaign: string;
+  projectUrl: string;
+  signals: Array<{
+    title: string;
+    url: string;
+    source: string;
+    score: number;
+    tier: string;
+    reasons: string[];
+    postedAt: string | null;
+  }>;
+}): Promise<{ sent: boolean; error?: string }> {
+  const c = client();
+  if (!c) return { sent: false, error: "RESEND_API_KEY not set" };
+  if (!input.signals.length) return { sent: false, error: "nothing to send" };
+
+  const best = Math.max(...input.signals.map((s) => s.score));
+  const n = input.signals.length;
+
+  const items = input.signals
+    .map((s) => {
+      const when = s.postedAt
+        ? new Date(s.postedAt).toISOString().slice(0, 16).replace("T", " ")
+        : "undated";
+      return [
+        `<li style="margin:0 0 14px">`,
+        `<a href="${s.url}" style="font-weight:600">${escapeHtml(s.title || s.url)}</a><br>`,
+        `<span style="font-size:13px;color:#666">`,
+        `${s.score}/100 ${escapeHtml(s.tier)} · ${escapeHtml(s.source)} · ${when}`,
+        `</span><br>`,
+        `<span style="font-size:13px;color:#666">${escapeHtml(s.reasons.slice(0, 3).join(" · "))}</span>`,
+        `</li>`,
+      ].join("");
+    })
+    .join("");
+
+  const res = await c.send({
+    from: env.resendFrom,
+    to: input.to,
+    subject:
+      n === 1
+        ? `1 person asked for what you sell (${best}/100) — ${input.campaign}`
+        : `${n} people asked for what you sell (best ${best}/100) — ${input.campaign}`,
+    html: [
+      `<p>Found by the <strong>${escapeHtml(input.campaign)}</strong> campaign in the last sweep.</p>`,
+      `<ul style="padding-left:18px">${items}</ul>`,
+      `<p style="font-size:13px;color:#666">Reply where they asked, in public, as a reply — these are people on a platform, not addresses to email. Answering early is most of the advantage.</p>`,
+      `<p><a href="${input.projectUrl}">Open the queue</a></p>`,
+    ].join(""),
+  });
+  if (!res.sent) return { sent: false, error: res.error };
+  return { sent: true };
+}
+
 export async function sendColdOutreachEmail(input: {
   to: string;
   subject: string;
diff --git a/lib/outreach/intent.ts b/lib/outreach/intent.ts
index 11be7536..6aa3903b 100644
--- a/lib/outreach/intent.ts
+++ b/lib/outreach/intent.ts
@@ -230,6 +230,12 @@ export type IntentSignal = {
    * is the difference between a lead and a bystander with the same question.
    */
   decisionMaker: boolean;
+  /**
+   * Which path put this on topic. Null means the keyword path found nothing
+   * and a description judgement has not been made yet — never that the signal
+   * is off-topic, which is what `disqualified` is for.
+   */
+  matchPath: "keyword" | "description" | null;
 };
 
 /**
@@ -263,6 +269,12 @@ export function scoreIntent(input: {
   /** Campaign topic words. At least one must appear. */
   keywords?: string[];
   negativeKeywords?: string[];
+  /**
+   * Let a signal survive a keyword miss so a description judgement can decide.
+   * Off by default: without somewhere to send the survivors this would simply
+   * widen the funnel.
+   */
+  allowDescriptionMatch?: boolean;
   now?: Date;
 }): IntentSignal {
   const text = (input.text ?? "").slice(0, 8000);
@@ -278,6 +290,7 @@ export function scoreIntent(input: {
     disqualified: null,
     ageHours,
     decisionMaker: false,
+    matchPath: null,
   };
   if (!text.trim()) return { ...base, disqualified: "no text to read" };
 
@@ -295,10 +308,17 @@ export function scoreIntent(input: {
   const keywords = (input.keywords ?? []).filter((k) => k.trim());
   if (keywords.length) {
     const hits = keywords.filter((k) => text.toLowerCase().includes(k.toLowerCase()));
-    if (!hits.length) {
+    if (hits.length) {
+      base.matchPath = "keyword";
+      base.reasons.push(`mentions ${hits.slice(0, 3).join(", ")}`);
+    } else if (!input.allowDescriptionMatch) {
       return { ...base, disqualified: "on-topic for nobody — no campaign keyword appears" };
     }
-    base.reasons.push(`mentions ${hits.slice(0, 3).join(", ")}`);
+    // With a description to judge against, a keyword miss is not a verdict.
+    // The people worth reaching describe their problem, not the product
+    // category that solves it, so the best requests avoid the campaign's
+    // vocabulary by construction. matchPath stays null for the caller to
+    // resolve.
   }
 
   const matched = TIERS.filter((t) => t.patterns.some((p) => p.test(text)));
@@ -309,6 +329,7 @@ export function scoreIntent(input: {
       tier: "none",
       disqualified: null,
       reasons: [...base.reasons, "no expression of intent — nobody asked for anything"],
+      matchPath: base.matchPath,
     };
   }
 
@@ -346,6 +367,7 @@ export function scoreIntent(input: {
     disqualified: factor === 0 ? `older than ${Math.round(MAX_AGE_HOURS / 24)} days` : null,
     ageHours,
     decisionMaker: authority.bonus > 0,
+    matchPath: base.matchPath,
   };
 }
 
diff --git a/lib/outreach/intentRelevance.ts b/lib/outreach/intentRelevance.ts
new file mode 100644
index 00000000..e6f21e1a
--- /dev/null
+++ b/lib/outreach/intentRelevance.ts
@@ -0,0 +1,117 @@
+// Is this person asking for what you sell?
+//
+// Keyword matching answers a narrower question — does this text contain a word
+// you listed — and drops the requests most worth having. Somebody writing "our
+// pipeline keeps falling over under traffic" is exactly the buyer a load
+// testing campaign wants, and contains none of its keywords, because people
+// with a problem describe the problem rather than the product category that
+// solves it.
+//
+// So a second path: judge the text against a prose description of what the
+// campaign sells. Deliberately the *second* path, and deliberately narrow:
+//
+//   - It only ever runs on signals the cheap path already found interesting
+//     enough to score. Running a model over a raw result set would be
+//     unbounded spend for a judgement most results do not need.
+//   - It cannot rescue a disqualified signal. Someone who wrote "no vendors"
+//     is not a lead however relevant they are, and a relevance judgement is
+//     not entitled to overturn a stated no.
+//   - It must give a reason. A keyword match is legible and wrong in obvious
+//     ways; a model deciding relevance is wrong in ways nobody sees unless it
+//     says why, and an unauditable score is one nobody can correct.
+
+import { z } from "zod/v4";
+import { env } from "@/lib/env";
+import { generateStructuredOutput } from "@/lib/lx/backendAi";
+import { aiClients } from "./pipeline";
+
+const RelevanceSchema = z.object({
+  relevant: z
+    .boolean()
+    .describe("True only if this person is asking for something the business sells."),
+  confidence: z.number().describe("0-100. How sure you are."),
+  reason: z
+    .string()
+    .describe("One short sentence, quoting the words that decided it."),
+});
+
+export type RelevanceVerdict = {
+  relevant: boolean;
+  confidence: number;
+  reason: string;
+};
+
+const SYSTEM = `You decide whether a public post is somebody asking for a product or service that a specific business sells.
+
+You are given what the business sells, and one post. Answer one question: is the author of this post looking for something this business could provide?
+
+Say yes when the author describes a need this business addresses, even if they use none of the business's vocabulary. Somebody saying "our checkout keeps timing out on Black Friday" is asking for load testing whether or not they know the phrase.
+
+Say no when:
+- The author is describing a problem this business does not solve.
+- The author is selling, advertising, or offering their own services.
+- The author is discussing the topic without wanting anything — an opinion, a tutorial, a news link, a retrospective.
+- You are unsure. A false yes puts a stranger's inbox or a public thread in front of an irrelevant pitch; a false no costs one lead. They are not equally bad.
+
+confidence is how sure you are, not how strong their intent is — something else already scored that.
+
+reason must quote the words that decided it, so a human can tell whether you were right.`;
+
+/**
+ * Judge one post against what a campaign sells.
+ *
+ * Returns null when there is no description to judge against or no provider
+ * configured, which callers treat as "the keyword path is the only path" —
+ * never as a rejection. A missing model must not silently narrow the funnel.
+ */
+export async function judgeRelevance(input: {
+  text: string;
+  sells: string;
+}): Promise<RelevanceVerdict | null> {
+  const sells = input.sells?.trim();
+  const text = input.text?.trim();
+  if (!sells || !text) return null;
+
+  const { anthropic, openai } = aiClients();
+  if (!anthropic && !openai) return null;
+
+  try {
+    const res = await generateStructuredOutput({
+      name: "intent_relevance",
+      schema: RelevanceSchema,
+      system: SYSTEM,
+      user: [
+        "THE BUSINESS SELLS:",
+        sells.slice(0, 2000),
+        "",
+        "THE POST:",
+        text.slice(0, 4000),
+      ].join("\n"),
+      anthropic,
+      openai,
+      preference: env.backendAiProvider,
+      // The cheapest model that can do this: it is one yes/no per shortlisted
+      // signal, and the sweep runs every fifteen minutes.
+      anthropicModel: "claude-haiku-4-5-20251001",
+      openaiModel: env.backendAiOpenaiModel,
+      maxTokens: 300,
+      anthropicEffort: false,
+    });
+    return {
+      relevant: Boolean(res.output.relevant),
+      confidence: Math.max(0, Math.min(100, Math.round(res.output.confidence))),
+      reason: res.output.reason.trim().slice(0, 300),
+    };
+  } catch {
+    // A failed judgement is not a rejection. The keyword path still stands.
+    return null;
+  }
+}
+
+/** Below this the model is guessing, and a guess is not a reason to contact someone. */
+export const MIN_RELEVANCE_CONFIDENCE = 65;
+
+export function acceptsRelevance(verdict: RelevanceVerdict | null): boolean {
+  if (!verdict) return false;
+  return verdict.relevant && verdict.confidence >= MIN_RELEVANCE_CONFIDENCE;
+}
diff --git a/lib/outreach/intentSources.ts b/lib/outreach/intentSources.ts
index 9af73e09..36644f56 100644
--- a/lib/outreach/intentSources.ts
+++ b/lib/outreach/intentSources.ts
@@ -22,6 +22,7 @@
 
 import { searchSerp } from "@/lib/alerts/valueserp";
 import { scoreIntent, type IntentSignal } from "./intent";
+import { acceptsRelevance, judgeRelevance } from "./intentRelevance";
 
 export type IntentSource = {
   id: string;
@@ -120,6 +121,15 @@ export const INTENT_PHRASINGS = [
   '"what do you use"',
 ];
 
+/**
+ * Model judgements one sweep may make.
+ *
+ * A ceiling rather than a budget-per-source, because the judgement is the only
+ * per-signal cost in the sweep and an index that suddenly returns three
+ * hundred results should not become three hundred model calls.
+ */
+const MAX_RELEVANCE_JUDGEMENTS = 15;
+
 export type IntentHit = {
   source: string;
   url: string;
@@ -199,6 +209,8 @@ export async function sweepIntent(input: {
   /** Only consider posts newer than this. */
   recency?: "day" | "week" | "month";
   minIntent?: number;
+  /** What the campaign sells, in prose. Enables the description path. */
+  sells?: string | null;
   now?: Date;
 }): Promise<IntentSweepResult> {
   const now = input.now ?? new Date();
@@ -208,6 +220,8 @@ export async function sweepIntent(input: {
   const notes: string[] = [];
   const seen = new Set<string>();
   const hits: IntentHit[] = [];
+  // Scored but not yet on-topic: awaiting a description judgement.
+  const pending: IntentHit[] = [];
   let calls = 0;
 
   // One phrasing at a time across every source, rather than every phrasing on
@@ -241,11 +255,12 @@ export async function sweepIntent(input: {
           postedAt,
           keywords: input.keywords,
           negativeKeywords: input.negativeKeywords,
+          allowDescriptionMatch: Boolean(input.sells?.trim()),
           now,
         });
         if (signal.disqualified) continue;
         if (signal.score < (input.minIntent ?? 0)) continue;
-        hits.push({
+        pending.push({
           source: source.id,
           url: r.url,
           title: r.title ?? "",
@@ -259,6 +274,37 @@ export async function sweepIntent(input: {
 
   // Strongest and freshest first — the score already folds both in, so this is
   // simply the order to work them in.
+  // Resolve the keyword misses, cheapest-first: the model only ever sees what
+  // already cleared the score bar, so an unbounded result set cannot turn into
+  // an unbounded number of judgements. Strongest first, so a capped run spends
+  // its judgements on the best candidates.
+  pending.sort((a, b) => b.signal.score - a.signal.score);
+  let judgements = 0;
+  for (const hit of pending) {
+    if (hit.signal.matchPath === "keyword") {
+      hits.push(hit);
+      continue;
+    }
+    if (!input.sells?.trim() || judgements >= MAX_RELEVANCE_JUDGEMENTS) continue;
+    judgements += 1;
+    const verdict = await judgeRelevance({
+      text: `${hit.title}\n${hit.snippet}`,
+      sells: input.sells,
+    });
+    if (!acceptsRelevance(verdict)) continue;
+    hits.push({
+      ...hit,
+      signal: {
+        ...hit.signal,
+        matchPath: "description",
+        // Carried so a user who only listed keywords can see why an unmatched
+        // post appeared, and can tell whether the model was right.
+        reasons: [...hit.signal.reasons, `matches what you sell: ${verdict!.reason}`],
+      },
+    });
+  }
+  if (judgements) notes.push(`${judgements} relevance judgements`);
+
   hits.sort((a, b) => b.signal.score - a.signal.score);
   notes.push(`${hits.length} intent signals from ${enabled.length} sources in ${calls} searches`);
   return { hits, calls, notes };
diff --git a/lib/outreach/runner.ts b/lib/outreach/runner.ts
index 4267e6db..875d3661 100644
--- a/lib/outreach/runner.ts
+++ b/lib/outreach/runner.ts
@@ -29,6 +29,8 @@ import { recordDiscoveredPeople } from "./contacts";
 import { sweepIntent } from "./intentSources";
 import { describeIntent } from "./intent";
 import { LEAD_RUN_CREDITS } from "@/lib/credits";
+import { sendIntentAlertEmail } from "@/lib/email";
+import { siteBase } from "./pipeline";
 
 export type CampaignRow = {
   id: string;
@@ -57,13 +59,17 @@ export type CampaignRow = {
   min_intent: number | null;
   intent_sources: string[] | null;
   intent_recency: "day" | "week" | "month" | null;
+  /** Prose description of what this campaign sells. Enables the description path. */
+  sells_description: string | null;
+  alert_email: string | null;
+  alerts_enabled: boolean;
   sender_name: string | null;
   reply_to: string | null;
   last_run_at: string | null;
 };
 
 export const CAMPAIGN_COLUMNS =
-  "id, project_id, owner_id, name, channel, active, queries, seed_urls, keywords, subreddits, negative_keywords, max_score, daily_send_limit, target_pipeline, auto_send, follow_ups, angle, sender_name, reply_to, last_run_at, pitch_mode, pitch_intro, pitch_ask, pitch_facts, scan_prospects, min_intent, intent_sources, intent_recency";
+  "id, project_id, owner_id, name, channel, active, queries, seed_urls, keywords, subreddits, negative_keywords, max_score, daily_send_limit, target_pipeline, auto_send, follow_ups, angle, sender_name, reply_to, last_run_at, pitch_mode, pitch_intro, pitch_ask, pitch_facts, scan_prospects, min_intent, intent_sources, intent_recency, sells_description, alert_email, alerts_enabled";
 
 export type TickResult = {
   campaign: string;
@@ -85,6 +91,8 @@ export type TickResult = {
   intentFound: number;
   /** Candidates dropped for showing no intent, when the campaign requires it. */
   intentRejected: number;
+  /** Signals included in an alert this tick. */
+  intentAlerted: number;
   skipped: string[];
   errors: string[];
 };
@@ -119,6 +127,7 @@ export async function runEmailCampaignTick(campaign: CampaignRow): Promise<TickR
     peopleRecorded: 0,
     intentFound: 0,
     intentRejected: 0,
+    intentAlerted: 0,
     researched: 0,
     drafted: 0,
     sent: 0,
@@ -279,6 +288,7 @@ export async function runEmailCampaignTick(campaign: CampaignRow): Promise<TickR
         sources: campaign.intent_sources ?? undefined,
         recency: campaign.intent_recency ?? "week",
         minIntent: campaign.min_intent,
+        sells: campaign.sells_description,
         maxCalls: MAX_INTENT_SEARCHES_PER_TICK,
       });
       result.intentFound = sweep.hits.length;
@@ -302,11 +312,18 @@ export async function runEmailCampaignTick(campaign: CampaignRow): Promise<TickR
             tier: hit.signal.tier,
             reasons: hit.signal.reasons,
             posted_at: hit.postedAt?.toISOString() ?? null,
+            match_path: hit.signal.matchPath,
             notes: describeIntent(hit.signal),
           },
           { onConflict: "project_id,url", ignoreDuplicates: true },
         );
       }
+
+      // Telling somebody is the point. A conversation worth answering has a
+      // useful life measured in hours, and a signal that sits in a table until
+      // someone happens to open the page is indistinguishable from one that
+      // was never found.
+      result.intentAlerted = await alertNewIntent(campaign);
     }
 
     const found = await discoverProspects({
@@ -534,6 +551,7 @@ export function summarize(r: TickResult): string {
   ];
   if (r.peopleRecorded) parts.push(`${r.peopleRecorded} people`);
   if (r.intentFound) parts.push(`${r.intentFound} INTENT`);
+  if (r.intentAlerted) parts.push(`${r.intentAlerted} alerted`);
   if (r.intentRejected) parts.push(`${r.intentRejected} no-intent`);
   if (r.awaitingAuth.length) parts.push(`${r.awaitingAuth.length} waiting_for_auth`);
   // Only when something was charged. Printing "0 credits" on every idle tick
@@ -543,3 +561,68 @@ export function summarize(r: TickResult): string {
   if (r.errors.length) parts.push(`${r.errors.length} errors`);
   return parts.join(", ");
 }
+
+/**
+ * Email whoever owns this campaign about signals they have not been told about.
+ *
+ * Dedupe is a column on the row rather than a timestamp window: "have we told
+ * them about this one" is a fact about the signal, and comparing found_at
+ * against a last-alerted-at would double-send anything that arrived while the
+ * previous alert was being composed.
+ *
+ * Marked as alerted only after the send succeeds. The other order loses a
+ * batch permanently to one SMTP hiccup, and a lead nobody heard about is the
+ * thing this exists to prevent.
+ */
+async function alertNewIntent(campaign: CampaignRow): Promise<number> {
+  if (!campaign.alerts_enabled) return 0;
+  const sb = serviceClient();
+
+  const { data } = await sb
+    .from("outreach_intent_signals")
+    .select("id, title, url, source, score, tier, reasons, posted_at")
+    .eq("campaign_id", campaign.id)
+    .is("alerted_at", null)
+    .neq("status", "dismissed")
+    .order("score", { ascending: false })
+    .limit(10);
+
+  const fresh = (data as Record<string, unknown>[] | null) ?? [];
+  if (!fresh.length) return 0;
+
+  // Falls back to the account address, so a campaign does not have to be
+  // configured before it is useful.
+  let to = campaign.alert_email?.trim() || null;
+  if (!to) {
+    const { data: profile } = await sb
+      .from("profiles")
+      .select("email")
+      .eq("id", campaign.owner_id)
+      .maybeSingle();
+    to = (profile?.email as string | null) ?? null;
+  }
+  if (!to) return 0;
+
+  const res = await sendIntentAlertEmail({
+    to,
+    campaign: campaign.name,
+    projectUrl: `${siteBase()}/projects/${campaign.project_id}/leads`,
+    signals: fresh.map((r) => ({
+      title: (r.title as string) ?? "",
+      url: r.url as string,
+      source: (r.source as string) ?? "",
+      score: (r.score as number) ?? 0,
+      tier: (r.tier as string) ?? "",
+      reasons: Array.isArray(r.reasons) ? (r.reasons as string[]) : [],
+      postedAt: (r.posted_at as string | null) ?? null,
+    })),
+  });
+  if (!res.sent) return 0;
+
+  await sb
+    .from("outreach_intent_signals")
+    .update({ alerted_at: new Date().toISOString() })
+    .in("id", fresh.map((r) => r.id as string));
+
+  return fresh.length;
+}
diff --git a/prd/0001-intent-lead-monitoring.md b/prd/0001-intent-lead-monitoring.md
new file mode 100644
index 00000000..0ea6fc11
--- /dev/null
+++ b/prd/0001-intent-lead-monitoring.md
@@ -0,0 +1,141 @@
+---
+openprd: "0.2"
+id: "0001"
+title: "Compete with intent-monitoring tools on the parts that matter"
+status: Partially Implemented
+authors:
+  - anthony@profullstack.com
+created: 2026-07-28
+updated: 2026-07-28
+repo: https://github.com/profullstack/crawlproof.com
+discussion:
+implementation: R1, R2 shipped; R3-R7 outstanding
+tags: [leads, outreach, intent, competitive]
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+CrawlProof shipped intent qualification today (#157, #158, #159): campaigns
+sweep Reddit, forums, Q&A and review sites for people publicly asking to buy,
+score them on explicitness × recency, and gate leads on a threshold.
+
+Leadmatically sells that as a whole product, at $19–$1,499/month. Reviewing
+what they offer against what we now have, the scoring engine is comparable and
+in two respects ours is stricter — we refuse people who said "no vendors", and
+we refuse drafts that state anything the campaign never claimed. But they beat
+us on everything that happens *after* a signal is found, and that gap is where
+the value of finding it goes.
+
+Three concrete losses:
+
+1. **We find a request and tell nobody.** They alert instantly on Email, Slack
+   or Telegram so the user "can be the first helpful reply". A conversation
+   worth answering has a useful life measured in hours; ours sits in a table
+   until someone loads the Leads page. Finding a lead nobody is told about is
+   indistinguishable from not finding it.
+
+2. **We match on keywords only.** They score against a *business description* —
+   what you sell, in prose — as well as keywords. Ours disqualifies anything
+   without a literal keyword hit, so "our pipeline keeps falling over under
+   traffic" is dropped by a load-testing campaign that listed "load testing".
+   The best-phrased requests are the ones least likely to use our words.
+
+3. **We do not help with the reply, or learn from it.** They keep a saved reply
+   prompt (tone and talking points) so replies stay consistent, and they track
+   what happened to each one — replied, removed, unavailable. We have a status
+   column nothing writes and no UI, so the intent queue cannot report whether
+   any of it works.
+
+## Goals
+
+- A user learns about a qualifying conversation within one tick, without
+  visiting the app.
+- Requests phrased in the user's own words are found even when they avoid the
+  campaign's keywords, without lowering precision.
+- Every signal ends in a recorded outcome, so per-source value is measurable
+  rather than assumed.
+- The intent queue answers "which of these is worth my next ten minutes"
+  without opening five tabs.
+
+## Non-Goals
+
+- **Facebook and Instagram monitoring.** Leadmatically lists both. Neither
+  carries meaningful public buying intent and neither is readable without
+  authenticated access we do not have. Listing them would be coverage we cannot
+  deliver, and this product's line is that a claim has to be true.
+- **Auto-posting replies.** They draft for review and so do we. Posting to a
+  social platform unattended is how an account gets banned and how the product
+  becomes a spam vector; the human stays in the loop deliberately.
+- **Per-keyword subscription tiers.** Their pricing meters businesses and
+  keywords. CrawlProof meters credits, and bolting a second quota system beside
+  it would make the cost of a run unpredictable — which is the one thing the
+  billing work this week was for.
+- **Replacing the email pipeline.** Intent and outreach answer different
+  questions. A person on a forum is not a domain to mail, and #157 already
+  keeps them in separate tables for that reason.
+
+## Users
+
+- **Founder or solo operator** running one project, who wants to be told when
+  somebody asks for what they sell and is not going to poll a dashboard.
+- **Agency running campaigns per client**, who needs the queue segmented by
+  project and needs to know which source is worth the credits.
+
+## Requirements
+
+- R1 [P0] **[shipped]** Alert on new qualifying signals by email, batched per campaign per
+  tick, with the strongest first and a direct link to each conversation. Never
+  alert twice for the same signal.
+- R2 [P0] **[shipped]** Score against a campaign's own description of what it sells, in
+  addition to keywords. A description match qualifies a signal that no keyword
+  matched; neither path may bypass the disqualifiers.
+- R3 [P0] Record an outcome per signal — working, replied, won, lost, dismissed
+  — from the queue, so the status column that already exists gets written.
+- R4 [P1] Report per-source performance: signals found, replied and won by
+  source, so a source that never converts can be switched off.
+- R5 [P1] A saved reply prompt per campaign (tone, talking points) and an
+  AI-drafted reply for a selected signal, checked by the existing grounding
+  guard before it is shown.
+- R6 [P2] Slack and Telegram alert channels, behind the same batching as R1.
+- R7 [P2] Keyword buckets by intent kind (brand, problem, competitor), so a
+  competitor complaint can be routed differently from a generic request.
+
+## UX Notes
+
+Alerts are batched per tick rather than sent per signal: a sweep that finds
+eleven conversations must produce one email, not eleven. The subject carries
+the count and the best score so it is triageable from a notification.
+
+The queue already sorts by score. Outcome buttons go inline on each row —
+recording an outcome is the most frequent action and should not need a detail
+page.
+
+A description-matched signal must say so in its reasons, because a user who
+listed keywords will otherwise not understand why an unmatched post appeared.
+
+## Success Metrics
+
+- Median time from a signal being found to being seen drops below one hour
+  (currently unbounded: it is however long until someone opens the page).
+- Description matching adds qualifying signals that keyword matching missed,
+  at a false-positive rate no worse than the keyword path — measured by
+  dismissal rate per match path.
+- Every source has a reply rate after 30 days, so R4 can retire the ones that
+  do not earn their credits.
+
+## Risks & Open Questions
+
+- **Alert fatigue.** A campaign with a low bar could mail hourly. Batching
+  bounds it to one per campaign per tick, but a daily cap may be needed;
+  deferred until there is a real send rate to look at.
+- **Description matching costs a model call per signal.** Cheap per call and
+  unbounded per sweep. Mitigated by only scoring what the cheap path already
+  short-listed, never the raw result set.
+- **Scoring on prose invites drift.** Keyword matching is legible and wrong in
+  obvious ways; a model deciding relevance is wrong in ways nobody sees. The
+  reasons string has to carry the model's stated basis, or R2 becomes
+  unauditable.
+- Open: whether a competitor complaint (R7) should outrank a generic request.
+  It is stronger intent but a worse first impression to answer.
diff --git a/supabase/migrations/20260729080000_intent_description_and_alerts.sql b/supabase/migrations/20260729080000_intent_description_and_alerts.sql
new file mode 100644
index 00000000..38de4e60
--- /dev/null
+++ b/supabase/migrations/20260729080000_intent_description_and_alerts.sql
@@ -0,0 +1,36 @@
+-- What a campaign sells, in prose, and who to tell when somebody asks for it.
+--
+-- Keyword matching drops the best-phrased requests. "Our pipeline keeps
+-- falling over under traffic" is exactly the person a load-testing campaign
+-- wants and contains none of its keywords, because the people with the problem
+-- describe the problem rather than the product category.
+--
+-- The description is also what makes a relevance judgement auditable: a model
+-- deciding "is this person asking for what you sell" needs a statement of what
+-- you sell, and that statement is the thing a user can correct when the
+-- judgement is wrong.
+alter table public.outreach_campaigns
+  add column if not exists sells_description text,
+  -- Where to send an alert. Null falls back to the account email, so a
+  -- campaign does not have to be configured to be useful.
+  add column if not exists alert_email text,
+  add column if not exists alerts_enabled boolean not null default true;
+
+comment on column public.outreach_campaigns.sells_description is
+  'Plain-prose description of what this campaign sells. Used to judge relevance for requests that avoid the campaign keywords.';
+
+-- Which path qualified a signal, so a description match can explain itself to
+-- a user who only ever listed keywords.
+alter table public.outreach_intent_signals
+  add column if not exists match_path text
+    check (match_path is null or match_path in ('keyword', 'description')),
+  -- Set once, when the signal has been included in an alert. The dedupe for
+  -- "never tell someone twice" is this column, not a timestamp comparison.
+  add column if not exists alerted_at timestamptz;
+
+create index if not exists outreach_intent_signals_unalerted_idx
+  on public.outreach_intent_signals (project_id)
+  where alerted_at is null;
+
+comment on column public.outreach_intent_signals.alerted_at is
+  'When this signal was included in an alert. Null means unsent; this column is what stops a signal being alerted twice.';
diff --git a/tests/intent-description.test.ts b/tests/intent-description.test.ts
new file mode 100644
index 00000000..cab76fab
--- /dev/null
+++ b/tests/intent-description.test.ts
@@ -0,0 +1,123 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { scoreIntent } from "@/lib/outreach/intent";
+import { acceptsRelevance, MIN_RELEVANCE_CONFIDENCE } from "@/lib/outreach/intentRelevance";
+
+const NOW = new Date("2026-07-28T12:00:00Z");
+const ago = (h: number) => new Date(NOW.getTime() - h * 3_600_000);
+
+// The request a keyword campaign misses: somebody with the problem, describing
+// the problem, using none of the words for the product that solves it.
+const OFF_VOCAB = "Our checkout keeps timing out whenever we run a promo. Anyone recommend a fix?";
+
+describe("keyword misses are not verdicts", () => {
+  it("still drops an off-keyword post when there is nothing to judge against", () => {
+    // Without a description the keyword gate is the only gate there is, and
+    // removing it would simply widen the funnel.
+    const s = scoreIntent({
+      text: OFF_VOCAB,
+      postedAt: ago(2),
+      keywords: ["load testing"],
+      now: NOW,
+    });
+    expect(s.disqualified).toMatch(/no campaign keyword/);
+  });
+
+  it("holds it open for judgement when a description exists", () => {
+    const s = scoreIntent({
+      text: OFF_VOCAB,
+      postedAt: ago(2),
+      keywords: ["load testing"],
+      allowDescriptionMatch: true,
+      now: NOW,
+    });
+    expect(s.disqualified).toBeNull();
+    // Null means undecided, never off-topic — that is what disqualified is for.
+    expect(s.matchPath).toBeNull();
+    expect(s.score).toBeGreaterThan(0);
+  });
+
+  it("marks a keyword hit as such without needing a judgement", () => {
+    const s = scoreIntent({
+      text: "Anyone recommend a load testing tool?",
+      postedAt: ago(2),
+      keywords: ["load testing"],
+      allowDescriptionMatch: true,
+      now: NOW,
+    });
+    expect(s.matchPath).toBe("keyword");
+  });
+
+  it("does not let the description path rescue a stated no", () => {
+    // A relevance judgement is not entitled to overturn "no vendors".
+    const s = scoreIntent({
+      text: "Our checkout times out. No vendors please.",
+      postedAt: ago(2),
+      keywords: ["load testing"],
+      allowDescriptionMatch: true,
+      now: NOW,
+    });
+    expect(s.disqualified).toMatch(/pitched/);
+  });
+
+  it("does not let it rescue somebody selling", () => {
+    const s = scoreIntent({
+      text: "I fix checkout timeouts — DM me for rates.",
+      postedAt: ago(2),
+      keywords: ["load testing"],
+      allowDescriptionMatch: true,
+      now: NOW,
+    });
+    expect(s.disqualified).toMatch(/selling/);
+  });
+});
+
+describe("a guess is not a reason to contact somebody", () => {
+  it("requires the model to be sure", () => {
+    expect(acceptsRelevance({ relevant: true, confidence: MIN_RELEVANCE_CONFIDENCE, reason: "x" })).toBe(true);
+    expect(acceptsRelevance({ relevant: true, confidence: MIN_RELEVANCE_CONFIDENCE - 1, reason: "x" })).toBe(false);
+  });
+
+  it("takes a no as a no however confident", () => {
+    expect(acceptsRelevance({ relevant: false, confidence: 100, reason: "x" })).toBe(false);
+  });
+
+  it("treats a missing verdict as no match, not as a rejection", () => {
+    // A missing model must narrow nothing: the keyword path still stands, and
+    // the sweep simply does not gain the extra signals.
+    expect(acceptsRelevance(null)).toBe(false);
+  });
+});
+
+describe("the alert is wired and bounded", () => {
+  const runner = readFileSync(new URL("../lib/outreach/runner.ts", import.meta.url), "utf8");
+  const sources = readFileSync(new URL("../lib/outreach/intentSources.ts", import.meta.url), "utf8");
+
+  it("tells somebody when a signal is found", () => {
+    // A signal sitting in a table until someone opens the page is
+    // indistinguishable from one that was never found.
+    expect(runner).toContain("alertNewIntent");
+    expect(runner).toContain("sendIntentAlertEmail");
+  });
+
+  it("never alerts the same signal twice", () => {
+    expect(runner).toContain('.is("alerted_at", null)');
+  });
+
+  it("marks alerted only after the send succeeds", () => {
+    // The other order loses a whole batch to one SMTP hiccup.
+    const fn = runner.slice(runner.indexOf("async function alertNewIntent"));
+    expect(fn.indexOf("if (!res.sent) return 0;")).toBeLessThan(fn.indexOf("alerted_at: new Date()"));
+  });
+
+  it("caps how many model judgements a sweep can make", () => {
+    // An index that suddenly returns three hundred results must not become
+    // three hundred model calls.
+    expect(sources).toContain("MAX_RELEVANCE_JUDGEMENTS");
+    expect(sources).toMatch(/judgements >= MAX_RELEVANCE_JUDGEMENTS/);
+  });
+
+  it("only judges what already cleared the score bar", () => {
+    expect(sources).toMatch(/pending\.push/);
+  });
+});