fullstackgtm 0.43.0 → 0.45.0

package/docs/outbox-format.md

@@ -0,0 +1,92 @@
+# Outbox format (governed send queue)
+
+The **outbox** is the send-side mirror of the [signal spool](./signal-spool-format.md).
+It is how an *approved* drafted opener leaves the CLI — as a governed artifact a
+downstream sender picks up, **not** as a transmitted message.
+
+`fullstackgtm` **drafts everything and transmits nothing.** The CLI never opens
+an SMTP or messaging-API connection. `apply --channel outbox` renders each
+approved opener to a local JSONL file; a sender you run (the hosted product, or
+your own MTA / ESP integration) drains the outbox and performs the actual send.
+This is the send-side half of the open-core boundary: the governed artifact and
+its format are open; always-on transmission infrastructure is hosted/opt-in.
+
+## The loop
+
+```
+signals fetch → icp judge → draft → plans approve → apply --channel outbox → <sender>
+   (detect)      (decide)   (write)   (human gate)     (render, no send)      (transmit)
+```
+
+`draft` stages a `needs_approval` plan of `create_task` operations, each carrying
+one opener grounded in a verbatim signal quote. After `plans approve`, applying
+the plan **through the outbox channel** (instead of a CRM provider) renders each
+approved operation to the outbox. Nothing is sent, and no CRM record is written.
+
+```bash
+fullstackgtm draft --from-judge latest --channel email --save
+fullstackgtm plans approve <planId> --operations all
+fullstackgtm apply --plan-id <planId> --channel outbox      # renders; transmits nothing
+```
+
+Applying the same plan through a CRM provider instead (`--provider hubspot`)
+logs the opener as a CRM task — the existing behavior. The two are alternatives:
+a plan applies to one target.
+
+## Where the outbox lives
+
+```
+<profile home>/signals/outbox/<channel>.jsonl   (default: ~/.fullstackgtm/signals/outbox/)
+```
+
+One file per channel (`email.jsonl`, `linkedin.jsonl`, `task.jsonl`), matching the
+draft op's channel. Profile-scoped, owner-only (0600). A sender reads the file(s)
+for the channel it handles and drains them on its own schedule.
+
+## The format
+
+Newline-delimited JSON (JSONL), one **outbox entry** per approved opener:
+
+| Field | Meaning |
+|---|---|
+| `id` | The source operation id — the **idempotency key**. Re-rendering the same op never duplicates a row. |
+| `channel` | `email` \| `linkedin` \| `task` — from the draft op. |
+| `objectType` | `contact` \| `account` — the CRM object the opener is addressed to. |
+| `objectId` | The CRM record id. A sender with CRM access resolves it to an email / profile. |
+| `body` | The **approved opener, verbatim** as it was signed in the plan operation. |
+| `reason` | The draft op's human-readable reason (carries the account and the trigger). |
+| `evidenceIds` | Ids of the evidence the opener was grounded in (the verbatim signal quote). |
+| `renderedAt` | ISO 8601 — when the CLI rendered this to the outbox. **Not** a send time. |
+
+Example (`email.jsonl`):
+
+```jsonl
+{"id":"op_draft_abc","channel":"email","objectType":"contact","objectId":"C123","body":"Saw the Series B — congrats. Worth a quick chat on revops?","reason":"Signal-grounded opener for globex.com -> contact vp@globex.com","evidenceIds":["ev_globex_funding"],"renderedAt":"2026-06-25T13:08:17.176Z"}
+```
+
+The entry carries the CRM `objectId`, not a resolved email address — the CLI does
+not resolve recipients (that is the sender's job, against the live CRM). The
+`body` is exactly what a human approved; a sender may template around it but the
+approved span is the source of truth.
+
+## Governance and what the channel will not do
+
+- **Only drafted openers.** The outbox channel renders `create_task` operations
+  produced by `draft` (policy `draft:<channel>`). Any other operation is
+  `skipped` — it is not a general CRM writer. Apply CRM changes through a CRM
+  provider.
+- **Approval-gated and integrity-checked.** Rendering reuses the same apply path
+  as a CRM write: only operations whose plan is `approved` are applied, and a
+  stored plan's approval signatures are verified before anything is rendered.
+- **Idempotent.** Re-rendering an operation already in the outbox is a no-op.
+- **Draining and retention are the sender's job.** The CLI appends; it never
+  truncates the outbox. Your sender removes or archives entries after it
+  transmits them.
+
+## See also
+
+- [signal-spool-format.md](./signal-spool-format.md) — the receive-side mirror.
+- `docs/api.md` — the `apply`/`draft` verbs and the connector contract.
+- The connector taxonomy and the hosted/open split (the managed sender stays
+  closed) are in the maintainer design doc
+  (monorepo `docs/spec-connectors-signals-outbound.md`).

package/docs/recipes.md

@@ -149,6 +149,43 @@ 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.

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,175 @@
+# 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) |
+
+## One container convention across staged intake
+
+The spool CONTAINER (JSONL one-object-per-line; JSON array accepted; a
+directory means every `*.jsonl` / `*.json` file in it, name-sorted) is shared
+by every staged-file intake path, not just `--connector file`:
+
+- `signals fetch --from <path>` — rows are staged signal rows (this doc's table);
+- `enrich ingest <path> --source <id>` — rows are that source's enrichment rows;
+- `market observe --from <path>` — each object is one observation-set envelope.
+
+Each verb keeps its original single-file `.json` / `.csv` handling unchanged;
+the row schema stays the verb's own. Shared reader: `src/spoolFiles.ts`.
+
+## 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.