fullstackgtm 0.33.0 → 0.37.0

package/dist/icp.js

@@ -0,0 +1,256 @@
+/**
+ * ICP — the Ideal Customer Profile that makes `enrich acquire` targeted instead
+ * of random. One structured artifact drives two things:
+ *   1. discovery filters — translated per provider (Explorium, pipe0/Crustdata)
+ *      so the pull only returns ICP-shaped companies + people, and
+ *   2. fit scoring — every discovered prospect is scored against the persona so
+ *      only above-threshold leads become create_record ops.
+ *
+ * Develop one via interview: an agent (Claude Code / Codex) reads INTERVIEW_SPEC,
+ * asks the questions with its AskUserQuestion tool, and writes the answers into
+ * an Icp (CLI: `icp interview` emits the spec, `icp show` renders the result).
+ *
+ * Zero runtime deps; pure functions (translation + scoring take plain data).
+ */
+export const DEFAULT_FIT_THRESHOLD = 0.5;
+const COUNTRY_NAMES = {
+    us: "United States",
+    ca: "Canada",
+    gb: "United Kingdom",
+    uk: "United Kingdom",
+};
+export function parseIcp(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`icp: not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!parsed || typeof parsed !== "object")
+        throw new Error("icp: expected a JSON object");
+    const icp = parsed;
+    if (!icp.name || typeof icp.name !== "string")
+        throw new Error('icp: missing "name"');
+    if (!icp.persona || (!icp.persona.titleKeywords?.length && !icp.persona.jobLevels?.length)) {
+        throw new Error('icp: "persona" needs at least titleKeywords or jobLevels (without them, scoring cannot rank fit)');
+    }
+    return icp;
+}
+// ---------------------------------------------------------------------------
+// Discovery-filter translation
+/** Explorium /v1/prospects filters from the ICP. */
+export function icpToExploriumFilters(icp) {
+    const f = { has_email: { value: true } };
+    if (icp.persona.jobLevels?.length)
+        f.job_level = { values: icp.persona.jobLevels };
+    if (icp.persona.departments?.length)
+        f.job_department = { values: icp.persona.departments };
+    if (icp.firmographics.employeeBands?.length)
+        f.company_size = { values: icp.firmographics.employeeBands };
+    if (icp.firmographics.geos?.length)
+        f.company_country_code = { values: icp.firmographics.geos };
+    if (icp.firmographics.naics?.length)
+        f.naics_category = { values: icp.firmographics.naics };
+    return f;
+}
+/**
+ * Crustdata / LinkedIn seniority vocab. ICP job levels are normalized lowercase;
+ * Crustdata expects these exact capitalized strings (verified: "CXO",
+ * "Vice President", "Director" appear in Crustdata's docs/examples).
+ */
+const CRUSTDATA_SENIORITY = {
+    cxo: "CXO",
+    "c-suite": "CXO",
+    c_suite: "CXO",
+    founder: "Owner",
+    owner: "Owner",
+    partner: "Partner",
+    vp: "Vice President",
+    "vice president": "Vice President",
+    head: "Director",
+    director: "Director",
+    manager: "Manager",
+    senior: "Senior",
+    entry: "Entry",
+};
+/**
+ * ICP industry keyword → LinkedIn industry names Crustdata filters on. Includes
+ * the current LinkedIn-v2 names; for software we send the cluster (dev + IT
+ * services + internet) so an OR match isn't overly narrow.
+ */
+const CRUSTDATA_INDUSTRY = {
+    software: ["Software Development", "Information Technology and Services", "Internet"],
+    saas: ["Software Development", "Information Technology and Services"],
+    "information technology & services": ["Information Technology and Services"],
+    "information technology and services": ["Information Technology and Services"],
+    internet: ["Internet"],
+    fintech: ["Financial Services"],
+    "financial services": ["Financial Services"],
+};
+/**
+ * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
+ * matches real LinkedIn title strings (case-sensitive), so keywords are Title
+ * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
+ * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
+ * live (pipe0 credits were exhausted) — validate when credits refill; fit
+ * scoring is the safety net for persona precision regardless.
+ */
+export function icpToCrustdataFilters(icp) {
+    const f = {};
+    if (icp.persona.titleKeywords?.length)
+        f.current_job_titles = icp.persona.titleKeywords.map(titleCase);
+    if (icp.firmographics.geos?.length) {
+        f.locations = icp.firmographics.geos.map((g) => COUNTRY_NAMES[g.toLowerCase()] ?? g);
+    }
+    if (icp.persona.jobLevels?.length) {
+        const include = [...new Set(icp.persona.jobLevels.map((l) => CRUSTDATA_SENIORITY[l.toLowerCase()]).filter(Boolean))];
+        if (include.length)
+            f.current_seniority_levels = { include, exclude: [] };
+    }
+    if (icp.firmographics.industries?.length) {
+        const inds = [
+            ...new Set(icp.firmographics.industries.flatMap((i) => CRUSTDATA_INDUSTRY[i.toLowerCase()] ?? [titleCase(i)])),
+        ];
+        if (inds.length)
+            f.current_employers_linkedin_industries = inds;
+    }
+    return f;
+}
+const ACRONYMS = new Set(["cro", "coo", "ceo", "cfo", "vp", "crm", "gtm", "saas"]);
+function titleCase(value) {
+    return value
+        .split(/\s+/)
+        .map((w) => (ACRONYMS.has(w.toLowerCase()) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+        .join(" ");
+}
+/**
+ * Score a prospect's PERSONA fit 0..1. Title-keyword match is the strongest
+ * signal (it's what defines the buyer); job level and department add to it.
+ * Firmographics aren't re-scored here — discovery already filtered on them.
+ */
+export function scoreProspectAgainstIcp(prospect, icp) {
+    const reasons = [];
+    const title = (prospect.jobTitle ?? "").toLowerCase();
+    const keywords = (icp.persona.titleKeywords ?? []).map((k) => k.toLowerCase());
+    const levels = (icp.persona.jobLevels ?? []).map((l) => l.toLowerCase());
+    const depts = (icp.persona.departments ?? []).map((d) => d.toLowerCase());
+    let score = 0;
+    let weightSum = 0;
+    if (keywords.length) {
+        weightSum += 0.6;
+        const hit = keywords.find((k) => title.includes(k));
+        if (hit) {
+            score += 0.6;
+            reasons.push(`title matches ICP keyword "${hit}"`);
+        }
+    }
+    if (levels.length) {
+        weightSum += 0.25;
+        const level = (prospect.jobLevel ?? "").toLowerCase();
+        if (level && levels.some((l) => level.includes(l))) {
+            score += 0.25;
+            reasons.push(`seniority "${prospect.jobLevel}" in ICP levels`);
+        }
+    }
+    if (depts.length) {
+        weightSum += 0.15;
+        const dept = (prospect.jobDepartment ?? "").toLowerCase();
+        if (dept && depts.some((d) => dept.includes(d))) {
+            score += 0.15;
+            reasons.push(`department "${prospect.jobDepartment}" in ICP`);
+        }
+    }
+    const normalized = weightSum > 0 ? score / weightSum : 0;
+    if (reasons.length === 0)
+        reasons.push("no persona signal matched the ICP");
+    return { score: Number(normalized.toFixed(3)), reasons };
+}
+export function fitThreshold(icp) {
+    return icp.scoring?.threshold ?? DEFAULT_FIT_THRESHOLD;
+}
+export const INTERVIEW_SPEC = [
+    {
+        id: "industries",
+        header: "Target market",
+        question: "What company profile are you targeting? (Drives firmographic discovery filters.)",
+        multiSelect: true,
+        options: [
+            { label: "B2B SaaS / software", value: ["software", "saas"], description: "Software & internet — classic messy-CRM, RevOps-equipped buyer." },
+            { label: "Broader tech-enabled B2B", value: ["software", "information technology & services", "financial services"], description: "Any B2B running a real sales motion on a CRM." },
+            { label: "Any B2B with a CRM", value: [], description: "Vertical-agnostic — qualify on persona, not industry." },
+        ],
+    },
+    {
+        id: "employeeBands",
+        header: "Company size",
+        question: "Company size (employee bands) that fit?",
+        multiSelect: true,
+        options: [
+            { label: "Seed–Series A (1–50)", value: ["1-10", "11-50"], description: "Early; often no dedicated RevOps yet." },
+            { label: "Series B–C (51–500)", value: ["51-200", "201-500"], description: "Sweet spot: messy CRM, RevOps exists, budget exists." },
+            { label: "Growth (501–2000)", value: ["501-1000", "1001-5000"], description: "Established RevOps, many CRM writers." },
+            { label: "Enterprise (2000+)", value: ["1001-5000", "5001-10000", "10001+"], description: "Up-market; longer cycles." },
+        ],
+    },
+    {
+        id: "titleKeywords",
+        header: "Buyer persona",
+        question: "Which buyer persona(s) should discovery target and scoring reward?",
+        multiSelect: true,
+        options: [
+            { label: "RevOps leadership", value: ["revenue operations", "revops", "head of revenue operations"], description: "VP/Head/Dir Revenue Operations." },
+            { label: "Sales/Marketing Ops", value: ["sales operations", "gtm operations", "marketing operations", "revenue ops"], description: "Hands-on the CRM daily." },
+            { label: "Exec buyers", value: ["chief revenue officer", "cro", "chief operating officer", "vp of sales"], description: "Economic sign-off." },
+            { label: "CRM/SF admins", value: ["salesforce admin", "hubspot admin", "crm manager", "revops analyst"], description: "Feel the pain, champion the fix." },
+        ],
+    },
+    {
+        id: "geos",
+        header: "Geography",
+        question: "Geography?",
+        multiSelect: true,
+        options: [
+            { label: "United States", value: ["us"], description: "US-only (best data coverage)." },
+            { label: "US + Canada", value: ["us", "ca"], description: "North America." },
+            { label: "US + UK/EU", value: ["us", "gb"], description: "English-speaking + Western Europe (mind GDPR)." },
+            { label: "Global", value: [], description: "No geo filter." },
+        ],
+    },
+];
+/** Assemble an Icp from flattened interview answers. */
+export function icpFromAnswers(name, answers) {
+    const levelsFromTitles = inferLevels(answers.titleKeywords);
+    return {
+        name,
+        firmographics: {
+            industries: dedupe(answers.industries),
+            naics: answers.industries.some((i) => /software|saas/i.test(i)) ? ["5112"] : undefined,
+            employeeBands: dedupe(answers.employeeBands),
+            geos: dedupe(answers.geos),
+        },
+        persona: {
+            jobLevels: answers.jobLevels?.length ? dedupe(answers.jobLevels) : levelsFromTitles,
+            departments: answers.departments?.length ? dedupe(answers.departments) : ["sales", "marketing", "operations"],
+            titleKeywords: dedupe(answers.titleKeywords),
+        },
+        scoring: { threshold: DEFAULT_FIT_THRESHOLD },
+    };
+}
+function inferLevels(titles) {
+    const levels = new Set();
+    for (const t of titles.map((x) => x.toLowerCase())) {
+        if (/chief|^c[a-z]o$|cro|coo/.test(t))
+            levels.add("cxo");
+        if (/vp|vice president|head of/.test(t))
+            levels.add("vp");
+        if (/director/.test(t))
+            levels.add("director");
+        if (/manager|admin|analyst|operations/.test(t))
+            levels.add("manager");
+    }
+    return levels.size ? [...levels] : ["cxo", "vp", "director", "manager"];
+}
+function dedupe(values) {
+    return [...new Set((values ?? []).filter(Boolean))];
+}

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { createFilePlanStore, type PlanStore, type StoredPlan } from "./planStor
 export { computeApprovalDigests, loadOrCreateSigningKey, loadSigningKey, signApproval, verifyApprovalDigests, type ApprovalVerification, } from "./integrity.ts";
 export { buildAuditLog, verifyAuditLog, type AuditLogEntry, type AuditLogExport, type AuditLogVerification, } from "./auditLog.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+export { computeHealth, summarizeHealth, healthToMarkdown, type HealthEntry, type HealthRollup, type HealthRuleDelta, } from "./health.ts";
 export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, type CrmObjectType, type FieldMappings, } from "./mappings.ts";
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.ts";
@@ -34,7 +35,7 @@ export { buildWorksheet, classifyMarket, type ClassifyMarketOptions, type Classi
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, type CallDocument, type ClaimMentionStats, type DirectiveStat, type DirectiveType, type MarketDirective, type OverlayOptions, type OverlayStats, type VendorMentionStats, } from "./marketOverlay.ts";
 export { computeScaleIndex, dimensionForMetric, scaleReportToText, type ScaleDimension, type ScaleReport, type SignalEstimate, type VendorScale, } from "./marketScale.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
-export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, type FetchText, type FetchBytes, type ResolveUrl, } from "./marketSourcing.ts";
+export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, discoverCompetitors, type FetchText, type FetchBytes, type ResolveUrl, type DiscoveredVendor, type DiscoverCompetitorsOptions, } from "./marketSourcing.ts";
 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 type { ApprovalStatus, AuditFinding, AuditFindingSeverity, CanonicalAccount, CanonicalActivity, CanonicalContact, CanonicalDeal, CanonicalGtmSnapshot, CanonicalUser, CrmProvider, GtmAuditRule, GtmConnector, GtmEvidence, GtmEvidenceSourceSystem, GtmObjectType, GtmPolicy, GtmRuleContext, GtmRuleResult, GtmSnapshotIndex, PatchOperation, PatchOperationResult, PatchOperationType, PatchPlan, PatchPlanRun, PatchPlanRunStatus, PatchVerification, PipelineFinding, PipelineFindingStatus, PipelineFindingType, ProviderIdentity, RiskLevel, SourceFreshness, } from "./types.ts";

package/dist/index.js

@@ -19,6 +19,7 @@ export { createFilePlanStore } from "./planStore.js";
 export { computeApprovalDigests, loadOrCreateSigningKey, loadSigningKey, signApproval, verifyApprovalDigests, } from "./integrity.js";
 export { buildAuditLog, verifyAuditLog, } from "./auditLog.js";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
+export { computeHealth, summarizeHealth, healthToMarkdown, } from "./health.js";
 export { auditReportToHtml, auditReportToMarkdown } from "./report.js";
 export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, } from "./mappings.js";
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.js";
@@ -34,6 +35,6 @@ export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";
 export { computeScaleIndex, dimensionForMetric, scaleReportToText, } from "./marketScale.js";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
-export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, } from "./marketSourcing.js";
+export { registrableDomain, categoryKeywords, pickCategoryPage, extractLogoUrl, resolveFinalUrl, detectDrift, findCategoryPageInSitemap, findCategoryPage, fetchLogoDataUri, discoverCompetitors, } from "./marketSourcing.js";
 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";

package/dist/mappings.js

@@ -13,6 +13,9 @@ export const HUBSPOT_DEFAULT_FIELD_MAPPINGS = {
         email: "email",
         phone: "phone",
         title: "jobtitle",
+        // HubSpot-standard "LinkedIn URL"; safe to request everywhere (HubSpot
+        // ignores unknown properties rather than erroring). Powers strong dedup.
+        linkedin: "hs_linkedin_url",
         ownerId: "hubspot_owner_id",
     },
     deals: {

package/dist/marketSourcing.d.ts

@@ -1,3 +1,4 @@
+import { type LlmCallOptions } from "./llm.ts";
 /** Fetch a text resource (sitemap, robots.txt); null on any failure. */
 export type FetchText = (url: string) => Promise<string | null>;
 /** Fetch raw bytes (a logo image); null on any failure. */
@@ -64,3 +65,27 @@ export declare function findCategoryPage(homepageHtml: string, homepageUrl: stri
  * Bounded to small raster/SVG (≤50KB).
  */
 export declare function fetchLogoDataUri(homepageUrl: string, html?: string, fetchBytes?: FetchBytes): Promise<string | null>;
+/** A vendor proposed by `discoverCompetitors`. */
+export type DiscoveredVendor = {
+    name: string;
+    /** Canonical homepage. */
+    url: string;
+    /** The page most specific to the category — the product page for multi-product
+     *  companies, else the homepage. Use as the capture seed. */
+    productUrl: string;
+};
+export type DiscoverCompetitorsOptions = {
+    llm: LlmCallOptions;
+    /** The user's own company: competitors are listed for it and it's excluded. */
+    anchorUrl?: string;
+    /** Vendor hosts already in the set, to exclude from results. */
+    exclude?: string[];
+};
+/**
+ * Propose the real vendor set for a category via the LLM — so a cold-start map
+ * needs only a category, not a hand-built vendor list. Returns canonical homepages
+ * plus a category-specific `productUrl` per vendor; excludes the anchor + any
+ * supplied hosts, de-dupes by registrable domain, and instructs the model to skip
+ * acquired/defunct brands. BYOK via the package's `forcedToolCall`.
+ */
+export declare function discoverCompetitors(category: string, options: DiscoverCompetitorsOptions): Promise<DiscoveredVendor[]>;

package/dist/marketSourcing.js

@@ -17,6 +17,7 @@
  *    headless browser, so the default fetch is sufficient even in the hosted layer.
  */
 import { assertPublicUrl } from "./market.js";
+import { DEFAULT_MODELS, forcedToolCall } from "./llm.js";
 const USER_AGENT = "fullstackgtm-market/0 (+https://github.com/fullstackgtm/core)";
 const FETCH_TIMEOUT_MS = 15_000;
 const MAX_REDIRECTS = 5;
@@ -403,3 +404,84 @@ export async function fetchLogoDataUri(homepageUrl, html, fetchBytes = defaultFe
     }
     return null;
 }
+const DISCOVERY_SCHEMA = {
+    type: "object",
+    required: ["competitors"],
+    properties: {
+        competitors: {
+            type: "array",
+            description: "Real vendors competing in this category today, each with its canonical https homepage URL.",
+            items: {
+                type: "object",
+                required: ["name", "url"],
+                properties: {
+                    name: { type: "string" },
+                    url: { type: "string", description: "Canonical homepage, https://domain, no tracking path." },
+                    productUrl: {
+                        type: "string",
+                        description: "URL of the page on THIS vendor's site most specific to the category. For a multi-product company (e.g. SAP, Oracle) this is the product/solution page for this category, NOT the corporate homepage. For a focused single-product vendor, repeat the homepage.",
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * Propose the real vendor set for a category via the LLM — so a cold-start map
+ * needs only a category, not a hand-built vendor list. Returns canonical homepages
+ * plus a category-specific `productUrl` per vendor; excludes the anchor + any
+ * supplied hosts, de-dupes by registrable domain, and instructs the model to skip
+ * acquired/defunct brands. BYOK via the package's `forcedToolCall`.
+ */
+export async function discoverCompetitors(category, options) {
+    const model = options.llm.model ?? DEFAULT_MODELS[options.llm.provider];
+    const anchorHost = options.anchorUrl ? hostOf(options.anchorUrl) : null;
+    const anchorNote = anchorHost
+        ? `The user's own company is ${anchorHost} — list its direct competitors and do NOT include ${anchorHost} itself.`
+        : "";
+    const prompt = `List the most significant vendors competing in the category "${category}" today.
+${anchorNote}
+Rules:
+- Real companies only, each with its canonical https homepage URL (domain root, no tracking path).
+- 7-9 vendors: a mix of established leaders and notable challengers.
+- EXCLUDE vendors that have been acquired and folded into another brand, or are defunct — i.e. anything whose own site now redirects to a different company. (Name the current independent players instead.)
+- For each, also give productUrl: the page most specific to "${category}". For a big multi-product company, that's its product/solution page for THIS category, not the corporate homepage.
+- No duplicates.`;
+    const result = (await forcedToolCall(prompt, "discover_competitors", DISCOVERY_SCHEMA, model, options.llm));
+    const excluded = new Set((options.exclude ?? []).map(hostOf).filter((h) => Boolean(h)));
+    if (anchorHost)
+        excluded.add(anchorHost);
+    const seenDomain = new Set();
+    const out = [];
+    for (const c of result?.competitors ?? []) {
+        let u;
+        try {
+            u = new URL(String(c.url));
+        }
+        catch {
+            continue;
+        }
+        if (u.protocol !== "http:" && u.protocol !== "https:")
+            continue;
+        const host = u.hostname.replace(/^www\./, "");
+        if (excluded.has(host))
+            continue;
+        const dom = registrableDomain(host);
+        if (seenDomain.has(dom))
+            continue;
+        seenDomain.add(dom);
+        let productUrl = u.toString();
+        if (c.productUrl) {
+            try {
+                const p = new URL(String(c.productUrl));
+                if (p.protocol === "http:" || p.protocol === "https:")
+                    productUrl = p.toString();
+            }
+            catch {
+                /* keep homepage */
+            }
+        }
+        out.push({ name: c.name || host, url: u.toString(), productUrl });
+    }
+    return out;
+}

package/dist/types.d.ts

@@ -10,7 +10,21 @@ export type RiskLevel = "low" | "medium" | "high";
 export type ApprovalStatus = "draft" | "needs_approval" | "approved" | "rejected" | "applied";
 export type GtmObjectType = "account" | "contact" | "deal" | "user" | "activity";
 export type GtmEvidenceSourceSystem = "salesforce" | "hubspot" | "gong" | "chorus" | "fathom" | "manual" | "csv" | "mock" | "web" | "unknown";
-export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task" | "merge_records";
+export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task" | "create_record" | "merge_records";
+/**
+ * The afterValue of a `create_record` operation. The connector re-resolves on
+ * `matchKey`/`matchValue` at apply time and creates only on a confirmed miss.
+ * `estCostUsd` is the acquire meter's per-record charge, recorded against the
+ * budget on a successful create.
+ */
+export type CreateRecordPayload = {
+    properties: Record<string, string>;
+    matchKey: string;
+    matchValue: string;
+    source: string;
+    estCostUsd?: number;
+    associateCompanyName?: string;
+};
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**
  * One claim that a canonical record exists in an external system. A record
@@ -125,6 +139,8 @@ export type CanonicalContact = {
     email?: string;
     phone?: string;
     title?: string;
+    /** LinkedIn profile URL — the strongest cross-system identity key for dedup. */
+    linkedin?: string;
     ownerId?: string;
     lastActivityAt?: string;
     lastSyncAt?: string;

package/docs/api.md

@@ -40,7 +40,7 @@ release.
 - `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
-- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). The Salesforce connector skips `merge_records` honestly (SOAP/Apex-only on that platform).
+- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `create_record` (resolve-first net-new contact/company create — re-checks the dedupe key at apply, never double-creates), `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). The Salesforce connector skips `merge_records` and `create_record` honestly (platform-specific).
 - `createSalesforceConnector(options)` — read/write/readField/fetchChanges; probabilities normalized to 0..1; `applyOperation` implements every operation type.
 - `createStripeConnector(options)` — read-only billing by design (`applyOperation` returns `skipped`); email domains are the cross-system merge keys. Implements `fetchChanges` (incremental via `created[gte]`).
 
@@ -62,7 +62,8 @@ Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `p
 `bulk-update`, `dedupe`, `reassign`, `fix`,
 `market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
 `axes` / `overlay` / `scale` / `report` / `refresh`),
-`enrich` (`append` / `refresh` / `ingest` / `status`),
+`enrich` (`append` / `refresh` / `ingest` / `acquire` / `status`),
+`icp` (`interview` / `set` / `show`),
 `schedule` (`add` / `list` / `remove` / `enable` / `disable` / `run` /
 `install` / `uninstall` / `status`), `rules`, `profiles`, `doctor`.
 Exit codes: `0` success · `1` error · `2` findings/regressions at the requested gate
@@ -120,6 +121,32 @@ dependency-free CSV intake; the Apollo client (`createApolloClient`,
 `pullApolloRecords`, 429-aware with `Retry-After`) is the first `api`-kind
 source.
 
+## Acquire (net-new lead generation)
+
+`buildAcquirePlan` turns sourced-but-unmatched prospects into `create_record`
+operations (matched / ambiguous are skipped — resolve-first never creates over
+a possible dup), capped by the meter's headroom. `builtinAcquirePreset` is the
+zero-config `EnrichConfig.acquire` (budget, provider, create-mapping) so
+`enrich acquire` runs with just an `icp.json`.
+
+- **ICP** (`icp.ts`): `Icp` type, `parseIcp`, `icpToExploriumFilters` /
+  `icpToCrustdataFilters` (per-provider discovery filters), `scoreProspectAgainstIcp`
+  (persona fit 0..1), `fitThreshold`, `INTERVIEW_SPEC` + `icpFromAnswers` (the
+  agent-driven interview).
+- **Prospect sources** (`connectors/prospectSources.ts`, `Prospect`):
+  `fetchExploriumProspects` (discovery), `pipe0ResolveWorkEmails` (work-email
+  waterfall, chunked, surfaces upstream errors), `fetchPipe0CrustdataProspects`
+  (people search). `prospectIdentityKeys` / `crmContactKeys` /
+  `partitionFreshProspects` power the pre-email dedup.
+- **Meter** (`acquireMeter.ts`): `AcquireBudget`, `loadMeter` / `remaining` /
+  `recordConsumption` — per-profile windowed record+spend budget, charged only
+  for landed creates.
+- **Seen cache** (`acquireSeen.ts`): `loadSeen` / `recordSeen` — cross-run
+  memory so a re-run never re-pays to enrich a known prospect.
+
+`CanonicalContact.linkedin` (mapped from HubSpot `hs_linkedin_url`) is the
+strong dedup key across all of the above.
+
 ## Schedule
 
 The horizontal scheduler: a declarative schedule-entry store, a

package/docs/architecture.md

@@ -72,7 +72,14 @@ provider  ──fetchSnapshot()──►  CanonicalGtmSnapshot
 - `market*.ts` (`market.ts`, `marketClassify.ts`, `marketAxes.ts`,
   `marketOverlay.ts`, `marketScale.ts`, `marketReport.ts`) — the competitive
   market-map layer; classifications are verbatim-verified against captures.
-- `enrich.ts` + `enrichApollo.ts` — third-party data enrichment (fill-blanks).
+- `enrich.ts` + `enrichApollo.ts` — third-party data enrichment (fill-blanks),
+  plus `buildAcquirePlan` / `builtinAcquirePreset` for net-new lead generation.
+- `icp.ts` — the Ideal Customer Profile artifact: per-provider discovery-filter
+  translation, prospect fit scoring, and the agent-driven interview spec.
+- `acquireMeter.ts` — per-profile windowed budget (records + spend) for acquire.
+- `acquireSeen.ts` — cross-run "seen" cache so re-runs don't re-pay for dupes.
+- `connectors/prospectSources.ts` — API prospect sources (Explorium discovery,
+  pipe0 work-email waterfall, pipe0/Crustdata search) + the pre-email dedup keys.
 
 **Surfaces & infra**
 - `cli.ts` — one async function per command, flat dispatch in `runCli`;

package/docs/dx-punch-list.md

@@ -0,0 +1,87 @@
+# DX / adoption punch list
+
+Audit date: 2026-06-19. Method: ran the CLI as a new adopter would (bare
+invoke → `doctor` → `audit --demo` → per-command `--help`) and measured the
+friction, rather than reading the source. Companion to the security/strategic
+findings that drove the 0.25.1–0.28.0 hardening releases — same format, same
+intent: a tracked list that drives a release.
+
+## Framing
+
+The **agent path** (SKILL.md verb map, MCP tools, `--json` everywhere,
+gate-shaped exit codes 0/1/2) is cohesive and adopts cleanly. The **human
+path** is the weak side — and the human is a primary user (the consultant-CLI,
+dogfood-on-client-work direction). Every fix below either *deepens an existing
+verb* or *connects two existing verbs*; none adds a new top-level noun. The
+adoption work **is** the "deeper not broader" work.
+
+`doctor` (ends with "Next step") and `fix` (chains audit→suggest→approve→apply)
+already do the right thing. Cohesion here = make every verb behave like
+`doctor` and `fix` already do.
+
+## Findings (evidence-backed)
+
+| # | Finding | Evidence | Impact |
+| --- | --- | --- | --- |
+| F1 | **Front door is a firehose** | bare invoke = 194 lines; 22 verbs / 87 distinct flags; `cli.ts` is 3,615 lines | New user can't find the ~6 things they actually do |
+| F2 | **Credential-free entry point dead-ends** | `audit --demo` (the README's "try it first") dumps **1,467 lines** to stdout and ends on a blank line — no "next step," unlike `doctor` | The single most-run first command strands you |
+| F3 | **No per-command help** | `dedupe --help`, `audit --help` fall through to the same 194-line global wall | A stuck user gets the firehose, not the answer |
+| F4 | **No altitude control on reads** | `audit` has only `--json` / `--out` / `--format`; no `--summary` / `--top` / `--quiet`. Human mode *is* the 1,467-line dump | Default human output is unreadable yet not machine-parseable |
+| F5 | **Tone undercuts positioning** | `audit --demo` footer: "This prototype is dry-run only" | Reads as toy vs. the beta/production-safety-invariant framing |
+| F6 | **No guided mode** | `readline` is used only for the login secret prompt | Every workflow is hand-assembled from flags; nothing scaffolds the loop |
+
+## Fix sequence (highest leverage first)
+
+### 1. Progressive-disclosure help — IN PROGRESS
+Fixes **F1, F3**. The full `usage()` becomes the explicit full reference
+(`fullstackgtm help --full`). Add:
+- `shortUsage()` — a ~30-line map of the verbs grouped by lifecycle phase
+  (Setup · Detect · Prevent · Remediate · Calls · Govern · Market · Schedule),
+  one line each, ending with `<command> --help` and `help --full` pointers.
+  Becomes the default for bare invoke and `--help`.
+- `commandHelp(command)` — focused per-verb help (summary, synopsis, where it
+  sits in the loop, key options, see-also). `<verb> --help` zooms in instead
+  of dumping the surface. `call`/`market`/`enrich`/`bulk-update`/`schedule`
+  keep their existing bespoke help.
+- `help [command] [--full]` command.
+
+### 2. Every verb hands you the next step — DONE (audit keystone)
+Fixes **F2**. `auditNextStep()` gives `audit` context-aware forward guidance on
+stderr (stdout stays clean for pipes/`--out`; suppressed under `--json`):
+- **demo/sample** → "Client-ready writeup: `report --demo`" + "Run on your CRM:
+  `login hubspot` → `audit --provider hubspot --save`"
+- **live + `--save`** → the governed spine: `suggest` → `plans approve
+  --values-from` → `apply`, with the real plan id
+- **0 findings** → "clean — gate new records with `resolve`, schedule a check"
+
+The lifecycle spine made *experiential* — each command knows its phase and
+points forward (`doctor`/`fix` were the templates). `audit` is the keystone
+(the documented dead-end); the helper pattern now generalizes to the other read
+verbs (`report`, `resolve`, `dedupe` previews) in a follow-up.
+
+### 3. Altitude control on the firehose — DONE
+Fixes **F4**. `patchPlanToMarkdown(plan, { summary })` gains a summary view
+(header + Findings-by-Rule table + operation count + pointers to `--full` and
+`report`). `audit` defaults to it — **1,467 → 24 lines** on the demo — with
+`--full` to opt back into the per-operation dump. The default stays *full* for
+every other caller (bulk-update, fix, dedupe, plans show, MCP): write-preview
+verbs keep full operation detail because you approve specific ops there. The
+principled split — audit = "what's wrong" (summary → `report`); write verbs =
+"exactly what I'll change" (full) — is the real win.
+
+### 4. Tone pass — DONE
+Fixes **F5**. The "This prototype is dry-run only" footer is replaced
+everywhere with safety-invariant framing matching README/SKILL: "Dry-run plan —
+read-only. No provider write happens until you approve specific operations and
+run `apply`; placeholder values are refused without an explicit override. These
+safety invariants are not beta." No "prototype" string remains in user output.
+
+## Deferred (bigger bets, gated on 1–4 landing)
+- **Engagement workspace**: per-client `.fullstackgtm/` state that accumulates
+  snapshots, plans, evidence, and a health-over-time score — turns episodic
+  audits into a continuously-operated system.
+- **Journey commands**: 2–3 opinionated composites (onboard-a-client,
+  health-rollup) sequencing existing verbs into revops jobs.
+
+There is no point building the engagement workspace while the front door dumps
+1,467 lines. Land the DX fixes first.

package/llms.txt

@@ -115,6 +115,22 @@ artifacts: plan ids / enrich run labels, trigger cron|manual) land under
 firings (visibility only — local cron has no catch-up). Providers beyond
 `local` are not yet implemented (future: codegen scaffolds, same contract).
 
+## Key invariants (engagement workspace / health)
+
+`fullstackgtm health` rolls up a per-profile CRM-health timeline that accrues
+from the verb teams already run: every `audit --save` stamps a deterministic
+0–100 hygiene score plus a snapshot onto the active profile. The score is
+`100 / (1 + severity-weighted findings per record)` (info ×1, warning ×3,
+critical ×10) — no LLM, so it is byte-stable in CI and comparable run-over-run;
+0 findings ⇒ 100, and the same findings over fewer clean records score lower.
+State is profile-scoped and owner-only (0600) under the same secured home as
+plans: `health.jsonl` (append-only, one entry per saved audit) and
+`snapshots/<planId>.json`. `health` is READ-ONLY — it only reads the timeline,
+never re-audits or writes; `--json` emits the rollup (current score, delta since
+the last audit, dated trend, per-rule deltas). Scope per client with
+`--profile <name>`; an empty timeline returns a pointer, never an error.
+Library: `computeHealth` / `summarizeHealth` / `healthToMarkdown`.
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`