fullstackgtm 0.34.0 → 0.37.0

package/dist/icp.js

@@ -0,0 +1,256 @@
+/**
+ * ICP — the Ideal Customer Profile that makes `enrich acquire` targeted instead
+ * of random. One structured artifact drives two things:
+ *   1. discovery filters — translated per provider (Explorium, pipe0/Crustdata)
+ *      so the pull only returns ICP-shaped companies + people, and
+ *   2. fit scoring — every discovered prospect is scored against the persona so
+ *      only above-threshold leads become create_record ops.
+ *
+ * Develop one via interview: an agent (Claude Code / Codex) reads INTERVIEW_SPEC,
+ * asks the questions with its AskUserQuestion tool, and writes the answers into
+ * an Icp (CLI: `icp interview` emits the spec, `icp show` renders the result).
+ *
+ * Zero runtime deps; pure functions (translation + scoring take plain data).
+ */
+export const DEFAULT_FIT_THRESHOLD = 0.5;
+const COUNTRY_NAMES = {
+    us: "United States",
+    ca: "Canada",
+    gb: "United Kingdom",
+    uk: "United Kingdom",
+};
+export function parseIcp(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`icp: not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!parsed || typeof parsed !== "object")
+        throw new Error("icp: expected a JSON object");
+    const icp = parsed;
+    if (!icp.name || typeof icp.name !== "string")
+        throw new Error('icp: missing "name"');
+    if (!icp.persona || (!icp.persona.titleKeywords?.length && !icp.persona.jobLevels?.length)) {
+        throw new Error('icp: "persona" needs at least titleKeywords or jobLevels (without them, scoring cannot rank fit)');
+    }
+    return icp;
+}
+// ---------------------------------------------------------------------------
+// Discovery-filter translation
+/** Explorium /v1/prospects filters from the ICP. */
+export function icpToExploriumFilters(icp) {
+    const f = { has_email: { value: true } };
+    if (icp.persona.jobLevels?.length)
+        f.job_level = { values: icp.persona.jobLevels };
+    if (icp.persona.departments?.length)
+        f.job_department = { values: icp.persona.departments };
+    if (icp.firmographics.employeeBands?.length)
+        f.company_size = { values: icp.firmographics.employeeBands };
+    if (icp.firmographics.geos?.length)
+        f.company_country_code = { values: icp.firmographics.geos };
+    if (icp.firmographics.naics?.length)
+        f.naics_category = { values: icp.firmographics.naics };
+    return f;
+}
+/**
+ * Crustdata / LinkedIn seniority vocab. ICP job levels are normalized lowercase;
+ * Crustdata expects these exact capitalized strings (verified: "CXO",
+ * "Vice President", "Director" appear in Crustdata's docs/examples).
+ */
+const CRUSTDATA_SENIORITY = {
+    cxo: "CXO",
+    "c-suite": "CXO",
+    c_suite: "CXO",
+    founder: "Owner",
+    owner: "Owner",
+    partner: "Partner",
+    vp: "Vice President",
+    "vice president": "Vice President",
+    head: "Director",
+    director: "Director",
+    manager: "Manager",
+    senior: "Senior",
+    entry: "Entry",
+};
+/**
+ * ICP industry keyword → LinkedIn industry names Crustdata filters on. Includes
+ * the current LinkedIn-v2 names; for software we send the cluster (dev + IT
+ * services + internet) so an OR match isn't overly narrow.
+ */
+const CRUSTDATA_INDUSTRY = {
+    software: ["Software Development", "Information Technology and Services", "Internet"],
+    saas: ["Software Development", "Information Technology and Services"],
+    "information technology & services": ["Information Technology and Services"],
+    "information technology and services": ["Information Technology and Services"],
+    internet: ["Internet"],
+    fintech: ["Financial Services"],
+    "financial services": ["Financial Services"],
+};
+/**
+ * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
+ * matches real LinkedIn title strings (case-sensitive), so keywords are Title
+ * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
+ * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
+ * live (pipe0 credits were exhausted) — validate when credits refill; fit
+ * scoring is the safety net for persona precision regardless.
+ */
+export function icpToCrustdataFilters(icp) {
+    const f = {};
+    if (icp.persona.titleKeywords?.length)
+        f.current_job_titles = icp.persona.titleKeywords.map(titleCase);
+    if (icp.firmographics.geos?.length) {
+        f.locations = icp.firmographics.geos.map((g) => COUNTRY_NAMES[g.toLowerCase()] ?? g);
+    }
+    if (icp.persona.jobLevels?.length) {
+        const include = [...new Set(icp.persona.jobLevels.map((l) => CRUSTDATA_SENIORITY[l.toLowerCase()]).filter(Boolean))];
+        if (include.length)
+            f.current_seniority_levels = { include, exclude: [] };
+    }
+    if (icp.firmographics.industries?.length) {
+        const inds = [
+            ...new Set(icp.firmographics.industries.flatMap((i) => CRUSTDATA_INDUSTRY[i.toLowerCase()] ?? [titleCase(i)])),
+        ];
+        if (inds.length)
+            f.current_employers_linkedin_industries = inds;
+    }
+    return f;
+}
+const ACRONYMS = new Set(["cro", "coo", "ceo", "cfo", "vp", "crm", "gtm", "saas"]);
+function titleCase(value) {
+    return value
+        .split(/\s+/)
+        .map((w) => (ACRONYMS.has(w.toLowerCase()) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+        .join(" ");
+}
+/**
+ * Score a prospect's PERSONA fit 0..1. Title-keyword match is the strongest
+ * signal (it's what defines the buyer); job level and department add to it.
+ * Firmographics aren't re-scored here — discovery already filtered on them.
+ */
+export function scoreProspectAgainstIcp(prospect, icp) {
+    const reasons = [];
+    const title = (prospect.jobTitle ?? "").toLowerCase();
+    const keywords = (icp.persona.titleKeywords ?? []).map((k) => k.toLowerCase());
+    const levels = (icp.persona.jobLevels ?? []).map((l) => l.toLowerCase());
+    const depts = (icp.persona.departments ?? []).map((d) => d.toLowerCase());
+    let score = 0;
+    let weightSum = 0;
+    if (keywords.length) {
+        weightSum += 0.6;
+        const hit = keywords.find((k) => title.includes(k));
+        if (hit) {
+            score += 0.6;
+            reasons.push(`title matches ICP keyword "${hit}"`);
+        }
+    }
+    if (levels.length) {
+        weightSum += 0.25;
+        const level = (prospect.jobLevel ?? "").toLowerCase();
+        if (level && levels.some((l) => level.includes(l))) {
+            score += 0.25;
+            reasons.push(`seniority "${prospect.jobLevel}" in ICP levels`);
+        }
+    }
+    if (depts.length) {
+        weightSum += 0.15;
+        const dept = (prospect.jobDepartment ?? "").toLowerCase();
+        if (dept && depts.some((d) => dept.includes(d))) {
+            score += 0.15;
+            reasons.push(`department "${prospect.jobDepartment}" in ICP`);
+        }
+    }
+    const normalized = weightSum > 0 ? score / weightSum : 0;
+    if (reasons.length === 0)
+        reasons.push("no persona signal matched the ICP");
+    return { score: Number(normalized.toFixed(3)), reasons };
+}
+export function fitThreshold(icp) {
+    return icp.scoring?.threshold ?? DEFAULT_FIT_THRESHOLD;
+}
+export const INTERVIEW_SPEC = [
+    {
+        id: "industries",
+        header: "Target market",
+        question: "What company profile are you targeting? (Drives firmographic discovery filters.)",
+        multiSelect: true,
+        options: [
+            { label: "B2B SaaS / software", value: ["software", "saas"], description: "Software & internet — classic messy-CRM, RevOps-equipped buyer." },
+            { label: "Broader tech-enabled B2B", value: ["software", "information technology & services", "financial services"], description: "Any B2B running a real sales motion on a CRM." },
+            { label: "Any B2B with a CRM", value: [], description: "Vertical-agnostic — qualify on persona, not industry." },
+        ],
+    },
+    {
+        id: "employeeBands",
+        header: "Company size",
+        question: "Company size (employee bands) that fit?",
+        multiSelect: true,
+        options: [
+            { label: "Seed–Series A (1–50)", value: ["1-10", "11-50"], description: "Early; often no dedicated RevOps yet." },
+            { label: "Series B–C (51–500)", value: ["51-200", "201-500"], description: "Sweet spot: messy CRM, RevOps exists, budget exists." },
+            { label: "Growth (501–2000)", value: ["501-1000", "1001-5000"], description: "Established RevOps, many CRM writers." },
+            { label: "Enterprise (2000+)", value: ["1001-5000", "5001-10000", "10001+"], description: "Up-market; longer cycles." },
+        ],
+    },
+    {
+        id: "titleKeywords",
+        header: "Buyer persona",
+        question: "Which buyer persona(s) should discovery target and scoring reward?",
+        multiSelect: true,
+        options: [
+            { label: "RevOps leadership", value: ["revenue operations", "revops", "head of revenue operations"], description: "VP/Head/Dir Revenue Operations." },
+            { label: "Sales/Marketing Ops", value: ["sales operations", "gtm operations", "marketing operations", "revenue ops"], description: "Hands-on the CRM daily." },
+            { label: "Exec buyers", value: ["chief revenue officer", "cro", "chief operating officer", "vp of sales"], description: "Economic sign-off." },
+            { label: "CRM/SF admins", value: ["salesforce admin", "hubspot admin", "crm manager", "revops analyst"], description: "Feel the pain, champion the fix." },
+        ],
+    },
+    {
+        id: "geos",
+        header: "Geography",
+        question: "Geography?",
+        multiSelect: true,
+        options: [
+            { label: "United States", value: ["us"], description: "US-only (best data coverage)." },
+            { label: "US + Canada", value: ["us", "ca"], description: "North America." },
+            { label: "US + UK/EU", value: ["us", "gb"], description: "English-speaking + Western Europe (mind GDPR)." },
+            { label: "Global", value: [], description: "No geo filter." },
+        ],
+    },
+];
+/** Assemble an Icp from flattened interview answers. */
+export function icpFromAnswers(name, answers) {
+    const levelsFromTitles = inferLevels(answers.titleKeywords);
+    return {
+        name,
+        firmographics: {
+            industries: dedupe(answers.industries),
+            naics: answers.industries.some((i) => /software|saas/i.test(i)) ? ["5112"] : undefined,
+            employeeBands: dedupe(answers.employeeBands),
+            geos: dedupe(answers.geos),
+        },
+        persona: {
+            jobLevels: answers.jobLevels?.length ? dedupe(answers.jobLevels) : levelsFromTitles,
+            departments: answers.departments?.length ? dedupe(answers.departments) : ["sales", "marketing", "operations"],
+            titleKeywords: dedupe(answers.titleKeywords),
+        },
+        scoring: { threshold: DEFAULT_FIT_THRESHOLD },
+    };
+}
+function inferLevels(titles) {
+    const levels = new Set();
+    for (const t of titles.map((x) => x.toLowerCase())) {
+        if (/chief|^c[a-z]o$|cro|coo/.test(t))
+            levels.add("cxo");
+        if (/vp|vice president|head of/.test(t))
+            levels.add("vp");
+        if (/director/.test(t))
+            levels.add("director");
+        if (/manager|admin|analyst|operations/.test(t))
+            levels.add("manager");
+    }
+    return levels.size ? [...levels] : ["cxo", "vp", "director", "manager"];
+}
+function dedupe(values) {
+    return [...new Set((values ?? []).filter(Boolean))];
+}

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { createFilePlanStore, type PlanStore, type StoredPlan } from "./planStor
 export { computeApprovalDigests, loadOrCreateSigningKey, loadSigningKey, signApproval, verifyApprovalDigests, type ApprovalVerification, } from "./integrity.ts";
 export { buildAuditLog, verifyAuditLog, type AuditLogEntry, type AuditLogExport, type AuditLogVerification, } from "./auditLog.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+export { computeHealth, summarizeHealth, healthToMarkdown, type HealthEntry, type HealthRollup, type HealthRuleDelta, } from "./health.ts";
 export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, type CrmObjectType, type FieldMappings, } from "./mappings.ts";
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.ts";

package/dist/index.js

@@ -19,6 +19,7 @@ export { createFilePlanStore } from "./planStore.js";
 export { computeApprovalDigests, loadOrCreateSigningKey, loadSigningKey, signApproval, verifyApprovalDigests, } from "./integrity.js";
 export { buildAuditLog, verifyAuditLog, } from "./auditLog.js";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
+export { computeHealth, summarizeHealth, healthToMarkdown, } from "./health.js";
 export { auditReportToHtml, auditReportToMarkdown } from "./report.js";
 export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, normalizeFieldMappings, readMappedValue, } from "./mappings.js";
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.js";

package/dist/mappings.js

@@ -13,6 +13,9 @@ export const HUBSPOT_DEFAULT_FIELD_MAPPINGS = {
         email: "email",
         phone: "phone",
         title: "jobtitle",
+        // HubSpot-standard "LinkedIn URL"; safe to request everywhere (HubSpot
+        // ignores unknown properties rather than erroring). Powers strong dedup.
+        linkedin: "hs_linkedin_url",
         ownerId: "hubspot_owner_id",
     },
     deals: {

package/dist/types.d.ts

@@ -10,7 +10,21 @@ export type RiskLevel = "low" | "medium" | "high";
 export type ApprovalStatus = "draft" | "needs_approval" | "approved" | "rejected" | "applied";
 export type GtmObjectType = "account" | "contact" | "deal" | "user" | "activity";
 export type GtmEvidenceSourceSystem = "salesforce" | "hubspot" | "gong" | "chorus" | "fathom" | "manual" | "csv" | "mock" | "web" | "unknown";
-export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task" | "merge_records";
+export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task" | "create_record" | "merge_records";
+/**
+ * The afterValue of a `create_record` operation. The connector re-resolves on
+ * `matchKey`/`matchValue` at apply time and creates only on a confirmed miss.
+ * `estCostUsd` is the acquire meter's per-record charge, recorded against the
+ * budget on a successful create.
+ */
+export type CreateRecordPayload = {
+    properties: Record<string, string>;
+    matchKey: string;
+    matchValue: string;
+    source: string;
+    estCostUsd?: number;
+    associateCompanyName?: string;
+};
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**
  * One claim that a canonical record exists in an external system. A record
@@ -125,6 +139,8 @@ export type CanonicalContact = {
     email?: string;
     phone?: string;
     title?: string;
+    /** LinkedIn profile URL — the strongest cross-system identity key for dedup. */
+    linkedin?: string;
     ownerId?: string;
     lastActivityAt?: string;
     lastSyncAt?: string;

package/docs/api.md

@@ -40,7 +40,7 @@ release.
 - `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
-- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). The Salesforce connector skips `merge_records` honestly (SOAP/Apex-only on that platform).
+- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `create_record` (resolve-first net-new contact/company create — re-checks the dedupe key at apply, never double-creates), `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). The Salesforce connector skips `merge_records` and `create_record` honestly (platform-specific).
 - `createSalesforceConnector(options)` — read/write/readField/fetchChanges; probabilities normalized to 0..1; `applyOperation` implements every operation type.
 - `createStripeConnector(options)` — read-only billing by design (`applyOperation` returns `skipped`); email domains are the cross-system merge keys. Implements `fetchChanges` (incremental via `created[gte]`).
 
@@ -62,7 +62,8 @@ 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`),
+`enrich` (`append` / `refresh` / `ingest` / `acquire` / `status`),
+`icp` (`interview` / `set` / `show`),
 `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
@@ -120,6 +121,32 @@ dependency-free CSV intake; the Apollo client (`createApolloClient`,
 `pullApolloRecords`, 429-aware with `Retry-After`) is the first `api`-kind
 source.
 
+## Acquire (net-new lead generation)
+
+`buildAcquirePlan` turns sourced-but-unmatched prospects into `create_record`
+operations (matched / ambiguous are skipped — resolve-first never creates over
+a possible dup), capped by the meter's headroom. `builtinAcquirePreset` is the
+zero-config `EnrichConfig.acquire` (budget, provider, create-mapping) so
+`enrich acquire` runs with just an `icp.json`.
+
+- **ICP** (`icp.ts`): `Icp` type, `parseIcp`, `icpToExploriumFilters` /
+  `icpToCrustdataFilters` (per-provider discovery filters), `scoreProspectAgainstIcp`
+  (persona fit 0..1), `fitThreshold`, `INTERVIEW_SPEC` + `icpFromAnswers` (the
+  agent-driven interview).
+- **Prospect sources** (`connectors/prospectSources.ts`, `Prospect`):
+  `fetchExploriumProspects` (discovery), `pipe0ResolveWorkEmails` (work-email
+  waterfall, chunked, surfaces upstream errors), `fetchPipe0CrustdataProspects`
+  (people search). `prospectIdentityKeys` / `crmContactKeys` /
+  `partitionFreshProspects` power the pre-email dedup.
+- **Meter** (`acquireMeter.ts`): `AcquireBudget`, `loadMeter` / `remaining` /
+  `recordConsumption` — per-profile windowed record+spend budget, charged only
+  for landed creates.
+- **Seen cache** (`acquireSeen.ts`): `loadSeen` / `recordSeen` — cross-run
+  memory so a re-run never re-pays to enrich a known prospect.
+
+`CanonicalContact.linkedin` (mapped from HubSpot `hs_linkedin_url`) is the
+strong dedup key across all of the above.
+
 ## Schedule
 
 The horizontal scheduler: a declarative schedule-entry store, a

package/docs/architecture.md

@@ -72,7 +72,14 @@ provider  ──fetchSnapshot()──►  CanonicalGtmSnapshot
 - `market*.ts` (`market.ts`, `marketClassify.ts`, `marketAxes.ts`,
   `marketOverlay.ts`, `marketScale.ts`, `marketReport.ts`) — the competitive
   market-map layer; classifications are verbatim-verified against captures.
-- `enrich.ts` + `enrichApollo.ts` — third-party data enrichment (fill-blanks).
+- `enrich.ts` + `enrichApollo.ts` — third-party data enrichment (fill-blanks),
+  plus `buildAcquirePlan` / `builtinAcquirePreset` for net-new lead generation.
+- `icp.ts` — the Ideal Customer Profile artifact: per-provider discovery-filter
+  translation, prospect fit scoring, and the agent-driven interview spec.
+- `acquireMeter.ts` — per-profile windowed budget (records + spend) for acquire.
+- `acquireSeen.ts` — cross-run "seen" cache so re-runs don't re-pay for dupes.
+- `connectors/prospectSources.ts` — API prospect sources (Explorium discovery,
+  pipe0 work-email waterfall, pipe0/Crustdata search) + the pre-email dedup keys.
 
 **Surfaces & infra**
 - `cli.ts` — one async function per command, flat dispatch in `runCli`;

package/docs/dx-punch-list.md

@@ -0,0 +1,87 @@
+# DX / adoption punch list
+
+Audit date: 2026-06-19. Method: ran the CLI as a new adopter would (bare
+invoke → `doctor` → `audit --demo` → per-command `--help`) and measured the
+friction, rather than reading the source. Companion to the security/strategic
+findings that drove the 0.25.1–0.28.0 hardening releases — same format, same
+intent: a tracked list that drives a release.
+
+## Framing
+
+The **agent path** (SKILL.md verb map, MCP tools, `--json` everywhere,
+gate-shaped exit codes 0/1/2) is cohesive and adopts cleanly. The **human
+path** is the weak side — and the human is a primary user (the consultant-CLI,
+dogfood-on-client-work direction). Every fix below either *deepens an existing
+verb* or *connects two existing verbs*; none adds a new top-level noun. The
+adoption work **is** the "deeper not broader" work.
+
+`doctor` (ends with "Next step") and `fix` (chains audit→suggest→approve→apply)
+already do the right thing. Cohesion here = make every verb behave like
+`doctor` and `fix` already do.
+
+## Findings (evidence-backed)
+
+| # | Finding | Evidence | Impact |
+| --- | --- | --- | --- |
+| F1 | **Front door is a firehose** | bare invoke = 194 lines; 22 verbs / 87 distinct flags; `cli.ts` is 3,615 lines | New user can't find the ~6 things they actually do |
+| F2 | **Credential-free entry point dead-ends** | `audit --demo` (the README's "try it first") dumps **1,467 lines** to stdout and ends on a blank line — no "next step," unlike `doctor` | The single most-run first command strands you |
+| F3 | **No per-command help** | `dedupe --help`, `audit --help` fall through to the same 194-line global wall | A stuck user gets the firehose, not the answer |
+| F4 | **No altitude control on reads** | `audit` has only `--json` / `--out` / `--format`; no `--summary` / `--top` / `--quiet`. Human mode *is* the 1,467-line dump | Default human output is unreadable yet not machine-parseable |
+| F5 | **Tone undercuts positioning** | `audit --demo` footer: "This prototype is dry-run only" | Reads as toy vs. the beta/production-safety-invariant framing |
+| F6 | **No guided mode** | `readline` is used only for the login secret prompt | Every workflow is hand-assembled from flags; nothing scaffolds the loop |
+
+## Fix sequence (highest leverage first)
+
+### 1. Progressive-disclosure help — IN PROGRESS
+Fixes **F1, F3**. The full `usage()` becomes the explicit full reference
+(`fullstackgtm help --full`). Add:
+- `shortUsage()` — a ~30-line map of the verbs grouped by lifecycle phase
+  (Setup · Detect · Prevent · Remediate · Calls · Govern · Market · Schedule),
+  one line each, ending with `<command> --help` and `help --full` pointers.
+  Becomes the default for bare invoke and `--help`.
+- `commandHelp(command)` — focused per-verb help (summary, synopsis, where it
+  sits in the loop, key options, see-also). `<verb> --help` zooms in instead
+  of dumping the surface. `call`/`market`/`enrich`/`bulk-update`/`schedule`
+  keep their existing bespoke help.
+- `help [command] [--full]` command.
+
+### 2. Every verb hands you the next step — DONE (audit keystone)
+Fixes **F2**. `auditNextStep()` gives `audit` context-aware forward guidance on
+stderr (stdout stays clean for pipes/`--out`; suppressed under `--json`):
+- **demo/sample** → "Client-ready writeup: `report --demo`" + "Run on your CRM:
+  `login hubspot` → `audit --provider hubspot --save`"
+- **live + `--save`** → the governed spine: `suggest` → `plans approve
+  --values-from` → `apply`, with the real plan id
+- **0 findings** → "clean — gate new records with `resolve`, schedule a check"
+
+The lifecycle spine made *experiential* — each command knows its phase and
+points forward (`doctor`/`fix` were the templates). `audit` is the keystone
+(the documented dead-end); the helper pattern now generalizes to the other read
+verbs (`report`, `resolve`, `dedupe` previews) in a follow-up.
+
+### 3. Altitude control on the firehose — DONE
+Fixes **F4**. `patchPlanToMarkdown(plan, { summary })` gains a summary view
+(header + Findings-by-Rule table + operation count + pointers to `--full` and
+`report`). `audit` defaults to it — **1,467 → 24 lines** on the demo — with
+`--full` to opt back into the per-operation dump. The default stays *full* for
+every other caller (bulk-update, fix, dedupe, plans show, MCP): write-preview
+verbs keep full operation detail because you approve specific ops there. The
+principled split — audit = "what's wrong" (summary → `report`); write verbs =
+"exactly what I'll change" (full) — is the real win.
+
+### 4. Tone pass — DONE
+Fixes **F5**. The "This prototype is dry-run only" footer is replaced
+everywhere with safety-invariant framing matching README/SKILL: "Dry-run plan —
+read-only. No provider write happens until you approve specific operations and
+run `apply`; placeholder values are refused without an explicit override. These
+safety invariants are not beta." No "prototype" string remains in user output.
+
+## Deferred (bigger bets, gated on 1–4 landing)
+- **Engagement workspace**: per-client `.fullstackgtm/` state that accumulates
+  snapshots, plans, evidence, and a health-over-time score — turns episodic
+  audits into a continuously-operated system.
+- **Journey commands**: 2–3 opinionated composites (onboard-a-client,
+  health-rollup) sequencing existing verbs into revops jobs.
+
+There is no point building the engagement workspace while the front door dumps
+1,467 lines. Land the DX fixes first.

package/llms.txt

@@ -115,6 +115,22 @@ artifacts: plan ids / enrich run labels, trigger cron|manual) land under
 firings (visibility only — local cron has no catch-up). Providers beyond
 `local` are not yet implemented (future: codegen scaffolds, same contract).
 
+## Key invariants (engagement workspace / health)
+
+`fullstackgtm health` rolls up a per-profile CRM-health timeline that accrues
+from the verb teams already run: every `audit --save` stamps a deterministic
+0–100 hygiene score plus a snapshot onto the active profile. The score is
+`100 / (1 + severity-weighted findings per record)` (info ×1, warning ×3,
+critical ×10) — no LLM, so it is byte-stable in CI and comparable run-over-run;
+0 findings ⇒ 100, and the same findings over fewer clean records score lower.
+State is profile-scoped and owner-only (0600) under the same secured home as
+plans: `health.jsonl` (append-only, one entry per saved audit) and
+`snapshots/<planId>.json`. `health` is READ-ONLY — it only reads the timeline,
+never re-audits or writes; `--json` emits the rollup (current score, delta since
+the last audit, dated trend, per-rule deltas). Scope per client with
+`--profile <name>`; an empty timeline returns a pointer, never an error.
+Library: `computeHealth` / `summarizeHealth` / `healthToMarkdown`.
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.34.0",
+  "version": "0.37.0",
   "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 LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/skills/fullstackgtm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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; to report a CRM's health and trend over time; 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
@@ -65,6 +65,7 @@ credentials AND stored plans per client org.
 | `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) |
+| `health [--json]` | Per-profile CRM health timeline: deterministic 0–100 score, trend, per-rule deltas — accrues from `audit --save`, read-only |
 | `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.