fullstackgtm 0.34.0 → 0.38.0

package/dist/icp.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 type Icp = {
+    name: string;
+    firmographics: {
+        /** human industry labels, e.g. ["software","saas"] — used for keyword/industry filters */
+        industries?: string[];
+        /** Explorium naics_category codes, e.g. ["5112"] (software publishers) */
+        naics?: string[];
+        /** provider-agnostic employee bands: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+" */
+        employeeBands?: string[];
+        /** ISO country codes, lowercased, e.g. ["us"] */
+        geos?: string[];
+    };
+    persona: {
+        /** seniority: "cxo","vp","director","manager","owner","senior" */
+        jobLevels?: string[];
+        /** "sales","marketing","operations","finance" */
+        departments?: string[];
+        /** the title phrases that DEFINE the buyer — also the scoring signal */
+        titleKeywords?: string[];
+    };
+    signals?: {
+        intentTopics?: string[];
+    };
+    scoring?: {
+        /** minimum fit (0..1) for a prospect to become a create_record op. Default 0.5. */
+        threshold?: number;
+    };
+};
+export declare const DEFAULT_FIT_THRESHOLD = 0.5;
+export declare function parseIcp(raw: string): Icp;
+/** Explorium /v1/prospects filters from the ICP. */
+export declare function icpToExploriumFilters(icp: Icp): Record<string, {
+    values?: string[];
+    value?: boolean;
+}>;
+/**
+ * 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 declare function icpToCrustdataFilters(icp: Icp): Record<string, unknown>;
+export type IcpFit = {
+    score: number;
+    reasons: string[];
+};
+/**
+ * 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 declare function scoreProspectAgainstIcp(prospect: {
+    jobTitle?: string;
+    jobLevel?: string;
+    jobDepartment?: string;
+}, icp: Icp): IcpFit;
+export declare function fitThreshold(icp: Icp): number;
+export type IcpInterviewQuestion = {
+    id: keyof FlatIcpAnswers;
+    header: string;
+    question: string;
+    multiSelect: boolean;
+    options: {
+        label: string;
+        value: string | string[];
+        description: string;
+    }[];
+};
+/** Flattened answer keys the interview collects (assembled into an Icp). */
+export type FlatIcpAnswers = {
+    industries: string[];
+    employeeBands: string[];
+    jobLevels: string[];
+    departments: string[];
+    titleKeywords: string[];
+    geos: string[];
+};
+export declare const INTERVIEW_SPEC: IcpInterviewQuestion[];
+/** Assemble an Icp from flattened interview answers. */
+export declare function icpFromAnswers(name: string, answers: FlatIcpAnswers): Icp;

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

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
+export { matchesTerritory, parseAssignmentPolicy, resolveAssignment, type AssignmentContext, type AssignmentPolicy, type AssignmentResult, type AssignmentStrategy, type TerritoryRule, } from "./assign.ts";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
 export { buildDedupePlan, dedupeKey, type DedupeOptions } from "./dedupe.ts";
 export { buildReassignPlans, type ReassignObjectType, type ReassignOptions } from "./reassign.ts";
@@ -19,6 +20,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";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.js";
+export { matchesTerritory, parseAssignmentPolicy, resolveAssignment, } from "./assign.js";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere } from "./bulkUpdate.js";
 export { buildDedupePlan, dedupeKey } from "./dedupe.js";
 export { buildReassignPlans } from "./reassign.js";
@@ -19,6 +20,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";

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/reassign.d.ts

@@ -1,10 +1,19 @@
 import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 export type ReassignObjectType = "account" | "contact" | "deal";
 export type ReassignOptions = {
-    /** the owner whose records are being handed off */
-    fromOwnerId: string;
+    /**
+     * the owner whose records are being handed off. Ignored (and not required)
+     * when `assignUnowned` is set — that mode targets ownerless records instead.
+     */
+    fromOwnerId?: string;
     /** the receiving owner — must be a known user in the snapshot */
     toOwnerId: string;
+    /**
+     * Backfill mode: instead of moving records from one owner to another, claim
+     * every OWNERLESS record (ownerId:empty) for `toOwnerId`. Shares the create-
+     * time assignment intent with `enrich acquire`, applied to existing debt.
+     */
+    assignUnowned?: boolean;
     /** which object types to compile plans for (default all three) */
     objects?: ReassignObjectType[];
     /** extra --where scoping, AND-ed into every plan (account fields lifted) */

package/dist/reassign.js

@@ -40,11 +40,16 @@ function scopeWhere(objectType, raw) {
     return raw;
 }
 export function buildReassignPlans(snapshot, options) {
-    if (!options.fromOwnerId || !options.toOwnerId) {
-        throw new Error("reassign requires both --from <ownerId> and --to <ownerId>.");
+    if (!options.toOwnerId) {
+        throw new Error("reassign requires --to <ownerId>.");
     }
-    if (options.fromOwnerId === options.toOwnerId) {
-        throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+    if (!options.assignUnowned) {
+        if (!options.fromOwnerId) {
+            throw new Error("reassign requires --from <ownerId> (or --assign-unowned to claim ownerless records).");
+        }
+        if (options.fromOwnerId === options.toOwnerId) {
+            throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+        }
     }
     // The receiving owner must exist: a typo'd --to would otherwise write an
     // invalid owner onto every matched record.
@@ -60,7 +65,7 @@ export function buildReassignPlans(snapshot, options) {
         }
     }
     return objects.map((objectType) => {
-        const where = [`ownerId=${options.fromOwnerId}`];
+        const where = [options.assignUnowned ? "ownerId:empty" : `ownerId=${options.fromOwnerId}`];
         if (objectType === "deal" && !options.includeClosedDeals) {
             where.push("isClosed=false"); // closed deals keep their historical owner
         }
@@ -80,7 +85,9 @@ export function buildReassignPlans(snapshot, options) {
             where,
             set: { ownerId: options.toOwnerId },
             reason: options.reason ??
-                `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`,
+                (options.assignUnowned
+                    ? `reassign: claim ownerless ${objectType}s for owner ${options.toOwnerId}`
+                    : `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`),
             maxOperations: options.maxOperations,
         });
     });

package/dist/runReport.d.ts

@@ -0,0 +1,9 @@
+/** A command annotates its headline metrics (merged). */
+export declare function reportCounts(values: Record<string, unknown>): void;
+/** A command annotates a structured event (plan saved, meter charged, …). */
+export declare function reportEvent(type: string, detail?: string): void;
+/**
+ * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
+ * swallows every error. Call once per process from the entry point.
+ */
+export declare function flushRunReport(args: string[], status: "success" | "partial" | "error", startedAt: number, error?: string): Promise<void>;

package/dist/runReport.js

@@ -0,0 +1,66 @@
+/**
+ * Opt-in CLI → hosted-app observability. When the user has paired the CLI
+ * (`login --via <url>` → broker token), each command fire-and-forgets a run
+ * record to the hosted app's `/api/cli/run`, authenticated by the broker token.
+ *
+ * Invariants: the CLI never requires web login; this does nothing when unpaired;
+ * it never throws and never changes the CLI's exit code or output. Reporting is
+ * pure added value for users who granted it.
+ */
+import { getCredential } from "./credentials.js";
+let counts;
+const events = [];
+/** A command annotates its headline metrics (merged). */
+export function reportCounts(values) {
+    counts = { ...(counts ?? {}), ...values };
+}
+/** A command annotates a structured event (plan saved, meter charged, …). */
+export function reportEvent(type, detail) {
+    events.push({ ts: Date.now(), type, detail });
+}
+// Setup/inspection verbs aren't interesting as "runs" — skip the noise.
+const SKIP_COMMANDS = new Set([
+    "login",
+    "logout",
+    "doctor",
+    "help",
+    "profiles",
+    "--help",
+    "-h",
+    "--version",
+    "-v",
+]);
+/**
+ * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
+ * swallows every error. Call once per process from the entry point.
+ */
+export async function flushRunReport(args, status, startedAt, error) {
+    const command = args[0];
+    if (!command || SKIP_COMMANDS.has(command))
+        return;
+    const broker = getCredential("broker");
+    if (!broker?.baseUrl || !broker.accessToken)
+        return; // opt-in: only when paired
+    const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+    const finishedAt = Date.now();
+    try {
+        await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                command: `${command}${sub}`,
+                status,
+                startedAt,
+                finishedAt,
+                durationMs: finishedAt - startedAt,
+                counts,
+                events: events.length ? events : undefined,
+                error,
+            }),
+            signal: AbortSignal.timeout(4000),
+        });
+    }
+    catch {
+        // Observability is best-effort; never affect the CLI outcome.
+    }
+}

package/dist/types.d.ts

@@ -10,7 +10,29 @@ 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;
+    /**
+     * Owner to stamp on the new record (canonical owner id). The connector maps
+     * it to the CRM's owner property (HubSpot `hubspot_owner_id`) at create time
+     * so a lead is never born ownerless. Absent = leave unassigned.
+     */
+    ownerId?: string;
+    /** Audit label for how the owner was chosen (e.g. "fixed", "territory:0"). */
+    assignedBy?: string;
+};
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**
  * One claim that a canonical record exists in an external system. A record
@@ -125,6 +147,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
@@ -101,7 +102,10 @@ emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
   duplicate groups by normalized identity key, one `merge_records` per group,
   deterministic survivor selection (`richest` / `oldest`).
 - `buildReassignPlans(snapshot, options: ReassignOptions)` — one plan per
-  `ReassignObjectType`, account-lifted scoping, stage exclusions.
+  `ReassignObjectType`, account-lifted scoping, stage exclusions. With
+  `assignUnowned` (CLI `--assign-unowned`) it targets ownerless records
+  (`ownerId:empty`) and claims them for `--to` — the backfill twin of
+  `enrich acquire`'s create-time assignment, for clearing existing ownerless debt.
 
 `fix` is CLI-only composition of existing surfaces (audit → suggest →
 approve → apply for one rule).
@@ -120,6 +124,52 @@ 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.
+- **LinkedIn source** (`connectors/linkedin.ts`, `acquireLinkedIn.ts`): the
+  injectable `LinkedInProvider` interface with a default HeyReach adapter
+  (`createHeyReachProvider`, `HEYREACH_BASE`, `X-API-KEY`, `normalizeHeyReachLead`)
+  and `createFakeLinkedInProvider` for keyless/offline tests; `createLinkedInProvider`
+  selects the adapter (`heyreach` only; rejects unknown). `discoverLinkedInProspects`
+  pulls a HeyReach lead list and `linkedInProspectToProspect` maps each lead to the
+  canonical `Prospect` (match key = LinkedIn URL), so ICP scoring / dedup / meter /
+  apply are reused unchanged. Phase 1 is discovery-only — read-only, never sends.
+- **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.
+- **Assignment** (`assign.ts`): `AssignmentPolicy` (`fixed` / `round-robin` /
+  `territory` / `account-owner`), `parseAssignmentPolicy`, pure
+  `resolveAssignment(policy, ctx, index, knownOwnerIds)`. Set
+  `EnrichConfig.acquire.assign` and `buildAcquirePlan` stamps `ownerId` into each
+  `create_record` payload so a **lead is never born ownerless** — the connector
+  maps it to HubSpot `hubspot_owner_id` at create time. Round-robin distributes
+  by the within-run index (deterministic, no persisted cursor); every result is
+  gated by the snapshot's active owners (an unknown/inactive owner collapses to
+  unassigned, never a bad write). The CLI defaults to the portal's sole active
+  owner when no policy is set (or `--assign-owner <id>`); with multiple owners
+  and no policy it warns and leaves leads unassigned rather than guess. The same
+  policy backfills existing debt via `reassign --assign-unowned`.
+
+`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