fullstackgtm 0.42.0 → 0.43.0

package/src/connectors/salesforce.ts

@@ -80,28 +80,52 @@ export function createSalesforceConnector(
   // confirmed miss is created, and an ambiguous name (>1 match) is refused.
   // Caches within the run so the same name is never created twice — shared by
   // `link_record`'s create:<Name> path and `create_record`'s company linking.
-  async function resolveOrCreateAccountByName(
+  async function resolveOrCreateAccount(
     name: string,
+    domain?: string,
   ): Promise<{ id: string; createdNew: boolean } | { ambiguous: number }> {
-    const nameKey = name.toLowerCase();
-    const cached = createdAccountsByName.get(nameKey);
+    const cacheKey = domain ? `d:${domain.toLowerCase()}` : `n:${name.toLowerCase()}`;
+    const cached = createdAccountsByName.get(cacheKey);
     if (cached) return { id: cached, createdNew: false };
-    const soqlName = name.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-    const matches = await query(`SELECT Id FROM Account WHERE Name = '${soqlName}' LIMIT 3`);
-    if (matches.length > 1) return { ambiguous: matches.length };
+    const esc = (v: string) => v.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+
+    // 1. Domain-first match on Website (the accurate key; Website often stores a
+    //    full URL, so match by substring).
+    if (domain) {
+      const byDomain = await query(`SELECT Id FROM Account WHERE Website LIKE '%${esc(domain)}%' LIMIT 3`);
+      if (byDomain.length > 1) return { ambiguous: byDomain.length };
+      if (byDomain.length === 1) {
+        const id = String(byDomain[0].Id);
+        createdAccountsByName.set(cacheKey, id);
+        return { id, createdNew: false };
+      }
+    }
+    // 2. Exact-name match; stamp Website if the account has none (fill-blank).
+    const byName = await query(`SELECT Id, Website FROM Account WHERE Name = '${esc(name)}' LIMIT 3`);
+    if (byName.length > 1) return { ambiguous: byName.length };
     let id: string;
     let createdNew = false;
-    if (matches.length === 1) {
-      id = String(matches[0].Id);
+    if (byName.length === 1) {
+      id = String(byName[0].Id);
+      if (domain && !stringOrUndefined(byName[0].Website)) {
+        try {
+          await request(`/services/data/${apiVersion}/sobjects/Account/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            body: JSON.stringify({ Website: domain }),
+          });
+        } catch {
+          // best-effort fill — a failed Website stamp must not sink the create.
+        }
+      }
     } else {
       const created = await request(`/services/data/${apiVersion}/sobjects/Account`, {
         method: "POST",
-        body: JSON.stringify({ Name: name }),
+        body: JSON.stringify({ Name: name, ...(domain ? { Website: domain } : {}) }),
       });
       id = String(created.id);
       createdNew = true;
     }
-    createdAccountsByName.set(nameKey, id);
+    createdAccountsByName.set(cacheKey, id);
     return { id, createdNew };
   }
 
@@ -534,7 +558,7 @@ export function createSalesforceConnector(
     }
 
     if (operation.objectType === "account") {
-      const resolved = await resolveOrCreateAccountByName(matchValue);
+      const resolved = await resolveOrCreateAccount(matchValue);
       if ("ambiguous" in resolved) {
         return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — ${resolved.ambiguous} accounts named "${matchValue}". Not creating.` };
       }
@@ -574,7 +598,7 @@ export function createSalesforceConnector(
     let companyNote = "";
     if (payload.associateCompanyName) {
       try {
-        const resolved = await resolveOrCreateAccountByName(payload.associateCompanyName);
+        const resolved = await resolveOrCreateAccount(payload.associateCompanyName, payload.associateCompanyDomain);
         if ("ambiguous" in resolved) {
           companyNote = ` Account "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
         } else {
@@ -582,7 +606,8 @@ export function createSalesforceConnector(
             method: "PATCH",
             body: JSON.stringify({ AccountId: resolved.id }),
           });
-          companyNote = ` Linked to account "${payload.associateCompanyName}" (${resolved.id}).`;
+          const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+          companyNote = ` Linked to account "${payload.associateCompanyName}"${domainNote} (${resolved.id}).`;
         }
       } catch (error) {
         // Association is best-effort — the contact create already succeeded.
@@ -726,7 +751,7 @@ export function createSalesforceConnector(
             if (!name) {
               return { operationId: operation.id, status: "skipped", detail: "create: needs an account name (create:<Name>)." };
             }
-            const resolved = await resolveOrCreateAccountByName(name);
+            const resolved = await resolveOrCreateAccount(name);
             if ("ambiguous" in resolved) {
               return {
                 operationId: operation.id,

package/src/draft.ts

@@ -305,9 +305,6 @@ export function draft(opts: {
   const minScore = opts.minScore ?? 80;
   const channel: DraftChannel = opts.channel ?? "task";
   const freshnessDays = opts.freshnessDays ?? DEFAULT_FRESHNESS_DAYS;
-  // `task`/`email`/`linkedin` all write a CRM task through the same gate; the
-  // object the task hangs off is the contact when known, else the account.
-  const objectType: GtmObjectType = "contact";
 
   const hot = opts.decisions
     .filter((d) => d.decision === "send" && d.score >= minScore)
@@ -349,11 +346,35 @@ export function draft(opts: {
       continue;
     }
 
+    // Resolve a REAL CRM target from the judge decision: a contact id (preferred
+    // — that's who we message), else the account id. A domain-only decision
+    // (the account isn't in the CRM yet) cannot hang a task off a record — reject
+    // it with the fix, instead of forging a contact-typed op carrying a domain.
+    let objectType: GtmObjectType;
+    let objectId: string;
+    let targetNote: string;
+    if (decision.contact?.id) {
+      objectType = "contact";
+      objectId = decision.contact.id;
+      targetNote = `contact ${decision.contact.email ?? decision.contact.id}`;
+    } else if (decision.accountId) {
+      objectType = "account";
+      objectId = decision.accountId;
+      targetNote = `account ${domain}`;
+    } else {
+      rejected.push({
+        accountDomain: domain,
+        opener,
+        reason: `account ${domain} is not in the CRM — acquire it first (enrich acquire), then judge with a snapshot, before drafting`,
+      });
+      continue;
+    }
+
     const stale = isStaleTrigger(signal.firstSeen, now, freshnessDays);
     const ev = draftEvidence(signal, nowIso);
     evidence.push(ev);
 
-    const reasonBase = `Signal-grounded opener for ${domain}: "${signal.trigger}"`;
+    const reasonBase = `Signal-grounded opener for ${domain} → ${targetNote}: "${signal.trigger}"`;
     const reason = stale
       ? `${reasonBase} [staleTrigger: grounding signal first seen ${signal.firstSeen}, older than ${freshnessDays}d — could this have gone out last month unchanged?]`
       : reasonBase;
@@ -361,7 +382,7 @@ export function draft(opts: {
     operations.push({
       id: draftOperationId(channel, domain),
       objectType,
-      objectId: domain,
+      objectId,
       operation: "create_task",
       field: "follow_up_task",
       beforeValue: null,

package/src/enrich.ts

@@ -92,6 +92,12 @@ export type AcquireCreateMap = {
   matchKey: string;
   /** Optional source path to a company name; the connector resolves-or-creates it. */
   associateCompanyFrom?: string;
+  /**
+   * Optional source path to the company domain. With it (or a derivable email
+   * domain) the connector resolves the account by domain and stamps the domain
+   * on it — so the lead's account is signal-watchable, not just a text field.
+   */
+  associateCompanyDomainFrom?: string;
 };
 
 /**
@@ -392,6 +398,8 @@ export function builtinAcquirePreset(source: string | undefined): EnrichConfig |
               company: "companyName",
               email: "email",
             },
+            associateCompanyFrom: "companyName",
+            associateCompanyDomainFrom: "companyDomain",
           },
         },
       },
@@ -418,6 +426,8 @@ export function builtinAcquirePreset(source: string | undefined): EnrichConfig |
             company: "companyName",
             hs_linkedin_url: "linkedin",
           },
+          associateCompanyFrom: "companyName",
+          associateCompanyDomainFrom: "companyDomain",
         },
       },
     },
@@ -733,6 +743,27 @@ function isEmptyValue(value: unknown): boolean {
   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: unknown): string | undefined {
+  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: unknown): string | undefined {
+  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: unknown, b: unknown): boolean {
   if (isEmptyValue(a) && isEmptyValue(b)) return true;
@@ -1130,6 +1161,20 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       const companyValue = sourceValueAt(record.payload, createMap.associateCompanyFrom);
       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: string | undefined;
+    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,
@@ -1162,8 +1207,13 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       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),
@@ -1173,7 +1223,7 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       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/src/health.ts

@@ -35,6 +35,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 = {
@@ -68,11 +80,21 @@ export type HealthRollup = {
 export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, at: string): HealthEntry {
   const byRule: Record<string, number> = {};
   const severityCounts: Record<AuditFindingSeverity, number> = { info: 0, warning: 0, critical: 0 };
+  const typeTally: Record<"account" | "contact" | "deal", { findings: number; weightedFindings: number }> = {
+    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 = {
@@ -82,8 +104,23 @@ export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, a
     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: number, recordCount: number) =>
+    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"] as const).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;
+    },
+    {} as HealthEntry["byObjectType"],
+  );
+
+  const score = scoreFor(weightedFindings, records.total);
 
   return {
     at,
@@ -94,6 +131,7 @@ export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, a
     records,
     byRule,
     severityCounts,
+    byObjectType,
   };
 }
 
@@ -155,6 +193,13 @@ export function healthToMarkdown(rollup: HealthRollup): string {
     "",
   );
 
+  lines.push("## By object type", "", "| Type | Score | Findings | Records |", "| --- | --- | --- | --- |");
+  for (const t of ["account", "contact", "deal"] as const) {
+    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/src/index.ts

@@ -97,6 +97,16 @@ export {
   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,

package/src/init.ts

@@ -0,0 +1,163 @@
+/**
+ * `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, type EnrichConfig } from "./enrich.ts";
+import { DEFAULT_FIT_THRESHOLD, 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 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(): Icp {
+  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: InitSource): EnrichConfig {
+  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?: string): string {
+  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: Required<Pick<ScaffoldOptions, "source" | "provider">> & { profile?: string }): string {
+  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: ScaffoldOptions = {}): ScaffoldFile[] {
+  const source: InitSource = opts.source ?? "pipe0";
+  const provider: InitProvider = 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/src/judge.ts

@@ -35,6 +35,23 @@ 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;
@@ -333,22 +350,75 @@ export function accountRecentlyTouched(
 }
 
 /**
- * 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(
+function findAccountAndBestContact(
   accountDomain: string,
   snapshot: CanonicalGtmSnapshot,
-): { jobTitle?: string; jobLevel?: string; jobDepartment?: string; headline?: string } | undefined {
+): {
+  account: CanonicalGtmSnapshot["accounts"][number];
+  contact?: CanonicalGtmSnapshot["contacts"][number];
+  contacts: CanonicalGtmSnapshot["contacts"];
+} | undefined {
   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) return undefined;
-  return { jobTitle: withTitle.title };
+  // 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: string,
+  snapshot: CanonicalGtmSnapshot,
+): { jobTitle?: string; jobLevel?: string; jobDepartment?: string; headline?: string } | undefined {
+  const found = findAccountAndBestContact(accountDomain, snapshot);
+  if (!found?.contact) return undefined;
+  return { jobTitle: found.contact.title };
+}
+
+/**
+ * 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 };
+
+/** Cap on candidate contacts surfaced per account (the rest stay in the CRM). */
+const MAX_CANDIDATE_CONTACTS = 10;
+
+const toContactRef = (c: CanonicalGtmSnapshot["contacts"][number]): ContactRef => ({
+  id: c.id,
+  ...(c.email ? { email: c.email } : {}),
+  ...(c.title ? { title: c.title } : {}),
+});
+
+export function resolveAccountTarget(
+  accountDomain: string,
+  snapshot: CanonicalGtmSnapshot,
+): { accountId?: string; contact?: ContactRef; contacts?: ContactRef[] } {
+  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) } : {}),
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -559,10 +629,11 @@ export async function judgeSignals(opts: {
 
   const decisions: JudgeDecision[] = [];
   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;
+      opts.withHistory && opts.icp && opts.snapshot ? bestContactForAccount(domain, opts.snapshot) : undefined;
     const score = scoreAccount({
       accountDomain: domain,
       signals,
@@ -578,7 +649,10 @@ export async function judgeSignals(opts: {
       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));