fullstackgtm 0.42.0 → 0.44.0

package/llms.txt

@@ -15,10 +15,12 @@ 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
 - [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
+- [TAM mapping](https://github.com/fullstackgtm/core/blob/main/docs/tam.md): size the reachable market from the ICP, then populate it with scheduled governed acquire and track coverage to an ETA
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history
 
 `fullstackgtm resolve <type>` is the create gate: exit 0 = safe to create,
@@ -57,6 +59,60 @@ uncertainty; report bubbles ∝ estimated share only when signals exist.
 Storage is profile-scoped under `<home>/market/<category>`. MCP:
 `fullstackgtm_market_worksheet`, `fullstackgtm_market_observe`.
 
+## Key invariants (TAM mapping)
+
+`fullstackgtm tam` sizes the reachable market FROM the ICP and then iteratively
+fills it — not a one-shot headline. `tam estimate` computes a transparent model:
+account universe × ACV = TAM (account/per-logo basis by default; `--acv-basis
+buyer` for per-seat = contacts × ACV), where contacts = accounts ×
+buyers/account is the population target. The account count is `--accounts <n>`
+(assumption), OR `--source theirstack` — the TECHNOGRAPHIC universe: counts
+companies that USE a CRM/MAP (`firmographics.technologies` → TheirStack
+`company_technology_slug_or`) + geo + employee bounds; the real RevOps buying signal
+AND the only source that returns a LIST (`tam accounts --source theirstack` pulls
+real companies name/domain, `--out csv`/`--json`, `--max` caps credit spend; a
+count is cheap but NOT free — limit:0 is rejected so a count returns 1 row ≈ 3
+credits, a list pull ≈ 3/company; `login theirstack`). OR `--source explorium` — a firmographic
+count via `/v1/businesses` (`total_results`), a count ONLY (Explorium 403s on
+list-pull, can't target by CRM-usage; must OMIT `size` or it caps the total; capped
+at 60,000 `EXPLORIUM_BUSINESS_COUNT_CAP` → `provider:explorium (≥60k cap — floor)` +
+⚠). Verified live: people endpoints can't size a market (Explorium `/v1/prospects`
+total == page size; pipe0/Crustdata returns only a cursor — `--source pipe0` for
+estimate is REJECTED, it's a population source). The model always LABELS
+`accountsSource` (provider:theirstack/explorium vs assumption). ACV must be a
+real ANNUAL figure the operator CONFIRMS — `--acv <annual-usd>`, OR `--acv-from-crm
+--deal-period monthly|quarterly|annual` which takes the median closed-won amount and
+ANNUALIZES it (the period is required — a deal can be MRR/quarterly/annual and
+guessing is a 4–12× error; $15k/mo → $180k). NO band defaults, and a bare
+`--provider` does NOT auto-set ACV (HubSpot is the COVERAGE source, not the ACV) —
+`estimate` REFUSES without a confirmed ACV. Buyers/account is `--buyers-per-account`
+OR the CRM's avg-contacts-per-account OR a labeled `assumption:1-buyer`. Both
+`acv.source` and `universe.buyersSource` are labeled (incl. deal count + the
+period×factor, so a thin signal like "1 deal" is visible). Optional
+citable cross-checks (`{claim,valueUsd?,sourceUrl,quote}`) sit beside the
+bottom-up number as a top-down sanity check. `estimate`
+records a coverage BASELINE (CRM counts now) so `status` attributes what the
+campaign added. `tam populate --cron` schedules `enrich acquire --source <s>
+--save` — the ONE create-side verb the schedule allowlist permits, and only in
+its plan-producing `--save` form: each firing queues a needs_approval lead plan,
+the acquire meter is charged only at apply, and apply stays `apply --plan-id`
+(re-checked approved). `tam status` measures coverage on the INTERSECTION of CRM ×
+TAM-ICP, not a raw count: `tam estimate` stores the ICP filter (`model.targeting`),
+and status CLASSIFIES each domain-bearing account into in-TAM / out-of-TAM / unknown
+(checked on size+industry — geo + "uses-CRM" aren't on a CanonicalAccount, so a
+`--reverify` re-enrich is future; the classifier labels what it checked). ONLY
+in-TAM counts toward coverage, so off-ICP accounts loaded from elsewhere can't
+inflate it. Bottom-up vs top-down reconciliation: the in-TAM count is a FLOOR on the
+real universe (those are verified members), so when in-TAM ≥ the estimate, status
+stops reporting a fake 100% and flips to "estimate was a floor — real market is at
+least N (`reconciledUniverse = max(estimate, inTam)`); re-estimate for the headroom".
+`--save` stamps an append-only timeline. `tam report` (markdown) and `status` project
+an ETA on the IN-TAM accounts/day burn across the timeline → days-remaining → fill
+date — and REFUSE to project (honest "not enough history") below two readings, a flat
+rate, or zero elapsed time.
+Coverage + ETA are deterministic (no LLM, byte-stable). Storage profile-scoped
+under `<home>/tam/<name>/` (`model.json` + `coverage.jsonl`, 0600).
+
 ## Key invariants (governed write verbs)
 
 `bulk-update <object> --where … (--set|--archive|--create-task)` filters the
@@ -117,12 +173,44 @@ 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 `--from`; connected platforms via `--connector`
+file/serpapi-news/hubspot-forms with secrets through the credential ladder; and
+push platforms via the webhook spool — `--connector file` reads the conventional
+landing zone `<home>/signals/spool/*.jsonl`, see docs/signal-spool-format.md),
+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. After `plans approve`, applying the draft
+plan logs the touch as a CRM task (`apply --provider <crm>`) OR renders it to the
+governed outbox (`apply --channel outbox` → `<home>/signals/outbox/<channel>.jsonl`
+for a downstream sender to drain). Either way the CLI **transmits nothing** — the
+outbox is the send-side mirror of the spool; the always-on sender is hosted/opt-in. `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
 owns cron logic. `add "<command>" --cron "<expr>"` validates the command
 against the read/plan-side allowlist (audit, snapshot, enrich append|refresh,
-market capture|refresh, suggest, report, doctor) and the 5-field cron
+enrich acquire --save, market capture|refresh, signals fetch, icp judge|eval,
+draft, suggest, report, doctor) and the 5-field cron
 expression, but touches no crontab; `install` materializes enabled entries
 into a sentinel-delimited managed block (`# >>> fullstackgtm <profile> >>>`)
 replaced wholesale on re-install, lines outside it untouched; `uninstall`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.42.0",
+  "version": "0.44.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,8 +62,12 @@ 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; `--from` staged files; `--connector file\|serpapi-news\|hubspot-forms` to pull connected platforms / read the webhook spool `<home>/signals/spool`, secrets via the credential ladder), 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** — after `plans approve`, `apply --provider <crm>` logs it as a CRM task, or `apply --channel outbox` renders it to `<home>/signals/outbox/<channel>.jsonl` for a downstream sender to drain; the CLI transmits nothing |
 | `market init\|capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |
+| `tam estimate\|accounts\|status\|report\|populate` | Size the reachable market FROM the ICP (real account count × real ACV; buyers/account → contact target), then iteratively fill it: `populate` schedules plan-only `enrich acquire --save` (apply stays gated), `status` classifies CRM accounts vs the TAM ICP into **in-TAM / out-of-TAM / unknown** (only in-TAM counts — junk loaded from elsewhere doesn't inflate coverage; checked on size+industry, geo/tech need re-enrich) and flips to "estimate was a FLOOR, revise up" when bottom-up in-CRM exceeds the top-down estimate; `--save` stamps a timeline, `report` projects burn-up + ETA on the in-TAM rate. **`estimate --source theirstack`** counts companies that USE a CRM/MAP (`firmographics.technologies`) — the real RevOps universe — and **`tam accounts --source theirstack`** pulls the actual company LIST (names+domains, `--out csv`) at ~3 credits/company — `--dry-run [--usd-per-credit <r>]` prices the pull + full TAM for 0 credits, `--confirm` gates pulls above `--max-credits` (default 150). `--source explorium` = firmographic count only (no list, 60k cap = floor); else `--accounts`. **ACV must be a real ANNUAL figure you confirm** — `--acv <annual-usd>`, or `--acv-from-crm --deal-period monthly\|quarterly\|annual` (median closed-won, annualized); NO band defaults, a bare `--provider` does NOT set ACV (HubSpot=coverage), refuses without one. Buyers/account = CRM avg-contacts or explicit. Every number labeled with its source |
 | `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) |
 | `health [--json]` | Per-profile CRM health timeline: deterministic 0–100 score, trend, per-rule deltas — accrues from `audit --save`, read-only |
@@ -84,8 +88,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.`,
   };
 }