fullstackgtm 0.50.1 → 0.51.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ The path to 1.0 is planned in [docs/roadmap-to-1.0.md](https://github.com/fullst
 
 ## [Unreleased]
 
+## [0.51.0] — 2026-07-11
+
+### Added
+
+- Native Clay Public API authentication and people search for governed lead
+  acquisition, including ICP-to-Clay filter translation and resumable search
+  checkpoints.
+- A provider-neutral, fill-only contact waterfall contract for work email,
+  mobile, and direct-dial enrichment, with Pipe0 as the first registered
+  provider and compatibility for existing Pipe0 email resolution.
+- Clay acquisition presets, initialization, doctor diagnostics, public API
+  exports, strategy documentation, and live-safe credential validation.
+
+### Changed
+
+- `enrich acquire` now uses the shared decision-first presentation contract:
+  compact cards by default, full evidence with `--verbose`, and a stable JSON
+  envelope with counts, cost, meter, and persistence state under `--json`.
+- Pre-enrichment deduplication and avoided-spend reporting are provider-neutral
+  so the same acquisition pipeline can support additional contact sources.
+
 ## [0.50.1] — 2026-07-10
 
 ### Added

package/dist/cli/auth.js

@@ -7,6 +7,7 @@ import { activeProfile, credentialsPath, DEFAULT_PROFILE, deleteCredential, getC
 import { activeWorkspaceProfile, readHealthTimeline, summarizeHealth } from "../health.js";
 import { resolveLlmCredential, validateLlmKey } from "../llm.js";
 import { createFilePlanStore } from "../planStore.js";
+import { validateClayApiKey } from "../connectors/clay.js";
 import { isOptionValue, numericOption, option, readPackageInfo, readSecret } from "./shared.js";
 import { box, colorEnabled, paint, scoreColor, sparkline } from "./ui.js";
 /**
@@ -351,6 +352,22 @@ export async function login(args) {
         console.log(`Stored Apollo API key in ${credentialsPath()}. \`fullstackgtm enrich append|refresh\` use it automatically.`);
         return;
     }
+    if (provider === "clay") {
+        rejectArgvSecret(args, "--token", "--key", "--api-key");
+        const key = await readSecret("Clay Public API key");
+        if (!key)
+            throw new Error("No Clay Public API key provided.");
+        if (!args.includes("--no-validate")) {
+            const validation = await validateClayApiKey(key);
+            if (!validation.ok)
+                throw new Error(validation.detail);
+            console.log(validation.detail);
+        }
+        const stamp = new Date().toISOString();
+        storeCredential("clay", { kind: "api_key", accessToken: key, createdAt: stamp, updatedAt: stamp });
+        console.log(`Stored Clay Public API key in ${credentialsPath()}. Clay connector commands resolve it automatically.`);
+        return;
+    }
     if (provider === "pipe0" || provider === "explorium" || provider === "heyreach" || provider === "theirstack") {
         rejectArgvSecret(args, "--token", "--key", "--api-key");
         const key = await readSecret(`${provider} API key`);
@@ -365,7 +382,7 @@ export async function login(args) {
         return;
     }
     if (provider !== "hubspot") {
-        throw new Error("login supports: hubspot, salesforce, stripe, anthropic, openai, apollo, pipe0, explorium, or --via <hosted url>. Usage: fullstackgtm login <provider> | fullstackgtm login --via https://gtm.example.com");
+        throw new Error("login supports: hubspot, salesforce, stripe, anthropic, openai, apollo, clay, pipe0, explorium, heyreach, theirstack, or --via <hosted url>. Usage: fullstackgtm login <provider> | fullstackgtm login --via https://gtm.example.com");
     }
     const now = new Date().toISOString();
     rejectArgvSecret(args, "--token");
@@ -450,6 +467,9 @@ export function doctorReport(env = process.env) {
         stripe: env.STRIPE_SECRET_KEY
             ? { source: "env", detail: "STRIPE_SECRET_KEY" }
             : providerStatus("stripe", broker),
+        clay: env.CLAY_API_KEY
+            ? { source: "env", detail: "CLAY_API_KEY" }
+            : providerStatus("clay", null),
     };
     const llm = resolveLlmCredential(env);
     const missingPeers = ["@modelcontextprotocol/sdk", "zod"].filter((name) => {
@@ -461,13 +481,13 @@ export function doctorReport(env = process.env) {
             return true;
         }
     });
-    const connected = Object.entries(providers).filter(([, status]) => status.source !== "none");
-    const nextSteps = connected.length === 0
+    const connectedCrm = ["hubspot", "salesforce"].filter((provider) => providers[provider].source !== "none");
+    const nextSteps = connectedCrm.length === 0
         ? [
             "fullstackgtm audit --demo            # no credentials needed",
             "fullstackgtm login hubspot           # hosted browser OAuth (default; or: login salesforce)",
         ]
-        : [`fullstackgtm audit --provider ${connected[0][0]}`];
+        : [`fullstackgtm audit --provider ${connectedCrm[0]}`];
     return {
         package: packageInfo,
         node: { version: process.versions.node, ok: nodeMajor >= 20, required: ">=20" },

package/dist/cli/enrich.js

@@ -8,6 +8,8 @@ import { createFilePlanStore } from "../planStore.js";
 import { buildAcquirePlan, buildEnrichPlan, createFileEnrichRunStore, DEFAULT_STALE_DAYS, ENRICH_CONFIG_FILE_NAME, builtinAcquirePreset, builtinEnrichPreset, enrichRunId, inferIngestObjectType, latestStamps, loadEnrichConfig, parseCsv, resolveCrmField, selectStaleWork, stagedSourceRecords, staleDaysFor } from "../enrich.js";
 import { loadMeter, remaining } from "../acquireMeter.js";
 import { crmContactKeys, fetchExploriumProspects, fetchPipe0CrustdataProspectPage, partitionFreshProspects, pipe0ResolveCompanyDomains, pipe0ResolveWorkEmails, prospectIdentityKeys } from "../connectors/prospectSources.js";
+import { createClaySearch, runClayPeopleSearchPage } from "../connectors/clay.js";
+import { runContactWaterfall } from "../contactProviders.js";
 import { loadSeen, recordSeen } from "../acquireSeen.js";
 import { acquireCheckpointId, createFileAcquireCheckpointStore } from "../acquireCheckpoint.js";
 import { readHostedAcquireCheckpoint, writeHostedAcquireCheckpoint } from "../hostedAcquireCheckpoint.js";
@@ -15,7 +17,7 @@ import { uploadHostedPatchPlan } from "../hostedPatchPlan.js";
 import { progressReporter, reportCounts, reportEvent } from "../runReport.js";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.js";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.js";
-import { fitThreshold, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp } from "../icp.js";
+import { fitThreshold, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp } from "../icp.js";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords } from "../enrichApollo.js";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.js";
 import { isOptionValue, loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.js";
@@ -193,8 +195,8 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         // Meter: how many MORE leads may we create right now? --max is an
         // additional per-run ceiling, never a way to exceed the budget.
         if (apiSkippedCrm || apiSkippedSeen) {
-            console.error(`Pre-email dedup: skipped ${apiSkippedCrm} already-in-CRM + ${apiSkippedSeen} seen before paying for emails ` +
-                `(≈$${((apiSkippedCrm + apiSkippedSeen) * costPerRecord).toFixed(2)} enrichment saved).`);
+            console.error(`Pre-enrichment dedup: skipped ${apiSkippedCrm} already-in-CRM + ${apiSkippedSeen} previously seen ` +
+                `(≈$${((apiSkippedCrm + apiSkippedSeen) * costPerRecord).toFixed(2)} downstream spend avoided).`);
         }
         // `cap` is the desired create count bounded by the persistent meter. Raw
         // discovery scanning has its own --scan-limit and may cross many duplicate-
@@ -264,16 +266,16 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         const meterLine = formatAcquireMeter(headroom, costPerRecord);
         const gaugeLine = acquireGaugeLine(headroom, config.acquire.budget ?? {}, paint(colorEnabled(process.stdout)));
         if (!save) {
-            if (rest.includes("--json")) {
-                console.log(JSON.stringify({ plan: result.plan, counts: result.counts, estCostUsd: result.estCostUsd, meter: headroom }, null, 2));
-            }
-            else {
-                console.log(verbosePlanRequested(rest) ? patchPlanToMarkdown(result.plan) : compactPlan(result.plan));
-                console.log(meterLine);
-                if (gaugeLine)
-                    console.log(gaugeLine);
-                console.log("\nDry run — nothing written. Re-run with --save to persist the plan, then approve + apply.");
-            }
+            printAcquireOutput({
+                args: rest,
+                result,
+                meter: headroom,
+                meterLine,
+                gaugeLine,
+                saved: false,
+                planSaved: false,
+                hostedPlanUrl: null,
+            });
             return;
         }
         const run = await openEnrichRun(store, source, "acquire", option(rest, "--run-label"), today);
@@ -319,28 +321,16 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         if (acquireTelemetry && acquireCheckpointSync) {
             await persistAcquireCheckpoint(acquireCheckpointSync.key, acquireTelemetry.discovery, acquireCheckpointSync.hostedVersion);
         }
-        if (planIds.length > 0) {
-            const hostedRuns = hostedRunsUrl();
-            console.log(`\nSaved plan ${result.plan.id}`);
-            console.log(`  Leads      ${result.counts.created} net-new`);
-            console.log(`  Est. cost  $${result.estCostUsd.toFixed(2)}`);
-            console.log(`  Budget     ${gaugeLine ?? meterLine}`);
-            if (hostedPlanUrl)
-                console.log(`  Plan       ${hostedPlanUrl}`);
-            if (hostedRuns)
-                console.log(`  Observe    ${hostedRuns}`);
-            console.log("\nNext steps");
-            console.log(`  Review     fullstackgtm plans show ${result.plan.id}`);
-            console.log(`  Approve    fullstackgtm plans approve ${result.plan.id} --operations all`);
-            console.log(`  Apply      fullstackgtm apply --plan-id ${result.plan.id} --provider hubspot`);
-            console.log("\nThe meter is charged only when a create lands at apply.");
-        }
-        else {
-            console.log(meterLine);
-            if (gaugeLine)
-                console.log(gaugeLine);
-            console.log("No net-new leads to create (everything sourced already matched, or was withheld by the meter).");
-        }
+        printAcquireOutput({
+            args: rest,
+            result,
+            meter: headroom,
+            meterLine,
+            gaugeLine,
+            saved: true,
+            planSaved: planIds.length > 0,
+            hostedPlanUrl,
+        });
         return;
     }
     const mode = subcommand === "refresh" ? "refresh" : "append";
@@ -501,8 +491,9 @@ function formatEnrichCounts(counts, ambiguities) {
 /**
  * Pull net-new prospects from an API acquire source into source records the
  * acquire builder dedupes + turns into create_record ops. Explorium discovers;
- * pipe0 (when resolveEmailsWith=pipe0) fills real work emails. Only rows that
- * carry the dedupe key (email) survive — you cannot resolve-first without it.
+ * A field-level provider waterfall fills missing contact data. Existing
+ * email-keyed and resolveEmailsWith=pipe0 configs translate to an implicit
+ * Pipe0 work-email step. Only rows that carry the configured dedupe key survive.
  */
 async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRun, targetFresh, persistCheckpoint, progress) {
     const acquire = config.acquire;
@@ -521,7 +512,9 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
         ? (icp ? icpToExploriumFilters(icp) : (disc.filters ?? {}))
         : disc.provider === "pipe0"
             ? (icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {}))
-            : {};
+            : disc.provider === "clay"
+                ? (icp ? icpToClayPeopleFilters(icp) : (disc.filters ?? {}))
+                : {};
     const queryFingerprint = createHash("sha256")
         .update(JSON.stringify({ source, provider: disc.provider, listId, filters, icp: icp ?? null }))
         .digest("hex");
@@ -584,6 +577,20 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
             cursor = result.nextCursor;
             exhausted = result.nextCursor === null;
         }
+        else if (disc.provider === "clay") {
+            if (!cursor) {
+                progress.note("creating Clay people-search iterator");
+                cursor = await createClaySearch({
+                    apiKey: providerKey("clay"), sourceType: "people", filters,
+                });
+            }
+            const result = await runClayPeopleSearchPage({
+                apiKey: providerKey("clay"), searchId: cursor, limit: requestSize,
+            });
+            page = result.prospects;
+            offset += page.length;
+            exhausted = !result.hasMore;
+        }
         else if (disc.provider === "explorium") {
             const pageNumber = offset + 1;
             exploriumPage = pageNumber;
@@ -604,7 +611,7 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
             exhausted = page.length < requestSize;
         }
         else {
-            throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0 | linkedin).`);
+            throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (clay | explorium | pipe0 | linkedin).`);
         }
         discovered += page.length;
         progress.items(discovered, scanLimit);
@@ -650,23 +657,35 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
     }
     progress.stage(ACQUIRE_STAGES[1], 1, ACQUIRE_STAGES.length);
     progress.note("checking work-email requirements");
-    // 3. Resolve real work emails. Triggered either when email IS the dedupe key
-    //    (Explorium's email is hashed, Crustdata returns none) or when a source
-    //    that keys on something else opts in via `resolveEmailsWith: "pipe0"`
-    //    (e.g. LinkedIn keys on the profile URL but still wants outreach emails).
-    //    pipe0 waterfall, chunked; resolves from name + company domain/name.
-    if (matchKey === "email" || disc.resolveEmailsWith === "pipe0") {
-        // The waterfall needs a company DOMAIN; LinkedIn/HeyReach lists carry only
-        // names. Resolve domains first (pipe0 company:identity) so resolution can
-        // actually land — without it, name-only resolution fails for every lead.
-        if (prospects.some((p) => !p.companyDomain && p.companyName)) {
-            progress.note(`resolving company domains for ${prospects.length} candidate(s)`);
-            const resolved = await pipe0ResolveCompanyDomains({ apiKey: providerKey("pipe0"), prospects });
-            prospects.splice(0, prospects.length, ...resolved);
-        }
-        progress.note(`resolving work emails for ${prospects.length} candidate(s)`);
-        const resolved = await pipe0ResolveWorkEmails({ apiKey: providerKey("pipe0"), prospects });
-        prospects.splice(0, prospects.length, ...resolved);
+    // 3. Resolve contact fields through the ordered, fill-only waterfall. Keep
+    // legacy behavior: email-keyed acquisition and resolveEmailsWith=pipe0 imply
+    // a Pipe0 work-email step when no explicit waterfall is configured.
+    const implicitPipe0 = matchKey === "email" || disc.resolveEmailsWith === "pipe0";
+    const contactWaterfall = disc.contactWaterfall ?? (implicitPipe0 ? [{ provider: "pipe0", fields: ["work_email"] }] : []);
+    if (contactWaterfall.length > 0) {
+        const adapters = {
+            pipe0: {
+                provider: "pipe0",
+                resolve: async (candidates, fields) => {
+                    let resolved = candidates;
+                    if (fields.includes("work_email") && resolved.some((p) => !p.companyDomain && p.companyName)) {
+                        progress.note(`resolving company domains for ${resolved.length} candidate(s)`);
+                        resolved = await pipe0ResolveCompanyDomains({ apiKey: providerKey("pipe0"), prospects: resolved });
+                    }
+                    if (fields.includes("work_email")) {
+                        progress.note(`resolving work emails with pipe0 for ${resolved.length} candidate(s)`);
+                        resolved = await pipe0ResolveWorkEmails({ apiKey: providerKey("pipe0"), prospects: resolved });
+                    }
+                    return resolved;
+                },
+            },
+        };
+        const result = await runContactWaterfall({ prospects, steps: contactWaterfall, adapters });
+        prospects.splice(0, prospects.length, ...result.prospects);
+        for (const attempt of result.attempts) {
+            const added = Object.entries(attempt.added).map(([field, count]) => `${count} ${field}`).join(", ") || "0 fields";
+            progress.note(`${attempt.provider}: ${attempt.attempted} attempted · ${added} added`);
+        }
     }
     progress.items(prospects.length, prospects.length);
     progress.note(`${prospects.length} candidate(s) ready for planning`);
@@ -756,6 +775,53 @@ function formatAcquireMeter(headroom, costPerRecord) {
         `Spend left: ${money(headroom.spendUsd.day)}/day, ${money(headroom.spendUsd.month)}/month ` +
         `(≈$${costPerRecord.toFixed(2)}/lead).`);
 }
+function printAcquireOutput(options) {
+    const { args, result, meter, meterLine, gaugeLine, saved, planSaved, hostedPlanUrl } = options;
+    if (args.includes("--json")) {
+        console.log(JSON.stringify({
+            plan: result.plan,
+            counts: result.counts,
+            estCostUsd: result.estCostUsd,
+            meter,
+            persistence: {
+                runSaved: saved,
+                planSaved,
+                planId: planSaved ? result.plan.id : null,
+                hostedPlanUrl,
+            },
+        }, null, 2));
+        return;
+    }
+    if (verbosePlanRequested(args)) {
+        console.log(patchPlanToMarkdown(result.plan));
+        console.log(`\nAcquisition`);
+        console.log(`  Leads      ${result.counts.created} net-new · ${result.counts.unassigned} unassigned`);
+        console.log(`  Est. cost  $${result.estCostUsd.toFixed(2)}`);
+        console.log(`  Budget     ${gaugeLine ?? meterLine}`);
+        if (hostedPlanUrl)
+            console.log(`  Plan       ${hostedPlanUrl}`);
+    }
+    else if (planSaved || !saved) {
+        console.log(compactPlan(result.plan, { saved: planSaved }));
+        console.log(meterLine);
+        if (gaugeLine)
+            console.log(gaugeLine);
+    }
+    else {
+        console.log(meterLine);
+        if (gaugeLine)
+            console.log(gaugeLine);
+        console.log("No net-new leads to create (everything sourced already matched, or was withheld by the meter).");
+    }
+    if (planSaved) {
+        console.log(`\nApprove  fullstackgtm plans approve ${result.plan.id} --operations all`);
+        console.log(`Apply    fullstackgtm apply --plan-id ${result.plan.id} --provider <hubspot|salesforce>`);
+        const hostedRuns = hostedRunsUrl();
+        if (hostedRuns)
+            console.log(`Observe  ${hostedRuns}`);
+        console.log("The meter is charged only when a create lands at apply.");
+    }
+}
 function hostedRunsUrl() {
     const baseUrl = getCredential("broker")?.baseUrl?.replace(/\/+$/, "");
     return baseUrl ? `${baseUrl}/dashboard/runs` : null;

package/dist/cli/help.js

@@ -16,13 +16,16 @@ Usage:
   fullstackgtm login salesforce --instance-url <url> [--no-validate]  advanced: paste access token
   fullstackgtm login stripe [--no-validate]
   fullstackgtm login anthropic | openai        store an LLM API key for call parse/score
-  fullstackgtm login apollo                    store an Apollo API key for enrich pulls\n  fullstackgtm login pipe0 | explorium | theirstack  store a discovery-provider key (theirstack = technographic TAM)\n  fullstackgtm login heyreach                  store a HeyReach key for enrich acquire --source linkedin\n  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|heyreach|broker>
+  fullstackgtm login apollo | clay             store a data-provider Public API key
+  fullstackgtm login pipe0 | explorium | theirstack  store a discovery-provider key (theirstack = technographic TAM)
+  fullstackgtm login heyreach                  store a HeyReach key for enrich acquire --source linkedin
+  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|clay|pipe0|explorium|heyreach|broker>
 
   Secrets (tokens, client secrets) are NEVER passed as flags — they leak via
   the process list and shell history. Pipe them on stdin or enter them at the
   interactive prompt:
     echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot --private-token
-  fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
+  fullstackgtm init [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
                                                cold start: scaffold icp.json + enrich.config.json + a
                                                PLAYBOOK wired for this workspace (the CLI ships primitives,
                                                your agent is the orchestrator — see docs/recipes.md)
@@ -72,7 +75,7 @@ Usage:
   fullstackgtm tam estimate [--name <n>] [--icp <path>] (--accounts <n> | --source theirstack|explorium) (--acv <annual-usd> | --acv-from-crm --deal-period monthly|quarterly|annual) [--acv-basis account|buyer] [--buyers-per-account <n>] [--cross-checks <file.json>] [source options] [--json]
   fullstackgtm tam status [--name <n>] <source options> [--save] [--json]
   fullstackgtm tam report [--name <n>] [--out <path>]
-  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--label <l>]
+  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--label <l>]
                                                size the reachable market FROM the ICP (a real account count ×
                                                ACV; buyers/account = the contact population target), then fill
                                                it: populate schedules plan-only enrich acquire --save (apply
@@ -276,7 +279,7 @@ export const HELP = {
         summary: "scaffold a workspace (icp.json + enrich.config.json + PLAYBOOK)",
         phase: "Setup",
         synopsis: [
-            "fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]",
+            "fullstackgtm init [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]",
         ],
         detail: "Cold start: writes a starter ICP, an acquire-ready enrich.config.json (with a visible assign seam so leads are never ownerless), and a PLAYBOOK wired with the cold-start + outbound-loop recipes for this workspace. Pure file-writer — no network, keeps existing files unless --force. The CLI ships governed primitives; your coding agent is the orchestrator (see docs/recipes.md).",
         seeAlso: ["icp", "enrich", "signals"],
@@ -289,7 +292,7 @@ export const HELP = {
             "fullstackgtm login hubspot | salesforce          hosted browser OAuth (default)",
             "fullstackgtm login --via <hosted url>            pair with a team deployment",
             "fullstackgtm login stripe",
-            "fullstackgtm login anthropic | openai | apollo",
+            "fullstackgtm login anthropic | openai | apollo | clay",
         ],
         detail: "HubSpot/Salesforce use hosted browser OAuth by default; BYO app/token paths are advanced. Secrets are NEVER passed as flags — pipe on stdin or enter at the prompt: `echo \"$TOKEN\" | fullstackgtm login hubspot --private-token`.",
         seeAlso: ["doctor", "logout", "profiles"],
@@ -297,7 +300,7 @@ export const HELP = {
     logout: {
         summary: "remove stored credentials for a provider",
         phase: "Setup",
-        synopsis: ["fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|broker>"],
+        synopsis: ["fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|clay|pipe0|explorium|broker>"],
         seeAlso: ["login", "doctor"],
     },
     doctor: {

package/dist/cli/init.js

@@ -13,7 +13,7 @@ import { option } from "./shared.js";
 export function initCommand(args) {
     if (args.includes("--help") || args.includes("-h")) {
         console.log(`Usage:
-  fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
+  fullstackgtm init [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
 
 Scaffolds a workspace so the first acquire/signals/judge/draft commands work:
   icp.json            starter ICP (edit, or rebuild with \`icp interview\`)
@@ -25,8 +25,8 @@ docs/recipes.md for the full play set. Existing files are kept unless --force.`)
         return;
     }
     const source = (option(args, "--source") ?? "pipe0");
-    if (!["pipe0", "explorium", "linkedin"].includes(source)) {
-        throw new Error(`init: --source must be pipe0|explorium|linkedin (got "${source}")`);
+    if (!["pipe0", "explorium", "clay", "linkedin"].includes(source)) {
+        throw new Error(`init: --source must be pipe0|explorium|clay|linkedin (got "${source}")`);
     }
     const provider = (option(args, "--provider") ?? "hubspot");
     if (!["hubspot", "salesforce"].includes(provider)) {

package/dist/cli/tam.d.ts

@@ -1,6 +1,6 @@
 /** Best-effort enrich-config load for apply-time acquire-budget enforcement. */
 /** Provider API key: env override first, then the credential store (`login`). */
-export declare function providerKey(provider: "explorium" | "pipe0" | "heyreach" | "theirstack"): string;
+export declare function providerKey(provider: "explorium" | "pipe0" | "clay" | "heyreach" | "theirstack"): string;
 /**
  * `tam` — Total Addressable Market mapping. Estimate a defensible universe from
  * the ICP, then iteratively populate it via scheduled governed acquire runs and

package/dist/cli/tam.js

@@ -5,6 +5,7 @@ import { getCredential } from "../credentials.js";
 import { appendCoverage, computeCoverage, coverageCountsFromSnapshot, classifyCoverage, coverageToText, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamReportToMarkdown } from "../tam.js";
 import { probeExploriumBusinessCount } from "../connectors/prospectSources.js";
 import { theirStackCountCompanies, theirStackPullCost, theirStackSearchCompanies } from "../connectors/theirstack.js";
+import { clayApiKey } from "../connectors/clay.js";
 import { icpToExploriumBusinessFilters, icpToTheirStackFilters } from "../icp.js";
 import { scheduleCommand } from "./schedule.js";
 import { loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.js";
@@ -12,6 +13,8 @@ import { unknownSubcommandError } from "./suggest.js";
 /** Best-effort enrich-config load for apply-time acquire-budget enforcement. */
 /** Provider API key: env override first, then the credential store (`login`). */
 export function providerKey(provider) {
+    if (provider === "clay")
+        return clayApiKey();
     const envName = provider === "explorium"
         ? "EXPLORIUM_API_KEY"
         : provider === "pipe0"
@@ -41,7 +44,7 @@ export async function tamCommand(args) {
   fullstackgtm tam accounts [--name <n>] [--icp <path>] --source theirstack [--max <n>] [--dry-run | --confirm] [--max-credits <n>] [--usd-per-credit <r>] [--out <file.csv> | --json]
   fullstackgtm tam status   [--name <n>] <source options> [--save] [--json]
   fullstackgtm tam report   [--name <n>] [--out <path>]
-  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--label <l>]
+  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--label <l>]
 
 Estimate the reachable market FROM your ICP: a real account count × a confirmed
 ANNUAL ACV (--acv <annual-usd>, or --acv-from-crm --deal-period monthly|quarterly|

package/dist/connectors/clay.d.ts

@@ -0,0 +1,33 @@
+import type { Prospect } from "./prospectSources.ts";
+export declare const CLAY_PUBLIC_API_BASE = "https://api.clay.com/public/v0";
+export type ClayKeyValidation = {
+    ok: boolean;
+    detail: string;
+    workspaceId?: string;
+};
+export type ClaySearchSourceType = "people" | "companies";
+export type ClayPeopleSearchPage = {
+    prospects: Prospect[];
+    hasMore: boolean;
+};
+/** Create a forward-only Clay search iterator. This call does not fetch a page. */
+export declare function createClaySearch(opts: {
+    apiKey: string;
+    sourceType: ClaySearchSourceType;
+    filters: Record<string, unknown>;
+    fetchImpl?: typeof fetch;
+    apiBaseUrl?: string;
+}): Promise<string>;
+/** Consume the next people page from a Clay search iterator. */
+export declare function runClayPeopleSearchPage(opts: {
+    apiKey: string;
+    searchId: string;
+    limit?: number;
+    fetchImpl?: typeof fetch;
+    apiBaseUrl?: string;
+}): Promise<ClayPeopleSearchPage>;
+export declare function normalizeClayPerson(value: unknown): Prospect;
+/** Validate a Clay Public API key without creating a search or spending enrichment credits. */
+export declare function validateClayApiKey(apiKey: string, fetchImpl?: typeof fetch, apiBaseUrl?: string): Promise<ClayKeyValidation>;
+/** Resolve Clay credentials using the standard env -> profile-scoped store ladder. */
+export declare function clayApiKey(env?: Record<string, string | undefined>): string;

package/dist/connectors/clay.js

@@ -0,0 +1,123 @@
+import { getCredential } from "../credentials.js";
+import { ProviderHttpError } from "../providerError.js";
+export const CLAY_PUBLIC_API_BASE = "https://api.clay.com/public/v0";
+function clayHeaders(apiKey) {
+    return { "clay-api-key": apiKey, Accept: "application/json", "Content-Type": "application/json" };
+}
+/** Create a forward-only Clay search iterator. This call does not fetch a page. */
+export async function createClaySearch(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? CLAY_PUBLIC_API_BASE).replace(/\/$/, "");
+    const response = await fetchImpl(`${base}/search/filters-mode`, {
+        method: "POST",
+        headers: clayHeaders(opts.apiKey),
+        body: JSON.stringify({ source_type: opts.sourceType, filters: opts.filters }),
+    });
+    if (!response.ok)
+        throw new ProviderHttpError("Clay", "create search", response.status);
+    const body = await response.json();
+    const searchId = body.search_id ?? body.searchId;
+    if (typeof searchId !== "string" || !searchId)
+        throw new Error("Clay create search returned no search_id.");
+    return searchId;
+}
+/** Consume the next people page from a Clay search iterator. */
+export async function runClayPeopleSearchPage(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? CLAY_PUBLIC_API_BASE).replace(/\/$/, "");
+    const limit = Math.max(1, Math.min(opts.limit ?? 25, 100));
+    const response = await fetchImpl(`${base}/search/filters-mode/${encodeURIComponent(opts.searchId)}/run`, {
+        method: "POST",
+        headers: clayHeaders(opts.apiKey),
+        body: JSON.stringify({ limit }),
+    });
+    if (!response.ok)
+        throw new ProviderHttpError("Clay", "run people search", response.status);
+    const body = await response.json();
+    if (!Array.isArray(body.data))
+        throw new Error("Clay people search returned an invalid data array.");
+    const hasMore = body.has_more ?? body.hasMore;
+    if (typeof hasMore !== "boolean")
+        throw new Error("Clay people search returned no has_more flag.");
+    return { prospects: body.data.map(normalizeClayPerson), hasMore };
+}
+export function normalizeClayPerson(value) {
+    const row = value && typeof value === "object" ? value : {};
+    const location = row.structured_location && typeof row.structured_location === "object"
+        ? row.structured_location
+        : {};
+    const fullName = stringValue(row.name);
+    return {
+        firstName: stringValue(row.first_name),
+        lastName: stringValue(row.last_name),
+        fullName,
+        jobTitle: stringValue(row.latest_experience_title),
+        companyName: stringValue(row.latest_experience_company),
+        companyDomain: bareDomain(stringValue(row.domain)),
+        linkedin: normalizeLinkedin(stringValue(row.url)),
+        headline: undefined,
+        sourceId: normalizeLinkedin(stringValue(row.url)) ?? fullName,
+        location: {
+            city: stringValue(location.city),
+            state: stringValue(location.state),
+            region: stringValue(location.region),
+            country: stringValue(location.country),
+            countryCode: stringValue(location.country_iso),
+        },
+    };
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function bareDomain(value) {
+    return value?.replace(/^https?:\/\//i, "").replace(/^www\./i, "").replace(/\/.*$/, "").toLowerCase() || undefined;
+}
+function normalizeLinkedin(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.startsWith("http") ? value : `https://${value.replace(/^\/+/, "")}`;
+    return normalized.replace(/\/$/, "");
+}
+/** Validate a Clay Public API key without creating a search or spending enrichment credits. */
+export async function validateClayApiKey(apiKey, fetchImpl = fetch, apiBaseUrl = CLAY_PUBLIC_API_BASE) {
+    let response;
+    try {
+        response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/me`, {
+            headers: { "clay-api-key": apiKey, Accept: "application/json" },
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, detail: `Cannot reach the Clay Public API: ${detail}` };
+    }
+    if (!response.ok)
+        return { ok: false, detail: `Clay rejected the key: HTTP ${response.status}` };
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return { ok: false, detail: "Clay accepted the request but returned an invalid JSON response." };
+    }
+    const record = body && typeof body === "object" ? body : {};
+    const workspace = record.workspace && typeof record.workspace === "object"
+        ? record.workspace
+        : undefined;
+    const rawWorkspaceId = record.workspace_id ?? record.workspaceId ?? workspace?.id;
+    const workspaceId = typeof rawWorkspaceId === "string" || typeof rawWorkspaceId === "number"
+        ? String(rawWorkspaceId)
+        : undefined;
+    return {
+        ok: true,
+        detail: workspaceId ? `Key accepted by Clay workspace ${workspaceId}.` : "Key accepted by the Clay Public API.",
+        workspaceId,
+    };
+}
+/** Resolve Clay credentials using the standard env -> profile-scoped store ladder. */
+export function clayApiKey(env = process.env) {
+    const key = env.CLAY_API_KEY ?? getCredential("clay")?.accessToken;
+    if (key)
+        return key;
+    throw new Error('No Clay credentials. Run `clay api-keys create --name "fullstackgtm"`, then pipe the key to ' +
+        '`fullstackgtm login clay`, or set CLAY_API_KEY.');
+}

package/dist/connectors/prospectSources.d.ts

@@ -32,6 +32,18 @@ export type Prospect = {
     linkedin?: string;
     /** real work email once resolved (pipe0); never the hashed value */
     email?: string;
+    /** Validated mobile number when a contact provider explicitly returns one. */
+    mobile?: string;
+    /** Validated business direct dial when distinct from mobile. */
+    directDial?: string;
+    /** Person geography returned by identity-search providers. */
+    location?: {
+        city?: string;
+        state?: string;
+        region?: string;
+        country?: string;
+        countryCode?: string;
+    };
     /** ICP fit score 0..1, set by the acquire scorer */
     fitScore?: number;
     /** provider-native id for traceability */