fullstackgtm 0.44.0 → 0.46.0

package/CHANGELOG.md

@@ -3,10 +3,302 @@
 All notable changes to the `fullstackgtm` package are documented here.
 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).
+The path to 1.0 is planned in the roadmap doc in the repository.
 
 ## [Unreleased]
 
+## [0.46.0] — 2026-07-06
+
+### Fixed — launch hardening
+
+- **`fullstackgtm-mcp --help`/`--version` now work without optional peers.**
+  The MCP entrypoint parsed argv before importing `@modelcontextprotocol/sdk`
+  and `zod`, so on a clean install `fullstackgtm-mcp --help` exited 1. It now
+  prints usage (and the `npx -y -p fullstackgtm -p @modelcontextprotocol/sdk
+  -p zod fullstackgtm-mcp` invocation) and exits 0.
+- **Packaging hygiene.** Narrowed `files` so internal planning docs
+  (`dx-punch-list`, `perf-notes`, `roadmap-to-1.0`) no longer ship in the npm
+  tarball; strengthened `prepublishOnly` to also run `npm pack --dry-run` and
+  smoke both bin `--help` paths.
+- **Doc accuracy.** README Stripe restricted-key guidance now includes
+  Invoices:Read (required by `backfill stripe`); schedule allowlist lists
+  `enrich acquire --save`; benchmark headline points to the leaderboard
+  caveats; `llms.txt` clarifies Stripe is read-only and fixes broken public
+  mirror links; CHANGELOG clarifies unmatched Stripe customers get a proposed,
+  approval-gated account-create (not silent auto-create).
+- **Public-surface scrub.** Replaced realistic fake LinkedIn prospect fixtures
+  with clearly-synthetic example identities and removed private-context
+  wording from shipped source/docs.
+
+### Added
+
+- **Hosted first-party CRM OAuth for the CLI.** `fullstackgtm login hubspot` and
+  `fullstackgtm login salesforce` now default to hosted browser OAuth (explicit
+  `--hosted`, `--via`/`FULLSTACKGTM_HOSTED_URL` override), storing the same local
+  broker credential used by team pairing while provider tokens are minted
+  server-side. BYO app/token paths remain as advanced fallbacks, secrets still
+  never travel via argv, and first-party app secrets never ship in the npm
+  package. Non-TTY missing-BYO-flag errors print a deterministic hosted-login
+  next command.
+
+- **Chunked LLM insight extraction (`extractInsightsChunked`) — the TamTone
+  "langextract" method.** Transcripts are never sent whole: they are chopped
+  into ~1,500-char speaker-turn-respecting chunks (the tested quality lever —
+  small chunks yielded ~95% more grounded signals than large ones) and each
+  chunk gets its own focused few-shot extraction call. Per-chunk results pass
+  the SAME verbatim-evidence and next-step-grounding gates as before (checked
+  against the chunk they came from — a quote from another chunk is treated as
+  a hallucination), then a quality gate
+  (0.25·length + 0.40·specificity + 0.35·confidence, reject < 0.15) filters
+  filler before per-call dedupe (richer statement wins) and ranking.
+  `call parse --llm` now uses this pipeline; single-shot remains for
+  one-chunk transcripts. Bounded: ≤80 chunks/call, 4 concurrent, a failed
+  chunk is skipped (all-failed throws).
+
+- **`backfill runs` — replay local execution history to the paired hosted
+  app.** An engagement that started CLI-only gets its full trail on pairing:
+  every stored plan's apply runs (with per-op result counts and ORIGINAL
+  timestamps) and the `health.jsonl` hygiene timeline (seeding the hosted
+  health trend). Idempotent by construction — deterministic per-run
+  `clientRunId`s and server-side timestamp dedupe make re-running safe.
+  `--dry-run` counts without sending. Privacy unchanged: only what live
+  reporting sends leaves the machine (statuses, counts, timestamps,
+  scores — never CRM field values). Live run reports also carry a stable
+  `clientRunId` now, so retried reports never duplicate.
+
+- **`backfill stripe` — paid Stripe invoices become closed-won CRM deals,
+  through the normal governed flow.** For a business whose revenue source of
+  truth is Stripe, the CRM can now be retroactively made honest: one
+  closed-won deal per paid invoice (amount = invoice total, close date = paid
+  date, associated to the customer's company), matched to CRM accounts by
+  billing-email domain first, then exact name. Unmatched customers are either
+  report-only (when they lack a usable name/domain, or with `--skip-unmatched`)
+  or an explicit proposed ACCOUNT create in the same `needs_approval` plan. The
+  command only ever proposes: `--save` persists the plan and writes happen
+  through `plans approve` → `apply`, where the connector re-resolves each
+  invoice id and creates only on a confirmed miss — re-running never
+  double-creates. Proposed account creates are one op per customer, use the
+  billing-email domain unless freemail, and stay approval-gated like every
+  other write.
+- **HubSpot deal creation in `create_record`.** `CreateRecordPayload` gains
+  `dealStage: "closed_won"` (a provider-neutral sentinel resolved to the
+  target pipeline's real closed-won stage id from pipeline metadata — never
+  substring guessing) and `dealPipeline` (id or label; default pipeline when
+  absent). The dedupe key is a custom deal property (default
+  `stripe_invoice_id`), ensured on demand; if it can't be ensured the create
+  is skipped rather than performed without its dedupe key. Salesforce deal
+  creation stays explicitly skipped for now.
+- **`fetchStripePaidInvoices`** on the Stripe connector: paginated
+  `status=paid` invoice reads with `created[gte]` incremental support,
+  cents→major conversion, and paid-date extraction.
+- **Node-free health scoring (`src/healthScore.ts`).** `computeHealth` /
+  `summarizeHealth` / `healthToMarkdown` split out of `health.ts` (which keeps
+  the fs-backed profile timeline and re-exports everything) so V8 runtimes —
+  the hosted app's Convex functions — can score CRM hygiene with the exact
+  same deterministic curve the CLI uses.
+
+### Changed
+
+- **CLI startup is ~20–30% faster (p50), with zero output changes.** The
+  dispatcher now loads verb modules lazily instead of compiling the full
+  78-module graph on every invocation, `node:http` (which transitively
+  compiles node's bundled undici on Node 22) is deferred to the OAuth
+  loopback login that actually starts a server, and the CRM connector /
+  demo-data modules load only when that data source is selected. Measured
+  p50 over interleaved A/B runs: `--version` −31%, `capabilities --json`
+  −30%, `audit --demo --json` −23%. Every output is byte-identical to the
+  previous build (verified against 57 golden outputs across help, audit,
+  doctor, rules, dedupe, resolve, snapshot, and error paths) and the public
+  import surface of `cli.ts` is unchanged. Profiling method, opportunity
+  matrix, and honest non-wins are documented in
+  [docs/perf-notes.md](./docs/perf-notes.md).
+
+## [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

package/INSTALL_FOR_AGENTS.md

@@ -45,13 +45,15 @@ Credential resolution ladder, first match wins:
 
 1. `--token-env <NAME>` — explicit env var for one invocation
 2. Ambient env: `HUBSPOT_ACCESS_TOKEN`, or `SALESFORCE_ACCESS_TOKEN` + `SALESFORCE_INSTANCE_URL`, or `STRIPE_SECRET_KEY`
-3. Stored login: `fullstackgtm login <provider>` (interactive; a human runs this once)
-4. Broker pairing: `fullstackgtm login --via <hosted url>` (a human approves the pairing code)
+3. BYO direct login: advanced token/OAuth paths stored locally; these override hosted
+4. Hosted OAuth / broker: `fullstackgtm login hubspot` or `fullstackgtm login salesforce` (default browser OAuth; stores a broker credential and mints provider tokens server-side) or `login --via <hosted url>`
 
-In an agent sandbox, prefer rung 1 or 2. Never echo tokens into argv —
-`login` reads secrets from stdin only. Set `FSGTM_NO_BROWSER=1` in headless
+In an agent sandbox, prefer rung 1 or 2. If a human is at a browser, the next
+command is usually `fullstackgtm login hubspot --hosted` or
+`fullstackgtm login salesforce --hosted`. Never echo tokens into argv — BYO
+secret paths read from stdin only. Set `FSGTM_NO_BROWSER=1` in headless
 environments — login flows then print verification URLs instead of opening
-the OS browser.
+the OS browser. First-party app secrets never ship in the npm package.
 
 LLM calls (`call parse`, `call score`, `market classify`): set
 `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in the environment, or have the human
@@ -77,11 +79,11 @@ count and provider spend per day and per month. It still flows through
 dry-run → approve → apply and never auto-writes — expect it to refuse rather
 than silently exceed the meter.
 
-Provider prerequisites (what the human must create, and which scopes) are in
-the README's **"Connect your CRM"** section: HubSpot needs a private app with
-four `crm.objects.*.read` scopes (plus write scopes only for `apply`);
-Salesforce needs an admin-created Connected App with device flow enabled;
-Stripe works with a restricted key (Customers + Subscriptions read).
+Provider prerequisites for BYO fallback (what the human must create, and which
+scopes) are in the README's **"Connect your CRM"** section: HubSpot private app
+or BYO OAuth app scopes, Salesforce admin-created Connected App for device
+flow, and Stripe restricted key (Customers + Subscriptions read). Hosted
+HubSpot/Salesforce OAuth is the default when available.
 
 ```bash
 HUBSPOT_ACCESS_TOKEN=$TOKEN fullstackgtm audit --provider hubspot --json --out plan.json
@@ -140,6 +142,6 @@ stored captures before anything is appended).
 | Symptom | Fix |
 | --- | --- |
 | `fullstackgtm: command not found` | Re-run with `npx fullstackgtm`, or check global npm bin is on PATH |
-| `No HubSpot credentials` (exit 1) | Set `HUBSPOT_ACCESS_TOKEN` or have a human run `fullstackgtm login hubspot` |
+| `No HubSpot credentials` (exit 1) | Set `HUBSPOT_ACCESS_TOKEN` or have a human run `fullstackgtm login hubspot --hosted` |
 | MCP server prints peer-dependency help | Install `@modelcontextprotocol/sdk` and `zod` (see step 6) |
 | Need machine state for orchestration | `fullstackgtm doctor --json` |

package/README.md

@@ -8,7 +8,7 @@ Think `terraform plan` for your CRM: agents and scripts may *read* everything, b
 
 Licensed under [Apache-2.0](./LICENSE). The boundary is deliberate and stable: the framework, CLI, and MCP server are open source; the hosted Full Stack GTM application (dashboard, sync backend, broker service, team workflows) is a separate, proprietary product built on top of this package. Features never move from open to closed. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how development and mirroring work.
 
-**Status: beta (0.x).** The surfaces in [docs/api.md](./docs/api.md) — the canonical model, rule interface, plan/apply contract, connector contract, merge/diff, config, CLI, and MCP tools — are settling but may still break in minor releases until 1.0; the path there is [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md). The safety invariants (read-only audits, approval-gated writes, placeholder refusal) are not beta and do not change. Connectors: HubSpot (read/write), Salesforce (read/write), Stripe (read-only billing).
+**Status: beta (0.x).** The surfaces in [docs/api.md](./docs/api.md) — the canonical model, rule interface, plan/apply contract, connector contract, merge/diff, config, CLI, and MCP tools — are settling but may still break in minor releases until 1.0. The safety invariants (read-only audits, approval-gated writes, placeholder refusal) are not beta and do not change. Connectors: HubSpot (read/write), Salesforce (read/write), Stripe (read-only billing).
 
 ## Install
 
@@ -136,8 +136,11 @@ fullstackgtm dedupe account --key domain --keep richest --save   # one merge_rec
 fullstackgtm reassign --from 411 --to 902 --except-deal-stage closing --save   # ownership handoff playbook
 fullstackgtm reassign --assign-unowned --to 902 --save          # claim every ownerless record for an owner
 fullstackgtm fix --rule missing-deal-owner --provider hubspot --yes  # audit one rule → suggest → approve → apply, one command
+fullstackgtm backfill stripe --save     # paid Stripe invoices → proposed closed-won deals, deduped by invoice id
 ```
 
+`backfill stripe` makes the CRM honest when Stripe is the revenue source of truth: one closed-won deal per paid invoice (amount = invoice total, close date = paid date, company association by billing-email domain). A customer the CRM doesn't know gets a proposed account create in the same approval-gated plan (freemail billing domains are never used as a company domain; `--skip-unmatched` keeps them report-only), and apply re-resolves each invoice id so re-running never double-creates.
+
 `bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `!~` not-substring, `:empty`/`:notempty`, type-aware comparisons `<` `>` `<=` `>=` where `today` resolves to the policy date — e.g. `closeDate<today` — and date/numeric fields coerce by value form, `|` any-of, relational pseudo-fields like `account.domain` or `openDealStages`) into a dry-run patch plan — and **the full filter is re-verified per record at apply time**, with mid-apply rechecks, so a record that stopped matching between audit and apply is skipped, not clobbered. For date/count hygiene (past close dates, stale deals, missing accounts, duplicates), prefer the rule-backed `fix --rule <id>` — the rule encodes the open-deal + date logic deterministically; use `bulk-update` only when no rule covers the task. Equality filters double as preconditions; `--require` adds explicit ones; `--guard` asserts cross-record conditions; `--max-operations` caps blast radius. `--set field=from:<sourceField>` derives values per record; `--create-task <text>` is the third change mode, emitting approval-gated `create_task` operations instead of field writes; `--archive` refuses records whose identity key (account domain, contact email) is shared with another record — that's a duplicate, and duplicates are merged with `dedupe`, not archived around (`--force-archive-duplicates` overrides that refusal explicitly).
 
 `dedupe` finds duplicate groups by normalized identity key and emits one `merge_records` operation per group with a deterministic survivor (`richest` = most populated fields, ties to lowest id; `oldest`). Merges stay irreversible-and-therefore-low-confidence-capped on approval, exactly like merge suggestions from the audit. `reassign` is the ownership-handoff playbook: one plan per object type, extra scoping account-lifted to deals and contacts, and `--except-deal-stage` excludes both deals in that stage and every record whose account has an open deal in it. `fix` is the one-shot composite for a single rule: audit → save → suggest → approve suggestion-backed operations at the confidence bar → with `--yes`, apply and print the stage-by-stage summary; without it, stop after approval and print the apply command.
@@ -254,15 +257,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`, `enrich acquire --save`, `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
 
@@ -281,6 +284,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
 
@@ -296,11 +310,14 @@ 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,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).
+"Built for agents" is measured, not asserted: a 1,904-run benchmark (17 CRM-operations scenarios × 3 tool-surface arms × up to 4 trials, across ten models from six vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface matching or beating raw CRM-API access on completion-under-policy for every model tested — strictly better in nine of ten — and the effect is vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+
+Caveat: the leaderboard documents the Opus reduced protocol and mixed-version Informed arms; treat the headline as a pointer to those exact RESULTS.md conditions.
 
 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.
 
@@ -309,9 +326,9 @@ The design is **deterministic apply, governed suggest**: the parts that touch yo
 Credential resolution is a ladder — the first rung that yields a token wins:
 
 1. **`--token-env <NAME>`** — explicit env var for one invocation (agent sandboxes, scripts)
-2. **`HUBSPOT_ACCESS_TOKEN`** — ambient env (CI)
-3. **Stored login** — `fullstackgtm login hubspot`, kept in `~/.fullstackgtm/credentials.json` (0600; override location with `FSGTM_HOME`)
-4. **Broker pairing** — `fullstackgtm login --via <hosted url>`: the team's deployment holds the CRM credentials; the CLI holds only a revocable pairing token
+2. **`HUBSPOT_ACCESS_TOKEN` / Salesforce env** — ambient env (CI)
+3. **BYO direct login** — advanced token/OAuth paths stored in `~/.fullstackgtm/credentials.json` (0600; override location with `FSGTM_HOME`); these override hosted
+4. **Hosted OAuth / broker** — `fullstackgtm login hubspot` or `fullstackgtm login salesforce` opens hosted browser OAuth by default, stores only a broker credential locally, and mints provider tokens server-side
 
 ### Teams: auth once, point every CLI at the stored sync credentials
 
@@ -325,22 +342,26 @@ An admin connects HubSpot **once** in the hosted dashboard (the org's OAuth toke
 
 **Run observability (paired CLIs).** Once paired, each command best-effort reports a run record — command, status (`success`/`partial`/`error`), duration, headline counts (e.g. ops emitted, leads created, est. cost), and structured events (plan saved, meter charged) — to the deployment's **run timeline** in the dashboard. It's opt-in by pairing (an unpaired CLI sends nothing), a 4-second-capped POST that swallows every error, and never changes the command's exit code. Setup/inspection verbs (`login`, `doctor`, `help`, `--version`) are skipped.
 
-### Individuals: no deployment needed
+### Individuals: hosted OAuth by default, BYO still available
 
 ```bash
-# HubSpot, zero web flow: paste a private app token once (validated, then stored)
+# Default: hosted first-party OAuth. No provider app or provider secret in the npm package.
 fullstackgtm login hubspot
+fullstackgtm login salesforce
+# optional: point at a self-hosted/team deployment
+fullstackgtm login hubspot --hosted --via https://gtm.yourco.com
+
+# Advanced HubSpot private app token (validated, then stored; token on stdin).
+# Note: hosted HubSpot OAuth covers reads and object writes but cannot create
+# tasks (HubSpot exposes no tasks scope to public apps) — use a private-app
+# token if your workflow relies on `create_task` proposals.
+echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot --private-token
 
-# HubSpot, bring-your-own-app OAuth. The browser is used exactly once — the
-# consent grant — captured on a 127.0.0.1 loopback (RFC 8252); the CLI
-# exchanges the code itself and refreshes silently from then on. The client
-# secret is read from stdin or an interactive prompt — never as a flag.
+# Advanced HubSpot BYO-app OAuth. Client secret is read from stdin/prompt — never a flag.
 echo "$CLIENT_SECRET" | fullstackgtm login hubspot --oauth --client-id <id>
 #   (register http://localhost:8763/callback as a redirect URL on your app)
 
-# Salesforce: native device flow — confirm a code on any device, no localhost
-# server, no client secret, silent refresh. Needs a Connected App consumer key
-# with device flow enabled (see "Connect your CRM" below).
+# Advanced Salesforce BYO Connected App device flow.
 fullstackgtm login salesforce --device --client-id <consumer key>
 # ...or a session token directly (token on stdin, never as a flag):
 echo "$SF_SESSION_TOKEN" | fullstackgtm login salesforce --instance-url https://yourorg.my.salesforce.com
@@ -348,7 +369,7 @@ echo "$SF_SESSION_TOKEN" | fullstackgtm login salesforce --instance-url https://
 fullstackgtm logout hubspot   # or: salesforce | broker
 ```
 
-A direct `login hubspot` always wins over a broker pairing, so an operator can override the team default. HubSpot does not support the device-authorization grant or secretless public clients, which is why the bring-your-own-app OAuth path requires client credentials; they are stored locally for silent refresh, the same model as `gcloud` and `aws` CLI profiles.
+BYO direct credentials always win over a hosted broker pairing, so an operator can override the team default. First-party app secrets never ship in the npm package; hosted login stores a local broker token and mints provider tokens server-side. HubSpot does not support the device-authorization grant or secretless public clients, which is why the bring-your-own-app OAuth path requires client credentials; they are stored locally for silent refresh, the same model as `gcloud` and `aws` CLI profiles.
 
 ## Connect your CRM
 
@@ -377,7 +398,7 @@ Connectors differ in what the provider's API allows — stated up front so nothi
    - `crm.objects.contacts.read`
    - `crm.objects.deals.read`
 3. If you plan to **apply** approved operations (not just audit), also grant write scopes for the objects you'll let it touch: `crm.objects.deals.write` (covers `deal.next_step` and other deal fields), plus `crm.objects.contacts.write` / `crm.objects.companies.write` for contact/company patches, and the **Tasks** write scope for `create_task` operations (search "tasks" in the scope picker; naming varies by portal).
-4. Create the app, copy the token (`pat-...`), then: `echo "$TOKEN" | fullstackgtm login hubspot`.
+4. Create the app, copy the token (`pat-...`), then: `echo "$TOKEN" | fullstackgtm login hubspot --private-token`.
 
 If a scope is missing you'll see a `403` mid-run whose body names the exact missing scope (`requiredGranularScopes`) — add it to the private app and re-run. Note that `login` only validates the token itself; it can't tell whether every scope you'll need is granted.
 
@@ -406,7 +427,7 @@ This is a **short-lived session token with no refresh** — ideal for a one-off
 
 ### Stripe: a restricted key is enough (read-only connector)
 
-The Stripe connector only reads customers and subscriptions, and `apply` is read-only by construction. Create a **restricted key** with just **Customers: Read** and **Subscriptions: Read** (Developers → API keys → Create restricted key) instead of pasting a full-access secret key: `echo "$KEY" | fullstackgtm login stripe`.
+The Stripe connector reads customers, subscriptions, and paid invoices (`backfill stripe` calls `/v1/invoices`), and `apply` is read-only by construction. Create a **restricted key** with just **Customers: Read**, **Subscriptions: Read**, and **Invoices: Read** (Developers → API keys → Create restricted key) instead of pasting a full-access secret key: `echo "$KEY" | fullstackgtm login stripe`.
 
 ## Concepts
 
@@ -488,14 +509,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:
@@ -505,7 +526,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.`,