fullstackgtm 0.42.0 → 0.43.0

package/docs/recipes.md

@@ -0,0 +1,158 @@
+# Recipes — composing the primitives into GTM plays
+
+fullstackgtm ships **governed primitives**, not a workflow engine. The
+orchestrator is **your coding agent**: it composes these verbs into the play the
+operator wants, surfaces the one human approval gate, and bridges the last mile
+to the sender. There is deliberately no `outbound` mega-command — that would
+hard-code one play when the value is that you assemble the play you need.
+
+Every verb emits stable `--json`, names the object type it operates on, and
+surfaces the join it traversed (`accountId` / `domain` / `contactId`), so chains
+compose without hand-gluing the contact↔account relationship. Every write goes
+through the same `dry-run → plans approve → apply` gate. **The package never
+sends** — `draft` produces an approved *task/opener*; the actual send happens in
+the operator's channel tool (HeyReach for LinkedIn, an email tool for email),
+which the agent drives with the operator's credentials.
+
+The data spine: a **contact** belongs to an **account** (`contact.accountId`); an
+account is keyed by its **domain**. `signals`/`icp judge` watch account domains;
+`acquire` creates contacts *and* their domain-stamped accounts, so an acquired
+lead is immediately watchable. Keep that join in mind when chaining.
+
+---
+
+## Recipe 1 — Cold start: fill the CRM with targeted, owned, emailed leads
+
+**Goal:** go from nothing to a CRM seeded with on-ICP contacts (and their
+signal-watchable accounts).
+
+```bash
+# 1. Connect (secrets via stdin/env, never argv)
+echo "$HUBSPOT_TOKEN"   | fullstackgtm login hubspot
+echo "$PIPE0_KEY"       | fullstackgtm login pipe0        # work-email + company-domain resolution
+echo "$EXPLORIUM_KEY"   | fullstackgtm login explorium    # net-new discovery (optional)
+
+# 2. Build the ICP (the agent drives the interview — the CLI can't call AskUserQuestion itself)
+fullstackgtm icp interview            # emits INTERVIEW_SPEC; agent asks the questions
+fullstackgtm icp set answers.json     # writes ./icp.json
+fullstackgtm icp show                 # renders the ICP + the per-provider discovery filters
+
+# 3. Acquire — dry-run first (writes NOTHING), then approve + apply
+fullstackgtm enrich acquire --source pipe0 --provider hubspot --json   # scored, deduped, metered create_record plan
+fullstackgtm enrich acquire --source pipe0 --provider hubspot --save    # persist as needs_approval
+fullstackgtm plans approve <plan-id> --operations all
+fullstackgtm apply --plan-id <plan-id> --provider hubspot
+```
+
+**What lands:** net-new contacts, owner-stamped (never born ownerless), each
+linked to a **domain-stamped account** (so `signals`/`judge` can watch it). The
+run is **metered** (records + spend, per profile) and **resolve-first** (never
+creates over a possible dup). The dry-run op reason names the account it will
+create/link — review it before `--save`.
+
+---
+
+## Recipe 2 — Trigger-based outbound loop (the core play)
+
+**Goal:** reach an account the week something changes, with a grounded opener
+that lands on a real contact.
+
+```bash
+# 1. Detect — fresh buying triggers (free ATS boards in the box; ingest for funding/social)
+fullstackgtm signals fetch --bucket job,funding --watchlist crm:<segment> --save
+
+# 2. Judge — rank into send/nurture/skip. PASS THE SNAPSHOT so each decision
+#    resolves its CRM target (accountId + the contact[s] to reach).
+fullstackgtm icp judge --signals-from latest --provider hubspot --save --json
+#    → each decision carries: accountDomain, accountId, contact {id,email,title},
+#      contacts[] (all in-CRM contacts at the account — for multi-threading)
+
+# 3. Draft — one trigger-grounded opener per hot account, as a governed create_task
+fullstackgtm draft --from-judge latest --channel email --save --json
+#    → the task targets the resolved contact.id (or accountId). A domain-only
+#      decision (account not in the CRM yet) is REJECTED with "acquire it first"
+#      — run Recipe 1 for that account, then re-judge with the snapshot.
+
+# 4. Approve + apply (the ONE human gate)
+fullstackgtm plans approve <plan-id> --operations all
+fullstackgtm apply --plan-id <plan-id> --provider hubspot
+
+# 5. Send — OUTSIDE the package. The agent pushes the approved opener to the
+#    operator's sender (e.g. HeyReach for LinkedIn, an email tool for email)
+#    using the operator's credentials. The package never sends.
+
+# 6. Record the outcome — credit the contact you reached, so weights re-learn
+fullstackgtm signals outcome --account <domain> --contact <contactId> --result replied
+```
+
+**Why the snapshot in step 2 matters:** without it, decisions are domain-only and
+`draft` cannot target a real record — it will reject them. With it, the loop is
+contact-coherent end to end. `--with-history` additionally enables the memory
+(don't re-touch a recently-touched account) and fit-scoring inputs.
+
+---
+
+## Recipe 3 — Continuous: schedule the detect/plan side, approve daily
+
+**Goal:** run steps 1–3 of Recipe 2 on a cadence; keep the write gated.
+
+```bash
+fullstackgtm schedule add "signals fetch --bucket job,funding --watchlist crm:<segment> --save" --cron "0 7 * * 1-5"
+fullstackgtm schedule add "icp judge --signals-from latest --provider hubspot --save" --cron "15 7 * * 1-5"
+fullstackgtm schedule add "draft --from-judge latest --save" --cron "30 7 * * 1-5"
+```
+
+`schedule` is **read/plan-side only and NEVER auto-approves** — each morning a
+queue of `needs_approval` plans is waiting; the agent presents them, the operator
+approves, and `apply` runs (only `apply --plan-id <id>` is schedulable, and the
+plan's `approved` status is re-checked at every firing).
+
+---
+
+## Recipe 4 — ABM: bring your target accounts, watch them, draft when they move
+
+**Goal:** start from a list of target *companies* (not people).
+
+```bash
+# 1. Acquire the ACCOUNTS (acquire is keyed by object type — company rows → account create_record)
+fullstackgtm enrich ingest target-companies.csv --source clay --objects companies
+fullstackgtm enrich acquire --source clay --provider hubspot --save   # create.company → accounts WITH domains
+fullstackgtm plans approve <id> --operations all && fullstackgtm apply --plan-id <id> --provider hubspot
+
+# 2. From here it's Recipe 2 — the accounts now carry domains, so signals/judge watch them,
+#    and (optionally) Recipe 1's acquire fills in contacts at each.
+```
+
+The `acquire.create.company` mapping (match key `domain`, properties →
+`name`/`domain`) makes each company a **signal-watchable account**. See
+[api.md → Acquire](./api.md).
+
+---
+
+## Recipe 5 — Hygiene-gate the outbound (don't outbound into a dirty CRM)
+
+**Goal:** clean first, so signals/judge reason over correct ownership and
+de-duplicated accounts; measure the lift.
+
+```bash
+fullstackgtm health --json                      # per-object-type score + trend (read-only)
+fullstackgtm audit --provider hubspot --save     # → plan id
+fullstackgtm dedupe account --key domain --save  # collapse duplicate accounts (signals key on domain)
+fullstackgtm reassign --assign-unowned --to <ownerId> --save   # no ownerless leads
+# approve + apply each, then run Recipe 2. Re-check `health` after to attribute the lift.
+```
+
+`health --json.byObjectType` tells you *which* object type is messy (clean
+contacts but a messy pipeline read differently). Clean the accounts before
+outbound — `signals`/`judge` key on account domain, so duplicate/owner-less
+accounts distort the queue.
+
+---
+
+## The boundary, restated
+
+- **Read freely. Write only through `plans approve → apply`.** Never bypass it.
+- **The package never sends.** `draft` is the last governed step; the send is the
+  agent calling the operator's channel tool with the operator's credentials.
+- **You (the agent) are the orchestrator.** These recipes are starting points —
+  compose, branch, and loop them into the play the operator actually wants.

package/llms.txt

@@ -15,6 +15,7 @@ at/above `--fail-on`.
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
 - [Agent skill](https://github.com/fullstackgtm/core/blob/main/skills/fullstackgtm/SKILL.md): compact operating guide, installable via `npx skills add fullstackgtm/core`
+- [Recipes](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md): five composable GTM plays over the primitives (cold-start lead-fill, the trigger→judge→draft outbound loop, scheduled-continuous, ABM-from-companies, hygiene-gated outbound) — the CLI ships primitives, your agent is the orchestrator, the package never sends
 - [Architecture](https://github.com/fullstackgtm/core/blob/main/docs/architecture.md): module map + snapshot → audit → plan → apply data flow; "where do I add a rule/connector/operation"
 - [Contributing](https://github.com/fullstackgtm/core/blob/main/CONTRIBUTING.md): dev setup, the open-core mirror model, the release ritual
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
@@ -117,6 +118,30 @@ injectable `LinkedInProvider` (default HeyReach; `FakeLinkedInProvider` for test
 LinkedIn is read-only — Phase 1 has no `linkedin_connect`/`linkedin_message` ops
 and no webhook ingestion (Phase 2). Never auto-writes.
 
+## Key invariants (GTM brain — signals / icp / judge / draft)
+
+The timing/outbound layer turns "who changed" into one grounded, governed
+opener — and **never sends**. `signals fetch` captures fresh buying triggers
+into a profile-scoped ledger (free Greenhouse/Lever/Ashby ATS scrapers in the
+box; funding/social via `ingest`/`--from`), keyed by **account domain**, ranked
+by learned `weights`; it writes NOTHING to the CRM. `icp interview|set|show`
+builds `icp.json`; `icp judge` ranks fresh signals into send/nurture/skip — pass
+a snapshot (`--provider`/`--input`/`--demo`) and each decision resolves its CRM
+target: `accountId`, the best `contact {id,email,title}`, and `contacts[]` (all
+in-CRM contacts at the account, titled-first, cap 10, for multi-threading);
+`--with-history` additionally gates memory (don't re-touch a recently-touched
+account) and fit-scoring. `icp eval` is the calibration gate (exit 2 below the
+bar). `draft` emits ONE trigger-grounded opener per hot account as a governed
+`create_task` targeting the resolved `contact.id` (or `accountId`) — a
+domain-only decision (account not yet in the CRM) is REJECTED with "acquire it
+first" (run `enrich acquire`, re-judge with the snapshot). `--channel
+email|linkedin|task` shapes the opener; it is a task the operator sends from
+their own tool, never an automated send. `signals outcome --account <domain>
+--contact <id> --result replied|...` credits the contact reached so weights
+re-learn. The contact↔account join (`contact.accountId` + `account.domain`) is
+surfaced at every hop, so the loop is contact-coherent end to end — see the
+[recipes](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md).
+
 ## Key invariants (schedule)
 
 `fullstackgtm schedule` is the horizontal scheduler — no feature namespace

package/package.json

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

package/skills/fullstackgtm/SKILL.md

@@ -62,7 +62,10 @@ credentials AND stored plans per client org.
 | `fix --rule <id>` | audit one rule → suggest → approve at the confidence bar → apply only with `--yes` |
 | `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
 | `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
-| `enrich acquire [--source explorium\|pipe0\|linkedin]` | Net-new ICP-targeted lead gen: resolve-first deduped `create_record` plans, capped by a per-profile windowed meter (records + spend); owner-stamped via `acquire.assign`/`--assign-owner` (never born ownerless); `--source linkedin --list <id>` reads a HeyReach lead list (Phase 1 discovery, read-only — never sends); never auto-writes |
+| `enrich acquire [--source explorium\|pipe0\|linkedin]` | Net-new ICP-targeted lead gen: resolve-first deduped `create_record` plans, capped by a per-profile windowed meter (records + spend); owner-stamped via `acquire.assign`/`--assign-owner` (never born ownerless); links each lead to a domain-stamped, signal-watchable account; `acquire.create.company` acquires accounts (ABM); `--source linkedin --list <id>` reads a HeyReach lead list (Phase 1 discovery, read-only — never sends); never auto-writes |
+| `signals fetch\|list\|outcome\|weights` | Detect-side timing layer: capture fresh buying triggers into a profile-scoped ledger (free Greenhouse/Lever/Ashby ATS in the box; funding/social via ingest), ranked by learned weights. Writes NOTHING to the CRM; `outcome --account <domain> --contact <id> --result …` re-weights which triggers earn a touch |
+| `icp interview\|set\|show\|judge\|eval` | Build the ICP, then `judge` ranks fresh signals into send/nurture/skip — pass a snapshot (`--provider`/`--input`) and each decision resolves its CRM target (`accountId` + the `contact`/`contacts` to reach). `eval` is the calibration gate (exit 2 below the bar) |
+| `draft [--from-judge latest] [--channel email\|linkedin\|task]` | One trigger-grounded opener per hot account → a governed `create_task` targeting the resolved `contact.id` (or `accountId`); rejects a domain-only decision ("acquire it first"). **Never sends** — the opener is a task the operator sends from their own tool |
 | `market init\|capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |
 | `schedule add\|list\|remove\|enable\|disable\|run\|install\|uninstall\|status` | Horizontal cron; read/plan-side allowlist only — scheduling NEVER auto-approves |
 | `report` | Client-ready audit deliverable (markdown or self-contained HTML) |
@@ -84,8 +87,20 @@ Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,
 `fullstackgtm_resolve`, `fullstackgtm_market_worksheet`,
 `fullstackgtm_market_observe`.
 
+## Composing the primitives into plays
+
+This CLI ships governed **primitives** — there is no `outbound` mega-command.
+**You (the agent) are the orchestrator:** chain these verbs into the play the
+operator wants, surface the one approve gate, and bridge the last mile to the
+sender (**the package never sends**). [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md)
+has five worked plays — cold-start lead-fill, the trigger→judge→draft outbound
+loop, scheduled-continuous, ABM-from-companies, and hygiene-gated outbound.
+`fullstackgtm init` scaffolds a workspace (icp.json + enrich config + a PLAYBOOK
+pointing at those recipes) to start from.
+
 ## Going deeper
 
+- [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md) — five composable GTM plays over the primitives (cold-start, outbound loop, scheduled, ABM, hygiene-gated)
 - [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule, engagement/health)
 - [INSTALL_FOR_AGENTS.md](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md) — deterministic install-and-verify with expected outputs
 - [docs/api.md](https://github.com/fullstackgtm/core/blob/main/docs/api.md) — semver-covered surfaces: canonical model, rule interface, plan/apply contract, connectors, config, CLI, MCP

package/src/calls.ts

@@ -369,6 +369,15 @@ export type CallDealSuggestion = {
   dealName?: string;
   accountId?: string;
   accountName?: string;
+  /**
+   * HOW the deal's account was matched — `account_domain` (the company-wide,
+   * reliable signal) vs `contact_email` (a specific person, possibly stale) vs
+   * `both`. An agent needs this to weight the match; the bare confidence hides it.
+   */
+  resolvedVia?: "account_domain" | "contact_email" | "both";
+  /** The attendee contacts that matched (the email path), so the contact↔account
+   *  hop is visible, not just the resolved account. */
+  matchedContacts?: { id: string; email?: string; accountId?: string }[];
   confidence: "high" | "low" | "none";
   reason: string;
 };
@@ -393,17 +402,27 @@ export function suggestCallDeal(
   }
 
   const accountIds = new Set<string>();
+  let viaDomain = false;
+  let viaEmail = false;
+  const matchedContacts: { id: string; email?: string; accountId?: string }[] = [];
   for (const account of snapshot.accounts) {
     const domain = account.domain?.trim().toLowerCase().replace(/^www\./, "");
-    if (domain && domains.has(domain)) accountIds.add(account.id);
+    if (domain && domains.has(domain)) {
+      accountIds.add(account.id);
+      viaDomain = true;
+    }
   }
   for (const contact of snapshot.contacts) {
     const email = contact.email?.trim().toLowerCase();
     const at = email ? email.indexOf("@") : -1;
     if (email && at > 0 && domains.has(email.slice(at + 1)) && contact.accountId) {
       accountIds.add(contact.accountId);
+      viaEmail = true;
+      matchedContacts.push({ id: contact.id, ...(contact.email ? { email: contact.email } : {}), accountId: contact.accountId });
     }
   }
+  const resolvedVia = viaDomain && viaEmail ? "both" : viaDomain ? "account_domain" : "contact_email";
+  const via = { resolvedVia, ...(matchedContacts.length ? { matchedContacts } : {}) } as const;
   if (accountIds.size === 0) {
     return {
       dealId: null,
@@ -432,8 +451,9 @@ export function suggestCallDeal(
       dealName: top.name,
       accountId: top.accountId,
       accountName: account?.name,
+      ...via,
       confidence: "high",
-      reason: `"${top.name}" is the only open deal on matched account "${account?.name ?? top.accountId}".`,
+      reason: `"${top.name}" is the only open deal on matched account "${account?.name ?? top.accountId}" (via ${resolvedVia}).`,
     };
   }
   return {
@@ -441,8 +461,9 @@ export function suggestCallDeal(
     dealName: top.name,
     accountId: top.accountId,
     accountName: account?.name,
+    ...via,
     confidence: "low",
-    reason: `${openDeals.length} open deals on matched account(s); "${top.name}" has the most recent activity. Confirm before writing.`,
+    reason: `${openDeals.length} open deals on matched account(s); "${top.name}" has the most recent activity (matched via ${resolvedVia}). Confirm before writing.`,
   };
 }
 

package/src/cli.ts

@@ -125,6 +125,11 @@ import {
   remaining,
   type AcquireRemaining,
 } from "./acquireMeter.ts";
+import {
+  scaffoldWorkspace,
+  type InitProvider,
+  type InitSource,
+} from "./init.ts";
 import {
   crmContactKeys,
   fetchExploriumProspects,
@@ -246,6 +251,10 @@ Usage:
   the process list and shell history. Pipe them on stdin or enter them at the
   interactive prompt:
     echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot
+  fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
+                                               cold start: scaffold icp.json + enrich.config.json + a
+                                               PLAYBOOK wired for this workspace (the CLI ships primitives,
+                                               your agent is the orchestrator — see docs/recipes.md)
   fullstackgtm snapshot [source options] [--since <iso>] [--out <path> | --archive <dir>]
   fullstackgtm audit [source options] [audit options] [--save]
   fullstackgtm report [source options] [audit options] [report options]
@@ -466,6 +475,17 @@ type HelpEntry = {
 };
 
 const HELP: Record<string, HelpEntry> = {
+  // Get started
+  init: {
+    summary: "scaffold a workspace (icp.json + enrich.config.json + PLAYBOOK)",
+    phase: "Setup",
+    synopsis: [
+      "fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]",
+    ],
+    detail:
+      "Cold start: writes a starter ICP, an acquire-ready enrich.config.json (with a visible assign seam so leads are never ownerless), and a PLAYBOOK wired with the cold-start + outbound-loop recipes for this workspace. Pure file-writer — no network, keeps existing files unless --force. The CLI ships governed primitives; your coding agent is the orchestrator (see docs/recipes.md).",
+    seeAlso: ["icp", "enrich", "signals"],
+  },
   // Setup & health
   login: {
     summary: "connect a provider or LLM key (secrets via stdin/env, never argv)",
@@ -726,12 +746,13 @@ const HELP: Record<string, HelpEntry> = {
 
 // Verbs that print their own richer multi-subcommand help; runCli routes their
 // `--help` to themselves, so commandHelp() only renders these via `help <verb>`.
-const BESPOKE_HELP = ["call", "market", "enrich", "bulk-update", "schedule", "signals", "icp", "draft"];
+const BESPOKE_HELP = ["init", "call", "market", "enrich", "bulk-update", "schedule", "signals", "icp", "draft"];
 
 // Lifecycle-grouped front door. One line per verb, organized by the
 // Prevent→Detect→Remediate→Verify loop so a new user sees ~6 jobs, not 22 verbs.
 function shortUsage() {
   const groups: Array<[string, string[]]> = [
+    ["Get started", ["init"]],
     ["Setup & health", ["login", "logout", "doctor", "profiles", "health"]],
     ["Detect — read-only", ["audit", "report", "snapshot", "diff", "rules"]],
     ["Prevent — gate writes", ["resolve"]],
@@ -2659,7 +2680,8 @@ NEVER emits a patch plan; --save persists only the local signal ledger (used by
       throw new Error(`signals outcome: --result must be one of ${valid.join(", ")}.`);
     }
     const touchId = option(rest, "--touch") ?? undefined;
-    const outcome = makeOutcome({ accountDomain: accountArg, touchId, result: result as SignalOutcomeResult });
+    const contactId = option(rest, "--contact") ?? undefined;
+    const outcome = makeOutcome({ accountDomain: accountArg, touchId, contactId, result: result as SignalOutcomeResult });
     await createFileSignalStore().appendOutcome(outcome);
     console.error(
       `Recorded outcome "${outcome.result}" for ${outcome.accountDomain} (${outcome.id}). ` +
@@ -2840,6 +2862,63 @@ LLM key it emits a clearly-labeled stub rather than fake authored copy.`);
   }
 }
 
+/**
+ * `init` — scaffold a GTM workspace from cold scratch: a starter icp.json, an
+ * enrich.config.json (acquire preset + a visible assign seam), and a PLAYBOOK
+ * wired with the chosen source/provider that points at the recipes. Pure
+ * file-writer: no network, never overwrites without --force.
+ */
+function initCommand(args: string[]) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`Usage:
+  fullstackgtm init [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--out <dir>] [--force]
+
+Scaffolds a workspace so the first acquire/signals/judge/draft commands work:
+  icp.json            starter ICP (edit, or rebuild with \`icp interview\`)
+  enrich.config.json  acquire preset for --source + a placeholder assign policy
+  PLAYBOOK.md         the cold-start + outbound-loop recipes wired for this workspace
+
+The CLI ships governed primitives; your coding agent is the orchestrator. See
+docs/recipes.md for the full play set. Existing files are kept unless --force.`);
+    return;
+  }
+  const source = (option(args, "--source") ?? "pipe0") as InitSource;
+  if (!["pipe0", "explorium", "linkedin"].includes(source)) {
+    throw new Error(`init: --source must be pipe0|explorium|linkedin (got "${source}")`);
+  }
+  const provider = (option(args, "--provider") ?? "hubspot") as InitProvider;
+  if (!["hubspot", "salesforce"].includes(provider)) {
+    throw new Error(`init: --provider must be hubspot|salesforce (got "${provider}")`);
+  }
+  const outDir = resolve(process.cwd(), option(args, "--out") ?? ".");
+  const force = args.includes("--force");
+  const current = activeProfile();
+  const profile = current === DEFAULT_PROFILE ? undefined : current;
+
+  const files = scaffoldWorkspace({ source, provider, profile });
+  const wrote: string[] = [];
+  const kept: string[] = [];
+  for (const file of files) {
+    const path = resolve(outDir, file.path);
+    if (existsSync(path) && !force) {
+      kept.push(file.path);
+      continue;
+    }
+    writeFileSync(path, file.content);
+    wrote.push(file.path);
+  }
+
+  console.log(
+    `Scaffolded workspace (${provider}, discovery via ${source}${profile ? `, profile ${profile}` : ""}).`,
+  );
+  if (wrote.length) console.log(`  wrote: ${wrote.join(", ")}`);
+  if (kept.length) console.log(`  kept (use --force to overwrite): ${kept.join(", ")}`);
+  console.log(
+    "\nNext: edit icp.json + set acquire.assign.ownerId in enrich.config.json, then follow PLAYBOOK.md\n" +
+      "(full recipe set: docs/recipes.md).",
+  );
+}
+
 /**
  * `icp` — develop and inspect the Ideal Customer Profile that targets acquire.
  * The CLI can't run AskUserQuestion itself; `icp interview` emits the question
@@ -2929,12 +3008,20 @@ ops. Develop one by interview, then \`enrich acquire\` picks up ./icp.json.
     const unjudged = signalRun.signals.filter((s) => !s.judgedBy);
     if (unjudged.length === 0) throw new Error(`Signal run "${signalRun.runLabel}" has no unjudged signals.`);
 
-    // 2) Optional inputs: ICP (may be undefined), snapshot (only --with-history),
-    //    outcomes + config from the signal store / DEFAULT_SIGNALS_CONFIG.
+    // 2) Optional inputs: ICP (may be undefined), snapshot, outcomes + config.
+    //    The snapshot is loaded whenever a source is given (--provider/--input/
+    //    --demo/--sample) — it resolves each decision's CRM target (accountId +
+    //    best contact) so `draft` can write against a real record. --with-history
+    //    additionally enables the memory + fit scoring inputs.
     const icp = loadIcp(rest);
     const config: SignalsConfig = DEFAULT_SIGNALS_CONFIG;
     const outcomes = await signalStore.listOutcomes();
-    const snapshot = withHistory ? await readSnapshot(rest) : undefined;
+    const hasSnapshotSource =
+      Boolean(option(rest, "--provider")) ||
+      Boolean(option(rest, "--input")) ||
+      rest.includes("--demo") ||
+      rest.includes("--sample");
+    const snapshot = withHistory || hasSnapshotSource ? await readSnapshot(rest) : undefined;
 
     // 3) Resolve the LLM seam ONLY if a key already exists (deterministic baseline
     //    otherwise — never PROMPT here; judge must run key-free).
@@ -5206,6 +5293,10 @@ export async function runCli(argv: string[]) {
     await enrichCommand(args);
     return;
   }
+  if (command === "init") {
+    initCommand(args);
+    return;
+  }
   if (command === "icp") {
     await icpCommand(args);
     return;

package/src/connectors/hubspot.ts

@@ -506,18 +506,34 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
-  /** Exact-name company lookup for resolve-first creates. Returns matching ids (max 3 fetched). */
-  async function searchCompaniesByName(name: string): Promise<string[]> {
+  /** Exact-value company lookup (by `name` or `domain`) for resolve-first creates. */
+  async function searchCompaniesBy(property: string, value: string): Promise<string[]> {
     const data = await request(`/crm/v3/objects/companies/search`, {
       method: "POST",
       body: JSON.stringify({
-        filterGroups: [{ filters: [{ propertyName: "name", operator: "EQ", value: name }] }],
-        properties: ["name"],
+        filterGroups: [{ filters: [{ propertyName: property, operator: "EQ", value }] }],
+        properties: [property],
         limit: 3,
       }),
     });
     return ((data?.results ?? []) as Array<{ id: string }>).map((row) => String(row.id));
   }
+  const searchCompaniesByName = (name: string) => searchCompaniesBy("name", name);
+
+  /** Stamp `domain` on a company only when it has none (fill-blank, never clobber). */
+  async function fillCompanyDomainIfEmpty(companyId: string, domain: string): Promise<void> {
+    try {
+      const data = await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}?properties=domain`);
+      const current = data?.properties?.domain;
+      if (typeof current === "string" && current.trim()) return; // already has one — leave it
+      await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}`, {
+        method: "PATCH",
+        body: JSON.stringify({ properties: { domain } }),
+      });
+    } catch {
+      // Best-effort: a failed domain fill must not sink the contact create.
+    }
+  }
 
   /** Exact-value contact lookup (by any searchable property) for resolve-first creates. */
   async function searchContactsBy(property: string, value: string): Promise<string[]> {
@@ -533,36 +549,51 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   }
 
   /**
-   * Resolve a company by exact name, creating it on a confirmed miss. Returns
-   * the company id, or null on ambiguity (≥2 existing) so the caller skips the
-   * association rather than guessing. Same-run safe via createdCompaniesByName.
+   * Resolve a company to a real account record, creating it on a confirmed miss.
+   * Matches by DOMAIN first (the accurate key) and falls back to exact name;
+   * creates with the domain stamped, and fills the domain on a name-matched
+   * account that lacks one — so the account is signal-watchable. Returns null on
+   * ambiguity (≥2 matches) so the caller skips the association rather than
+   * guessing. Same-run safe via createdCompaniesByName.
    */
-  async function resolveOrCreateCompanyByName(name: string, opId: string): Promise<string | null> {
-    const nameKey = name.toLowerCase();
-    const already = createdCompaniesByName.get(nameKey);
+  async function resolveOrCreateCompany(name: string, domain: string | undefined, opId: string): Promise<string | null> {
+    const cacheKey = domain ? `d:${domain.toLowerCase()}` : `n:${name.toLowerCase()}`;
+    const already = createdCompaniesByName.get(cacheKey);
     if (already) return already;
-    const matches = await searchCompaniesByName(name);
-    if (matches.length > 1) return null;
-    if (matches.length === 1) {
-      createdCompaniesByName.set(nameKey, matches[0]);
-      return matches[0];
+
+    // 1. Domain-first match (accurate; an account matched here already has it).
+    if (domain) {
+      const byDomain = await searchCompaniesBy("domain", domain);
+      if (byDomain.length > 1) return null;
+      if (byDomain.length === 1) {
+        createdCompaniesByName.set(cacheKey, byDomain[0]);
+        return byDomain[0];
+      }
     }
+    // 2. Exact-name match; stamp the domain if the account has none.
+    const byName = await searchCompaniesByName(name);
+    if (byName.length > 1) return null;
+    if (byName.length === 1) {
+      if (domain) await fillCompanyDomainIfEmpty(byName[0], domain);
+      createdCompaniesByName.set(cacheKey, byName[0]);
+      return byName[0];
+    }
+    // 3. Create with name + domain (provenance is best-effort).
+    const props: Record<string, string> = { name, ...(domain ? { domain } : {}) };
     let created;
     try {
       created = await request(`/crm/v3/objects/companies`, {
         method: "POST",
-        body: JSON.stringify({
-          properties: { name, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` },
-        }),
+        body: JSON.stringify({ properties: { ...props, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` } }),
       });
     } catch {
       created = await request(`/crm/v3/objects/companies`, {
         method: "POST",
-        body: JSON.stringify({ properties: { name } }),
+        body: JSON.stringify({ properties: props }),
       });
     }
     const id = String(created.id);
-    createdCompaniesByName.set(nameKey, id);
+    createdCompaniesByName.set(cacheKey, id);
     return id;
   }
 
@@ -588,7 +619,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     }
 
     if (operation.objectType === "account") {
-      const id = await resolveOrCreateCompanyByName(matchValue, operation.id);
+      const id = await resolveOrCreateCompany(matchValue, stringOrUndefined(payload.properties?.domain), operation.id);
       if (id === null) {
         return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — multiple companies named "${matchValue}". Not creating.` };
       }
@@ -637,13 +668,14 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     let companyNote = "";
     if (payload.associateCompanyName) {
       try {
-        const companyId = await resolveOrCreateCompanyByName(payload.associateCompanyName, operation.id);
+        const companyId = await resolveOrCreateCompany(payload.associateCompanyName, payload.associateCompanyDomain, operation.id);
         if (companyId) {
           await request(
             `/crm/v4/objects/contacts/${encodeURIComponent(contactId)}/associations/default/companies/${encodeURIComponent(companyId)}`,
             { method: "PUT" },
           );
-          companyNote = ` Linked to company "${payload.associateCompanyName}" (${companyId}).`;
+          const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+          companyNote = ` Linked to company "${payload.associateCompanyName}"${domainNote} (${companyId}).`;
         } else {
           companyNote = ` Company "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
         }