fullstackgtm 0.24.0 → 0.25.1

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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).
 
+## [0.25.1] — 2026-06-12
+
+Docs-sync release — no code changes.
+
+### Fixed
+
+- README, INSTALL_FOR_AGENTS.md, the agent skill, and docs/api.md corrected
+  against the shipped surface: the MCP tool list now enumerates all 8 tools
+  (read-only vs gated), the builtin rule count is 12, docs/api.md gains a
+  Schedule section and the `schedule` command in its CLI list, the README
+  cites the 612-run CRM-ops benchmark and the `diff --fail-on-new-findings`
+  CI gate, the bulk-update section covers `!~` / `--create-task` /
+  `--force-archive-duplicates`, and the skill's verb map completes the
+  `schedule`, `market`, and `plans` rows and adds `report`.
+- The 0.23.0 entry below is amended retroactively: `dedupe`, `reassign`,
+  `fix`, and `--set <field>=from:<sourceField>` shipped in 0.23.0 without a
+  changelog record.
+
+## [0.25.0] — 2026-06-12
+
+### Added
+
+- **Agent skill distribution** — `npx skills add fullstackgtm/core` installs
+  [skills/fullstackgtm/SKILL.md](./skills/fullstackgtm/SKILL.md) into any
+  skills-compatible agent (Claude Code, Cursor, Codex, …): a compact operating
+  guide covering the governed audit → suggest → approve → apply loop, the
+  non-negotiable safety invariants, the verb map, and the credential ladder.
+  Documentation only — no runtime surface changes.
+
 ## [0.24.0] — 2026-06-12
 
 ### Added
@@ -125,6 +154,29 @@ everything that shipped 0.19–0.23. (No code changes.)
   - Every `enrich` subcommand catches `--help`/`-h` before config load,
     credential resolution, or any network call. No scheduling/cron logic —
     that is the horizontal schedule layer's job (docs/schedule.md).
+- **Four task-shaped verbs** (entry added retroactively — these shipped in
+  0.23.0 without a changelog record). The 612-run benchmark's gated-agent
+  failures clustered into four missing verbs; all four compile to plans
+  through the existing plan → approve → apply gate — nothing writes directly.
+  - `dedupe <account|contact|deal> --key <domain|email|name>` — duplicate
+    groups by normalized identity key, one `merge_records` operation per
+    group with a deterministic survivor (`richest` = most populated data
+    fields, ties to lowest id; `oldest` = lowest id). High risk, approval
+    required; merges are irreversible on apply.
+  - `reassign --from <ownerId> --to <ownerId>` — the ownership-handoff
+    playbook: one bulk-update-style plan per object type, extra `--where`
+    scoping account-lifted for deals/contacts, `--except-deal-stage`
+    excluding the stage AND records whose account has an open deal in it —
+    re-verified per record at apply time.
+  - `fix --rule <id>` — one-shot composite: audit one rule → save → suggest
+    → approve only suggestion-backed values at the confidence bar → apply
+    (`--yes` required), with a stage-by-stage summary.
+  - `bulk-update --set <field>=from:<sourceField>` — per-record derived
+    values resolved from the filter view (relational sources like
+    `account.ownerId` included); empty-source records are skipped and
+    counted, never guessed. Plus the `--archive` duplicate guard: archiving
+    a record that shares its identity key with another is refused and
+    pointed at `dedupe`, overridable with `--force-archive-duplicates`.
 
 ## [0.22.0] — 2026-06-12
 

package/INSTALL_FOR_AGENTS.md

@@ -3,6 +3,10 @@
 Deterministic install-and-verify steps. Every command is non-interactive, every
 check has an expected output, and nothing here writes to a CRM.
 
+If your harness supports agent skills, `npx skills add fullstackgtm/core`
+installs the compact operating guide; this document remains the deterministic
+install-and-verify path.
+
 ## 1. Install
 
 ```bash
@@ -60,6 +64,11 @@ page texts — every span is checked character-for-character against the stored
 capture, and paraphrased quotes are rejected. In non-interactive contexts the
 CLI never prompts — it fails with this guidance.
 
+Apollo enrichment (`enrich append --source apollo`) needs `APOLLO_API_KEY` in
+the environment, or have the human run `echo "$KEY" | fullstackgtm login apollo`
+once. Without it, `enrich ingest <file> --source clay` still stages push-style
+data keyless.
+
 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`);
@@ -111,8 +120,12 @@ If the working directory's project already has the peers in its node_modules,
 the server resolves them from there (peer-dependency semantics) — so this
 works from inside existing projects too.
 
-Tools exposed over stdio: `fullstackgtm_audit` (read-only),
-`fullstackgtm_rules`, `fullstackgtm_apply` (requires `approvedOperationIds`).
+Tools exposed over stdio — read-only: `fullstackgtm_audit`,
+`fullstackgtm_rules`, `fullstackgtm_suggest`, `fullstackgtm_call_parse`,
+`fullstackgtm_resolve`, `fullstackgtm_market_worksheet`. Gated:
+`fullstackgtm_apply` (requires explicit `approvedOperationIds`),
+`fullstackgtm_market_observe` (every quoted span is verified against the
+stored captures before anything is appended).
 
 ## Troubleshooting
 

package/README.md

@@ -27,7 +27,13 @@ Requires Node 20+. The core has zero runtime dependencies; only the MCP server e
 npx fullstackgtm doctor   # verify the install: node version, credentials, MCP peers, next step
 ```
 
-Installing for an AI agent? Hand it [INSTALL_FOR_AGENTS.md](./INSTALL_FOR_AGENTS.md) — a deterministic install-and-verify script with expected outputs. A documentation map lives in [llms.txt](./llms.txt).
+Installing for an AI agent? The fastest path is the agent skill:
+
+```bash
+npx skills add fullstackgtm/core   # Claude Code, Cursor, Codex, and other skills-compatible agents
+```
+
+It installs a compact operating guide ([skills/fullstackgtm/SKILL.md](./skills/fullstackgtm/SKILL.md)) — the governed loop, the safety invariants, and the verb map — so the agent reaches for plans instead of raw writes. For a deterministic install-and-verify script with expected outputs, hand it [INSTALL_FOR_AGENTS.md](./INSTALL_FOR_AGENTS.md). A documentation map lives in [llms.txt](./llms.txt).
 
 ## Five-minute loop
 
@@ -121,7 +127,7 @@ fullstackgtm reassign --from 411 --to 902 --except-deal-stage closing --save   #
 fullstackgtm fix --rule missing-deal-owner --provider hubspot --yes  # audit one rule → suggest → approve → apply, one command
 ```
 
-`bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `:empty`/`:notempty`, `|` 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. 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; `--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.
+`bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `!~` not-substring, `:empty`/`:notempty`, `|` 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. 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.
 
@@ -204,12 +210,17 @@ fullstackgtm audit --input snap.json --rules stale-deal --stale-days 45 --json
 
 # Gate a nightly CI job or agent run on hygiene: exit 2 if findings ≥ threshold
 fullstackgtm audit --provider hubspot --fail-on warning
+
+# Gate CI on hygiene drift instead: exit 2 only when a NEW (rule, record) finding appears
+fullstackgtm diff --before old.json --after new.json --fail-on-new-findings
 ```
 
 - 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 612-run benchmark (17 scenarios × 3 tool-surface arms × 4 trials, 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. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+
 ## Authentication: CLI-first, browser only at the consent moment
 
 Credential resolution is a ladder — the first rung that yields a token wins:
@@ -291,7 +302,7 @@ The Stripe connector only reads customers and subscriptions, and `apply` is read
 | Concept | What it is |
 |---|---|
 | **Canonical snapshot** | Provider-independent view of users, accounts, contacts, deals, activities. Records carry `identities` — `(provider, externalId)` claims — so the same real-world entity can be tracked across several systems. |
-| **Audit rule** | A deterministic function `(context) => { findings, operations }`. Eleven built-ins cover orphan accounts, ownerless/unlinked/amount-less deals, past close dates, stale pipeline, duplicates, and more — `fullstackgtm rules` lists them all. Write your own in ~10 lines. |
+| **Audit rule** | A deterministic function `(context) => { findings, operations }`. Twelve built-ins cover orphan accounts, ownerless/unlinked/amount-less deals, past close dates, stale pipeline, duplicates, and more — `fullstackgtm rules` lists them all. Write your own in ~10 lines. |
 | **Patch plan** | The dry-run output of an audit: findings plus typed patch operations with before/after values, reasons, risk levels, and approval flags. Always a proposal, never a mutation. |
 | **Connector** | A provider adapter: `fetchSnapshot()` for reads, optional `applyOperation()` for writes. HubSpot and Salesforce reference connectors ship in the package; connectors never drop records they can't fully resolve — the audit flags them instead. |
 | **Patch plan run** | The audit record of one apply attempt: per-operation applied/failed/skipped results. |
@@ -390,7 +401,13 @@ Or configure any MCP client (Cursor, Claude Desktop, …) with:
 }
 ```
 
-Exposes `fullstackgtm_audit` (read-only; sample, demo, file, or live provider sources with optional rule scoping), `fullstackgtm_rules` (rule discovery), and `fullstackgtm_apply` (requires explicit `approvedOperationIds`) over stdio. Tokens stored via `fullstackgtm login` are picked up automatically — the env var is only needed when no stored login exists.
+Eight tools are exposed over stdio.
+
+**Read-only:** `fullstackgtm_audit` (sample, demo, file, or live provider sources with optional rule scoping), `fullstackgtm_rules` (rule discovery), `fullstackgtm_suggest` (deterministic placeholder values with confidence + reasons), `fullstackgtm_call_parse` (transcripts → provenance-marked segments, insights, and evidence), `fullstackgtm_resolve` (the create gate: exists / ambiguous / safe_to_create), and `fullstackgtm_market_worksheet` (the classification packet for one vendor: claims, judging rules, captured page texts).
+
+**Gated:** `fullstackgtm_apply` (requires explicit `approvedOperationIds`; placeholders still need value overrides) and `fullstackgtm_market_observe` (verifies every quoted span against the stored captures before appending — nothing is stored unless the whole set passes).
+
+Tokens stored via `fullstackgtm login` are picked up automatically — the env var is only needed when no stored login exists.
 
 ## Safety model
 

package/docs/api.md

@@ -21,7 +21,7 @@ release.
 - `GtmAuditRule` — `{ id, title, description, category?, evaluate(context) }`; the public extension point.
 - `GtmRuleContext` — `{ snapshot, policy, index }` with the prebuilt O(n) `GtmSnapshotIndex`.
 - `auditSnapshot(snapshot, policy?, rules?)` → `PatchPlan`.
-- `builtinAuditRules` (11 rules) plus each rule exported individually.
+- `builtinAuditRules` (12 rules) plus each rule exported individually.
 - **Determinism guarantee**: identical inputs produce identical findings and operations with identical ids (`auditFindingId`, `patchOperationId` are stable hashes of rule + record).
 
 ## Patch plans and application
@@ -62,7 +62,9 @@ Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `p
 `bulk-update`, `dedupe`, `reassign`, `fix`,
 `market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
 `axes` / `overlay` / `scale` / `report` / `refresh`),
-`enrich` (`append` / `refresh` / `ingest` / `status`), `rules`, `profiles`, `doctor`.
+`enrich` (`append` / `refresh` / `ingest` / `status`),
+`schedule` (`add` / `list` / `remove` / `enable` / `disable` / `run` /
+`install` / `uninstall` / `status`), `rules`, `profiles`, `doctor`.
 Exit codes: `0` success · `1` error · `2` findings/regressions at the requested gate
 (`--fail-on`, `--fail-on-new-findings`). `--json` everywhere; JSON output shapes are stable.
 
@@ -115,6 +117,30 @@ dependency-free CSV intake; the Apollo client (`createApolloClient`,
 `pullApolloRecords`, 429-aware with `Retry-After`) is the first `api`-kind
 source.
 
+## Schedule
+
+The horizontal scheduler: a declarative schedule-entry store, a
+dependency-free 5-field cron parser, and the read/plan-side `SCHEDULABLE`
+allowlist. `validateSchedulableArgv` enforces the allowlist at `schedule add`
+time and re-checks it at run time (`tokenizeCommand` splits the quoted command
+string — tokenization, never shell). `apply` is schedulable only as
+`apply --plan-id <id>`, with the plan's `approved` status re-checked at every
+firing — an unapproved plan records a `plan_not_approved` no-op run
+(`ScheduleRunRecord.noopReason`) instead of executing.
+
+- Entries: `ScheduleEntry` (`ScheduleProvider` is `"local"` for now),
+  `scheduleId`, `ScheduleStore` / `createFileScheduleStore`.
+- Run history: `ScheduleRunRecord` (`ScheduleRunTrigger`: `cron` | `manual`),
+  `ScheduleRunStore` / `createFileScheduleRunStore`, with `schedulesPath` /
+  `scheduleRunsDir` for the profile-scoped file layout.
+- Cron: `parseCron` → `CronExpression`, `cronMatches`, `nextCronFiring`,
+  `expectedFirings`, `computeMissedFirings` (status and missed-firing
+  visibility — local cron has no catch-up).
+- Local provider: `schedule install` renders enabled entries into a
+  sentinel-managed crontab block — `crontabSentinels`, `renderManagedBlock`,
+  `replaceManagedBlock`, and `systemCrontabIo` behind the injectable
+  `CrontabIo` seam (tests never touch a real crontab).
+
 ## Market map
 
 Newer surface (0.16–0.23); shapes are settling toward the 1.0 contract. A live

package/docs/crm-health-lifecycle.md

@@ -78,18 +78,21 @@ values win, **merges cannot be undone**, and a record stops merging after
 250 cumulative merges. Salesforce merge is SOAP/Apex only (no REST), only
 Lead/Contact/Account/Case, max 3 records per call.
 
-**The gap:** our three duplicate rules (`duplicate-account-domain`,
-`duplicate-contact-email`, `duplicate-open-deal`) detect groups but emit
-only merge-review *tasks* — detection without remediation.
+**The gap (closed in 0.12):** our three duplicate rules
+(`duplicate-account-domain`, `duplicate-contact-email`,
+`duplicate-open-deal`) used to detect groups but emit only merge-review
+*tasks* — detection without remediation.
 
-**The plan (0.12):** a `merge_records` operation type —
+**Shipped (0.12):** a `merge_records` operation type —
 `requires_human_survivor_selection` placeholder, survivor heuristics in
 `suggest` (ordered, evidence-based: most engagements → oldest → most
 complete, each with a written reason), high risk, approval required, with
 the irreversibility called out in the plan text. The dry-run plan is the
 preview every commercial tool charges for; the pre-apply snapshot is the
 loser-record archive. HubSpot first; Salesforce merge documented as
-unsupported until an Apex path justifies itself.
+unsupported until an Apex path justifies itself. 0.23 added `dedupe` as a
+first-class verb over the same operation type (groups → one governed merge
+per group, deterministic survivor).
 
 ## D — Delete/Archive: the exit ramp
 
@@ -131,5 +134,7 @@ Lessons from auditing our own apply path:
 | 0.11.1 | Fix our own faucet: resolve-first `create:` + plan-scoped dedup, HubSpot association-aware CAS for `link_record`, domain normalization in `duplicate-account-domain`, `create_task` idempotency token |
 | 0.12 (shipped) | `merge_records` (HubSpot contacts/companies/deals) + survivor suggestions capped at low confidence; the three duplicate rules emit governed merges instead of review tasks |
 | 0.15 (shipped) | `resolve` gate (CLI/lib/MCP, gate exit codes), provenance capture (`hs_object_source*` → `RecordProvenance`) + attribution in duplicate findings, self-stamped creates |
-| 0.16 | prevention-posture checks (native duplicate rules active? unique-value properties defined?) · live targeted resolve lookups |
+| 0.16 (shipped the market map instead) | prevention-posture checks (native duplicate rules active? unique-value properties defined?) and live targeted resolve lookups were slated here but did not ship — they remain future work; 0.16 went to the market map layer |
+| 0.23 (shipped) | `dedupe <object> --key <domain\|email\|name>` — the Remediate layer as a first-class verb: duplicate groups by normalized identity key, one governed `merge_records` per group, deterministic survivor (`richest`/`oldest`) |
+| 0.24 (shipped) | schedule layer — recurring Detect: the nightly watch recipe becomes a declared cadence (`schedule add "audit --provider hubspot --save" --cron "0 2 * * *"`); read/plan-side allowlist only, scheduling never auto-approves |
 | docs | The nightly watch recipe (existing flags, documented as CRM CI) |

package/docs/roadmap-to-1.0.md

@@ -106,6 +106,33 @@ The original thesis: GTM data disagrees across systems.
 - Docs site with the operating-model registry as browsable reference.
 - Performance pass: streaming snapshots for very large orgs.
 
+## 0.10 → 0.25 — the layers, as shipped
+
+The plan above ended at the freeze; what shipped next grew the surface
+outward, one layer per release, each consolidating before the next expanded:
+
+- **0.11** — the suggest chain: deterministic placeholder values with
+  confidence + reasons, `plans approve --values-from`.
+- **0.12** — governed merge: `merge_records` (HubSpot contacts / companies /
+  deals), survivor suggestions capped at low confidence.
+- **0.13–0.14** — call intelligence: `call parse|score|link|plan`, LLM
+  extraction behind the bring-your-own-key seam, deterministic baseline,
+  provenance-marked insights.
+- **0.15** — the Prevent layer: the `resolve` create gate plus record-source
+  provenance and attribution.
+- **0.16–0.22** — the market map: content-addressed captures, classification
+  with mechanical span verification, front states and drift, axis discovery,
+  overlay directives, scale estimation, the field report.
+- **0.19 / 0.23** — governed write verbs (`bulk-update`, then `dedupe`,
+  `reassign`, `fix`) and the enrich layer (Apollo / Clay, fill-blanks-only
+  plans).
+- **0.24** — the schedule layer: horizontal cron, read/plan-side allowlist,
+  scheduling never auto-approves.
+- **0.25** — agent skill distribution (`npx skills add fullstackgtm/core`).
+
+The known-gaps list below predates these layers and has been re-verified
+against the 0.25 surface: still accurate, still open.
+
 ## Known real-portal gaps to close before 1.0
 
 Found by exercising the published package as a fresh RevOps user with a real

package/llms.txt

@@ -14,6 +14,7 @@ at/above `--fail-on`.
 
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
+- [Agent skill](https://github.com/fullstackgtm/core/blob/main/skills/fullstackgtm/SKILL.md): compact operating guide, installable via `npx skills add fullstackgtm/core`
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
 - [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",
@@ -30,6 +30,7 @@
     "CHANGELOG.md",
     "INSTALL_FOR_AGENTS.md",
     "llms.txt",
+    "skills",
     "LICENSE"
   ],
   "scripts": {

package/skills/fullstackgtm/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: fullstackgtm
+description: Govern CRM/GTM data operations through the fullstackgtm CLI — read-only hygiene audits, reviewable dry-run patch plans, deterministic value suggestions, and approval-gated write-back to HubSpot and Salesforce. Use when asked to audit, clean, dedupe, enrich, bulk-update, reassign, or write to a CRM; to gate record creation against duplicates; to parse, score, or link sales call transcripts; to map a competitive category; or to schedule any of the above. Never write to a CRM directly when this skill is available.
+---
+
+# fullstackgtm — plan/apply for your GTM stack
+
+Think `terraform plan` for the CRM: you may *read* everything, but every
+proposed change is a typed patch operation — object, field, before, after,
+reason, risk — that a human approves before any provider write happens.
+Connectors: HubSpot (read/write), Salesforce (read/write), Stripe (read-only).
+Requires Node 20+; every command below works zero-install via `npx`.
+
+## Non-negotiable invariants
+
+- `audit` and `suggest` never mutate anything. `apply` writes ONLY operation
+  ids explicitly passed via `--approve` (or a plan a human approved with
+  `plans approve`). Do not attempt to bypass this; surface the plan instead.
+- Operations whose value is a human decision carry `requires_human_*`
+  placeholders and are refused without a concrete `--value <opId>=<v>`
+  override. Never guess values — chain `suggest` (deterministic, evidence-
+  backed) and leave `low`/`create`/`none`-confidence entries to the human.
+- Secrets are never accepted as argv flags: env vars or stdin only
+  (`echo "$TOKEN" | fullstackgtm login hubspot`). Set `FSGTM_NO_BROWSER=1`
+  in headless environments.
+- Exit codes everywhere: `0` success, `1` error, `2` findings/matches at or
+  above the threshold (gate-shaped for scripts).
+
+## Verify the install, then prove the pipeline with zero credentials
+
+```bash
+npx fullstackgtm doctor --json        # node.ok: true + package.version
+npx fullstackgtm audit --demo --json  # dry-run plan over a seeded messy CRM
+```
+
+## The governed loop (the core of everything)
+
+```bash
+fullstackgtm audit --provider hubspot --save                  # read-only → saved plan id
+fullstackgtm suggest --plan-id <id> --provider hubspot --out suggestions.json
+fullstackgtm plans approve <id> --values-from suggestions.json  # high-confidence only
+fullstackgtm apply --plan-id <id> --provider hubspot          # writes ONLY approved ops
+```
+
+Credentials resolve in order: `--token-env <NAME>` → ambient env
+(`HUBSPOT_ACCESS_TOKEN`; `SALESFORCE_ACCESS_TOKEN` + `SALESFORCE_INSTANCE_URL`;
+`STRIPE_SECRET_KEY`) → stored `fullstackgtm login <provider>` → broker pairing.
+In a sandbox prefer the first two. LLM-powered verbs (`call parse`, `call
+score`, `market classify`) take `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`, or use
+their deterministic/worksheet fallbacks — the CLI never prompts when
+non-interactive. `--profile <name>` (or `FULLSTACKGTM_PROFILE`) scopes
+credentials AND stored plans per client org.
+
+## Verb map
+
+| Verb | What it does |
+| --- | --- |
+| `resolve <contact\|account\|deal>` | Create gate: exit 0 = safe to create, 2 = exists/ambiguous — never blind-create |
+| `dedupe <object> --key <domain\|email\|name>` | One merge op per duplicate group, deterministic survivor; merges are irreversible |
+| `bulk-update <object> --where … --set\|--archive\|--create-task` | Filtered dry-run plan; filter re-verified per record at apply time |
+| `reassign --from <owner> --to <owner>` | Ownership handoff plans per object type |
+| `fix --rule <id>` | audit one rule → suggest → approve at the confidence bar → apply only with `--yes` |
+| `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
+| `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
+| `market init\|capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |
+| `schedule add\|list\|remove\|enable\|disable\|run\|install\|uninstall\|status` | Horizontal cron; read/plan-side allowlist only — scheduling NEVER auto-approves |
+| `report` | Client-ready audit deliverable (markdown or self-contained HTML) |
+| `plans list\|show\|approve\|reject` / `snapshot` / `rules` / `doctor` | Plan lifecycle, raw snapshots, rule registry, machine state |
+
+All write-shaped verbs produce plans; none writes outside approve → apply.
+Add `--json` for machine-readable output on any command.
+
+## MCP server (alternative surface, same gates)
+
+```bash
+npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+```
+
+Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,
+`fullstackgtm_suggest`, `fullstackgtm_call_parse`,
+`fullstackgtm_apply` (requires `approvedOperationIds`),
+`fullstackgtm_resolve`, `fullstackgtm_market_worksheet`,
+`fullstackgtm_market_observe`.
+
+## Going deeper
+
+- [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule)
+- [INSTALL_FOR_AGENTS.md](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md) — deterministic install-and-verify with expected outputs
+- [docs/api.md](https://github.com/fullstackgtm/core/blob/main/docs/api.md) — semver-covered surfaces: canonical model, rule interface, plan/apply contract, connectors, config, CLI, MCP