fullstackgtm 0.54.0 → 0.55.1

package/dist/index.d.ts

@@ -54,6 +54,7 @@ export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl,
 export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, type CronExpression, type CrontabIo, type ScheduleEntry, type ScheduleProvider, type ScheduleRunRecord, type ScheduleRunStore, type ScheduleRunTrigger, type ScheduleStore, } from "./schedule.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export { buildSignalsFromAts, computeWeights, createFileSignalStore, DEFAULT_SIGNALS_CONFIG, dedupKey, dedupeSignals, loadSignalsConfig, makeOutcome, normalizeAccountDomain, parseSignalsConfig, recencyFactor, SIGNAL_BUCKETS, SIGNALS_CONFIG_FILE_NAME, signalId, signalRunId, signalsDir, signalWeight, type Signal, type SignalBucket, type SignalBucketConfig, type SignalOutcome, type SignalOutcomeResult, type SignalRun, type SignalsConfig, type SignalStore, } from "./signals.ts";
+export { DEFAULT_DISCOVERY_ATS_DOMAINS, discoverSignalsWithExa, exaQueryForHypothesis, parseJobIdentity, triggerHypothesesForIcp, type DiscoverSignalsOptions, type EvidenceCandidate, type SignalDiscoveryResult, type SignalDiscoverySummary, } from "./signalDiscovery.ts";
 export { fetchAtsJobs, snippetFor, type AtsBoardSource, type AtsJob, } from "./connectors/atsBoards.ts";
 export { scoreBand, judgeRunId, normalizeSpan, isGroundedSpan, scoreAccount, accountRecentlyTouched, bestContactForAccount, deterministicDecision, deterministicWhyNow, JUDGE_SCHEMA, DEFAULT_JUDGE_PROMPT, judgeDecisionLlm, judgeSignals, judgeDir, createFileJudgeStore, type JudgeDecisionKind, type JudgeDecision, type JudgeRun, type JudgeBand, type AccountScore, type JudgeStore, } from "./judge.ts";
 export { draft, authorOpeners, draftOpenerLlm, deterministicOpener, creditedTriggerSignal, draftEvidence, sanitizeOpener, firstLine, firstLineGroundedInTrigger, hasBannedGreeting, isStaleTrigger, draftOperationId, draftEvidenceId, DRAFT_CHANNELS, DRAFT_SCHEMA, DEFAULT_DRAFT_PROMPT, DEFAULT_FRESHNESS_DAYS, type Draft, type RejectedDraft, type DraftResult, type DraftChannel, } from "./draft.ts";

package/dist/index.js

@@ -54,6 +54,7 @@ export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl,
 export { computeMissedFirings, createFileScheduleRunStore, createFileScheduleStore, cronMatches, crontabSentinels, expectedFirings, nextCronFiring, parseCron, renderManagedBlock, replaceManagedBlock, scheduleId, scheduleRunsDir, schedulesPath, systemCrontabIo, tokenizeCommand, validateSchedulableArgv, } from "./schedule.js";
 export { suggestValues } from "./suggest.js";
 export { buildSignalsFromAts, computeWeights, createFileSignalStore, DEFAULT_SIGNALS_CONFIG, dedupKey, dedupeSignals, loadSignalsConfig, makeOutcome, normalizeAccountDomain, parseSignalsConfig, recencyFactor, SIGNAL_BUCKETS, SIGNALS_CONFIG_FILE_NAME, signalId, signalRunId, signalsDir, signalWeight, } from "./signals.js";
+export { DEFAULT_DISCOVERY_ATS_DOMAINS, discoverSignalsWithExa, exaQueryForHypothesis, parseJobIdentity, triggerHypothesesForIcp, } from "./signalDiscovery.js";
 export { fetchAtsJobs, snippetFor, } from "./connectors/atsBoards.js";
 export { scoreBand, judgeRunId, normalizeSpan, isGroundedSpan, scoreAccount, accountRecentlyTouched, bestContactForAccount, deterministicDecision, deterministicWhyNow, JUDGE_SCHEMA, DEFAULT_JUDGE_PROMPT, judgeDecisionLlm, judgeSignals, judgeDir, createFileJudgeStore, } from "./judge.js";
 export { draft, authorOpeners, draftOpenerLlm, deterministicOpener, creditedTriggerSignal, draftEvidence, sanitizeOpener, firstLine, firstLineGroundedInTrigger, hasBannedGreeting, isStaleTrigger, draftOperationId, draftEvidenceId, DRAFT_CHANNELS, DRAFT_SCHEMA, DEFAULT_DRAFT_PROMPT, DEFAULT_FRESHNESS_DAYS, } from "./draft.js";

package/dist/schedule.js

@@ -38,18 +38,18 @@ const SCHEDULABLE = {
     // approved). So scheduled acquire accumulates proposals, never surprise leads.
     enrich: ["append", "refresh", "acquire"],
     market: ["capture", "refresh"],
-    // The GTM brain. `signals fetch` is read-only re: CRM (--save persists only
+    // The GTM brain. `signals fetch|discover` are read-only re: CRM (--save persists only
     // the local signal ledger). `icp judge`/`icp eval` are read-only/grade-only
     // (--save writes only the local judge store, never a plan). `draft` is
     // plan-side — it only stages a needs_approval plan, never applies — so the
     // whole verb is safely schedulable (apply stays `apply --plan-id` only and
     // re-checks `approved` at run time, so a scheduled draft still cannot send).
-    signals: ["fetch"],
+    signals: ["fetch", "discover"],
     icp: ["judge", "eval"],
     draft: null,
 };
 const ALLOWLIST_SUMMARY = "audit, snapshot, enrich append|refresh, enrich acquire --save (stages a lead plan), " +
-    "market capture|refresh, signals fetch, icp judge|eval, draft (stages a plan), " +
+    "market capture|refresh, signals fetch|discover, icp judge|eval, draft (stages a plan), " +
     "suggest, report, doctor — plus apply --plan-id <id> (re-checked approved at every firing)";
 /**
  * Validate that an argv resolves to a schedulable fullstackgtm command.

package/dist/signalDiscovery.d.ts

@@ -0,0 +1,52 @@
+import type { Icp, TriggerHypothesis } from "./icp.ts";
+import { type Signal, type SignalsConfig } from "./signals.ts";
+export declare const DEFAULT_DISCOVERY_ATS_DOMAINS: string[];
+export type EvidenceCandidate = {
+    hypothesisId: string;
+    hypothesisLabel: string;
+    companyName: string;
+    jobTitle: string;
+    sourceUrl: string;
+    quote: string;
+    publishedAt?: string;
+    accountDomain?: string;
+};
+export type SignalDiscoverySummary = {
+    provider: "exa";
+    readOnly: true;
+    searchesUsed: number;
+    searchLimit: number;
+    costUsd: number;
+    costLimitUsd: number;
+    rawResults: number;
+    matchedEvidence: number;
+    resolvedAccounts: number;
+    unresolvedAccounts: number;
+    warnings: string[];
+};
+export type SignalDiscoveryResult = {
+    summary: SignalDiscoverySummary;
+    candidates: EvidenceCandidate[];
+    signals: Signal[];
+};
+export type DiscoverSignalsOptions = {
+    icp: Icp;
+    apiKey: string;
+    since: Date;
+    maxAccounts: number;
+    maxResults: number;
+    maxSearches: number;
+    maxUsd: number;
+    now?: Date;
+    config?: SignalsConfig;
+    fetch?: typeof globalThis.fetch;
+    apiBaseUrl?: string;
+};
+/** Explicit hypotheses win; intent topics remain a backwards-compatible fallback. */
+export declare function triggerHypothesesForIcp(icp: Icp): TriggerHypothesis[];
+export declare function exaQueryForHypothesis(hypothesis: TriggerHypothesis): string;
+export declare function parseJobIdentity(rawTitle: string, sourceUrl?: string): {
+    companyName: string;
+    jobTitle: string;
+} | null;
+export declare function discoverSignalsWithExa(options: DiscoverSignalsOptions): Promise<SignalDiscoveryResult>;

package/dist/signalDiscovery.js

@@ -0,0 +1,235 @@
+import { DEFAULT_SIGNALS_CONFIG, normalizeAccountDomain, signalId, signalWeight, } from "./signals.js";
+export const DEFAULT_DISCOVERY_ATS_DOMAINS = [
+    "job-boards.greenhouse.io",
+    "boards.greenhouse.io",
+    "jobs.lever.co",
+    "jobs.ashbyhq.com",
+    "jobs.smartrecruiters.com",
+    "apply.workable.com",
+];
+const NON_COMPANY_DOMAINS = new Set([
+    ...DEFAULT_DISCOVERY_ATS_DOMAINS,
+    "linkedin.com", "facebook.com", "instagram.com", "x.com", "twitter.com",
+    "crunchbase.com", "wikipedia.org", "glassdoor.com", "indeed.com",
+]);
+const STOP_WORDS = new Set(["about", "after", "before", "company", "could", "from", "hiring", "into", "their", "there", "these", "they", "this", "with", "your"]);
+function strings(value, max = 12) {
+    return [...new Set((Array.isArray(value) ? value : []).filter((v) => typeof v === "string")
+            .map((v) => v.replace(/\s+/g, " ").trim()).filter(Boolean))].slice(0, max);
+}
+function slug(value, fallback) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || fallback;
+}
+/** Explicit hypotheses win; intent topics remain a backwards-compatible fallback. */
+export function triggerHypothesesForIcp(icp) {
+    const explicit = icp.signals?.triggerHypotheses ?? [];
+    const valid = explicit.map((item, index) => ({
+        id: slug(item.id || item.label, `trigger-${index + 1}`),
+        label: item.label?.trim(),
+        positiveEvidence: strings(item.positiveEvidence),
+        activeProjects: strings(item.activeProjects),
+        buyerFunctions: strings(item.buyerFunctions),
+        negativeEvidence: strings(item.negativeEvidence),
+        preferredSources: item.preferredSources,
+    })).filter((item) => item.label && (item.positiveEvidence.length || item.activeProjects.length));
+    if (valid.length)
+        return valid;
+    const topics = strings(icp.signals?.intentTopics);
+    if (topics.length) {
+        return [{ id: "intent-topics", label: topics.join(" or "), positiveEvidence: topics, preferredSources: ["job"] }];
+    }
+    throw new Error("signals discover: the ICP has no behavioral trigger hypotheses. Add signals.triggerHypotheses (or intentTopics), or regenerate it with `fullstackgtm icp derive --domain <domain>`.");
+}
+function evidenceTerms(hypothesis) {
+    return strings([...(hypothesis.positiveEvidence ?? []), ...(hypothesis.activeProjects ?? []), ...(hypothesis.buyerFunctions ?? [])], 20);
+}
+export function exaQueryForHypothesis(hypothesis) {
+    const terms = evidenceTerms(hypothesis).slice(0, 8).map((v) => `"${v.replace(/"/g, "")}"`);
+    return `recent company job posting showing ${hypothesis.label}${terms.length ? ` (${terms.join(" OR ")})` : ""}`;
+}
+function words(value) {
+    return value.toLowerCase().match(/[a-z0-9]+/g)?.filter((word) => word.length >= 4 && !STOP_WORDS.has(word)) ?? [];
+}
+function evidenceMatches(text, hypothesis) {
+    const hay = text.toLowerCase();
+    if ((hypothesis.negativeEvidence ?? []).some((term) => term && hay.includes(term.toLowerCase())))
+        return false;
+    const terms = evidenceTerms(hypothesis);
+    if (terms.some((term) => term && hay.includes(term.toLowerCase())))
+        return true;
+    const significant = [...new Set(terms.flatMap(words))];
+    return significant.filter((term) => hay.includes(term)).length >= 2;
+}
+function cleanTitle(value) {
+    return value.replace(/\s+/g, " ").replace(/\s*[|–—-]\s*(Greenhouse|Lever|Ashby|SmartRecruiters|Workable).*$/i, "").trim();
+}
+export function parseJobIdentity(rawTitle, sourceUrl) {
+    const title = cleanTitle(rawTitle);
+    const application = /^Job Application for (.+?) at (.+)$/i.exec(title);
+    if (application)
+        return { jobTitle: application[1].trim(), companyName: application[2].trim() };
+    const at = /^(.+?)\s+(?:at|@)\s+(.+)$/i.exec(title);
+    if (at)
+        return { jobTitle: at[1].trim(), companyName: at[2].trim() };
+    const dash = /^(.+?)\s+[–—-]\s+(.+)$/.exec(title);
+    if (dash)
+        return { companyName: dash[1].trim(), jobTitle: dash[2].trim() };
+    if (sourceUrl && title) {
+        try {
+            const parts = new URL(sourceUrl).pathname.split("/").filter(Boolean);
+            const boardSlug = parts.find((part) => !["jobs", "job", "positions", "posting"].includes(part.toLowerCase()) && !/^\d+$/.test(part));
+            if (boardSlug)
+                return { companyName: decodeURIComponent(boardSlug).replace(/[-_]+/g, " ").trim(), jobTitle: title };
+        }
+        catch { /* source URL validation happens separately */ }
+    }
+    return null;
+}
+function safeHostname(raw) {
+    try {
+        return normalizeAccountDomain(new URL(raw).hostname);
+    }
+    catch {
+        return "";
+    }
+}
+function isExcludedDomain(domain) {
+    return [...NON_COMPANY_DOMAINS].some((excluded) => domain === excluded || domain.endsWith(`.${excluded}`));
+}
+function companyMatches(companyName, resultTitle, url) {
+    const companyWords = words(companyName);
+    const candidate = `${resultTitle} ${safeHostname(url).split(".")[0]}`.toLowerCase();
+    return companyWords.length > 0 && companyWords.some((word) => candidate.includes(word));
+}
+function finiteCost(response) {
+    const total = response.costDollars?.total;
+    return typeof total === "number" && Number.isFinite(total) && total >= 0 ? total : 0;
+}
+async function exaSearch(args) {
+    let response;
+    try {
+        response = await args.fetch(`${args.apiBaseUrl.replace(/\/$/, "")}/search`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "x-api-key": args.apiKey },
+            body: JSON.stringify(args.body),
+        });
+    }
+    catch (error) {
+        throw new Error(`signals discover: could not reach Exa (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (!response.ok) {
+        if (response.status === 401 || response.status === 403) {
+            throw new Error("signals discover: Exa rejected the API key. Run `fullstackgtm login exa` and try again.");
+        }
+        if (response.status === 429)
+            throw new Error("signals discover: Exa rate limit reached; retry later or lower --max-searches.");
+        throw new Error(`signals discover: Exa search failed (HTTP ${response.status}).`);
+    }
+    return await response.json();
+}
+function resultRows(response) {
+    return Array.isArray(response.results) ? response.results.filter((row) => Boolean(row && typeof row === "object")) : [];
+}
+function firstQuote(result, title) {
+    const highlights = strings(result.highlights, 4);
+    return (highlights.find((value) => value.length >= 20) ?? highlights[0] ?? title).slice(0, 600);
+}
+export async function discoverSignalsWithExa(options) {
+    if (!options.apiKey.trim())
+        throw new Error("signals discover: missing Exa API key. Set EXA_API_KEY or run `fullstackgtm login exa`.");
+    if (!Number.isInteger(options.maxSearches) || options.maxSearches < 1)
+        throw new Error("signals discover: --max-searches must be a positive integer.");
+    if (!Number.isInteger(options.maxAccounts) || options.maxAccounts < 1)
+        throw new Error("signals discover: --max-accounts must be a positive integer.");
+    if (!Number.isInteger(options.maxResults) || options.maxResults < 1)
+        throw new Error("signals discover: --max-results must be a positive integer.");
+    if (!Number.isFinite(options.maxUsd) || options.maxUsd <= 0)
+        throw new Error("signals discover: --max-usd must be greater than zero.");
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const apiBaseUrl = options.apiBaseUrl ?? process.env.EXA_API_BASE_URL ?? "https://api.exa.ai";
+    const hypotheses = triggerHypothesesForIcp(options.icp).filter((h) => !h.preferredSources?.length || h.preferredSources.includes("job"));
+    if (!hypotheses.length)
+        throw new Error("signals discover: no trigger hypothesis allows the currently supported `job` source.");
+    const now = options.now ?? new Date();
+    const config = options.config ?? DEFAULT_SIGNALS_CONFIG;
+    const warnings = [];
+    let searchesUsed = 0;
+    let costUsd = 0;
+    let rawResults = 0;
+    const found = [];
+    const seenUrls = new Set();
+    const canSearch = () => searchesUsed < options.maxSearches && costUsd < options.maxUsd;
+    for (const hypothesis of hypotheses) {
+        if (!canSearch() || rawResults >= options.maxResults)
+            break;
+        const remaining = options.maxResults - rawResults;
+        const response = await exaSearch({ apiKey: options.apiKey, fetch: fetchImpl, apiBaseUrl, body: {
+                query: exaQueryForHypothesis(hypothesis),
+                includeDomains: DEFAULT_DISCOVERY_ATS_DOMAINS,
+                startCrawlDate: options.since.toISOString(),
+                numResults: Math.min(25, remaining),
+                contents: { highlights: { maxCharacters: 1200 } },
+            } });
+        searchesUsed += 1;
+        costUsd += finiteCost(response);
+        const rows = resultRows(response);
+        rawResults += rows.length;
+        for (const row of rows) {
+            const title = typeof row.title === "string" ? row.title.trim() : "";
+            const sourceUrl = typeof row.url === "string" ? row.url.trim() : "";
+            if (!title || !sourceUrl || seenUrls.has(sourceUrl) || !DEFAULT_DISCOVERY_ATS_DOMAINS.some((domain) => safeHostname(sourceUrl).endsWith(domain)))
+                continue;
+            const identity = parseJobIdentity(title, sourceUrl);
+            if (!identity)
+                continue;
+            const quote = firstQuote(row, title);
+            if (!evidenceMatches(`${title} ${quote}`, hypothesis))
+                continue;
+            seenUrls.add(sourceUrl);
+            found.push({ hypothesisId: hypothesis.id, hypothesisLabel: hypothesis.label, companyName: identity.companyName,
+                jobTitle: identity.jobTitle, sourceUrl, quote,
+                ...(typeof row.publishedDate === "string" && Number.isFinite(Date.parse(row.publishedDate)) ? { publishedAt: new Date(row.publishedDate).toISOString() } : {}) });
+        }
+    }
+    const companyNames = [...new Set(found.map((item) => item.companyName))].slice(0, options.maxAccounts);
+    const domainByCompany = new Map();
+    for (const companyName of companyNames) {
+        if (!canSearch())
+            break;
+        const response = await exaSearch({ apiKey: options.apiKey, fetch: fetchImpl, apiBaseUrl, body: {
+                query: `${companyName} official company website`, category: "company", numResults: 3,
+            } });
+        searchesUsed += 1;
+        costUsd += finiteCost(response);
+        const match = resultRows(response).find((row) => {
+            const url = typeof row.url === "string" ? row.url : "";
+            const domain = safeHostname(url);
+            return domain && !isExcludedDomain(domain) && companyMatches(companyName, typeof row.title === "string" ? row.title : "", url);
+        });
+        if (match && typeof match.url === "string")
+            domainByCompany.set(companyName, safeHostname(match.url));
+    }
+    for (const item of found)
+        item.accountDomain = domainByCompany.get(item.companyName);
+    const resolved = found.filter((item) => item.accountDomain).slice(0, options.maxAccounts);
+    if (searchesUsed >= options.maxSearches && (hypotheses.length > 1 || domainByCompany.size < companyNames.length)) {
+        warnings.push(`Search limit reached (${options.maxSearches}); some evidence or company domains were not resolved.`);
+    }
+    if (costUsd >= options.maxUsd)
+        warnings.push(`Reported Exa cost reached the $${options.maxUsd.toFixed(2)} budget; no further requests were made.`);
+    const nowIso = now.toISOString();
+    const signals = resolved.map((item) => {
+        const base = { accountDomain: item.accountDomain, bucket: "job", trigger: `evidence: ${item.hypothesisLabel} — ${item.jobTitle}` };
+        return { ...base, id: signalId(base), quote: item.quote, sourceUrl: item.sourceUrl, firstSeen: nowIso,
+            weight: signalWeight({ bucketWeight: config.buckets.job.weight, firstSeen: nowIso, now,
+                windowDays: config.dedupWindowDays, repostedRoleBoost: config.repostedRoleBoost }),
+            source: "exa", judgedBy: null, roleKey: item.sourceUrl, hypothesisId: item.hypothesisId,
+            companyName: item.companyName, ...(item.publishedAt ? { publishedAt: item.publishedAt } : {}) };
+    });
+    const roundedCost = Math.round(costUsd * 1_000_000) / 1_000_000;
+    return { summary: { provider: "exa", readOnly: true, searchesUsed, searchLimit: options.maxSearches,
+            costUsd: roundedCost, costLimitUsd: options.maxUsd, rawResults, matchedEvidence: found.length,
+            resolvedAccounts: new Set(signals.map((s) => s.accountDomain)).size,
+            unresolvedAccounts: new Set(found.filter((item) => !item.accountDomain).map((item) => item.companyName)).size, warnings },
+        candidates: found, signals };
+}

package/dist/signals.d.ts

@@ -47,6 +47,10 @@ export type Signal = {
      * id under the same title) from one continuously-open req. job-bucket only.
      */
     roleKey?: string;
+    /** Optional provenance carried by evidence-first discovery. */
+    hypothesisId?: string;
+    companyName?: string;
+    publishedAt?: string;
 };
 export type SignalOutcomeResult = "replied" | "meeting" | "bounced" | "no_reply";
 export type SignalOutcome = {

package/docs/api.md

@@ -126,7 +126,7 @@ Four flags name "where data comes from / goes to"; they are not interchangeable:
 | Flag | Meaning | Values |
 |---|---|---|
 | `--provider` | The CRM the data lives in — the system a snapshot is read from and an approved plan is applied to. | `hubspot`, `salesforce` (plus `stripe`, read-only) |
-| `--source` | The external data source feeding a verb: an enrichment/discovery vendor on `enrich`/`tam` (`--source apollo`, `acquire --source pipe0`), a staged-ingest label on `enrich ingest`, or — on `signals fetch` — which no-auth ATS board adapters to scan. | `apollo`, `clay`, `pipe0`, `explorium`, `theirstack`, `linkedin` (HeyReach); `greenhouse` / `lever` / `ashby` on `signals fetch` |
+| `--source` | The external data source feeding a verb: an enrichment/discovery vendor on `enrich`/`tam` (`--source apollo`, `acquire --source pipe0`), a staged-ingest label on `enrich ingest`, on `signals fetch` which no-auth ATS board adapters to scan, or `exa` on `signals discover`. | `apollo`, `clay`, `pipe0`, `explorium`, `theirstack`, `linkedin` (HeyReach), `exa`; `greenhouse` / `lever` / `ashby` on `signals fetch` |
 | `--connector` | A signal-intake source connector on `signals fetch`: pulls candidate signals from a connected platform or the local webhook spool into the signal ledger. | `file`, `serpapi-news`, `hubspot-forms` |
 | `--channel` | Where a plan's output is delivered. On `apply`, the delivery terminus — a plan applies to `--provider <crm>` *or* `--channel outbox` (render approved openers to a local outbox file; transmits nothing), never both. On `draft`, which outreach channel the opener is drafted for (shapes the emitted op). | `apply`: `outbox` · `draft`: `email`, `linkedin`, `task` |
 
@@ -136,7 +136,7 @@ Additive; every legacy flag keeps working:
 
 - `--dry-run` — accepted on the plan-spine verbs (`audit`, `suggest`,
   `bulk-update`, `dedupe`, `reassign`, `fix`, `call plan`,
-  `enrich append`/`refresh`/`acquire`, `signals fetch`, `icp judge`, `draft`,
+  `enrich append`/`refresh`/`acquire`, `signals fetch`/`discover`, `icp judge`, `draft`,
   `tam status`, `market overlay`). These verbs are already preview-by-default
   (plans are dry-run; nothing writes to a CRM outside approve → apply), so the
   flag asserts that default rather than changing it: it additionally suppresses

package/llms.txt

@@ -190,7 +190,10 @@ file/serpapi-news/hubspot-forms with secrets through the credential ladder; and
 push platforms via the webhook spool — `--connector file` reads the conventional
 landing zone `<home>/signals/spool/*.jsonl`, see docs/signal-spool-format.md),
 keyed by **account domain**, ranked by learned `weights`; it writes NOTHING to
-the CRM. `icp interview|set|show`
+the CRM. `signals discover` starts from editable ICP behavioral hypotheses,
+searches canonical public ATS evidence through Exa with explicit request and
+reported-cost limits, resolves official employer domains, and writes NOTHING
+unless `--save` persists the local signal ledger. `icp interview|set|show`
 builds `icp.json`; `icp judge` ranks fresh signals into send/nurture/skip — pass
 a snapshot (`--provider`/`--input`/`--demo`) and each decision resolves its CRM
 target: `accountId`, the best `contact {id,email,title}`, and `contacts[]` (all
@@ -216,7 +219,7 @@ surfaced at every hop, so the loop is contact-coherent end to end — see the
 `fullstackgtm schedule` is the horizontal scheduler — no feature namespace
 owns cron logic. `add "<command>" --cron "<expr>"` validates the command
 against the read/plan-side allowlist (audit, snapshot, enrich append|refresh,
-enrich acquire --save, market capture|refresh, signals fetch, icp judge|eval,
+enrich acquire --save, market capture|refresh, signals fetch|discover, icp judge|eval,
 draft, suggest, report, doctor) and the 5-field cron
 expression, but touches no system timer; `install` materializes enabled
 entries into the platform timer (`--timer` defaults launchd on macOS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.54.0",
+  "version": "0.55.1",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/skills/fullstackgtm/SKILL.md

@@ -64,7 +64,7 @@ credentials AND stored plans per client org.
 | `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
 | `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
 | `enrich acquire [--source explorium\|pipe0\|linkedin] [--max <new>] [--scan-limit <raw>]` | Net-new ICP-targeted lead gen: independent per-provider/list/query checkpoints traverse full audiences instead of rereading page one; paired CLIs CAS-sync opaque, non-PII continuation to the hosted org; resolve-first deduped `create_record` plans, meter-capped and owner-stamped; `enrich status --runs` exposes funnel + continuation; never auto-writes |
-| `signals fetch\|list\|outcome\|weights` | Detect-side timing layer: capture fresh buying triggers into a profile-scoped ledger (free Greenhouse/Lever/Ashby ATS in the box; `--from` staged files; `--connector file\|serpapi-news\|hubspot-forms` to pull connected platforms / read the webhook spool `<home>/signals/spool`, secrets via the credential ladder), ranked by learned weights. Writes NOTHING to the CRM; `outcome --account <domain> --contact <id> --result …` re-weights which triggers earn a touch |
+| `signals fetch\|discover\|list\|outcome\|weights` | Detect-side timing layer: capture fresh buying triggers into a profile-scoped ledger (free Greenhouse/Lever/Ashby watchlist scans; Exa-backed ICP behavioral evidence discovery; `--from` staged files; `--connector file\|serpapi-news\|hubspot-forms` to pull connected platforms / read the webhook spool `<home>/signals/spool`, secrets via the credential ladder), ranked by learned weights. Writes NOTHING to the CRM; `outcome --account <domain> --contact <id> --result …` re-weights which triggers earn a touch |
 | `icp interview\|set\|show\|judge\|eval` | Build the ICP, then `judge` ranks fresh signals into send/nurture/skip — pass a snapshot (`--provider`/`--input`) and each decision resolves its CRM target (`accountId` + the `contact`/`contacts` to reach). `eval` is the calibration gate (exit 2 below the bar) |
 | `draft [--from-judge latest] [--channel email\|linkedin\|task]` | One trigger-grounded opener per hot account → a governed `create_task` targeting the resolved `contact.id` (or `accountId`); rejects a domain-only decision ("acquire it first"). **Never sends** — after `plans approve`, `apply --provider <crm>` logs it as a CRM task, or `apply --channel outbox` renders it to `<home>/signals/outbox/<channel>.jsonl` for a downstream sender to drain; the CLI transmits nothing |
 | `market init\|capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |

package/src/cli/auth.ts

@@ -399,7 +399,7 @@ export async function login(args: string[]) {
     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") {
+  if (provider === "pipe0" || provider === "explorium" || provider === "heyreach" || provider === "theirstack" || provider === "exa") {
     rejectArgvSecret(args, "--token", "--key", "--api-key");
     const key = await readSecret(`${provider} API key`);
     if (!key) throw new Error(`No ${provider} key provided.`);
@@ -408,13 +408,14 @@ export async function login(args: string[]) {
     const stamp = new Date().toISOString();
     storeCredential(provider, { kind: "api_key", accessToken: key, createdAt: stamp, updatedAt: stamp });
     const usedBy =
-      provider === "theirstack" ? "`fullstackgtm tam estimate --source theirstack`" : "`fullstackgtm enrich acquire`";
+      provider === "theirstack" ? "`fullstackgtm tam estimate --source theirstack`" :
+      provider === "exa" ? "`fullstackgtm signals discover`" : "`fullstackgtm enrich acquire`";
     console.log(`Stored ${provider} API key in ${credentialsPath()}. ${usedBy} uses it automatically (validated on first pull).`);
     return;
   }
   if (provider !== "hubspot") {
     throw new Error(
-      "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",
+      "login supports: hubspot, salesforce, stripe, anthropic, openai, openrouter, apollo, clay, pipe0, explorium, heyreach, theirstack, exa, or --via <hosted url>. Usage: fullstackgtm login <provider> | fullstackgtm login --via https://gtm.example.com",
     );
   }
   const now = new Date().toISOString();

package/src/cli/enrich.ts

@@ -25,7 +25,7 @@ import { isSpoolPath, readSpoolPath } from "../spoolFiles.ts";
 import { isOptionValue, loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.ts";
 import { providerKey } from "./tam.ts";
 import { unknownSubcommandError } from "./suggest.ts";
-import { box, colorEnabled, createProgressRenderer, createStatusLine, formatBar, formatDuration, paint, truncateToWidth, type Paint } from "./ui.ts";
+import { box, colorEnabled, createProgressRenderer, createStatusLine, formatBar, formatDuration, paint, scoreColor, truncateToWidth, type Paint } from "./ui.ts";
 import { compactPlan, verbosePlanRequested } from "./planOutput.ts";
 import type { AcquireBudget } from "../acquireMeter.ts";
 
@@ -946,12 +946,14 @@ function renderAcquireLeadCards(result: ReturnType<typeof buildAcquirePlan>): st
     let fit: number | undefined;
     const item = operation.evidenceIds?.[0] ? evidence.get(operation.evidenceIds[0]) : undefined;
     try { fit = Number((JSON.parse(item?.text ?? "{}") as { fitScore?: unknown }).fitScore); } catch { /* malformed evidence remains display-only */ }
+    const fitPercent = Number.isFinite(fit) ? Math.round((fit ?? 0) * 100) : undefined;
     const lines = [
-      truncateToWidth(name, 84),
-      truncateToWidth(`${title} · ${company}`, 84),
-      truncateToWidth([payload.associateCompanyDomain, props.hs_linkedin_url].filter(Boolean).join(" · "), 84),
+      p.bold(truncateToWidth(name, 84)),
+      p.cyan(truncateToWidth(`${title} · ${company}`, 84)),
+      p.blue(truncateToWidth([payload.associateCompanyDomain, props.hs_linkedin_url].filter(Boolean).join(" · "), 84)),
     ];
-    return box(lines, p, `Lead ${index + 1}/${result.plan.operations.length}${Number.isFinite(fit) ? ` · ${Math.round((fit ?? 0) * 100)}% fit` : ""}`).join("\n");
+    const fitLabel = fitPercent === undefined ? "" : ` · ${scoreColor(fitPercent, p)}% fit`;
+    return box(lines, p, `Lead ${index + 1}/${result.plan.operations.length}${fitLabel}`).join("\n");
   }).join("\n");
 }
 

package/src/cli/help.ts

@@ -21,9 +21,9 @@ Usage:
   fullstackgtm login stripe [--no-validate]
   fullstackgtm login anthropic | openai        store an LLM API key for call parse/score
   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 pipe0 | explorium | theirstack | exa  store a discovery-provider key
   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>
+  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|clay|pipe0|explorium|theirstack|exa|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
@@ -105,10 +105,12 @@ Usage:
                                                in the same plan (freemail domains never used;
                                                --skip-unmatched = report-only). HubSpot-only for now.
   fullstackgtm signals fetch [--bucket job,…] [--source greenhouse,lever,ashby] [--watchlist <path|crm:seg>] [--keywords …] [--from <file.json|spool.jsonl|spool-dir>] [--save]
+  fullstackgtm signals discover [--icp <path>] [--source exa] [--since 30d] [--max-accounts 10] [--max-results 50] [--max-searches 12] [--max-usd 0.25] [--save]
   fullstackgtm signals list [--since 7d] [--bucket b] [--account d] [--unjudged]
   fullstackgtm signals outcome --account <d> [--touch <id>] --result replied|meeting|bounced|no_reply
   fullstackgtm signals weights [--explain]
-                                               detect fresh buying triggers (ATS hiring scrapes + staged
+                                               detect fresh buying triggers (ICP-driven evidence discovery,
+                                               ATS hiring scans, and staged
                                                funding/company/social ingest), rank them, persist a local
                                                signal ledger. READ-ONLY re: CRM — fetch NEVER emits a plan;
                                                --save persists only the signal ledger. outcome feeds the
@@ -324,7 +326,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|clay|pipe0|explorium|broker>"],
+    synopsis: ["fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|clay|pipe0|explorium|theirstack|exa|broker>"],
     seeAlso: ["login", "doctor"],
   },
   doctor: {
@@ -622,12 +624,13 @@ export const HELP: Record<string, HelpEntry> = {
     phase: "Detect",
     synopsis: [
       "fullstackgtm signals fetch [--bucket job,…] [--source greenhouse,lever,ashby] [--connector file,serpapi-news,hubspot-forms] [--connector-opt k=v] [--watchlist <path|crm:seg>] [--keywords …] [--from <file.json|spool.jsonl|spool-dir>] [--save]",
+      "fullstackgtm signals discover [--icp <path>] [--source exa] [--since 30d] [--max-accounts 10] [--max-results 50] [--max-searches 12] [--max-usd 0.25] [--save]",
       "fullstackgtm signals list [--since 7d] [--bucket b] [--account d] [--unjudged]",
       "fullstackgtm signals outcome --account <d> [--touch <id>] --result replied|meeting|bounced|no_reply",
       "fullstackgtm signals weights [--explain]",
     ],
     detail:
-      "Read-only re: CRM — `fetch` NEVER emits a patch plan; `--save` persists only the local signal ledger. ATS adapters are no-auth; source connectors (`--connector`) pull from connected platforms with secrets via the credential ladder, never argv. `outcome` feeds the learned per-bucket `weights`.",
+      "Read-only re: CRM — `fetch` and `discover` NEVER emit a patch plan; `--save` persists only the local signal ledger. `discover` matches ICP behavioral hypotheses against canonical public ATS evidence through Exa, with explicit request and reported-cost budgets. Secrets resolve through env/login, never argv. `outcome` feeds the learned per-bucket `weights`.",
     seeAlso: ["icp", "draft"],
   },
   icp: {
@@ -699,13 +702,13 @@ export const COMMAND_FLAGS: Record<string, string[]> = {
   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", "--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"],
+  signals: ["--bucket", "--source", "--connector", "--connector-opt", "--watchlist", "--keywords", "--from", "--label", "--since", "--icp", "--max-accounts", "--max-results", "--max-searches", "--max-usd", "--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"],
 };
 
 export const FLAGS_WITH_VALUES = new Set([
-  "--account", "--account-id", "--accounts", "--acv", "--acv-basis", "--after", "--anchor", "--api-key", "--approve", "--archive", "--assign-owner", "--attendees", "--before", "--bucket", "--buyers-per-account", "--call", "--call-type", "--calls", "--capture-run", "--category", "--channel", "--client", "--client-id", "--client-secret", "--config", "--connector", "--connector-opt", "--contact", "--cron", "--cross-checks", "--deal", "--deal-period", "--diff", "--domain", "--email", "--except-deal-stage", "--format", "--from", "--from-judge", "--golden", "--guard", "--icp", "--in", "--input", "--instance-url", "--keep", "--key", "--keywords", "--label", "--list", "--login-url", "--match", "--match-property", "--max", "--max-claims", "--max-credits", "--max-examples", "--max-operations", "--min-accuracy", "--min-confidence", "--min-mentions", "--min-score", "--model", "--name", "--objects", "--operations", "--out", "--pipeline", "--plan", "--plan-id", "--policy", "--port", "--prepared-by", "--prior-run", "--profile", "--promote-lift", "--prompt", "--provider", "--reason", "--require", "--result", "--rubric", "--rule", "--rules", "--run", "--run-label", "--runs", "--scan-limit", "--scopes", "--seed", "--set", "--signals-from", "--since", "--snapshot", "--source", "--staged-run", "--stale-days", "--status", "--task-account", "--task-deal", "--timer", "--title", "--to", "--today", "--token", "--token-env", "--touch", "--transcript", "--trigger", "--usd-per-credit", "--value", "--values-from", "--vendor", "--via", "--watchlist", "--where",
+  "--account", "--account-id", "--accounts", "--acv", "--acv-basis", "--after", "--anchor", "--api-key", "--approve", "--archive", "--assign-owner", "--attendees", "--before", "--bucket", "--buyers-per-account", "--call", "--call-type", "--calls", "--capture-run", "--category", "--channel", "--client", "--client-id", "--client-secret", "--config", "--connector", "--connector-opt", "--contact", "--cron", "--cross-checks", "--deal", "--deal-period", "--diff", "--domain", "--email", "--except-deal-stage", "--format", "--from", "--from-judge", "--golden", "--guard", "--icp", "--in", "--input", "--instance-url", "--keep", "--key", "--keywords", "--label", "--list", "--login-url", "--match", "--match-property", "--max", "--max-accounts", "--max-claims", "--max-credits", "--max-examples", "--max-operations", "--max-results", "--max-searches", "--max-usd", "--min-accuracy", "--min-confidence", "--min-mentions", "--min-score", "--model", "--name", "--objects", "--operations", "--out", "--pipeline", "--plan", "--plan-id", "--policy", "--port", "--prepared-by", "--prior-run", "--profile", "--promote-lift", "--prompt", "--provider", "--reason", "--require", "--result", "--rubric", "--rule", "--rules", "--run", "--run-label", "--runs", "--scan-limit", "--scopes", "--seed", "--set", "--signals-from", "--since", "--snapshot", "--source", "--staged-run", "--stale-days", "--status", "--task-account", "--task-deal", "--timer", "--title", "--to", "--today", "--token", "--token-env", "--touch", "--transcript", "--trigger", "--usd-per-credit", "--value", "--values-from", "--vendor", "--via", "--watchlist", "--where",
 ]);
 
 // Lifecycle-grouped front door. One line per verb, organized by the

package/src/cli/shared.ts

@@ -336,6 +336,35 @@ export function loadIcp(args: string[]): Icp | undefined {
  *     e.g. `echo "$TOKEN" | fullstackgtm login hubspot`
  *   - interactive: prompted on the TTY with the input muted
  */
+export function createSecretMaskRenderer(options: {
+  label: string;
+  lineLength: () => number;
+  write: (value: string) => void;
+}) {
+  let muted = false;
+  let renderQueued = false;
+  let settled = false;
+  return {
+    mute() { muted = true; },
+    settle() { settled = true; },
+    write(value: string) {
+      if (!muted) { options.write(value); return; }
+      if (settled || renderQueued) return;
+      renderQueued = true;
+      queueMicrotask(() => {
+        renderQueued = false;
+        // readline clears `line` during close. Submission settles this renderer
+        // first so an Enter-triggered repaint cannot redraw an empty prompt
+        // after the final mask/newline ("0 characters received").
+        if (settled) return;
+        const length = options.lineLength();
+        const mask = `${"•".repeat(Math.min(length, 12))}${length > 12 ? "…" : ""}`;
+        options.write(`\r\u001b[2K${options.label}: ${mask} (${length} character${length === 1 ? "" : "s"} received)`);
+      });
+    },
+  };
+}
+
 export async function readSecret(label: string): Promise<string> {
   if (!process.stdin.isTTY) {
     const chunks: Buffer[] = [];
@@ -362,26 +391,20 @@ export async function readSecret(label: string): Promise<string> {
       output: process.stderr,
       terminal: true,
     });
-    let muted = false;
     const mutable = rl as unknown as { _writeToOutput?: (value: string) => void; line?: string };
-    let renderQueued = false;
-    mutable._writeToOutput = (value: string) => {
-      if (!muted) { process.stderr.write(value); return; }
-      if (renderQueued) return;
-      renderQueued = true;
-      queueMicrotask(() => {
-        renderQueued = false;
-        const length = mutable.line?.length ?? 0;
-        const mask = `${"•".repeat(Math.min(length, 12))}${length > 12 ? "…" : ""}`;
-        process.stderr.write(`\r\u001b[2K${label}: ${mask} (${length} character${length === 1 ? "" : "s"} received)`);
-      });
-    };
+    const renderer = createSecretMaskRenderer({
+      label,
+      lineLength: () => mutable.line?.length ?? 0,
+      write: (value) => process.stderr.write(value),
+    });
+    mutable._writeToOutput = (value: string) => renderer.write(value);
     rl.question(`${label}: `, (answer) => {
+      renderer.settle();
       rl.close();
       process.stderr.write("\n");
       resolveSecret(answer.trim());
     });
-    muted = true;
+    renderer.mute();
   });
 }