fullstackgtm 0.41.0 → 0.43.0

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[];
@@ -384,6 +396,17 @@ export type GtmConnector = {
     provider: CrmProvider;
     fetchSnapshot: () => Promise<CanonicalGtmSnapshot>;
     applyOperation?: (operation: PatchOperation) => Promise<PatchOperationResult>;
+    /**
+     * Bulk fast-path for independent `create_record` contact ops: batch the
+     * resolve-first read and the create writes instead of one round-trip per
+     * record (orders of magnitude fewer API calls for lead acquisition). The
+     * caller (`applyPatchPlan`) only routes ops here that are safe to batch —
+     * approved, no group, no value override, no company association — and falls
+     * back to `applyOperation` for the rest. Implementations MUST preserve
+     * resolve-first (never create over an existing match) and return exactly one
+     * result per input op. Optional: connectors without it use `applyOperation`.
+     */
+    applyCreateContactsBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
     /**
      * Read the live value of one canonical field, used for compare-and-set:
      * apply orchestration refuses to write over values that drifted since the

package/docs/api.md

@@ -37,9 +37,16 @@ release.
 
 ## Connectors
 
-- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, readField?, fetchChanges? }`.
+- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, applyCreateContactsBatch?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
+  - `applyCreateContactsBatch?(operations)` — optional bulk fast-path for
+    independent `create_record` contact ops. `applyPatchPlan` routes safe-to-batch
+    creates here (batched resolve-first + batched create — ~N/100 calls instead of
+    ~2N), and falls back to `applyOperation` per record on a batch rejection and
+    for any op that isn't batch-safe (grouped, value-overridden, company-
+    associated, conflicted). HubSpot: `search IN` + `batch/create`; Salesforce:
+    SOQL `IN` + Composite sObject Collections (`allOrNone:false`).
 - `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `create_record` (resolve-first net-new contact/company create — re-checks the dedupe key at apply, never double-creates), `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). (The Salesforce connector implements the same operation set, with the platform-specific constraints noted below.)
 - `createSalesforceConnector(options)` — read/write/readField/fetchChanges; probabilities normalized to 0..1. `applyOperation` implements every operation type, with two platform constraints: `merge_records` covers **Accounts and Contacts** only (Salesforce exposes no Opportunity merge), and `create_record` resolve-first creates **contacts/accounts** (SOQL search on the match key, create only on a confirmed miss; stamps the canonical `ownerId` onto `OwnerId`).
 - `createStripeConnector(options)` — read-only billing by design (`applyOperation` returns `skipped`); email domains are the cross-system merge keys. Implements `fetchChanges` (incremental via `created[gte]`).
@@ -132,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

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.41.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