fullstackgtm 0.42.0 → 0.44.0

package/docs/recipes.md

@@ -0,0 +1,195 @@
+# 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.
+
+---
+
+## Recipe 6 — Size your TAM, then fill it on a schedule
+
+**Goal:** turn the ICP into a defensible market size, then close the gap to it
+over weeks — with a number for "how far along am I."
+
+```bash
+# 1. Estimate the universe FROM the ICP. Either probe a provider for the
+#    ICP-match count, or pass --accounts from a known segment. Record a baseline.
+fullstackgtm tam estimate --source explorium --provider hubspot --acv 180000
+#    → accounts: matching COMPANIES (Explorium /v1/businesses) = the account universe.
+#    → ACV: a real ANNUAL figure you confirm (--acv), or --acv-from-crm
+#      --deal-period monthly|quarterly|annual to derive+annualize from closed-won.
+#      (--provider is your coverage source, not your ACV — it won't auto-set it.)
+#    → buyers/account: CRM avg-contacts/account (or --buyers-per-account); labeled.
+#    → TAM model: accounts × ACV = $; contacts = accounts × buyers (population target)
+
+# 2. Schedule the population — plan-only acquire, apply stays a human gate.
+fullstackgtm tam populate --cron "0 7 * * 1-5" --source pipe0 --provider hubspot
+fullstackgtm schedule install
+
+# 3. Each cycle: approve the morning's lead plan (Recipe 1's tail), then apply.
+fullstackgtm plans list && fullstackgtm plans approve <id> --operations all
+fullstackgtm apply --plan-id <id> --provider hubspot
+
+# 4. Track where you're getting to — stamp a coverage reading; once a couple
+#    accumulate, report projects a burn-up + ETA to full coverage.
+fullstackgtm tam status --provider hubspot --save
+fullstackgtm tam report > tam-report.md
+```
+
+The estimate is honest about its source (provider count vs. assumption), the
+population never auto-writes (the meter is charged only at apply), and the ETA is
+refused rather than faked until the timeline shows real movement. See
+[tam.md](./tam.md).
+
+---
+
+## 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/docs/roadmap-to-1.0.md

@@ -140,8 +140,38 @@ outward, one layer per release, each consolidating before the next expanded:
   broker-https enforcement, the build/CI dist-integrity gate (published dist is
   provably from source), Salesforce-merge capability matrix.
 
+## 0.29 → 0.43 — from hygiene to the full outbound loop, as shipped
+
+The next train extended the governed spine from *fixing the CRM* to *filling
+it and acting on it*, without ever loosening the write gate:
+
+- **0.29–0.34** — market-map maturation (config suggestion + taxonomy types,
+  sourcing helpers, competitor discovery, vendor logos/scale in the report)
+  plus call-type classification with type-specific coaching rubrics (0.32);
+  Salesforce `dedupe`/`merge_records` via SOAP and pipeline-aware closed/won
+  detection (0.30).
+- **0.35–0.36** — DX cohesion: progressive-disclosure help, summary-first
+  `audit` with next-step guidance; the engagement workspace — a deterministic
+  `health` verb over a per-profile timeline.
+- **0.37–0.39** — acquire: `enrich acquire` (net-new, ICP-targeted,
+  resolve-first deduped, metered lead creation), lead assignment policies so
+  leads are never born ownerless, the LinkedIn (HeyReach) discovery source
+  with email resolution, and run observability for broker-paired CLIs.
+- **0.40** — Salesforce reaches full write parity with HubSpot
+  (`create_record`); HubSpot date-field writes no longer false-conflict.
+- **0.41** — signal-based outbound: `signals fetch/list/outcome/weights`,
+  `icp judge`/`icp eval` (timing × fit × memory, golden-set calibration
+  gate), `draft` (trigger-grounded openers as governed plans), and the LLM
+  base-URL override.
+- **0.42** — bulk apply for lead creation (HubSpot batch + Salesforce
+  composite).
+- **0.43** — the on-ramp and the seams: `init` workspace scaffolding,
+  `docs/recipes.md` (five composable plays), and the contact/account seam
+  campaign — contact-granular outbound end to end, account-level acquire for
+  ABM, `health` by object type.
+
 The known-gaps list below predates these layers and has been re-verified
-against the 0.28 surface: still accurate, still open.
+against the 0.43 surface (2026-07): still accurate, still open.
 
 ## Known real-portal gaps to close before 1.0
 

package/docs/signal-spool-format.md

@@ -0,0 +1,162 @@
+# Signal spool format (webhook landing zone)
+
+The **spool** is how push-based signal platforms — website de-anonymization
+(RB2B), social/job listening (Trigify), form-submission webhooks (HubSpot) —
+reach `fullstackgtm`. The CLI is a deterministic batch tool, not an always-on
+server, so it does not receive webhooks itself. Instead:
+
+1. A **receiver** you run (any HTTP endpoint — 20 lines, or an off-the-shelf
+   webhook-to-file tool) appends one JSON row per event to a spool file.
+2. `fullstackgtm signals fetch --connector file` reads the spool on its next run,
+   turning each row into a ranked signal through the same evidence-gate → dedup →
+   weight pipeline as every other source.
+
+The spool format and the `file` connector that reads it are open source. The
+package ships **no receiver** — operating an always-on endpoint is out of scope
+for the CLI (a managed receiver is part of the hosted product). This doc is the
+contract your receiver writes to.
+
+## The format
+
+A spool file is **newline-delimited JSON (JSONL)**: one JSON object per line,
+append-only. (A single `.json` file containing a JSON array is also accepted, for
+convenience when staging by hand.) Each object is a **staged signal row**:
+
+| Field | Required | Meaning |
+|---|---|---|
+| `bucket` | yes¹ | One of `demand`, `funding`, `job`, `company`, `social`. |
+| `accountDomain` | yes | The company domain. `domain` is accepted as an alias. Normalized (protocol/`www`/path stripped, lowercased) on read. |
+| `trigger` | yes | Short human label, e.g. `"visited pricing page"`, `"raised Series B"`. |
+| `quote` | yes | **Verbatim evidence** — the exact text a human can verify (a headline, a page title, the submitted form + email). A row with no quote is **dropped**, never faked. |
+| `sourceUrl` | no | Link to the evidence. |
+| `firstSeen` | no | ISO 8601 timestamp. Defaults to the fetch time. |
+| `weight` | no | Explicit weight; defaults to the bucket's configured weight. |
+
+¹ `bucket` may be omitted in a spool file — the `file` connector fills its
+default (`company`). Set it explicitly per row when a source spans buckets.
+
+Example spool file (`rb2b.jsonl`):
+
+```jsonl
+{"bucket":"company","accountDomain":"globex.com","trigger":"visited pricing 3x","quote":"globex.com — viewed /pricing and /demo, 3 sessions","sourceUrl":"https://app.rb2b.com/v/abc123"}
+{"bucket":"company","accountDomain":"initech.com","trigger":"visited docs","quote":"initech.com — viewed /docs/api","sourceUrl":"https://app.rb2b.com/v/def456"}
+```
+
+A row that fails validation (unknown bucket, missing domain/trigger/quote) makes
+the fetch error and names the offending row — a corrupt spool is surfaced, not
+silently skipped. Keep your receiver's mapping faithful to this table.
+
+## Where the spool lives
+
+`--connector file` with **no path** reads the conventional landing zone:
+
+```
+<profile home>/signals/spool/      (default: ~/.fullstackgtm/signals/spool/)
+```
+
+Every `*.jsonl` (and `*.json`) file in that directory is read and concatenated,
+name-sorted — so each platform can append to its own file and they all land in
+one fetch:
+
+```
+~/.fullstackgtm/signals/spool/rb2b.jsonl
+~/.fullstackgtm/signals/spool/trigify.jsonl
+~/.fullstackgtm/signals/spool/hubspot.jsonl
+```
+
+Point at a different file or directory with `--connector-opt path=<path>`:
+
+```bash
+# the conventional landing zone (zero-arg)
+fullstackgtm signals fetch --connector file --save
+
+# a specific file or directory
+fullstackgtm signals fetch --connector file --connector-opt path=./events.jsonl --save
+fullstackgtm signals fetch --connector file --connector-opt path=/var/spool/fsgtm --save
+```
+
+The CLI **never writes** to the spool — your receiver does. The directory is
+profile-scoped, so spools for different client workspaces stay separate.
+
+### Re-reads and retention
+
+Re-reading the same spool is safe: signals dedup on `(accountDomain, bucket,
+trigger)` within the configured window (`dedupWindowDays`, default 30), so a row
+that's still in the spool on the next fetch is deduped, not double-counted. The
+CLI does not consume or truncate the spool — **retention is yours**: rotate or
+truncate the files on your own schedule (e.g. nightly, or after a successful
+`--save`). Unbounded spool growth is a self-host concern the CLI doesn't manage.
+
+## Writing a receiver
+
+A receiver is whatever turns a platform's webhook POST into spool rows. The
+minimum: verify the platform's signature, map the payload to the fields above,
+append one JSON line. Pseudocode:
+
+```js
+// POST handler for your platform's webhook
+function onWebhook(req) {
+  verifySignature(req);                       // platform's HMAC / shared secret
+  const row = mapToStagedRow(req.body);       // per-platform mapping (below)
+  if (!row.quote) return 204;                 // no verifiable evidence -> skip
+  appendLine("~/.fullstackgtm/signals/spool/<platform>.jsonl", JSON.stringify(row));
+  return 204;
+}
+```
+
+Keep the receiver dumb: no ranking, no CRM writes, no judgment. All of that is
+the CLI's job, gated and deterministic, on the next `signals fetch`.
+
+## Per-platform mapping
+
+These map each platform's webhook payload to a staged row. Payload shapes drift —
+verify against the platform's current webhook docs before relying on a field.
+
+### RB2B (website visitor de-anonymization)
+
+RB2B delivers an identified visitor (person + company) via outbound webhook.
+Use the **company domain** as `accountDomain` and the visited pages as the
+verbatim `quote`.
+
+| Spool field | From RB2B payload |
+|---|---|
+| `bucket` | `"company"` (or `"demand"` for high-intent pages) |
+| `accountDomain` | the visitor's company domain |
+| `trigger` | e.g. `"visited pricing"` derived from the top page |
+| `quote` | `"<domain> — <pages viewed>"` (verbatim page paths) |
+| `sourceUrl` | the RB2B visitor permalink |
+
+### Trigify (social / job-change listening)
+
+Trigify pushes social and job-change events. Map the monitored account's domain;
+the post/job text is the evidence.
+
+| Spool field | From Trigify payload |
+|---|---|
+| `bucket` | `"social"` or `"job"` |
+| `accountDomain` | the account/company domain |
+| `trigger` | e.g. `"new role: VP Sales"` or `"posted about <topic>"` |
+| `quote` | the verbatim post text or job title + snippet |
+| `sourceUrl` | the source post / listing URL |
+
+### HubSpot form-submission webhook
+
+The `hubspot-forms` **pull** connector already covers recent submissions via the
+Forms API (Phase 1). For real-time, subscribe to HubSpot's form-submission
+webhook and append a `demand` row per submission — the same shape the pull
+connector produces, so both paths dedup against each other.
+
+| Spool field | From HubSpot submission |
+|---|---|
+| `bucket` | `"demand"` |
+| `accountDomain` | corporate domain of the submitted email (drop free-mail) |
+| `trigger` | `"form: <form name>"` |
+| `quote` | `"Submitted \"<form name>\" — <email>"` |
+| `firstSeen` | submission timestamp (ISO 8601) |
+
+## See also
+
+- `docs/api.md` — the `signals` verb and the `SignalSourceConnector` contract.
+- The connector taxonomy and the hosted/open-source split for the receiver are
+  described in the maintainer design doc (monorepo
+  `docs/spec-connectors-signals-outbound.md`).

package/docs/tam.md

@@ -0,0 +1,195 @@
+# TAM mapping — size the reachable market, then fill it
+
+`tam` answers a longer-horizon question than `market` (the competitive map): **how
+big is the reachable market for my ICP, and how far along am I in actually putting
+it in the CRM?** It is deliberately *not* a one-shot "$10B TAM" headline — it pairs
+a defensible estimate with an iterative, governed population loop and a coverage
+timeline so "this will take a while" becomes a quantified ETA.
+
+```
+tam estimate  → tam populate  → (approve/apply each cycle)  → tam status --save  → tam report
+   model           schedule          governed acquire             coverage point      burn-up + ETA
+```
+
+## The model
+
+`tam estimate` derives the universe **from your ICP** (`icp.json`):
+
+```
+universe accounts = a real count for the ICP filter
+contacts (population target) = accounts × buyers/account
+TAM $ = accounts × ACV            (account/per-logo basis — the default)
+       = contacts × ACV           (buyer/per-seat basis, --acv-basis buyer)
+```
+
+The account count comes from one of three places, always **labeled** in the model:
+
+- `--source theirstack` — **the real, technographically-targeted universe** (and the
+  only one that returns an actual list). TheirStack counts companies that *use* a
+  CRM/MAP — set `firmographics.technologies` (e.g. `["salesforce","hubspot",
+  "pipedrive"]`) — plus geo + employee bounds. `accountsSource:
+  "provider:theirstack (uses-CRM)"`. This is the buying signal for a CRM-hygiene/
+  RevOps tool: "company runs a CRM", not "company is a software publisher". **And
+  `tam accounts --source theirstack` pulls the actual company list** (real names +
+  domains) you can review, save (`--out <csv>`), and acquire into the CRM.
+  (Counting is cheap but **not free** — TheirStack rejects `limit:0`, so a count
+  returns 1 row ≈ 3 credits; a list pull is ~3 credits/company. `login theirstack`.)
+- `--source explorium` — a firmographic **company count** from Explorium
+  `/v1/businesses` (geo + employee bands + NAICS). A count only — **Explorium 403s
+  when you try to pull the list**, and it can't target by CRM-usage, so it's a rough
+  size estimate, not a list. `accountsSource: "provider:explorium"`.
+- `--accounts <n>` — an explicit assumption (e.g. a number from a provider export).
+  `accountsSource: "assumption"`.
+
+  > **Why technographic, and why a count isn't enough** (verified live, 2026-06-25/26):
+  > lead/people endpoints don't report a real universe — Explorium `/v1/prospects`
+  > `total_results` equals the requested page size (1→1, 10→10), and pipe0/Crustdata
+  > returns only a pagination cursor with no total. Explorium `/v1/businesses` counts
+  > companies (e.g. US mid-market software ≈ 19,000) — **as long as you don't send a
+  > `size` field, which silently caps the total** — but it can't filter by CRM-usage
+  > and **403s when you try to pull the list**. TheirStack is the technographic
+  > source that does both (target by tech, return real records). pipe0 stays a
+  > discovery/population source (`tam populate`), not a counting one; `--source pipe0`
+  > for `estimate` is rejected with that explanation.
+
+  Explorium caps `total_results` at **60,000** (a `provider:explorium (≥60k cap —
+  floor)` label + a ⚠). TheirStack has no such cap but list-pull costs credits, so
+  `tam accounts --max <n>` pages it.
+
+### List-pull cost (never spend by surprise)
+
+`tam accounts` pulls real records at **~3 TheirStack credits/company**, so it always
+prints the cost up front and guards big pulls:
+
+- `tam accounts --dry-run [--usd-per-credit <rate>]` — prices the pull AND the full
+  TAM (e.g. *"up to 100 companies ≈ 300 credits. Full TAM (~43,517) ≈ 130,551
+  credits (~$5,483) to materialize."*) and spends **0 credits**. The dollar figure
+  appears only when you give a rate — TheirStack pricing is ~$0.04–$0.11/credit by
+  tier, and the tool won't fabricate a default.
+- A pull above `--max-credits` (default **150** ≈ 50 companies) requires `--confirm`
+  — so a large pull is always a deliberate choice, not an accident.
+
+So the natural pattern is **count freely, pull in confirmed batches** (`--max N`),
+acquire, measure coverage, repeat — rather than one large up-front spend.
+
+**ACV must be a real, ANNUAL figure that you confirm** — never a band default, and
+never silently lifted from the CRM. `--provider` is your **coverage** source, not
+your ACV: the account universe is Explorium, coverage is the CRM, and the TAM's
+economics are yours to confirm. Two confirmed paths, always labeled (`acv.source`):
+
+- `--acv <annual-usd>` — your confirmed annualized ACV (`source: "explicit (annual)"`).
+- `--acv-from-crm --deal-period monthly|quarterly|annual` — derive the **median
+  closed-won deal amount** and **annualize** it by the period you specify
+  (`source: "crm:closed-won (N deals, median $X/monthly ×12 = annual)"`). The period
+  is **required** because a deal amount can be MRR, quarterly, or annual — guessing
+  it is a 4–12× error (a $15k/mo deal is a $180k ACV). The deal count is in the
+  label, so a thin signal (e.g. "1 deal") is visible — don't over-trust it.
+
+If you give neither, `estimate` errors rather than invent a number — and a bare
+`--provider` does NOT auto-set ACV.
+
+**Buyers/account** (the contact population target = accounts × buyers) gets the same
+treatment: `--buyers-per-account <n>`, else the CRM's **average contacts per account**
+(`crm:avg-contacts/account (N)`), else a clearly-labeled minimal assumption of 1
+(`assumption:1-buyer`) — never a silent guess. `--acv-basis buyer` makes ACV per-seat
+(TAM = contacts × ACV) instead of per-logo.
+
+Optional citable **cross-checks** (`--cross-checks <file.json>`, an array of
+`{claim, valueUsd?, sourceUrl, quote, asOf?}`) sit alongside the bottom-up number as a
+top-down sanity check — the market-research flavor, evidence-attached.
+
+`estimate` also records a **coverage baseline** (the CRM account/contact counts right
+now, when a `--provider`/`--input`/`--demo` source is given) so `status` can attribute
+what *this campaign* added versus what was already there.
+
+## Populate it (governed, never auto-writes)
+
+`tam populate --cron "<expr>"` wires a recurring **`enrich acquire --source <s> --save`**
+into the scheduler. Each firing queues a `needs_approval` lead plan — it does **not**
+write to the CRM, and the acquire meter is charged only at apply. Apply stays a separate
+human gate (`apply --plan-id <id>`, re-checked approved at every firing). So a scheduled
+TAM populates by *accumulating proposals you approve*, never by surprise leads.
+
+```bash
+fullstackgtm tam populate --cron "0 7 * * 1-5" --source pipe0 --provider hubspot
+fullstackgtm schedule install            # activate the crontab entry
+# each cycle:
+fullstackgtm plans list                  # the morning's lead plan
+fullstackgtm plans approve <id> --operations all
+fullstackgtm apply --plan-id <id> --provider hubspot
+```
+
+This is the one place the schedule allowlist permits a create-side verb, and only in
+its plan-producing `--save` form (scheduling `enrich acquire` without `--save` is
+rejected — it would queue nothing).
+
+## Track coverage (where you're getting to)
+
+Coverage is measured on the **intersection** of your CRM and the TAM's ICP — not a
+raw account count. `tam estimate` stores the ICP filter on the model, and `tam
+status` classifies every domain-bearing CRM account against it:
+
+- **in-TAM** — matches every CRM-checkable criterion (size, industry) with no
+  contradiction. *Only these count toward coverage.*
+- **out-of-TAM** — contradicts a criterion (wrong size/industry). Reported
+  separately; never inflates coverage. So 50k accounts loaded from other sources
+  that aren't your target market don't fake a high number.
+- **unknown** — the record lacks the fields to judge. Surfaced, never silently
+  counted — it tells you what to enrich.
+
+```bash
+fullstackgtm tam status --provider hubspot --save     # classified coverage + a timeline reading
+fullstackgtm tam report                                # markdown: model + in/out/unknown + burn-up + ETA
+```
+
+> **Honest limit:** geo and "uses a CRM" aren't on a CRM account record, so an
+> in-TAM classification means "matches what the CRM lets us check" (size + industry),
+> not a full technographic match. A `--reverify` pass (re-confirm geo/tech per
+> domain via TheirStack) is planned; until then, status labels what it checked.
+
+**Bottom-up vs top-down — squaring "more in CRM than estimated."** The estimate is a
+*lower-bound prior*, not a ceiling — TheirStack only knows ~740k US firms, so your
+multi-source CRM can legitimately hold more valid in-TAM accounts than it predicted.
+Every in-TAM account is a *proven* member of the real market, so the in-TAM count is
+the strongest floor on the true universe. When `in-TAM ≥ estimate`, `status` stops
+reporting a fake "100%" and flips the signal: **"the estimate was a floor — your real
+market is at least N; re-estimate (broader ICP / better source) to find the
+headroom."** `reconciledUniverse = max(estimate, in-TAM)`.
+
+Once two-plus readings show movement, `report`/`status` project an **ETA** on the
+**in-TAM** burn rate (off-ICP accounts loaded elsewhere don't count as progress) →
+days remaining → a projected fill date. Fewer than two readings, a flat rate, or no
+elapsed time returns an honest "not enough history yet," never a fabricated date.
+
+## Storage
+
+Profile-scoped under `<home>/tam/<name>/`:
+
+- `model.json` — the TAM model (universe, ACV, cross-checks, baseline). 0600.
+- `coverage.jsonl` — append-only coverage readings (one per `status --save`). 0600.
+
+Scope per client with `--profile <name>`; name multiple TAMs with `--name <n>`
+(default `default`).
+
+## Invariants
+
+- **Estimate is honest about its source.** Every model says whether the account count
+  is a `provider:*` probe or an `assumption`; the probe errors rather than silently
+  guessing when the provider returns no count.
+- **No fabricated economics.** ACV must be explicit or CRM-derived (closed-won) — there
+  are no band defaults, and `estimate` refuses without a real ACV. Buyers/account and
+  ACV both carry a `source` label so a thin signal is visible, never hidden.
+- **Population never auto-writes.** `tam populate` schedules plan-only acquire; apply
+  is a separate gate, the meter is charged only at apply, and the allowlist requires
+  `--save`.
+- **Coverage is deterministic** from the CRM snapshot + the model baseline — no LLM,
+  byte-stable, comparable run-over-run.
+- **ETA is refused when unprojectable** rather than faked.
+
+## Library
+
+`estimateTam`, `computeCoverage`, `coverageCountsFromSnapshot`, `projectEta`,
+`tamReportToMarkdown`, the store (`saveTamModel`/`loadTamModel`/`appendCoverage`/
+`readCoverageTimeline`), the count probe (`probeExploriumBusinessCount` +
+`EXPLORIUM_BUSINESS_COUNT_CAP`), and the ICP→firmographic filter
+(`icpToExploriumBusinessFilters`) are all exported for programmatic use.