fullstackgtm 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -5,7 +5,384 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
-## [Unreleased]
+## [0.45.0] — 2026-07-02
+
+### Added (TUI glamour — interactive terminals only)
+
+- **A terminal presentation layer (`src/cli/ui.ts`, zero new dependencies) —
+  styling and animation exist ONLY on an interactive TTY.** Piped, redirected,
+  `--json`, CI, and `NO_COLOR` output is byte-identical to the pre-TUI CLI
+  (verified against the previous build for 14 verbs: stdout, stderr, exit
+  codes); a new `agent-cli.yml` step and `tests/fullstackgtmAnsiSafety.test.ts`
+  enforce zero ANSI bytes in piped output permanently. `FORCE_COLOR=1` opts
+  piped output back into color per spec. On a TTY:
+  - `doctor` colors each check (green ok / red MISSING), dims what's not
+    connected, bands the health score, appends a score-history sparkline, and
+    frames "Next step" in a box. `--help` gets a dimmed brand header
+    (version · active profile), bold command names, cyan lifecycle groups.
+  - `health` renders a styled rollup: banded score, ▲/▼ delta, score
+    sparkline, aligned object-type and per-rule tables (positive finding
+    deltas red — more findings is worse — negative green).
+  - Live provider pulls show a stderr spinner with a running tally ("Pulling
+    contacts from hubspot… 2,400 fetched · 12s"): the HubSpot/Salesforce
+    connectors accept an optional per-page `onProgress` (presentation-only,
+    errors swallowed). `audit` renders its rule registry as a live checklist
+    (○ → spinner → ✓ with finding counts) via a new optional `onRule` on
+    `auditSnapshot`; `signals fetch` shows a per-domain ATS tally.
+  - `apply` and `fix --yes` tick per-operation progress ("Applying 41/120 ·
+    ✓ 40 applied · 0 failed · 1 conflict") via a new optional `onOperation` on
+    `applyPatchPlan`, closing with a colored outcome badge. `enrich
+    append/refresh` gets a progress bar with rate + ETA over the Apollo pull;
+    `enrich acquire` adds a budget fuel gauge (records + spend vs day/month
+    caps, color-banded by burn).
+  - LLM waits show an elapsed status line (`call parse` / `call score`);
+    `icp judge` and `market classify` report per-account / per-vendor progress
+    via new optional `onAccount` / `onVendor` callbacks.
+  - Patch plans render with severity banding and value diffs — current value
+    red, proposed value green, `requires_human_*` placeholders yellow — in
+    `audit` and `plans show`; `plans list` becomes an aligned status-banded
+    table (summaries truncated with `…` to the terminal width so rows never
+    wrap); `fix` frames its stop-before-apply command in a box.
+
+### Added (agent ergonomics pass 1)
+
+- **Flag typos are caught instead of silently ignored.** Any `--flag` that is
+  documented nowhere in the help reference but sits within one edit of a
+  documented flag (after lowercasing and `_`→`-` normalization) now stops with
+  exit 1, a `Did you mean: --json` hint, and the exact corrected command;
+  `--json` callers get a structured `UNKNOWN_FLAG` envelope. Previously
+  `audit --demo --jsn` exited 0 and printed markdown where the caller asked
+  for JSON, and `reassign … --sav` exited 0 without saving. Suggest-only —
+  the correction is never auto-executed, so a typo can never change what a
+  write-shaped invocation stages. The known-flag registry is derived at
+  runtime from the help table (no parallel list); unknown flags with no
+  near-miss behave exactly as before.
+- **Unknown commands get a did-you-mean on the plain-text path too.**
+  `fullstackgtm plan` now answers `Did you mean: fullstackgtm plans` plus one
+  pointer line each to `--help` and `capabilities --json`, instead of the
+  full usage-reference dump. (The `--json` envelope already had the hint.)
+- **`doctor` is now the one-call triage surface.** `doctor --json` adds a
+  `workspace` slice — `healthScore`, `scoreDelta`, `lastAuditAt`,
+  `auditCount`, and `pendingPlans` (id, summary, operation/approved counts) —
+  and when a plan is awaiting approval `nextSteps` becomes the copy-pasteable
+  `plans show` → `plans approve` → `apply` chain with the connected provider
+  filled in. Text `doctor` gains the matching `Workspace:` section.
+  Previously orienting an agent took three calls (doctor + health +
+  plans list).
+- **`audit` output is byte-deterministic under `SOURCE_DATE_EPOCH`.** The
+  plan's `createdAt` honors the reproducible-build convention (seconds since
+  the epoch) so golden tests and CI diffs can pin `audit --demo --json`
+  byte-for-byte. Unset, it remains the real clock.
+- **GNU-style `--flag=value` is corrected too.** `audit --rules=x` was
+  silently dropped (the audit ran with all rules); an `=`-form whose base
+  resolves to a documented flag now stops with the space-separated form this
+  CLI parses (`Try: … --rules x`).
+- **A flag-shaped first token is diagnosed as flag-before-command.**
+  `fullstackgtm --jsn` was "Unknown command: --jsn"; now it explains that a
+  command must come first and resolves the flag when it near-misses a
+  documented one.
+- **Subverb typos get a nearest-match did-you-mean on all 7 multi-verb
+  commands** (`enrich`, `market`, `icp`, `signals`, `plans`, `schedule`,
+  `tam`): `enrich apend` → `Did you mean: fullstackgtm enrich append?` plus
+  the full list. `market <typo>` no longer dies with a `market.config.json`
+  ENOENT before the subcommand is validated.
+
+### Changed (agent ergonomics pass 1)
+
+- **`apply <planId>` / `suggest <planId>` (positional) now name the exact
+  corrected command** (`apply --plan-id <id> --provider <…>`) instead of
+  misdiagnosing the mistake as a missing `--provider`. Both verbs stay
+  flag-explicit; nothing is inferred into execution.
+- **`Unknown provider: hubpsot` now adds `Did you mean hubspot?`** (CLI and
+  MCP paths); the supported-provider list is unchanged.
+
+### Changed
+
+- **MCP zero-install is now one short command: `npx -y fullstackgtm-mcp`.** A
+  thin wrapper package (`fullstackgtm-mcp@0.1.0`, monorepo
+  `packages/fullstackgtm-mcp`, published manually — the OIDC release flow
+  covers only this package) pins the optional MCP peers as hard dependencies
+  and delegates to this package's `dist/mcp-bin.js`. README, SKILL.md, and the
+  missing-peer help text now lead with the short command; the explicit
+  `-p fullstackgtm -p @modelcontextprotocol/sdk -p zod` form still works.
+
+### Added
+
+- **`schedule install` no longer needs Full Disk Access on macOS: launchd
+  LaunchAgents are the default timer there.** macOS gates `crontab` writes
+  behind FDA — an unpromptable TCC permission granted to the terminal app,
+  not the CLI — so on darwin `install` now writes one LaunchAgent plist per
+  enabled entry (`com.fullstackgtm.<profile>.<id>` in
+  `~/Library/LaunchAgents`, loaded via `launchctl bootstrap gui/<uid>`),
+  which needs no permission at all. The cron expression compiles to
+  `StartCalendarInterval` dicts (full-range fields become launchd wildcards;
+  dense expressions are capped at 512 dicts with a clear error; Vixie
+  dom+dow OR becomes a Day set plus a Weekday set). Every plist's
+  `ProgramArguments` is `… schedule run <id> --profile <p> --trigger cron`
+  and nothing else — the same single-entry-point audit story as the crontab
+  block — and re-install replaces the profile's plist fleet wholesale,
+  never touching foreign plists. launchd also coalesces firings missed
+  during sleep into one run on wake, where cron silently skips. `--timer
+  crontab|launchd` overrides the platform default (launchd on macOS, crontab
+  elsewhere); stdout/stderr of each firing lands in
+  `<home>/schedule/logs/<label>.log`. New run no-op reason
+  `duplicate_firing`: `schedule run` drops a second cron trigger in the same
+  minute, so a date matching both the Day and Weekday interval sets cannot
+  double-run a command.
+
+- **Standardized flag aliases (additive — every legacy flag keeps working).**
+  `--dry-run` is now accepted on the plan-spine verbs (`audit`, `suggest`,
+  `bulk-update`, `dedupe`, `reassign`, `fix`, `call plan`,
+  `enrich append`/`refresh`/`acquire`, `signals fetch`, `icp judge`, `draft`,
+  `tam status`, `market overlay`): these verbs were already preview-by-default,
+  so the flag asserts that default — it suppresses `--save` (with a stderr note
+  when both are passed) and locks `fix` to its stop-before-apply path even with
+  `--yes`. Omitting it changes nothing. `--confirm` is now an accepted alias
+  for `fix --yes` (matching `tam accounts --confirm`); `--dry-run` beats both.
+- **Staged-file ingestion converged on the spool container convention
+  (additive).** `signals fetch --from` and `enrich ingest` now also accept a
+  `*.jsonl` spool file (one JSON row per line) or a directory of `*.jsonl` /
+  `*.json` spool files — the Phase-2 webhook landing-zone format
+  (docs/signal-spool-format.md) — and `market observe --from` accepts a
+  `*.jsonl` file / directory of observation-set envelopes, each validated and
+  appended through the same gates as the single-file path. Existing `.json` /
+  `.csv` inputs parse exactly as before. Shared reader: `src/spoolFiles.ts`
+  (the `file` signal-source connector now delegates to it, error text
+  unchanged).
+- **Machine-readable agent contract: `capabilities`, `robot-docs`, and
+  `--help --json`.** `capabilities` prints the CLI contract as JSON: the
+  command inventory with read-only vs write-shaped access derived from the
+  help table's lifecycle phases (never a hand-maintained parallel list), the
+  documented exit-code contract, safety defaults, and the MCP entrypoint.
+  `<command> --help --json` (and `help <command> --json`) prints the same
+  per-command help as JSON — plain `--help` output is unchanged except that
+  `audit --help` now documents the pre-existing `--input <path>` flag.
+  Unknown commands invoked with `--json` return a structured
+  `{ ok: false, error: { code: "UNKNOWN_COMMAND", hints: [did-you-mean] } }`
+  envelope on stdout (exit 1) instead of the full-usage text wall.
+  `robot-docs` prints the packaged agent guide (skills/fullstackgtm/SKILL.md,
+  already shipped in the npm tarball) — one maintained guide, not a third
+  parallel one.
+- **MCP `fullstackgtm_capabilities` tool.** The MCP server's tools are now
+  declared in a single registration table and registered in a loop; the new
+  tool reports the inventory (with per-tool `writesCrm` flags — only
+  `fullstackgtm_apply` can reach a CRM) from that same table, so the
+  advertised list cannot drift from what is actually registered. The existing
+  tools' behavior is unchanged.
+- **`--input` snapshot files are validated.** `--input` now checks the file
+  parses to the canonical snapshot shape (the JSON `snapshot --out` writes)
+  and fails with a field-level error naming what's missing, instead of a
+  blind cast that surfaced as a crash deep in a rule — or an empty "clean"
+  audit.
+
+### Fixed
+
+- **`bulk-update` restored to the help front door.** The grouped short-usage
+  map listed the verb in its Remediate group but silently skipped rendering
+  it (no help-table entry), and `help bulk-update` dead-ended on the short
+  map. It now has a proper entry and appears in the derived `capabilities`
+  inventory.
+
+### Changed
+
+- **Internal: `src/cli.ts` (6,003 lines) split into per-verb modules under
+  `src/cli/`** (help, audit, fix, call, market, enrich, signals, draft, tam,
+  icp, init, schedule, plans, auth, shared). No behavior change: `dist/bin.js`
+  stays the entry, arg parsing / help text / exit codes are unchanged, and
+  `cli.ts` still exports `runCli`, `doctorReport`, `assertSecureBrokerUrl`.
+
+## [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
 

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
@@ -243,15 +254,15 @@ Everything the CLI produces is accurate the moment it runs and silently stale af
 fullstackgtm schedule add "enrich refresh --source apollo --save" --cron "0 6 * * 1" --label weekly-apollo
 fullstackgtm schedule add "audit --provider hubspot --save" --cron "0 2 * * *"   # nightly drift baseline
 fullstackgtm schedule list                       # declarative entries; nothing runs yet
-fullstackgtm schedule install                    # materialize enabled entries into a managed crontab block
+fullstackgtm schedule install                    # materialize enabled entries into the system timer (launchd on macOS, crontab elsewhere)
 fullstackgtm schedule run <id>                   # execute now; same run record a cron firing produces
 fullstackgtm schedule status --runs 5            # last runs, exit codes, artifacts, next + missed firings
 fullstackgtm schedule uninstall                  # remove the managed block, touch nothing else
 ```
 
-**Scheduling never auto-approves.** Schedulable commands are read/plan-side only — `audit`, `snapshot`, `enrich append|refresh`, `market capture|refresh`, `signals fetch`, `icp judge`, `icp eval`, `draft`, `suggest`, `report`, `doctor` — so unattended runs accumulate *proposals* (plans in the queue, run records, reports), never CRM writes. `apply` is schedulable only as `apply --plan-id <id>`, and every firing re-checks the plan's status is approved: an unapproved plan records a `plan_not_approved` no-op run instead of executing, and no flag relaxes this. Arbitrary shell is not schedulable — an entry's argv must resolve to a known fullstackgtm command (validated at `add` time and re-checked at run time), and the crontab line you audit is always `fullstackgtm schedule run <id>` and nothing else.
+**Scheduling never auto-approves.** Schedulable commands are read/plan-side only — `audit`, `snapshot`, `enrich append|refresh`, `market capture|refresh`, `signals fetch`, `icp judge`, `icp eval`, `draft`, `suggest`, `report`, `doctor` — so unattended runs accumulate *proposals* (plans in the queue, run records, reports), never CRM writes. `apply` is schedulable only as `apply --plan-id <id>`, and every firing re-checks the plan's status is approved: an unapproved plan records a `plan_not_approved` no-op run instead of executing, and no flag relaxes this. Arbitrary shell is not schedulable — an entry's argv must resolve to a known fullstackgtm command (validated at `add` time and re-checked at run time), and the timer line you audit — crontab entry or LaunchAgent `ProgramArguments` — is always `fullstackgtm schedule run <id>` and nothing else.
 
-`install` renders enabled entries into a sentinel-delimited block (`# >>> fullstackgtm <profile> >>>` … `# <<< fullstackgtm <profile> <<<`) in your user crontab; re-install replaces the block wholesale and never touches lines outside it. Honest limitation: local cron has no catch-up — a laptop asleep at firing time means a missed run. `schedule status` surfaces missed firings by comparing expected-vs-actual run history, so the gap is at least visible. Entries are provider-agnostic; cloud providers (Modal, AWS) arrive as scaffold generators that call the same `schedule run <id>` contract, and are refused as "not yet implemented" until then.
+`install` materializes enabled entries into the system timer; `--timer` defaults by platform. On macOS it writes one LaunchAgent plist per entry (`com.fullstackgtm.<profile>.<id>` in `~/Library/LaunchAgents`, loaded via `launchctl bootstrap`) — macOS gates `crontab` writes behind Full Disk Access, a permission no program can request, while LaunchAgents need none; launchd also coalesces firings missed during sleep into one run on wake. Re-install replaces the profile's plist fleet wholesale and never touches foreign plists. Elsewhere (or with `--timer crontab`) it renders a sentinel-delimited block (`# >>> fullstackgtm <profile> >>>` … `# <<< fullstackgtm <profile> <<<`) in your user crontab; re-install replaces the block wholesale and never touches lines outside it. Honest limitation: cron has no catch-up — a laptop asleep at firing time means a missed run. `schedule status` surfaces missed firings by comparing expected-vs-actual run history, so the gap is at least visible. Entries are provider-agnostic; cloud providers (Modal, AWS) arrive as scaffold generators that call the same `schedule run <id>` contract, and are refused as "not yet implemented" until then.
 
 ### Working across organizations
 
@@ -270,6 +281,17 @@ Set `FULLSTACKGTM_PROFILE=acme` to pin a shell (or agent sandbox) to one client.
 Every command is designed to compose in an agent loop — deterministic output, machine-readable everywhere, meaningful exit codes:
 
 ```bash
+# Discover the machine-readable contract: every command, read-only vs
+# write-shaped access, exit codes, safety defaults (derived from the same
+# help table humans read, so it can't drift)
+fullstackgtm capabilities --json
+
+# Per-command help as JSON; plain --help stays human-shaped
+fullstackgtm audit --help --json
+
+# Print the shipped agent operating guide (the same SKILL.md `npx skills add` installs)
+fullstackgtm robot-docs
+
 # Discover what the auditor checks
 fullstackgtm rules --json
 
@@ -285,11 +307,12 @@ fullstackgtm audit --provider hubspot --fail-on warning
 fullstackgtm diff --before old.json --after new.json --fail-on-new-findings
 ```
 
+- Terminal polish never leaks into machine output: color, spinners, progress bars, and sparklines render **only on an interactive TTY** (stderr for anything animated). Piped, redirected, `--json`, CI, and `NO_COLOR` output carries **zero ANSI bytes** — enforced by tests and a CI contract check — so transcripts and pipes see the same plain text they always did (`FORCE_COLOR=1` opts back in).
 - Finding and operation ids are **stable hashes** of rule + record, so two runs over the same data produce identical ids — agents can diff plans, track findings across runs, and approve operations by id without re-parsing.
 - `--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.
 
@@ -477,14 +500,14 @@ The MCP entrypoint needs the optional peer dependencies `@modelcontextprotocol/s
 npm install fullstackgtm @modelcontextprotocol/sdk zod
 HUBSPOT_ACCESS_TOKEN=pat-... npx fullstackgtm-mcp
 
-# Zero-install
-npx -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+# Zero-install (the fullstackgtm-mcp wrapper package bundles the MCP peers)
+npx -y fullstackgtm-mcp
 ```
 
 Add it to Claude Code in one command:
 
 ```bash
-claude mcp add fullstackgtm -e HUBSPOT_ACCESS_TOKEN=pat-... -- npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+claude mcp add fullstackgtm -e HUBSPOT_ACCESS_TOKEN=pat-... -- npx -y fullstackgtm-mcp
 ```
 
 Or configure any MCP client (Cursor, Claude Desktop, …) with:
@@ -494,7 +517,7 @@ Or configure any MCP client (Cursor, Claude Desktop, …) with:
   "mcpServers": {
     "fullstackgtm": {
       "command": "npx",
-      "args": ["-y", "-p", "fullstackgtm", "-p", "@modelcontextprotocol/sdk", "-p", "zod", "fullstackgtm-mcp"],
+      "args": ["-y", "fullstackgtm-mcp"],
       "env": { "HUBSPOT_ACCESS_TOKEN": "pat-..." }
     }
   }

package/dist/audit.d.ts

@@ -3,5 +3,7 @@ export declare function defaultPolicy(today?: string): GtmPolicy;
 /**
  * Run every rule over the snapshot and collect the results into a single
  * dry-run patch plan. Pass custom rules to extend or replace the built-ins.
+ * `onRule` reports per-rule progress (presentation only — a throwing callback
+ * never fails the audit).
  */
-export declare function auditSnapshot(snapshot: CanonicalGtmSnapshot, policy?: GtmPolicy, rules?: GtmAuditRule[]): PatchPlan;
+export declare function auditSnapshot(snapshot: CanonicalGtmSnapshot, policy?: GtmPolicy, rules?: GtmAuditRule[], onRule?: (ruleId: string, phase: "start" | "done", findings?: number) => void): PatchPlan;

package/dist/audit.js

@@ -4,6 +4,19 @@ const DEFAULT_POLICY = {
     requireDealOwner: true,
     requireAccountForDeal: true,
 };
+/**
+ * Wall clock for the plan's stdout-bound `createdAt`, honoring the
+ * SOURCE_DATE_EPOCH reproducible-build convention (seconds since the Unix
+ * epoch). When set, `audit --demo --json` is byte-deterministic across
+ * re-runs — golden tests and CI diffs can pin the payload. Unset (normal
+ * use) it is the real clock, exactly as before.
+ */
+function nowIso() {
+    const epoch = process.env.SOURCE_DATE_EPOCH;
+    if (epoch && /^\d+$/.test(epoch))
+        return new Date(Number(epoch) * 1000).toISOString();
+    return new Date().toISOString();
+}
 export function defaultPolicy(today = new Date().toISOString().slice(0, 10)) {
     return {
         ...DEFAULT_POLICY,
@@ -13,15 +26,29 @@ export function defaultPolicy(today = new Date().toISOString().slice(0, 10)) {
 /**
  * Run every rule over the snapshot and collect the results into a single
  * dry-run patch plan. Pass custom rules to extend or replace the built-ins.
+ * `onRule` reports per-rule progress (presentation only — a throwing callback
+ * never fails the audit).
  */
-export function auditSnapshot(snapshot, policy = defaultPolicy(), rules = builtinAuditRules) {
+export function auditSnapshot(snapshot, policy = defaultPolicy(), rules = builtinAuditRules, onRule) {
     const context = { snapshot, policy, index: buildSnapshotIndex(snapshot) };
     const findings = [];
     const operations = [];
     for (const rule of rules) {
+        try {
+            onRule?.(rule.id, "start");
+        }
+        catch {
+            // progress is presentation-only
+        }
         const result = rule.evaluate(context);
         findings.push(...result.findings);
         operations.push(...result.operations);
+        try {
+            onRule?.(rule.id, "done", result.findings.length);
+        }
+        catch {
+            // progress is presentation-only
+        }
     }
     const evidence = buildEvidence(snapshot, findings, policy.today);
     const pipelineFindings = buildPipelineFindings(findings, operations, evidence, policy.today);
@@ -29,7 +56,7 @@ export function auditSnapshot(snapshot, policy = defaultPolicy(), rules = builti
     return {
         id: `patch_plan_${stableHash(`${snapshot.provider}:${snapshot.generatedAt}:${findings.length}:${operations.length}`)}`,
         title: "GTM hygiene audit patch plan",
-        createdAt: new Date().toISOString(),
+        createdAt: nowIso(),
         status: operations.length > 0 ? "needs_approval" : "draft",
         dryRun: true,
         summary: `${findings.length} findings and ${operations.length} proposed dry-run operations.`,

package/dist/cli/audit.d.ts

@@ -0,0 +1,15 @@
+export declare function snapshotCommand(args: string[]): Promise<void>;
+export declare function audit(args: string[]): Promise<void>;
+/**
+ * Roll up the active profile's health timeline (accrued by `audit --save`):
+ * current deterministic score, change since the last audit, and per-rule
+ * deltas. Read-only — it only reads `health.jsonl`, never re-audits.
+ */
+export declare function healthCommand(args: string[]): void;
+/**
+ * Render an audit as a client-facing deliverable. Same sources and audit
+ * options as `audit`; `--plan` instead renders an existing plan JSON without
+ * re-fetching (useful for a plan produced earlier or by another machine).
+ */
+export declare function reportCommand(args: string[]): Promise<void>;
+export declare function rulesCommand(args: string[]): Promise<void>;