fullstackgtm 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -7,6 +7,279 @@ The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md)
 
 ## [Unreleased]
 
+## [0.44.0] — 2026-07-01
+
+### Added
+
+- **Paired CLI auto-links HubSpot to the hosted deployment.** When a broker
+  credential exists (a paired CLI), `audit --provider hubspot` hands the local
+  HubSpot private-app token to the deployment over the broker channel
+  (best-effort, with a printed notice), so the hosted Integrations page shows
+  HubSpot connected and syncing without a separate OAuth setup. Unpaired CLIs
+  are unaffected — pairing remains opt-in via `login --via`.
+
+### Added
+
+- **`tam accounts` credit-cost preview + spend guard.** Pulling the list costs ~3
+  TheirStack credits/company, so `tam accounts` now prints the cost up front and
+  never spends by surprise: `--dry-run [--usd-per-credit <rate>]` prices the pull
+  AND the full TAM (e.g. "up to 100 ≈ 300 credits; full TAM ~43,517 ≈ 130,551
+  credits (~$5,483)") for **0 credits**, and a pull above `--max-credits` (default
+  150 ≈ 50 companies) requires `--confirm`. The dollar figure appears only with an
+  explicit rate (no fabricated default; TheirStack is ~$0.04–$0.11/credit by tier).
+  `tam populate` also notes where spend lives — the acquire meter governs
+  population, separate from the TheirStack list pull. Library:
+  `theirStackPullCost` + `THEIRSTACK_CREDITS_PER_COMPANY`.
+
+### Changed
+
+- **`tam status` coverage is now classified against the TAM ICP — not a raw
+  account count.** Previously it counted *every* domain-bearing CRM account over
+  the universe, so accounts loaded from any source (off-ICP or not) inflated
+  coverage and could read >100%. Now `tam estimate` stores the ICP filter
+  (`model.targeting`), and `status` classifies each account into **in-TAM /
+  out-of-TAM / unknown** (checked on size + industry; geo and "uses-CRM" aren't on
+  a `CanonicalAccount`, so they need re-enrichment — a `--reverify` pass is
+  planned, and the classifier labels what it checked). Only in-TAM counts toward
+  coverage; off-ICP junk is bucketed out. **Bottom-up vs top-down reconciliation:**
+  the in-TAM count is a floor on the real universe, so when it meets/exceeds the
+  estimate, `status` stops reporting a fake 100% and flips to "the estimate was a
+  floor — your real market is at least N (`reconciledUniverse`); re-estimate for
+  the headroom." ETA now burns on in-TAM accounts/day. New library:
+  `classifyAccount`, `classifyCoverage`, `crmCheckableCriteria`, `coveredAccounts`,
+  `TamTargeting`/`TamClassified` (and `TamModel.targeting`). Legacy models without
+  targeting fall back to counting all accounts, with a "re-estimate to classify"
+  note.
+
+### Added
+
+- **`tam` technographic sourcing via TheirStack — target by CRM-usage, get a real
+  list.** The Explorium firmographic count (NAICS/size/geo) is a weak proxy for a
+  RevOps/CRM-hygiene tool and can't return the list (it 403s on pull). New
+  `--source theirstack` counts companies that actually **use** a CRM/MAP — set
+  `icp.firmographics.technologies` (e.g. `["salesforce","hubspot","pipedrive"]`),
+  mapped to TheirStack `company_technology_slug_or` + employee bounds + country —
+  which is the real buying signal, labeled `provider:theirstack (uses-CRM)`. And a
+  new **`tam accounts --source theirstack`** pulls the actual company list (real
+  names + domains, `--out <csv>` or `--json`, `--max` caps the credit spend), so the
+  TAM is a list you can review and acquire, not just a number. 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). New connector
+  `connectors/theirstack.ts` (`theirStackCountCompanies` / `theirStackSearchCompanies`),
+  `icpToTheirStackFilters` + `employeeBandsToRange`, and `login theirstack`.
+  (Verified live: filters + `metadata.total_results`; `limit` must be ≥ 1.)
+
+### Changed
+
+- **`tam estimate` requires a confirmed ANNUAL ACV — no fabricated defaults, and
+  the CRM is not silently the ACV source.** A TAM dollar figure built on a guessed
+  ACV is a false signal, so the `--acv-band smb|mid|enterprise` presets (hardcoded
+  $6k/$24k/$90k) are removed and `estimate` refuses to run without a real ACV. Two
+  confirmed paths, always labeled on the model (`acv.source`): `--acv <annual-usd>`
+  (`"explicit (annual)"`), or `--acv-from-crm --deal-period monthly|quarterly|annual`
+  — the median closed-won deal amount **annualized** by the stated period
+  (`"crm:closed-won (N deals, median $X/monthly ×12 = annual)"`). The period is
+  **required**: a deal amount can be MRR/quarterly/annual and guessing it is a
+  4–12× error (a $15k/mo deal is a $180k ACV). A bare `--provider` is the COVERAGE
+  source and **no longer auto-sets ACV**. **Buyers/account** likewise:
+  `--buyers-per-account <n>`, else the CRM's **average contacts per account**
+  (`"crm:avg-contacts/account (N)"`), else a labeled `"assumption:1-buyer"` — never
+  a silent default of 3. New library helpers `deriveAcvFromClosedWon` /
+  `deriveBuyersPerAccount`; `TamModel.acv.source` and `universe.buyersSource` are
+  new fields (and `acv.band` is gone).
+
+### Fixed
+
+- **`icp eval --golden default` no longer rots with the calendar.** The default
+  golden set's `firstSeen` stamps are relative to a pinned instant
+  (`DEFAULT_GOLDEN_NOW_ISO`, exported), but grading used wall-clock `new Date()`
+  — so freshness decay silently degraded the "fresh → send" rows until the gate
+  started failing (~8 days after the set was authored) on every fresh install
+  and in CI, with no code change. The default set is now graded on its own
+  pinned clock; file-based golden sets still grade against wall time (their
+  timestamps are the caller's).
+
+- **`enrich acquire` (pipe0/Crustdata) over-narrow ICP filter → zero discovery.**
+  Live testing surfaced that a RevOps ICP returned 0 prospects from pipe0/Crustdata
+  even though a title-only search returned plenty — the prime suspect is the
+  industry vocabulary: LinkedIn renamed its industry taxonomy (v1→v2) and the map
+  sent only one generation, so a vendor on the other generation matches nothing.
+  `CRUSTDATA_INDUSTRY` now sends BOTH generations per cluster (e.g. "Software
+  Development" *and* "Computer Software"), OR-matched within the field. (pipe0
+  credits were exhausted mid-investigation, so this is a reasoned fix not yet
+  re-confirmed end-to-end — re-run `enrich acquire --source pipe0` once credits
+  refill; if still zero, the next suspects are the `current_seniority_levels`
+  shape and `locations`. Note `scoreProspectAgainstIcp` backstops persona but NOT
+  industry, so the industry filter is load-bearing.)
+- **`enrich acquire` now surfaces a zero-discovery result** instead of emitting a
+  silent empty plan: when a provider returns 0 prospects it warns that this is
+  usually an over-narrow filter (not an empty market) and points at `icp show`;
+  and when all discovered prospects score below the fit threshold it says so.
+
+### Added
+
+- **`tam` — Total Addressable Market mapping.** Size the reachable market FROM
+  the ICP, then iteratively fill it and track coverage to an ETA. `tam estimate`
+  computes a transparent model (account universe × ACV = TAM, account/per-logo
+  basis by default or `--acv-basis buyer`; contacts = accounts × buyers/account
+  is the population target). The account count is `--accounts <n>` (assumption)
+  or `--source explorium` — a live count of matching **companies** via Explorium
+  `/v1/businesses`, which is the account universe directly. (Verified against the
+  live APIs: people/lead endpoints can't size a market — Explorium `/v1/prospects`
+  `total_results` equals the page size and pipe0/Crustdata returns only a cursor —
+  so `--source pipe0` for estimate is rejected; pipe0 remains a discovery/
+  population source. The businesses count omits `size`, which otherwise caps the
+  total.) Explorium caps the count at 60,000; a saturated reading is surfaced as a
+  floor (`provider:explorium (≥60k cap — floor)` + a warning to narrow the ICP).
+  The model always labels `accountsSource` provider-vs-assumption. Optional citable
+  cross-checks sit beside the bottom-up number. `tam populate --cron` schedules
+  governed `enrich acquire --save` (plan-only; see below). `tam status --save`
+  stamps a coverage timeline (CRM accounts-with-domain + contacts vs. the
+  universe, `$ covered` proportional, what the campaign added since baseline);
+  `tam report` renders a markdown burn-up. `status`/`report` project a linear
+  accounts/day ETA and refuse to project (honest "not enough history") below two
+  readings or a flat rate. Coverage + ETA are deterministic (no LLM). Library:
+  `estimateTam`, `computeCoverage`, `projectEta`, `tamReportToMarkdown`, the
+  store, and the count probe (`probeExploriumBusinessCount` +
+  `EXPLORIUM_BUSINESS_COUNT_CAP`). See [docs/tam.md](./docs/tam.md).
+- **Source connectors for `signals` (Phase 1).** `signals fetch` gains an
+  additive, opt-in `--connector <id>[,<id>] [--connector-opt k=v …]` that pulls
+  signals from connected platforms instead of only ATS boards and hand-staged
+  `--from` files. Three connectors ship: `file` (local JSON/JSONL — also the
+  webhook landing-zone spool, no auth), `serpapi-news` (funding/company news via
+  a news REST API, key through the credential ladder), and `hubspot-forms`
+  (first-party `demand` from recent form submissions, reusing the existing
+  HubSpot login). Secrets resolve through the env → login → broker ladder, never
+  argv; `--connector-opt` carries non-secret knobs only. **Default behavior is
+  unchanged** when no `--connector` is passed. Connectors are read-only re: the
+  CRM and run through the same evidence-gate/dedup/weight pipeline as `--from`
+  (the `readStagedSignals` row validator is now the shared `stagedRowToSignal`).
+  Library: `connectors/signalSources.ts` (`listSignalSources`, `getSignalSource`,
+  `fileSource`, `serpapiNewsSource`, `hubspotFormsSource`), `stagedRowToSignal` +
+  `StagedSignalRow` from `signals.ts`. Design:
+  [docs/spec-connectors-signals-outbound.md](../../docs/spec-connectors-signals-outbound.md)
+  (the connector taxonomy + the Phase 2/3 webhook-spool and governed-channel plan).
+- **Webhook spool format + conventional landing zone (signals Phase 2).**
+  `--connector file` with no path now reads the conventional spool directory
+  (`<profile home>/signals/spool`, via `signalsSpoolDir`) — every `*.jsonl` in
+  it, name-sorted, so a webhook receiver can append one row per event (per
+  source: `rb2b.jsonl`, `hubspot.jsonl`, …) and they all land in one fetch. The
+  `file` connector reads a directory as well as a single file. New
+  [docs/signal-spool-format.md](./docs/signal-spool-format.md) documents the row
+  format, the landing zone, re-read/retention semantics, and per-platform
+  payload mappings (RB2B, Trigify, HubSpot form webhook). Per the open-core
+  boundary the format + reader are open; the always-on receiver is a hosted
+  concern — the package ships no receiver. Also fixes a latent filter bug:
+  explicitly-provided rows (`--from`, connectors) whose bucket has no configured
+  `sources` (notably `demand`) were silently dropped unless `--bucket` was given;
+  now only an explicit `--bucket` narrows them, so spool/`hubspot-forms` `demand`
+  signals flow by default.
+- **Outbox channel — governed send terminus (signals Phase 3).** `apply
+  --channel outbox` renders each APPROVED drafted opener to a local outbox
+  (`<profile home>/signals/outbox/<channel>.jsonl`, via `signalsOutboxDir`) for a
+  downstream sender to drain — and **transmits nothing**, preserving the "drafts
+  everything, transmits nothing" invariant (the send-side mirror of the spool).
+  The outbox channel is a `GtmConnector` whose `applyOperation` renders instead
+  of writing a CRM, so it reuses the entire governed apply path (approval set,
+  integrity verification, idempotency, run recording) with no change to the apply
+  engine; `apply` now takes `--provider <crm>` OR `--channel <id>`. It only
+  renders `draft:`-policy `create_task` ops (any other op is skipped) and is
+  idempotent on the operation id. New
+  [docs/outbox-format.md](./docs/outbox-format.md). Per the open-core boundary the
+  governed artifact + format are open; the always-on sender that actually
+  transmits (ESP/LinkedIn) is a hosted concern — no sender ships in the package.
+  Library: `connectors/outboxChannel.ts` (`createOutboxChannelConnector`,
+  `createChannelConnector`, `listOutbox`, `OutboxEntry`), `signalsOutboxDir`.
+
+### Changed
+
+- **`enrich acquire --save` is now schedulable** (for `tam populate`). It joins
+  the read/plan-side schedule allowlist in its plan-producing form ONLY — a
+  scheduled `enrich acquire` must include `--save` (rejected otherwise), so each
+  firing queues a `needs_approval` lead plan and writes nothing. The acquire
+  meter is still charged only at apply, and apply stays a separate human gate
+  (`apply --plan-id`, re-checked approved). Scheduling never auto-approves.
+
+## [0.43.0] — 2026-06-25
+
+### Added
+
+- **`init` — scaffold a GTM workspace from cold scratch.** `fullstackgtm init
+  [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce]` writes
+  three files so the first acquire/signals/judge/draft commands work: a valid
+  starter `icp.json`, an acquire-ready `enrich.config.json` (the source preset
+  plus an explicit `acquire.assign` seam, placeholder owner id, so leads are
+  never silently ownerless), and a `PLAYBOOK.md` wired with the cold-start and
+  outbound-loop recipes for this workspace's source/provider/profile. Pure
+  file-writer: no network, keeps existing files unless `--force`. Library:
+  `scaffoldWorkspace`, `starterIcp`, `starterEnrichConfig`, `starterPlaybook`.
+- **`docs/recipes.md` — five composable GTM plays.** Documents how the governed
+  primitives compose into real plays (cold-start lead-fill, the
+  trigger→judge→draft outbound loop, scheduled-continuous, ABM-from-companies,
+  hygiene-gated outbound) — making explicit that the CLI ships primitives, the
+  coding agent is the orchestrator (no `outbound` mega-verb), and the package
+  never sends. Surfaced from the agent skill and `llms.txt`, which also now
+  carry the previously-undocumented GTM-brain layer (`signals`/`icp`/`judge`/
+  `draft`) and the `init`/`enrich acquire` account-stamping behavior.
+- **Account-level acquire for ABM (seam I).** `enrich acquire` creates net-new
+  **accounts**, not just contacts: configure `acquire.create.company` (match key
+  `domain`) and feed company rows (`enrich ingest companies.csv --objects
+  companies`). Each unmatched company becomes a `create_record` of
+  `objectType: account` with its domain stamped — so the acquired account is
+  immediately signal-watchable. (The spine already routed by object type; this
+  validates + documents the account path so it's discoverable.)
+- **`health` breaks down by object type.** `HealthEntry.byObjectType` reports a
+  separate record-normalized score (same 100/(1+weighted-per-record) curve) plus
+  finding/record counts for `account`, `contact`, and `deal` — so "is my contact
+  data clean but my pipeline messy?" is answerable from one audit, and `health`
+  speaks each object type instead of a single aggregate. Rendered as a "By object
+  type" table in `healthToMarkdown`.
+- **Outbound is contact-granular end to end (seam D).** `icp judge` now surfaces
+  `contacts` — all in-CRM contacts at the hot account (primary first, capped) —
+  alongside the single `contact`, so an agent can multi-thread instead of being
+  limited to one person. `signals outcome --contact <id>` records which contact a
+  touch reached (`SignalOutcome.contactId`), so the feedback loop credits the
+  person, not just the account domain.
+
+### Changed
+
+- **`call link` says HOW it matched (seam H); the findings split is documented
+  (seam G).** `CallDealSuggestion` now carries `resolvedVia`
+  (`account_domain` | `contact_email` | `both`) and `matchedContacts`, so an
+  agent can weight a deal match by whether it came from the company-wide domain
+  or a single (possibly stale) attendee email — and the contact↔account hop is
+  visible, not just the resolved account. Separately, `PatchPlan.findings` (the
+  complete, object-typed list) and `pipelineFindings` (the deliberately
+  deal/sales-pipeline subset) are now documented so account/contact findings
+  aren't mistaken for "dropped" — they live in `findings`.
+- **`enrich acquire` now gives every lead a signal-watchable account (contact↔
+  account seam).** Previously the presets wrote the company as a text field only,
+  so an acquired lead had no account record — invisible to `signals`/`icp judge`,
+  which key on account domain. Now acquire resolves-or-creates the lead's account
+  **by domain**: `AcquireCreateMap.associateCompanyDomainFrom` (preset:
+  `companyDomain`) threads the resolved domain — or the work-email's domain as a
+  free fallback — onto `CreateRecordPayload.associateCompanyDomain`. The HubSpot
+  and Salesforce connectors then match the account by domain first (the accurate
+  key), create it **with** the domain (`domain` / `Website`), and fill the domain
+  on a name-matched account that lacks one (fill-blank, never clobber). The dry-
+  run op reason now names the account + domain instead of resolving it silently.
+
+### Fixed
+
+- **Outbound now writes against a real record, not a domain (contact↔account
+  seam).** `draft` previously emitted a `create_task` op hardcoded to
+  `objectType: "contact"` while carrying the account **domain** as `objectId` —
+  an incoherent operation the apply layer had to re-interpret. The bridge is now
+  explicit: `icp judge` resolves each decision's CRM target and surfaces it on
+  `JudgeDecision` — `accountId` plus the best `contact` (`id`/`email`/`title`) at
+  the account — whenever a snapshot source is given (`--provider`/`--input`/etc;
+  `--with-history` still gates the memory + fit scoring inputs, so scores are
+  unchanged). `draft` writes the task against `contact.id` (who to message), or
+  the `accountId` when no contact resolves, and **rejects a domain-only decision**
+  ("acquire it first") instead of forging a contact-typed op with a domain. The
+  object-type coherence invariant — every op's `objectId` is a real id of its
+  declared type — now holds for the outbound path.
+
 ## [0.42.0] — 2026-06-25
 
 ### Added

package/README.md

@@ -38,13 +38,17 @@ It installs a compact operating guide ([skills/fullstackgtm/SKILL.md](./skills/f
 ## Five-minute loop
 
 ```bash
-# 0. No credentials? Try it on a realistic, deliberately messy demo CRM
+# 0. Scaffold a workspace: a starter icp.json, an enrich.config.json acquire
+#    preset, and a PLAYBOOK.md wired for your provider + discovery source
+npx fullstackgtm init --provider hubspot --source pipe0
+
+# 1. No credentials? Try it on a realistic, deliberately messy demo CRM
 npx fullstackgtm audit --demo
 
-# 1. Audit your real HubSpot portal (private app token or OAuth access token)
+# 2. Audit your real HubSpot portal (private app token or OAuth access token)
 HUBSPOT_ACCESS_TOKEN=pat-... npx fullstackgtm audit --provider hubspot --out plan.json
 
-# 2. Review plan.json, then apply ONLY the operations you approve
+# 3. Review plan.json, then apply ONLY the operations you approve
 HUBSPOT_ACCESS_TOKEN=pat-... npx fullstackgtm apply \
   --plan plan.json --provider hubspot \
   --approve op_abc123,op_def456 \
@@ -53,6 +57,8 @@ HUBSPOT_ACCESS_TOKEN=pat-... npx fullstackgtm apply \
 
 Nothing is ever written without an explicit `--approve`. Operations whose value is a human decision (`requires_human_*` placeholders, e.g. which owner to assign) are refused unless you supply a concrete `--value` override.
 
+`init` keeps any files you already have (`--force` overwrites) and works with `--source pipe0|explorium|linkedin` and `--provider hubspot|salesforce`. The PLAYBOOK.md it writes wires the cold-start and outbound-loop recipes to your workspace; the full play set — cold start, trigger-based outbound, scheduling, ABM, hygiene-gating, TAM — is [docs/recipes.md](./docs/recipes.md).
+
 ## Call workflows: calls become governed evidence
 
 Calls are where pipeline truth lives. `call parse` normalizes any transcript dialect — `Speaker: text` lines (Fathom, Gong exports), `[Speaker]:` labels, or raw Granola utterance JSON — into canonical segments, insights, and `GtmEvidence` records.
@@ -211,8 +217,11 @@ LinkedIn is just another discovery source on the same scored → deduped → met
 Cleaning and filling the CRM tells you *who* to reach; it never tells you *when*. The **signal → judge → draft** loop adds timing — and, like everything else, it stays on the dry-run → approve → apply spine and sends nothing.
 
 ```bash
-# 1. Watch for movement. Free, no-auth public job boards in the box; funding/company/social via staged ingest.
+# 1. Watch for movement. Free, no-auth public job boards in the box; pull from
+#    connected platforms via source connectors; webhook platforms via the spool.
 fullstackgtm signals fetch --bucket job --source greenhouse,lever,ashby --keywords "revops,growth" --save
+fullstackgtm signals fetch --connector serpapi-news,hubspot-forms --save   # news + first-party form demand
+fullstackgtm signals fetch --connector file --save                         # webhook landing zone (see docs/signal-spool-format.md)
 fullstackgtm signals list --since 7d                         # ranked triggers, each with a verbatim source quote
 
 # 2. Decide who's worth a touch — and who isn't. Scores timing × fit × memory into send/nurture/skip.
@@ -220,8 +229,10 @@ fullstackgtm icp judge --signals-from latest --with-history --save
 fullstackgtm icp eval --golden default                       # gate: prove the judge is calibrated before any send (exits 2 if not)
 
 # 3. Draft the opener from the trigger. A create_task plan — proposed, never transmitted.
-fullstackgtm draft --from-judge latest --min-score 80 --save
-fullstackgtm plans approve <id> --operations all && fullstackgtm apply --plan-id <id> --provider hubspot
+fullstackgtm draft --from-judge latest --min-score 80 --channel email --save
+fullstackgtm plans approve <id> --operations all
+fullstackgtm apply --plan-id <id> --provider hubspot          # log the touch as a CRM task
+fullstackgtm apply --plan-id <id> --channel outbox            # OR render to the outbox for a sender — transmits nothing (docs/outbox-format.md)
 
 # 4. Close the loop. Outcomes re-weight which signals earn a touch.
 fullstackgtm signals outcome --account acme.com --result replied
@@ -289,7 +300,7 @@ fullstackgtm diff --before old.json --after new.json --fail-on-new-findings
 - `--demo` (with `--seed`) generates a realistic mid-market CRM with injected real-world failure modes — departed owners, unlinked deals, orphan accounts, stale pipeline — so agents and CI can exercise the full snapshot → audit → apply pipeline with zero credentials.
 - Exit codes: `0` success, `1` error, `2` findings at/above `--fail-on`.
 
-"Built for agents" is measured, not asserted: a 1,088-run benchmark (17 scenarios = 14 synthetic + 3 seeded from an anonymized real portal, × 3 tool-surface arms × 4 trials, across six models from three vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface beating raw CRM-API access on completion-under-policy for every model tested — and the tool-surface effect is monotonic and vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+"Built for agents" is measured, not asserted: a 1,892-run benchmark (20 scenarios = 17 synthetic + 3 seeded from an anonymized real portal, × 3 tool-surface arms × up to 4 trials, across nine models from six vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface beating raw CRM-API access on completion-under-policy for every model tested — and the tool-surface effect is monotonic and vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
 
 The design is **deterministic apply, governed suggest**: the parts that touch your CRM — the audit rules, the plan/apply contract, compare-and-set, the survivor/merge logic — are deterministic and replayable; the parts that read free text (`call parse`/`score`, `market classify`) are LLM-powered but bounded, with every quoted span mechanically verified against the source before it can drive a writeback. Nondeterministic suggestion, deterministic governance.
 

package/dist/calls.d.ts

@@ -63,6 +63,19 @@ 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;
 };

package/dist/calls.js

@@ -295,18 +295,27 @@ export function suggestCallDeal(snapshot, options) {
         return { dealId: null, confidence: "none", reason: "No attendee emails or domain supplied to match on." };
     }
     const accountIds = new Set();
+    let viaDomain = false;
+    let viaEmail = false;
+    const matchedContacts = [];
     for (const account of snapshot.accounts) {
         const domain = account.domain?.trim().toLowerCase().replace(/^www\./, "");
-        if (domain && domains.has(domain))
+        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 } : {}) };
     if (accountIds.size === 0) {
         return {
             dealId: null,
@@ -335,8 +344,9 @@ export function suggestCallDeal(snapshot, options) {
             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 {
@@ -344,8 +354,9 @@ export function suggestCallDeal(snapshot, options) {
         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.`,
     };
 }
 function callHash(value) {