fullstackgtm 0.50.1 → 0.52.0

package/src/cli/auth.ts

@@ -8,6 +8,7 @@ import { activeProfile, credentialsPath, DEFAULT_PROFILE, deleteCredential, getC
 import { activeWorkspaceProfile, readHealthTimeline, summarizeHealth } from "../health.ts";
 import { resolveLlmCredential, validateLlmKey } from "../llm.ts";
 import { createFilePlanStore, type StoredPlan } from "../planStore.ts";
+import { validateClayApiKey } from "../connectors/clay.ts";
 import { isOptionValue, numericOption, option, readPackageInfo, readSecret } from "./shared.ts";
 import { box, colorEnabled, paint, scoreColor, sparkline } from "./ui.ts";
 
@@ -346,18 +347,24 @@ export async function login(args: string[]) {
     console.log(`Logged in to Stripe. Credentials stored in ${credentialsPath()}.`);
     return;
   }
-  if (provider === "anthropic" || provider === "openai") {
+  if (provider === "anthropic" || provider === "openai" || provider === "openrouter") {
     rejectArgvSecret(args, "--token", "--key", "--api-key");
-    const key = await readSecret(`${provider} API key (${provider === "anthropic" ? "sk-ant-..." : "sk-..."})`);
+    const key = await readSecret(`${provider} API key (${provider === "anthropic" ? "sk-ant-..." : provider === "openrouter" ? "sk-or-..." : "sk-..."})`);
     if (!key) throw new Error(`No ${provider} key provided.`);
     if (!args.includes("--no-validate")) {
-      const validation = await validateLlmKey(provider, key);
-      if (!validation.ok) throw new Error(`${provider} rejected the key: ${validation.detail}`);
-      console.log(validation.detail);
+      if (provider === "openrouter") {
+        const response = await fetch("https://openrouter.ai/api/v1/key", { headers: { Authorization: `Bearer ${key}` } });
+        if (!response.ok) throw new Error(`openrouter rejected the key: ${safeStatus(response)}`);
+        console.log("Key accepted by OpenRouter.");
+      } else {
+        const validation = await validateLlmKey(provider, key);
+        if (!validation.ok) throw new Error(`${provider} rejected the key: ${validation.detail}`);
+        console.log(validation.detail);
+      }
     }
     const stamp = new Date().toISOString();
     storeCredential(provider, { kind: "api_key", accessToken: key, createdAt: stamp, updatedAt: stamp });
-    console.log(`Stored ${provider} API key in ${credentialsPath()}. \`fullstackgtm call parse\` and \`call score\` use it automatically.`);
+    console.log(`Stored ${provider} API key in ${credentialsPath()}. \`fullstackgtm icp derive\` uses it automatically${provider === "openrouter" ? "." : "; call parse/score use it too."}`);
     return;
   }
   if (provider === "apollo") {
@@ -378,6 +385,20 @@ export async function login(args: string[]) {
     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`);
@@ -393,7 +414,7 @@ export async function login(args: string[]) {
   }
   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",
+      "login supports: hubspot, salesforce, stripe, anthropic, openai, openrouter, 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();
@@ -491,6 +512,12 @@ export function doctorReport(env: Record<string, string | undefined> = process.e
     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),
+    openrouter: env.OPENROUTER_API_KEY
+      ? { source: "env", detail: "OPENROUTER_API_KEY" }
+      : providerStatus("openrouter", null),
   };
 
   const llm = resolveLlmCredential(env);
@@ -503,14 +530,14 @@ export function doctorReport(env: Record<string, string | undefined> = process.e
     }
   });
 
-  const connected = Object.entries(providers).filter(([, status]) => status.source !== "none");
+  const connectedCrm = ["hubspot", "salesforce"].filter((provider) => providers[provider].source !== "none");
   const nextSteps =
-    connected.length === 0
+    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,

package/src/cli/enrich.ts

@@ -9,6 +9,8 @@ import { createFilePlanStore } from "../planStore.ts";
 import { buildAcquirePlan, buildEnrichPlan, createFileEnrichRunStore, DEFAULT_STALE_DAYS, ENRICH_CONFIG_FILE_NAME, builtinAcquirePreset, builtinEnrichPreset, enrichRunId, inferIngestObjectType, latestStamps, loadEnrichConfig, parseCsv, resolveCrmField, selectStaleWork, stagedSourceRecords, staleDaysFor, type EnrichConfig, type EnrichCounts, type EnrichObjectType, type EnrichRun, type EnrichRunStore, type EnrichSourceRecord } from "../enrich.ts";
 import { loadMeter, remaining, type AcquireRemaining } from "../acquireMeter.ts";
 import { crmContactKeys, fetchExploriumProspects, fetchPipe0CrustdataProspectPage, partitionFreshProspects, pipe0ResolveCompanyDomains, pipe0ResolveWorkEmails, prospectIdentityKeys, type Prospect } from "../connectors/prospectSources.ts";
+import { createClaySearch, runClayPeopleSearchPage } from "../connectors/clay.ts";
+import { runContactWaterfall, type ContactProviderAdapter, type ContactWaterfallStep } from "../contactProviders.ts";
 import { loadSeen, recordSeen } from "../acquireSeen.ts";
 import { acquireCheckpointId, createFileAcquireCheckpointStore, type AcquireCheckpointKey } from "../acquireCheckpoint.ts";
 import { readHostedAcquireCheckpoint, writeHostedAcquireCheckpoint } from "../hostedAcquireCheckpoint.ts";
@@ -16,7 +18,7 @@ import { uploadHostedPatchPlan } from "../hostedPatchPlan.ts";
 import { progressReporter, reportCounts, reportEvent } from "../runReport.ts";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.ts";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.ts";
-import { fitThreshold, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
+import { fitThreshold, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloPullKey } from "../enrichApollo.ts";
 import type { CanonicalGtmSnapshot } from "../types.ts";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.ts";
@@ -217,8 +219,8 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     // 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).`,
+        `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
@@ -301,20 +303,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;
     }
 
@@ -363,24 +361,16 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         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;
   }
 
@@ -561,8 +551,9 @@ function formatEnrichCounts(counts: EnrichCounts, ambiguities: number) {
 /**
  * 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: EnrichConfig,
@@ -602,7 +593,9 @@ async function acquireFromApi(
     ? (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");
@@ -677,6 +670,19 @@ async function acquireFromApi(
       page = result.prospects;
       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;
@@ -695,7 +701,7 @@ async function acquireFromApi(
       offset += page.length;
       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);
@@ -747,23 +753,37 @@ async function acquireFromApi(
   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);
+  // 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: ContactWaterfallStep[] = disc.contactWaterfall ?? (
+    implicitPipe0 ? [{ provider: "pipe0", fields: ["work_email"] }] : []
+  );
+  if (contactWaterfall.length > 0) {
+    const adapters: Record<string, ContactProviderAdapter> = {
+      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.note(`resolving work emails for ${prospects.length} candidate(s)`);
-    const resolved = await pipe0ResolveWorkEmails({ apiKey: providerKey("pipe0"), prospects });
-    prospects.splice(0, prospects.length, ...resolved);
   }
   progress.items(prospects.length, prospects.length);
   progress.note(`${prospects.length} candidate(s) ready for planning`);
@@ -876,6 +896,61 @@ function formatAcquireMeter(headroom: AcquireRemaining, costPerRecord: number):
   );
 }
 
+function printAcquireOutput(options: {
+  args: readonly string[];
+  result: ReturnType<typeof buildAcquirePlan>;
+  meter: AcquireRemaining;
+  meterLine: string;
+  gaugeLine: string | null;
+  /** The acquisition run/checkpoint was persisted. */
+  saved: boolean;
+  /** A non-empty plan was persisted to the plan store. */
+  planSaved: boolean;
+  hostedPlanUrl: string | null;
+}): void {
+  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(): string | null {
   const baseUrl = getCredential("broker")?.baseUrl?.replace(/\/+$/, "");
   return baseUrl ? `${baseUrl}/dashboard/runs` : null;

package/src/cli/help.ts

@@ -20,13 +20,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)
@@ -76,7 +79,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
@@ -298,7 +301,7 @@ export const HELP: Record<string, HelpEntry> = {
     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).",
@@ -312,7 +315,7 @@ export const HELP: Record<string, HelpEntry> = {
       "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`.",
@@ -321,7 +324,7 @@ export const HELP: Record<string, HelpEntry> = {
   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: {
@@ -695,7 +698,7 @@ export const COMMAND_FLAGS: Record<string, string[]> = {
   merge: ["--input", "--out", "--json"],
   market: ["--category", "--config", "--vendor", "--snapshot", "--task-account", "--task-deal", "--capture-run", "--run", "--prior-run", "--diff", "--from", "--calls", "--anchor", "--min-mentions", "--max-claims", "--promote-lift", "--model", "--format", "--auto", "--unverified", "--save", "--dry-run", "--verbose", "--json", "--out"],
   tam: [...SOURCE_FLAGS, "--source", "--name", "--icp", "--accounts", "--acv", "--acv-basis", "--acv-from-crm", "--deal-period", "--buyers-per-account", "--cross-checks", "--max", "--max-credits", "--usd-per-credit", "--dry-run", "--confirm", "--cron", "--label", "--save", "--verbose", "--json", "--out"],
-  icp: [...SOURCE_FLAGS, "--name", "--signals-from", "--with-history", "--prompt", "--min-score", "--from-judge", "--golden", "--against-outcomes", "--min-accuracy", "--model", "--label", "--save", "--verbose", "--json", "--out"],
+  icp: [...SOURCE_FLAGS, "--name", "--icp", "--domain", "--no-interactive", "--signals-from", "--with-history", "--prompt", "--min-score", "--from-judge", "--golden", "--against-outcomes", "--min-accuracy", "--model", "--label", "--save", "--verbose", "--json", "--out"],
   signals: ["--bucket", "--source", "--connector", "--connector-opt", "--watchlist", "--keywords", "--from", "--label", "--since", "--account", "--contact", "--unjudged", "--touch", "--result", "--save", "--verbose", "--json", "--explain"],
   draft: ["--from-judge", "--min-score", "--prompt", "--model", "--channel", "--save", "--dry-run", "--verbose", "--json", "--out"],
   schedule: ["--cron", "--label", "--provider", "--trigger", "--timer", "--runs", "--verbose", "--json"],

package/src/cli/icp.ts

@@ -1,15 +1,20 @@
 // Extracted verbatim from src/cli.ts (mechanical split, no behavior change).
 
 import { readFileSync, writeFileSync } from "node:fs";
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
 import { resolve } from "node:path";
-import { resolveLlmCredential } from "../llm.ts";
+import { resolveLlmCredential, type LlmCallOptions } from "../llm.ts";
 import { fitThreshold, icpFromAnswers, icpToCrustdataFilters, icpToExploriumFilters, INTERVIEW_SPEC } from "../icp.ts";
 import { createFileSignalStore, DEFAULT_SIGNALS_CONFIG, type SignalsConfig } from "../signals.ts";
 import { createFileJudgeStore, DEFAULT_JUDGE_PROMPT, judgeRunId, judgeSignals } from "../judge.ts";
 import { DEFAULT_GOLDEN_NOW_ISO, DEFAULT_GOLDEN_SET, DEFAULT_MIN_ACCURACY, defaultJudgeFn, gradeAgainstOutcomes, gradeJudge, parseGoldenSet } from "../judgeEval.ts";
-import type { LlmCallOptions } from "../llm.ts";
-import { loadIcp, numericOption, option, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.ts";
+import { loadIcp, numericOption, option, readSecret, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.ts";
 import { createStatusLine } from "./ui.ts";
+import { box, colorEnabled, paint } from "./ui.ts";
+import { getCredential, storeCredential } from "../credentials.ts";
+import { deriveWebsiteIcp, icpReviewSegments, OPENROUTER_API_BASE, type WebsiteIcpDerivation } from "../icpDerive.ts";
+import type { Icp } from "../icp.ts";
 import { unknownSubcommandError } from "./suggest.ts";
 
 function renderJudgeDecisions(decisions: Awaited<ReturnType<typeof judgeSignals>>): string {
@@ -24,6 +29,110 @@ function renderJudgeDecisions(decisions: Awaited<ReturnType<typeof judgeSignals>
   return lines.join("\n");
 }
 
+function updateReviewSegment(icp: Icp, id: string, raw: string): Icp {
+  const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
+  if (id === "threshold") return { ...icp, scoring: { ...icp.scoring, threshold: Number(raw) } };
+  if (["industries", "employeeBands", "geos", "technologies"].includes(id)) {
+    return { ...icp, firmographics: { ...icp.firmographics, [id]: values } };
+  }
+  if (["titleKeywords", "jobLevels", "departments"].includes(id)) {
+    return { ...icp, persona: { ...icp.persona, [id]: values } };
+  }
+  return { ...icp, signals: { ...icp.signals, intentTopics: values } };
+}
+
+function renderDerivedIcp(result: WebsiteIcpDerivation, selected = -1): string {
+  const p = paint(colorEnabled());
+  const segments = icpReviewSegments(result.icp);
+  const lines = [
+    `${result.company.name}  ${result.company.domain}`,
+    `${Math.round(result.confidence * 100)}% confidence · ${result.derivation.model}`,
+    "",
+    ...segments.map((segment, index) => `${index === selected ? "›" : " "} ${segment.label.padEnd(15)} ${segment.value}`),
+    "",
+    selected >= 0 ? "↑/↓ select · enter edit · s save · q cancel" : `${result.evidence.length} website-verifiable evidence quote(s)`,
+  ];
+  return box(lines, p, "ICP preview").join("\n");
+}
+
+async function resolveIcpDeriveLlm(args: string[]): Promise<LlmCallOptions> {
+  const requested = option(args, "--provider")?.toLowerCase();
+  if (requested && !["openrouter", "openai", "anthropic"].includes(requested)) {
+    throw new Error(`icp derive --provider must be openrouter, openai, or anthropic; got "${requested}".`);
+  }
+  const openRouterKey = process.env.OPENROUTER_API_KEY ?? getCredential("openrouter")?.accessToken;
+  const normal = resolveLlmCredential();
+  if ((!requested || requested === "openrouter") && openRouterKey) {
+    return { provider: "openai", apiKey: openRouterKey, openaiBaseUrl: OPENROUTER_API_BASE };
+  }
+  if (requested === "openai" || requested === "anthropic") {
+    const envKey = requested === "openai" ? process.env.OPENAI_API_KEY : process.env.ANTHROPIC_API_KEY;
+    const key = envKey ?? getCredential(requested)?.accessToken;
+    if (key) return { provider: requested, apiKey: key, ...resolveLlmBaseUrls() };
+  }
+  if (normal && (!requested || requested === normal.provider)) return { ...normal, ...resolveLlmBaseUrls() };
+  const provider = requested as "openrouter" | "openai" | "anthropic" | undefined;
+  if (!process.stdin.isTTY || process.env.CI) {
+    throw new Error(
+      "ICP derivation needs an LLM key. Run one of:\n" +
+      "  fullstackgtm login openrouter\n  fullstackgtm login openai\n  fullstackgtm login anthropic\n" +
+      "Then rerun the same icp derive command.",
+    );
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const answer = provider ?? ((await rl.question("LLM provider [openrouter/openai/anthropic] (openrouter): ")).trim().toLowerCase() || "openrouter");
+  rl.close();
+  if (!['openrouter', 'openai', 'anthropic'].includes(answer)) throw new Error(`Unknown LLM provider "${answer}".`);
+  const selectedProvider = answer as "openrouter" | "openai" | "anthropic";
+  const key = await readSecret(`${selectedProvider} API key`);
+  if (!key) throw new Error(`No ${answer} API key provided.`);
+  const now = new Date().toISOString();
+  storeCredential(selectedProvider, { kind: "api_key", accessToken: key, createdAt: now, updatedAt: now });
+  console.error(`Stored ${selectedProvider} key in the active FullStackGTM profile.`);
+  return selectedProvider === "openrouter"
+    ? { provider: "openai", apiKey: key, openaiBaseUrl: OPENROUTER_API_BASE }
+    : { provider: selectedProvider, apiKey: key };
+}
+
+async function reviewDerivedIcp(result: WebsiteIcpDerivation): Promise<WebsiteIcpDerivation | null> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return result;
+  let current = result;
+  let selected = 0;
+  const render = () => process.stdout.write(`\u001b[2J\u001b[H${renderDerivedIcp(current, selected)}\n`);
+  emitKeypressEvents(process.stdin);
+  process.stdin.setRawMode?.(true);
+  process.stdin.resume();
+  render();
+  return new Promise((resolveReview) => {
+    const finish = (value: WebsiteIcpDerivation | null) => {
+      process.stdin.off("keypress", onKey);
+      process.stdin.setRawMode?.(false);
+      process.stdin.pause();
+      resolveReview(value);
+    };
+    const onKey = async (_input: string, key: { name?: string; ctrl?: boolean }) => {
+      const segments = icpReviewSegments(current.icp);
+      if (key.ctrl && key.name === "c" || key.name === "q") return finish(null);
+      if (key.name === "up") { selected = (selected - 1 + segments.length) % segments.length; return render(); }
+      if (key.name === "down") { selected = (selected + 1) % segments.length; return render(); }
+      if (key.name === "s") return finish(current);
+      if (key.name !== "return") return;
+      process.stdin.off("keypress", onKey);
+      process.stdin.setRawMode?.(false);
+      const segment = segments[selected];
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      const answer = await rl.question(`\n${segment.label} [${segment.value}]: `);
+      rl.close();
+      if (answer.trim()) current = { ...current, icp: updateReviewSegment(current.icp, segment.id, answer) };
+      emitKeypressEvents(process.stdin);
+      process.stdin.setRawMode?.(true);
+      process.stdin.on("keypress", onKey);
+      render();
+    };
+    process.stdin.on("keypress", onKey);
+  });
+}
+
 
 /**
  * `icp` — develop and inspect the Ideal Customer Profile that targets acquire.
@@ -38,6 +147,8 @@ export async function icpCommand(args: string[]) {
   if (!sub || args.includes("--help") || args.includes("-h")) {
     console.log(`Usage:
   fullstackgtm icp interview                      emit the interview spec (an agent drives it with AskUserQuestion)
+  fullstackgtm icp derive --domain <site> [--model <id>] [--out icp.json] [--json]
+                                                derive an evidence-backed ICP from a public website (OpenRouter/OpenAI/Anthropic)
   fullstackgtm icp set <answers.json> [--name <n>] [--out <path>]   write icp.json from interview answers
   fullstackgtm icp show [--icp <path>]            render the ICP + the discovery filters it produces
   fullstackgtm icp judge [--signals-from latest|<label>] [--with-history] [--prompt <path>] [--min-score 0] [--save]   rank unjudged signals into send/nurture/skip decisions (timing x fit x memory)
@@ -65,6 +176,36 @@ ops. Develop one by interview, then \`enrich acquire\` picks up ./icp.json.
     );
     return;
   }
+  if (sub === "derive") {
+    const domain = option(rest, "--domain");
+    if (!domain) throw new Error("Usage: fullstackgtm icp derive --domain <company.com> [--out icp.json] [--json]");
+    const llm = await resolveIcpDeriveLlm(rest);
+    const status = createStatusLine();
+    let derived: WebsiteIcpDerivation;
+    try {
+      derived = await deriveWebsiteIcp({
+        domain,
+        llm,
+        model: option(rest, "--model") ?? undefined,
+        onProgress: (event) => status.set(event.message),
+      });
+    } finally {
+      status.done();
+    }
+    if (!rest.includes("--json") && !rest.includes("--no-interactive")) {
+      const reviewed = await reviewDerivedIcp(derived);
+      if (!reviewed) throw new Error("ICP review cancelled; no file was written.");
+      derived = reviewed;
+    }
+    const out = option(rest, "--out");
+    if (out) {
+      const path = resolve(process.cwd(), out);
+      writeFileSync(path, `${JSON.stringify(derived.icp, null, 2)}\n`);
+      console.error(`Wrote reviewed ICP to ${path}. Next: fullstackgtm enrich acquire --source clay --icp ${path}`);
+    }
+    console.log(rest.includes("--json") ? JSON.stringify(derived, null, 2) : renderDerivedIcp(derived));
+    return;
+  }
   if (sub === "set") {
     const file = rest.find((a) => !a.startsWith("--"));
     if (!file) throw new Error("Usage: fullstackgtm icp set <answers.json> [--name <n>] [--out <path>]");

package/src/cli/init.ts

@@ -16,7 +16,7 @@ import { option } from "./shared.ts";
 export function initCommand(args: string[]) {
   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\`)
@@ -28,8 +28,8 @@ docs/recipes.md for the full play set. Existing files are kept unless --force.`)
     return;
   }
   const source = (option(args, "--source") ?? "pipe0") as InitSource;
-  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") as InitProvider;
   if (!["hubspot", "salesforce"].includes(provider)) {