fullstackgtm 0.42.0 → 0.43.0

package/dist/enrich.js

@@ -247,6 +247,8 @@ export function builtinAcquirePreset(source) {
                             company: "companyName",
                             email: "email",
                         },
+                        associateCompanyFrom: "companyName",
+                        associateCompanyDomainFrom: "companyDomain",
                     },
                 },
             },
@@ -274,6 +276,8 @@ export function builtinAcquirePreset(source) {
                         company: "companyName",
                         hs_linkedin_url: "linkedin",
                     },
+                    associateCompanyFrom: "companyName",
+                    associateCompanyDomainFrom: "companyDomain",
                 },
             },
         },
@@ -490,6 +494,28 @@ function crmFieldValue(snapshot, objectType, objectId, field) {
 function isEmptyValue(value) {
     return value === undefined || value === null || (typeof value === "string" && value.trim() === "");
 }
+/** Bare registrable host from a domain or URL ("https://www.x.com/a" → "x.com"). */
+function normalizeCompanyDomain(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const host = value
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//, "")
+        .replace(/^www\./, "")
+        .replace(/\/.*$/, "")
+        .replace(/\s+/g, "");
+    return host && host.includes(".") ? host : undefined;
+}
+/** The domain of a work email ("vp@acme.com" → "acme.com"), else undefined. */
+function domainFromEmail(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const at = value.lastIndexOf("@");
+    if (at < 0)
+        return undefined;
+    return normalizeCompanyDomain(value.slice(at + 1));
+}
 /** Values compare as trimmed strings; numbers compare numerically. */
 function sameValue(a, b) {
     if (isEmptyValue(a) && isEmptyValue(b))
@@ -831,6 +857,21 @@ export function buildAcquirePlan(options) {
             if (!isEmptyValue(companyValue))
                 associateCompanyName = String(companyValue);
         }
+        // The company domain makes the lead's account signal-watchable. Prefer the
+        // configured source path; fall back to the work email's domain (free, and
+        // for B2B leads the email domain IS the company domain).
+        let associateCompanyDomain;
+        if (associateCompanyName) {
+            const fromPath = createMap.associateCompanyDomainFrom
+                ? sourceValueAt(record.payload, createMap.associateCompanyDomainFrom)
+                : undefined;
+            const candidate = !isEmptyValue(fromPath)
+                ? String(fromPath)
+                : domainFromEmail(sourceValueAt(record.payload, "email"));
+            const normalized = normalizeCompanyDomain(candidate);
+            if (normalized)
+                associateCompanyDomain = normalized;
+        }
         const recordEvidence = evidenceFor(source, sourceConfig.kind, sourceConfig.format, record, undefined, nowIso);
         evidence.push(recordEvidence);
         // Resolve ownership BEFORE the meter-charged create lands, so the lead is
@@ -853,8 +894,13 @@ export function buildAcquirePlan(options) {
             source,
             estCostUsd: costPerRecord,
             associateCompanyName,
+            ...(associateCompanyDomain ? { associateCompanyDomain } : {}),
             ...(ownerId ? { ownerId, assignedBy } : {}),
         };
+        // Surface the account link in the dry-run so it is not a silent side-effect.
+        const accountNote = associateCompanyName
+            ? ` Resolves/creates its account "${associateCompanyName}"${associateCompanyDomain ? ` (${associateCompanyDomain})` : ""} and links the lead.`
+            : "";
         operations.push({
             id: `op_acq_${fnv1a(`${source}:${record.objectType}:${matchValue}`)}`,
             objectType: canonicalObjectType(record.objectType),
@@ -863,7 +909,7 @@ export function buildAcquirePlan(options) {
             beforeValue: null,
             afterValue: payload,
             reason: `${source} sourced net-new ${record.objectType} "${describeSourceRecord(record)}" ` +
-                `(${createMap.matchKey}=${matchValue}); no CRM match — create as a lead.`,
+                `(${createMap.matchKey}=${matchValue}); no CRM match — create as a lead.${accountNote}`,
             sourceRuleOrPolicy: `acquire:${source}`,
             riskLevel: "medium",
             approvalRequired: true,

package/dist/health.d.ts

@@ -21,6 +21,18 @@ export type HealthEntry = {
     byRule: Record<string, number>;
     /** Finding count per severity. */
     severityCounts: Record<AuditFindingSeverity, number>;
+    /**
+     * Per-object-type breakdown — so "is my contact data clean but my pipeline
+     * messy?" is answerable without re-auditing. Each type carries its own
+     * record-normalized score (same curve as the overall score, scoped to that
+     * type's records + findings).
+     */
+    byObjectType: Record<"account" | "contact" | "deal", {
+        records: number;
+        findings: number;
+        weightedFindings: number;
+        score: number;
+    }>;
 };
 export type HealthRuleDelta = {
     ruleId: string;

package/dist/health.js

@@ -23,11 +23,21 @@ const SEVERITY_WEIGHT = { info: 1, warning: 3, critical: 10 };
 export function computeHealth(plan, snapshot, at) {
     const byRule = {};
     const severityCounts = { info: 0, warning: 0, critical: 0 };
+    const typeTally = {
+        account: { findings: 0, weightedFindings: 0 },
+        contact: { findings: 0, weightedFindings: 0 },
+        deal: { findings: 0, weightedFindings: 0 },
+    };
     let weightedFindings = 0;
     for (const finding of plan.findings) {
         byRule[finding.ruleId] = (byRule[finding.ruleId] ?? 0) + 1;
         severityCounts[finding.severity] += 1;
         weightedFindings += SEVERITY_WEIGHT[finding.severity];
+        const t = finding.objectType;
+        if (t === "account" || t === "contact" || t === "deal") {
+            typeTally[t].findings += 1;
+            typeTally[t].weightedFindings += SEVERITY_WEIGHT[finding.severity];
+        }
     }
     const records = {
         accounts: snapshot.accounts.length,
@@ -35,8 +45,18 @@ export function computeHealth(plan, snapshot, at) {
         deals: snapshot.deals.length,
         total: snapshot.accounts.length + snapshot.contacts.length + snapshot.deals.length,
     };
-    const penalty = weightedFindings / Math.max(records.total, 1);
-    const score = Math.round(100 / (1 + penalty));
+    const scoreFor = (weighted, recordCount) => Math.round(100 / (1 + weighted / Math.max(recordCount, 1)));
+    const recordsByType = { account: records.accounts, contact: records.contacts, deal: records.deals };
+    const byObjectType = ["account", "contact", "deal"].reduce((acc, t) => {
+        acc[t] = {
+            records: recordsByType[t],
+            findings: typeTally[t].findings,
+            weightedFindings: typeTally[t].weightedFindings,
+            score: scoreFor(typeTally[t].weightedFindings, recordsByType[t]),
+        };
+        return acc;
+    }, {});
+    const score = scoreFor(weightedFindings, records.total);
     return {
         at,
         planId: plan.id,
@@ -46,6 +66,7 @@ export function computeHealth(plan, snapshot, at) {
         records,
         byRule,
         severityCounts,
+        byObjectType,
     };
 }
 /** Roll a timeline up into the current state, the change since last time, and per-rule deltas. */
@@ -95,6 +116,12 @@ export function healthToMarkdown(rollup) {
         ? "(first audit — no prior reading)"
         : `${arrow(scoreDelta)} ${scoreDelta >= 0 ? "+" : ""}${scoreDelta} since the previous audit`;
     lines.push(`Score: **${current.score}/100** ${deltaText}`, `Audits: ${rollup.auditCount} over ${shortDate(rollup.first)} → ${shortDate(rollup.latest)}`, `Findings: ${current.findings} (${current.severityCounts.critical} critical, ${current.severityCounts.warning} warning, ${current.severityCounts.info} info)`, `Records: ${current.records.accounts} accounts, ${current.records.contacts} contacts, ${current.records.deals} deals`, "");
+    lines.push("## By object type", "", "| Type | Score | Findings | Records |", "| --- | --- | --- | --- |");
+    for (const t of ["account", "contact", "deal"]) {
+        const b = current.byObjectType[t];
+        lines.push(`| ${t} | ${b.score}/100 | ${b.findings} | ${b.records} |`);
+    }
+    lines.push("");
     if (rollup.history.length > 1) {
         lines.push("## Trend", "");
         for (const point of rollup.history) {

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { createStripeConnector, type StripeConnectorOptions } from "./connectors
 export { activeProfile, credentialsDir, credentialsPath, DEFAULT_PROFILE, deleteCredential, getCredential, listProfiles, resolveHubspotAccessToken, resolveHubspotConnection, setActiveProfile, storeCredential, type HubspotConnection, type StoredCredential, } from "./credentials.ts";
 export { generateDemoSnapshot, type DemoSnapshotOptions } from "./demo.ts";
 export { buildEnrichPlan, createFileEnrichRunStore, DEFAULT_STALE_DAYS, ENRICH_CONFIG_FILE_NAME, enrichRunId, inferIngestObjectType, ingestKeyValue, latestStamps, loadEnrichConfig, matchSourceRecord, parseCsv, parseEnrichConfig, resolveCrmField, selectStaleWork, sourceValueAt, stagedSourceRecords, staleDaysFor, type BuildEnrichPlanOptions, type EnrichAmbiguity, type EnrichConfig, type EnrichCounts, type EnrichFieldConfig, type EnrichMatchConfig, type EnrichMode, type EnrichObjectType, type EnrichPlanResult, type EnrichRun, type EnrichRunStore, type EnrichSourceConfig, type EnrichSourceRecord, type EnrichStamp, type EnrichWorkItem, type MatchOutcome, } from "./enrich.ts";
+export { scaffoldWorkspace, starterEnrichConfig, starterIcp, starterPlaybook, type InitProvider, type InitSource, type ScaffoldFile, type ScaffoldOptions, } from "./init.ts";
 export { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloClient, type ApolloClientOptions, type ApolloPullKey, type ApolloPullResult, } from "./enrichApollo.ts";
 export { diffFindings, diffSnapshots, diffToMarkdown, type CollectionDiff, type FieldChange, type FindingsDrift, type RecordChange, type SnapshotDiff, } from "./diff.ts";
 export { mergeSnapshots, type MergeConflict, type MergeMatch, type MergeReport, type MergeSuggestion, } from "./merge.ts";

package/dist/index.js

@@ -13,6 +13,7 @@ export { createStripeConnector } from "./connectors/stripe.js";
 export { activeProfile, credentialsDir, credentialsPath, DEFAULT_PROFILE, deleteCredential, getCredential, listProfiles, resolveHubspotAccessToken, resolveHubspotConnection, setActiveProfile, storeCredential, } from "./credentials.js";
 export { generateDemoSnapshot } from "./demo.js";
 export { buildEnrichPlan, createFileEnrichRunStore, DEFAULT_STALE_DAYS, ENRICH_CONFIG_FILE_NAME, enrichRunId, inferIngestObjectType, ingestKeyValue, latestStamps, loadEnrichConfig, matchSourceRecord, parseCsv, parseEnrichConfig, resolveCrmField, selectStaleWork, sourceValueAt, stagedSourceRecords, staleDaysFor, } from "./enrich.js";
+export { scaffoldWorkspace, starterEnrichConfig, starterIcp, starterPlaybook, } from "./init.js";
 export { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, } from "./enrichApollo.js";
 export { diffFindings, diffSnapshots, diffToMarkdown, } from "./diff.js";
 export { mergeSnapshots, } from "./merge.js";

package/dist/init.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `fullstackgtm init` — scaffold a GTM workspace from cold scratch.
+ *
+ * The product thesis (see docs/recipes.md): the CLI ships governed PRIMITIVES;
+ * the user's coding agent is the orchestrator. There is deliberately no
+ * `outbound` mega-verb. `init` is the one piece of scaffolding that earns its
+ * keep — it writes the three files a workspace needs so the very first
+ * `enrich acquire` / `signals` / `judge` / `draft` commands work, plus a
+ * PLAYBOOK that points at the recipes wired with THIS workspace's source and
+ * provider.
+ *
+ * It is a pure file-writer: no network, no credentials, never overwrites
+ * without `--force`. The starter ICP is a valid (editable) example so
+ * `icp show` / `enrich acquire` run immediately; re-run `icp interview` to
+ * replace it with a real one.
+ */
+import { type EnrichConfig } from "./enrich.ts";
+import { type Icp } from "./icp.ts";
+export type InitProvider = "hubspot" | "salesforce";
+export type InitSource = "pipe0" | "explorium" | "linkedin";
+export type ScaffoldOptions = {
+    /** discovery source the acquire preset + playbook are wired for. Default "pipe0". */
+    source?: InitSource;
+    /** CRM the playbook writes against. Default "hubspot". */
+    provider?: InitProvider;
+    /** profile the playbook scopes commands to (omitted = default profile). */
+    profile?: string;
+};
+export type ScaffoldFile = {
+    path: string;
+    content: string;
+};
+/** A generic, valid starter ICP. Edit it, or replace via `icp interview`. */
+export declare function starterIcp(): Icp;
+/** The acquire preset for the chosen source, with an explicit (placeholder)
+ *  assign policy so the seam is visible — leads are never silently ownerless. */
+export declare function starterEnrichConfig(source: InitSource): EnrichConfig;
+/** The workspace PLAYBOOK: the cold-start + outbound-loop recipes wired with the
+ *  chosen source/provider/profile, pointing at docs/recipes.md for the rest. */
+export declare function starterPlaybook(opts: Required<Pick<ScaffoldOptions, "source" | "provider">> & {
+    profile?: string;
+}): string;
+/**
+ * Build the set of files `init` would write (pure — no IO). The caller decides
+ * which to actually write (skipping existing files unless --force).
+ */
+export declare function scaffoldWorkspace(opts?: ScaffoldOptions): ScaffoldFile[];

package/dist/init.js

@@ -0,0 +1,140 @@
+/**
+ * `fullstackgtm init` — scaffold a GTM workspace from cold scratch.
+ *
+ * The product thesis (see docs/recipes.md): the CLI ships governed PRIMITIVES;
+ * the user's coding agent is the orchestrator. There is deliberately no
+ * `outbound` mega-verb. `init` is the one piece of scaffolding that earns its
+ * keep — it writes the three files a workspace needs so the very first
+ * `enrich acquire` / `signals` / `judge` / `draft` commands work, plus a
+ * PLAYBOOK that points at the recipes wired with THIS workspace's source and
+ * provider.
+ *
+ * It is a pure file-writer: no network, no credentials, never overwrites
+ * without `--force`. The starter ICP is a valid (editable) example so
+ * `icp show` / `enrich acquire` run immediately; re-run `icp interview` to
+ * replace it with a real one.
+ */
+import { builtinAcquirePreset, ENRICH_CONFIG_FILE_NAME } from "./enrich.js";
+import { DEFAULT_FIT_THRESHOLD } from "./icp.js";
+/** A placeholder owner id that can never match a real one, so the assign block
+ *  is VISIBLE (leads route through it) yet safe: an unknown owner resolves to
+ *  unassigned with a warning, never a wrong owner. Replace before acquiring. */
+const PLACEHOLDER_OWNER = "REPLACE_WITH_OWNER_ID";
+/** A generic, valid starter ICP. Edit it, or replace via `icp interview`. */
+export function starterIcp() {
+    return {
+        name: "Example ICP — edit me (or rebuild with `fullstackgtm icp interview`)",
+        firmographics: {
+            industries: ["software", "saas"],
+            employeeBands: ["51-200", "201-500", "501-1000"],
+            geos: ["us"],
+        },
+        persona: {
+            jobLevels: ["vp", "director", "manager"],
+            departments: ["sales", "operations"],
+            titleKeywords: ["revenue operations", "revops", "sales operations", "gtm operations"],
+        },
+        scoring: { threshold: DEFAULT_FIT_THRESHOLD },
+    };
+}
+/** The acquire preset for the chosen source, with an explicit (placeholder)
+ *  assign policy so the seam is visible — leads are never silently ownerless. */
+export function starterEnrichConfig(source) {
+    const preset = builtinAcquirePreset(source);
+    if (!preset?.acquire) {
+        // builtinAcquirePreset covers pipe0/explorium/linkedin, so this is unreachable
+        // for the typed InitSource set — guard anyway rather than emit a broken file.
+        throw new Error(`init: no acquire preset for source "${source}"`);
+    }
+    return {
+        ...preset,
+        acquire: { ...preset.acquire, assign: { strategy: "fixed", ownerId: PLACEHOLDER_OWNER } },
+    };
+}
+function profileFlag(profile) {
+    return profile ? ` --profile ${profile}` : "";
+}
+/** The workspace PLAYBOOK: the cold-start + outbound-loop recipes wired with the
+ *  chosen source/provider/profile, pointing at docs/recipes.md for the rest. */
+export function starterPlaybook(opts) {
+    const { source, provider, profile } = opts;
+    const p = profileFlag(profile);
+    const loginSource = source === "linkedin" ? "heyreach" : source;
+    return `# Workspace playbook
+
+Scaffolded by \`fullstackgtm init\` for **${provider}**, discovery via **${source}**${profile ? `, profile **${profile}**` : ""}.
+
+This CLI ships governed **primitives** — there is no \`outbound\` command. **You
+(the coding agent) are the orchestrator:** chain the verbs into the play the
+operator wants, surface the one approve gate, and bridge the last mile to the
+sender. **The package never sends** — \`draft\` produces an approved task/opener;
+the actual send happens in the operator's own channel tool.
+
+Full recipe set: **docs/recipes.md** (cold-start, the trigger→judge→draft
+outbound loop, scheduled-continuous, ABM-from-companies, hygiene-gated).
+
+## 0. Connect (secrets via stdin/env, never argv)
+
+\`\`\`bash
+echo "$${provider === "hubspot" ? "HUBSPOT_TOKEN" : "SALESFORCE_ACCESS_TOKEN"}" | fullstackgtm login ${provider}${p}
+echo "$${loginSource.toUpperCase()}_API_KEY" | fullstackgtm login ${loginSource}${p}
+\`\`\`
+
+## 1. Edit your targeting + assignment
+
+- \`icp.json\` — the starter ICP. Edit it, or rebuild: \`fullstackgtm icp interview\`
+  (an agent drives the questions) → \`fullstackgtm icp set answers.json\`.
+- \`${ENRICH_CONFIG_FILE_NAME}\` — set \`acquire.assign.ownerId\` (currently
+  \`${PLACEHOLDER_OWNER}\`) so acquired leads are never ownerless, or pass
+  \`--assign-owner <id>\` per run. Tune \`acquire.budget\` (records + spend caps).
+
+## 2. Cold start — fill the CRM with targeted, owned, emailed leads
+
+\`\`\`bash
+fullstackgtm enrich acquire --source ${source} --provider ${provider}${p} --json   # dry-run plan, writes NOTHING
+fullstackgtm enrich acquire --source ${source} --provider ${provider}${p} --save    # persist as needs_approval
+fullstackgtm plans approve <plan-id>${p} --operations all
+fullstackgtm apply --plan-id <plan-id> --provider ${provider}${p}
+\`\`\`
+
+Each lead lands owner-stamped and linked to a domain-stamped **account**, so the
+signals/judge layer can watch it.
+
+## 3. Outbound loop — reach an account the week something changes
+
+\`\`\`bash
+fullstackgtm signals fetch --bucket job,funding --watchlist crm:<segment>${p} --save
+fullstackgtm icp judge --signals-from latest --provider ${provider}${p} --save --json   # pass the snapshot → resolves accountId + contact
+fullstackgtm draft --from-judge latest --channel email${p} --save --json                # one grounded opener per hot account, as a create_task
+fullstackgtm plans approve <plan-id>${p} --operations all
+fullstackgtm apply --plan-id <plan-id> --provider ${provider}${p}
+# → the agent sends the approved opener via the operator's channel tool, then:
+fullstackgtm signals outcome --account <domain> --contact <contactId> --result replied${p}
+\`\`\`
+
+A domain-only judge decision (account not yet in the CRM) is rejected by \`draft\`
+with "acquire it first" — run step 2 for that account, then re-judge.
+
+## The boundary
+
+- **Read freely. Write only through \`plans approve → apply\`.**
+- **The package never sends.** \`draft\` is the last governed step.
+- **You are the orchestrator.** These are starting points — compose them.
+`;
+}
+/**
+ * Build the set of files `init` would write (pure — no IO). The caller decides
+ * which to actually write (skipping existing files unless --force).
+ */
+export function scaffoldWorkspace(opts = {}) {
+    const source = opts.source ?? "pipe0";
+    const provider = opts.provider ?? "hubspot";
+    return [
+        { path: "icp.json", content: `${JSON.stringify(starterIcp(), null, 2)}\n` },
+        {
+            path: ENRICH_CONFIG_FILE_NAME,
+            content: `${JSON.stringify(starterEnrichConfig(source), null, 2)}\n`,
+        },
+        { path: "PLAYBOOK.md", content: starterPlaybook({ source, provider, profile: opts.profile }) },
+    ];
+}

package/dist/judge.d.ts

@@ -26,6 +26,23 @@ import type { CanonicalGtmSnapshot } from "./types.ts";
 export type JudgeDecisionKind = "send" | "nurture" | "skip";
 export type JudgeDecision = {
     accountDomain: string;
+    /**
+     * The CRM account this domain resolves to, when a snapshot was provided.
+     * Absent = the account is not in the CRM (a net-new domain) — downstream
+     * verbs must acquire it before they can write against it.
+     */
+    accountId?: string;
+    /**
+     * The contact at the account to reach, when resolvable from the snapshot —
+     * the answer to "who do I message at this hot account". `draft` targets this
+     * contact's id; absent contact + present accountId targets the account.
+     */
+    contact?: ContactRef;
+    /**
+     * All in-CRM contacts at the account (primary first), capped — so an agent can
+     * multi-thread beyond the single primary. `contact` is `contacts[0]`.
+     */
+    contacts?: ContactRef[];
     /** 0-100. */
     score: number;
     decision: JudgeDecisionKind;
@@ -125,9 +142,9 @@ export declare function scoreAccount(opts: {
  */
 export declare function accountRecentlyTouched(accountDomain: string, snapshot: CanonicalGtmSnapshot, now?: Date, windowDays?: number): boolean;
 /**
- * Find the best-matching contact for an account from the snapshot, for fit
- * scoring: the account's contacts, preferring one with a title (a title is what
- * fit scores on). Returns undefined when the account/contact isn't in snapshot.
+ * Best-matching contact for an account, shaped for fit scoring (the title is
+ * what `scoreProspectAgainstIcp` reads). Returns undefined when the
+ * account/contact isn't in the snapshot.
  */
 export declare function bestContactForAccount(accountDomain: string, snapshot: CanonicalGtmSnapshot): {
     jobTitle?: string;
@@ -135,6 +152,22 @@ export declare function bestContactForAccount(accountDomain: string, snapshot: C
     jobDepartment?: string;
     headline?: string;
 } | undefined;
+/**
+ * Resolve the CRM target for an account domain: its `accountId` (when the
+ * account exists in the snapshot) and the best `contact` to reach (id + email +
+ * title). This is what `draft` writes against — a real record id, never the
+ * domain. `{}` when the account is not in the CRM (a net-new domain).
+ */
+export type ContactRef = {
+    id: string;
+    email?: string;
+    title?: string;
+};
+export declare function resolveAccountTarget(accountDomain: string, snapshot: CanonicalGtmSnapshot): {
+    accountId?: string;
+    contact?: ContactRef;
+    contacts?: ContactRef[];
+};
 /**
  * Build a `JudgeDecision` from an `AccountScore` with the deterministic baseline:
  * whyNow taken VERBATIM from the top credited signal's quote (grounded by

package/dist/judge.js

@@ -223,22 +223,54 @@ export function accountRecentlyTouched(accountDomain, snapshot, now = new Date()
     return false;
 }
 /**
- * Find the best-matching contact for an account from the snapshot, for fit
- * scoring: the account's contacts, preferring one with a title (a title is what
- * fit scores on). Returns undefined when the account/contact isn't in snapshot.
+ * Resolve a signal's account domain to the CRM account record and the best
+ * contact at it (preferring one with a title). The single domain→account→contact
+ * join used by both fit scoring and target surfacing — so "who do I message at
+ * this account" is computed once and consistently.
  */
-export function bestContactForAccount(accountDomain, snapshot) {
+function findAccountAndBestContact(accountDomain, snapshot) {
     const domain = normalizeAccountDomain(accountDomain);
     if (!domain)
         return undefined;
     const account = (snapshot.accounts ?? []).find((a) => normalizeAccountDomain(a.domain ?? "") === domain);
     if (!account)
         return undefined;
-    const contacts = (snapshot.contacts ?? []).filter((c) => c.accountId === account.id);
-    const withTitle = contacts.find((c) => c.title) ?? contacts[0];
-    if (!withTitle)
+    // Titled contacts first (a title is what fit scores on); the first is primary.
+    const contacts = (snapshot.contacts ?? [])
+        .filter((c) => c.accountId === account.id)
+        .sort((a, b) => (b.title ? 1 : 0) - (a.title ? 1 : 0));
+    return { account, contact: contacts[0], contacts };
+}
+/**
+ * Best-matching contact for an account, shaped for fit scoring (the title is
+ * what `scoreProspectAgainstIcp` reads). Returns undefined when the
+ * account/contact isn't in the snapshot.
+ */
+export function bestContactForAccount(accountDomain, snapshot) {
+    const found = findAccountAndBestContact(accountDomain, snapshot);
+    if (!found?.contact)
         return undefined;
-    return { jobTitle: withTitle.title };
+    return { jobTitle: found.contact.title };
+}
+/** Cap on candidate contacts surfaced per account (the rest stay in the CRM). */
+const MAX_CANDIDATE_CONTACTS = 10;
+const toContactRef = (c) => ({
+    id: c.id,
+    ...(c.email ? { email: c.email } : {}),
+    ...(c.title ? { title: c.title } : {}),
+});
+export function resolveAccountTarget(accountDomain, snapshot) {
+    const found = findAccountAndBestContact(accountDomain, snapshot);
+    if (!found)
+        return {};
+    const { account, contact, contacts } = found;
+    return {
+        accountId: account.id,
+        ...(contact ? { contact: toContactRef(contact) } : {}),
+        // The candidate contacts at the account, so an agent can multi-thread
+        // beyond the single primary. Capped; primary is contacts[0].
+        ...(contacts.length ? { contacts: contacts.slice(0, MAX_CANDIDATE_CONTACTS).map(toContactRef) } : {}),
+    };
 }
 // ---------------------------------------------------------------------------
 // Deterministic baseline decision
@@ -406,8 +438,9 @@ export async function judgeSignals(opts) {
     }
     const decisions = [];
     for (const [domain, signals] of byAccount) {
+        // Memory + fit stay gated on --with-history (scoring semantics unchanged).
         const recentlyTouched = opts.withHistory && opts.snapshot ? accountRecentlyTouched(domain, opts.snapshot, now) : false;
-        const bestContact = opts.icp && opts.snapshot ? bestContactForAccount(domain, opts.snapshot) : undefined;
+        const bestContact = opts.withHistory && opts.icp && opts.snapshot ? bestContactForAccount(domain, opts.snapshot) : undefined;
         const score = scoreAccount({
             accountDomain: domain,
             signals,
@@ -422,7 +455,10 @@ export async function judgeSignals(opts) {
         const decision = opts.llm && opts.promptTemplate
             ? await judgeDecisionLlm(score, opts.promptTemplate, opts.llm)
             : deterministicDecision(score);
-        decisions.push(decision);
+        // Surface the CRM target (accountId + best contact) whenever a snapshot is
+        // present — independent of --with-history. This is what makes a decision
+        // actionable: draft writes against contact.id / accountId, never the domain.
+        decisions.push(opts.snapshot ? { ...decision, ...resolveAccountTarget(domain, opts.snapshot) } : decision);
     }
     return decisions.sort((a, b) => b.score - a.score || a.accountDomain.localeCompare(b.accountDomain));
 }

package/dist/signals.d.ts

@@ -53,6 +53,9 @@ export type SignalOutcome = {
     id: string;
     accountDomain: string;
     touchId?: string;
+    /** The contact the touch went to (from the judge decision), when known — so an
+     *  outcome credits the person reached, not just the account domain. */
+    contactId?: string;
     result: SignalOutcomeResult;
     recordedAt: string;
     /** Signal ids credited (from the judge decision). */
@@ -191,6 +194,7 @@ export declare function createFileSignalStore(directory?: string): SignalStore;
 export declare function makeOutcome(input: {
     accountDomain: string;
     touchId?: string;
+    contactId?: string;
     result: SignalOutcomeResult;
     creditedSignals?: string[];
     recordedAt?: string;

package/dist/signals.js

@@ -508,6 +508,7 @@ export function makeOutcome(input) {
         id: outcomeId({ accountDomain, touchId: input.touchId, result: input.result, recordedAt }),
         accountDomain,
         ...(input.touchId !== undefined ? { touchId: input.touchId } : {}),
+        ...(input.contactId !== undefined ? { contactId: input.contactId } : {}),
         result: input.result,
         recordedAt,
         creditedSignals: input.creditedSignals ?? [],

package/dist/types.d.ts

@@ -24,6 +24,13 @@ export type CreateRecordPayload = {
     source: string;
     estCostUsd?: number;
     associateCompanyName?: string;
+    /**
+     * The company's domain, when known. The connector resolves the account by
+     * DOMAIN first (the accurate key), creates it with the domain, and fills the
+     * domain on an existing account that lacks one — so the lead's account is a
+     * real, signal-watchable record (`signals`/`icp judge` key on account domain).
+     */
+    associateCompanyDomain?: 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
@@ -291,7 +298,12 @@ export type PatchPlan = {
     status: ApprovalStatus;
     dryRun: true;
     summary: string;
+    /** The COMPLETE, object-typed findings list — every account/contact/deal
+     *  finding, each carrying its `objectType`. This is the canonical set. */
     findings: AuditFinding[];
+    /** A deal/sales-PIPELINE projection of `findings` (deal-level + the
+     *  call-next-step type) for the pipeline-trust queue — intentionally a subset.
+     *  Account/contact hygiene findings are NOT here; read `findings` for those. */
     pipelineFindings?: PipelineFinding[];
     evidence?: GtmEvidence[];
     operations: PatchOperation[];

package/docs/api.md

@@ -139,6 +139,14 @@ 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`.
 
+**Contacts or accounts.** `acquire.create` is keyed by object type, so the same
+spine acquires net-new **accounts** for ABM, not just contacts: configure
+`acquire.create.company` (match key `domain`, properties → `name`/`domain`) and
+feed company rows (`enrich ingest companies.csv --objects companies`). Each
+unmatched company becomes a `create_record` op of `objectType: account` with its
+domain stamped — so the acquired account is immediately signal-watchable
+(`signals`/`icp judge` key on account domain).
+
 - **ICP** (`icp.ts`): `Icp` type, `parseIcp`, `icpToExploriumFilters` /
   `icpToCrustdataFilters` (per-provider discovery filters), `scoreProspectAgainstIcp`
   (persona fit 0..1), `fitThreshold`, `INTERVIEW_SPEC` + `icpFromAnswers` (the