fullstackgtm 0.45.0 → 0.47.0

package/dist/progress.js

@@ -0,0 +1,142 @@
+/**
+ * The shared progress-event vocabulary — ONE set of semantics for every
+ * long-running process, rendered natively by each surface:
+ *
+ *   CLI  → ui.ts (spinner / checklist / apply-ticker; TTY-only styling)
+ *   app  → Convex heartbeat patches → reactive ProgressChip / StageTimeline
+ *   both → optional broker streaming (a paired CLI POSTs heartbeats to the
+ *          hosted app under its clientRunId, so long local runs tick live in
+ *          the org's activity feed)
+ *
+ * Renderer-agnostic by contract: no event assumes persistence (the CLI drops
+ * them after painting) or ANSI (the app can't use it). Listeners are
+ * best-effort — a throwing renderer must never fail the work — and the
+ * throttle policy lives HERE so both surfaces feel identical.
+ *
+ * Standing convention: if a verb loops, it emits. New long-running verbs wire
+ * an emitter at the package layer; surfaces get feedback for free.
+ */
+const DEFAULT_THROTTLE_MS = 2000;
+/**
+ * Throttled emitter: `items` heartbeats coalesce to at most one delivery per
+ * throttle window (terminal `done === total` always delivers); `stage`,
+ * `opResult`, `note`, and `meter` are structural and always deliver.
+ */
+export function createProgressEmitter(listener, options = {}) {
+    const throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+    const now = options.now ?? Date.now;
+    const state = {
+        opsApplied: 0,
+        opsSkipped: 0,
+        opsFailed: 0,
+        updatedAt: now(),
+    };
+    let lastItemsDelivery = 0;
+    let pendingItems = false;
+    function deliver(event) {
+        state.updatedAt = now();
+        try {
+            listener(event, { ...state });
+        }
+        catch {
+            // Renderers are presentation-only; never fail the work.
+        }
+    }
+    return {
+        stage(stage, stageIndex, stageCount) {
+            state.stage = stage;
+            state.stageIndex = stageIndex;
+            state.stageCount = stageCount;
+            state.itemsDone = undefined;
+            state.itemsTotal = undefined;
+            state.note = undefined;
+            pendingItems = false;
+            deliver({ kind: "stage", stage, stageIndex, stageCount });
+        },
+        items(done, total) {
+            state.itemsDone = done;
+            state.itemsTotal = total;
+            const terminal = total !== undefined && done >= total;
+            const due = now() - lastItemsDelivery >= throttleMs;
+            if (terminal || due) {
+                lastItemsDelivery = now();
+                pendingItems = false;
+                deliver({ kind: "items", done, total });
+            }
+            else {
+                pendingItems = true;
+            }
+        },
+        note(note) {
+            state.note = note;
+            deliver({ kind: "note", note });
+        },
+        opResult(opId, status, detail) {
+            if (status === "applied")
+                state.opsApplied += 1;
+            else if (status === "skipped")
+                state.opsSkipped += 1;
+            else
+                state.opsFailed += 1;
+            deliver({ kind: "opResult", opId, status, detail });
+        },
+        meter(spent, budget, unit) {
+            deliver({ kind: "meter", spent, budget, unit });
+        },
+        snapshot() {
+            return { ...state, updatedAt: now() };
+        },
+        flush() {
+            if (pendingItems && state.itemsDone !== undefined) {
+                lastItemsDelivery = now();
+                pendingItems = false;
+                deliver({ kind: "items", done: state.itemsDone, total: state.itemsTotal });
+            }
+        },
+    };
+}
+/**
+ * Fan one event stream out to several listeners (e.g. the CLI's local renderer
+ * plus the broker heartbeat streamer). Each listener is isolated: one throwing
+ * never starves the others, matching the emitter's own best-effort contract.
+ */
+export function composeListeners(...listeners) {
+    const active = listeners.filter((listener) => Boolean(listener));
+    return (event, snapshot) => {
+        for (const listener of active) {
+            try {
+                listener(event, snapshot);
+            }
+            catch {
+                // Listeners are presentation/observability only; never fail the work.
+            }
+        }
+    };
+}
+// ── Shared stage registries ─────────────────────────────────────────────────
+// Package constants so the CLI checklist and the app StageTimeline render
+// LITERALLY the same stages in the same order — one mental model everywhere.
+export const CRM_SYNC_STAGES = [
+    "owners",
+    "accounts",
+    "contacts",
+    "deals",
+    "counters",
+    "health",
+];
+/** A connector snapshot pull — the CRM-sync stages that happen CLI-side. */
+export const SNAPSHOT_PULL_STAGES = ["owners", "accounts", "contacts", "deals"];
+/** The Stripe connector's snapshot pull (billing systems have no owners). */
+export const STRIPE_SNAPSHOT_STAGES = ["customers", "subscriptions"];
+export const CALL_SYNC_STAGES = ["notes", "transcripts", "insights"];
+export const BACKFILL_STRIPE_STAGES = ["invoices", "snapshot", "matching", "plan"];
+/** `backfill runs` — replaying local plan runs + health history to the broker. */
+export const RUNS_REPLAY_STAGES = ["runs", "health"];
+export const APPLY_STAGES = ["preflight", "operations", "results"];
+/** `enrich acquire` — routing sourced candidate rows into a create plan. */
+export const ACQUIRE_STAGES = ["candidates"];
+export const MARKET_CAPTURE_STAGES = ["sources", "capture", "classify", "persist"];
+/** No-op emitter for callers that don't care (keeps signatures simple). */
+export function nullProgressEmitter() {
+    return createProgressEmitter(() => { });
+}

package/dist/runReport.d.ts

@@ -1,3 +1,4 @@
+import type { ProgressListener } from "./progress.ts";
 /**
  * Per-row finding for the hosted run timeline. IDs + issue type ONLY — no field
  * values ever leave the CLI, keeping the audit's row data on the operator's side
@@ -28,6 +29,29 @@ export declare function reportFindings(values: RunFinding[]): void;
 export declare function reportCrm(value: RunCrm): void;
 /** A command annotates a structured event (plan saved, meter charged, …). */
 export declare function reportEvent(type: string, detail?: string): void;
+/**
+ * Arm heartbeat streaming for this invocation. Call once from the entry point
+ * (alongside capturing `startedAt`); without it, progress listeners from
+ * `progressReporter()` are inert. Safe to call for any command — skip-listed
+ * commands simply never stream.
+ */
+export declare function beginRunReport(args: string[], startedAt: number): void;
+/**
+ * A ProgressListener that streams the run's progress snapshot to the paired
+ * hosted app. Verbs compose it with their local renderer:
+ *
+ *   createProgressEmitter(composeListeners(renderer.listener, progressReporter()))
+ *
+ * Throttled to one POST per ~5s, first no earlier than ~5s into the run,
+ * 2s-capped and fire-and-forget. Privacy: stage names and counts only — notes
+ * must stay generic ("batch 4/12"); CRM field values never leave the machine.
+ */
+export declare function progressReporter(overrides?: {
+    now?: () => number;
+    intervalMs?: number;
+    minRunMs?: number;
+    fetchImpl?: typeof fetch;
+}): ProgressListener;
 /**
  * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
  * swallows every error. Call once per process from the entry point.

package/dist/runReport.js

@@ -31,6 +31,15 @@ export function reportCrm(value) {
 export function reportEvent(type, detail) {
     events.push({ ts: Date.now(), type, detail });
 }
+// FNV-1a — the stable-id hash used across the package (see backfill.ts).
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
 // Setup/inspection verbs aren't interesting as "runs" — skip the noise.
 const SKIP_COMMANDS = new Set([
     "login",
@@ -43,25 +52,151 @@ const SKIP_COMMANDS = new Set([
     "--version",
     "-v",
 ]);
+/** The stable per-invocation identity flushRunReport and heartbeats share. */
+function runIdentity(args, startedAt) {
+    const command = args[0];
+    if (!command || SKIP_COMMANDS.has(command))
+        return null;
+    const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+    const full = `${command}${sub}`;
+    return { command: full, clientRunId: `run_${fnv1a(`${full}:${startedAt}:${process.pid}`)}` };
+}
+// ── Live progress streaming ─────────────────────────────────────────────────
+// While a long command runs, a paired CLI streams heartbeats to the hosted
+// app: POST /api/cli/run with the SAME clientRunId the final flushRunReport
+// will use, status "in_progress", and the progress emitter's snapshot. The
+// server upserts by clientRunId, so the terminal flush simply wins. Same
+// invariants as flushRunReport: opt-in (paired only), fire-and-forget,
+// time-capped, never affects the command's outcome or output.
+const HEARTBEAT_INTERVAL_MS = 5000;
+/** No heartbeat before the run is ~this old — fast commands never stream. */
+const HEARTBEAT_MIN_RUN_MS = 5000;
+const HEARTBEAT_TIMEOUT_MS = 2000;
+let runContext = null;
+let lastHeartbeatAt = 0;
+// Broker credential resolved once per run (undefined = not looked up yet;
+// null = looked up, not paired).
+let heartbeatBroker;
+let inflightHeartbeat = null;
+/**
+ * Arm heartbeat streaming for this invocation. Call once from the entry point
+ * (alongside capturing `startedAt`); without it, progress listeners from
+ * `progressReporter()` are inert. Safe to call for any command — skip-listed
+ * commands simply never stream.
+ */
+export function beginRunReport(args, startedAt) {
+    lastHeartbeatAt = 0;
+    heartbeatBroker = undefined;
+    inflightHeartbeat = null;
+    const identity = runIdentity(args, startedAt);
+    runContext = identity ? { ...identity, startedAt } : null;
+}
+/**
+ * A ProgressListener that streams the run's progress snapshot to the paired
+ * hosted app. Verbs compose it with their local renderer:
+ *
+ *   createProgressEmitter(composeListeners(renderer.listener, progressReporter()))
+ *
+ * Throttled to one POST per ~5s, first no earlier than ~5s into the run,
+ * 2s-capped and fire-and-forget. Privacy: stage names and counts only — notes
+ * must stay generic ("batch 4/12"); CRM field values never leave the machine.
+ */
+export function progressReporter(overrides = {}) {
+    const now = overrides.now ?? Date.now;
+    const intervalMs = overrides.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+    const minRunMs = overrides.minRunMs ?? HEARTBEAT_MIN_RUN_MS;
+    const fetchImpl = overrides.fetchImpl ?? fetch;
+    return (_event, snapshot) => {
+        try {
+            if (!runContext)
+                return;
+            const at = now();
+            if (at - runContext.startedAt < minRunMs)
+                return;
+            if (at - lastHeartbeatAt < intervalMs)
+                return;
+            if (heartbeatBroker === undefined) {
+                const broker = getCredential("broker");
+                heartbeatBroker =
+                    broker?.baseUrl && broker.accessToken
+                        ? { baseUrl: broker.baseUrl.replace(/\/+$/, ""), accessToken: broker.accessToken }
+                        : null; // opt-in: only when paired
+            }
+            if (!heartbeatBroker)
+                return;
+            lastHeartbeatAt = at;
+            sendHeartbeat(fetchImpl, heartbeatBroker, runContext, snapshot, at);
+        }
+        catch {
+            // Observability is best-effort; never affect the command.
+        }
+    };
+}
+function sendHeartbeat(fetchImpl, broker, context, snapshot, at) {
+    // One heartbeat in flight at a time: a stalled POST is superseded, and the
+    // terminal flush aborts any straggler so it can never delay process exit.
+    inflightHeartbeat?.abort();
+    const controller = new AbortController();
+    inflightHeartbeat = controller;
+    const timer = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
+    timer.unref?.();
+    void fetchImpl(`${broker.baseUrl}/api/cli/run`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            command: context.command,
+            clientRunId: context.clientRunId,
+            status: "in_progress",
+            startedAt: context.startedAt,
+            finishedAt: at,
+            durationMs: at - context.startedAt,
+            progress: {
+                // Stage names + counts only — never CRM field values.
+                stage: snapshot.stage,
+                stageIndex: snapshot.stageIndex,
+                stageCount: snapshot.stageCount,
+                itemsDone: snapshot.itemsDone,
+                itemsTotal: snapshot.itemsTotal,
+                note: snapshot.note,
+                heartbeatAt: at,
+            },
+        }),
+        signal: controller.signal,
+    })
+        .catch(() => {
+        // fire-and-forget
+    })
+        .finally(() => {
+        clearTimeout(timer);
+        if (inflightHeartbeat === controller)
+            inflightHeartbeat = null;
+    });
+}
 /**
  * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
  * swallows every error. Call once per process from the entry point.
  */
 export async function flushRunReport(args, status, startedAt, error) {
-    const command = args[0];
-    if (!command || SKIP_COMMANDS.has(command))
+    // The terminal upsert supersedes any streaming heartbeat still in flight.
+    inflightHeartbeat?.abort();
+    inflightHeartbeat = null;
+    // Stable per-invocation identity: the server dedupes on clientRunId, so a
+    // retried report, an "in_progress" heartbeat, or a later `backfill runs`
+    // replay of local history never duplicates.
+    const identity = runIdentity(args, startedAt);
+    if (!identity)
         return;
     const broker = getCredential("broker");
     if (!broker?.baseUrl || !broker.accessToken)
         return; // opt-in: only when paired
-    const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
     const finishedAt = Date.now();
     try {
         await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
             method: "POST",
             headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
             body: JSON.stringify({
-                command: `${command}${sub}`,
+                command: identity.command,
+                clientRunId: identity.clientRunId,
                 status,
                 startedAt,
                 finishedAt,

package/dist/types.d.ts

@@ -15,7 +15,8 @@ export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "
  * 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.
+ * budget on a successful create. Emitted by `enrich acquire` (metered) and
+ * `backfill stripe` (closed-won deals from paid invoices, unmetered).
  */
 export type CreateRecordPayload = {
     properties: Record<string, string>;
@@ -39,6 +40,22 @@ export type CreateRecordPayload = {
     ownerId?: string;
     /** Audit label for how the owner was chosen (e.g. "fixed", "territory:0"). */
     assignedBy?: string;
+    /**
+     * Deal creates only: provider-neutral stage sentinel. "closed_won" tells the
+     * connector to resolve the target pipeline's REAL closed-won stage id from
+     * the provider's pipeline metadata at apply time (HubSpot: stage with
+     * `metadata.isClosed` true and probability 1) — never by substring-guessing
+     * a stage name. If no such stage is resolvable the operation is skipped.
+     * Plain deal properties (amount, closedate, dealname, …) travel in
+     * `properties` as provider property names, like every other create.
+     */
+    dealStage?: "closed_won";
+    /**
+     * Deal creates only: which pipeline to create the deal in — a pipeline id
+     * or a case-insensitive pipeline label. Absent = the portal's default
+     * pipeline (lowest displayOrder).
+     */
+    dealPipeline?: string;
 };
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**
@@ -418,6 +435,21 @@ export type GtmConnector = {
      * result per input op. Optional: connectors without it use `applyOperation`.
      */
     applyCreateContactsBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
+    /**
+     * Optional bulk apply path for homogeneous operation runs selected by
+     * `applyPatchPlan` (currently consecutive `set_field` ops on one object type
+     * and consecutive `archive_record` ops on one object type). Implementations
+     * MUST return exactly one result per input operation, preserve per-operation
+     * CAS/conflict semantics for field writes, and must not write operations that
+     * would have conflicted under the serial `readField` + `applyOperation` path.
+     * Connectors without it use `applyOperation` per operation.
+     */
+    applyBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
+    /**
+     * Maximum number of operations `applyPatchPlan` should pass to one
+     * `applyBatch` call. Defaults to 200 when unspecified.
+     */
+    applyBatchLimit?: number;
     /**
      * Read the live value of one canonical field, used for compare-and-set:
      * apply orchestration refuses to write over values that drifted since the

package/docs/api.md

@@ -37,9 +37,10 @@ release.
 
 ## Connectors
 
-- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, applyCreateContactsBatch?, readField?, fetchChanges? }`.
+- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, applyCreateContactsBatch?, applyBatch?, applyBatchLimit?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
+  - `applyBatch?(operations)` — optional bulk apply path for consecutive homogeneous `set_field`, `clear_field`, or `archive_record` runs selected by `applyPatchPlan`. It must return one result per input operation; field-write implementations preserve CAS by batch-reading live target values first and writing only clean records. Connectors without it stay on the sequential `applyOperation` path. `applyBatchLimit?` declares max operations per `applyBatch` call (default 200; Salesforce 200, HubSpot 100). Salesforce uses SOQL `IN` CAS reads plus Composite sObject Collections update/delete (`allOrNone:false`); HubSpot uses batch/read + batch/update/archive.
   - `applyCreateContactsBatch?(operations)` — optional bulk fast-path for
     independent `create_record` contact ops. `applyPatchPlan` routes safe-to-batch
     creates here (batched resolve-first + batched create — ~N/100 calls instead of
@@ -47,9 +48,10 @@ release.
     for any op that isn't batch-safe (grouped, value-overridden, company-
     associated, conflicted). HubSpot: `search IN` + `batch/create`; Salesforce:
     SOQL `IN` + Composite sObject Collections (`allOrNone:false`).
-- `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 implements the same operation set, with the platform-specific constraints noted below.)
+- `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/**deal** create — re-checks the dedupe key at apply, never double-creates; a deal create requires `dealStage: "closed_won"`, resolved to the target pipeline's real closed-won stage id from pipeline metadata, and its dedupe key is a custom deal property ensured on demand), `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). (The Salesforce connector implements the same operation set, with the platform-specific constraints noted below.)
 - `createSalesforceConnector(options)` — read/write/readField/fetchChanges; probabilities normalized to 0..1. `applyOperation` implements every operation type, with two platform constraints: `merge_records` covers **Accounts and Contacts** only (Salesforce exposes no Opportunity merge), and `create_record` resolve-first creates **contacts/accounts** (SOQL search on the match key, create only on a confirmed miss; stamps the canonical `ownerId` onto `OwnerId`).
 - `createStripeConnector(options)` — read-only billing by design (`applyOperation` returns `skipped`); email domains are the cross-system merge keys. Implements `fetchChanges` (incremental via `created[gte]`).
+- `fetchStripePaidInvoices(options, { sinceIso? })` — paginated `status=paid` invoice reads (`created[gte]` incremental, cents→major, paid-date extraction); feeds `buildStripeBackfillPlan(invoices, snapshot, opts)` (`src/backfill.ts`), which proposes one closed-won deal `create_record` per paid invoice, matched to CRM accounts by billing-email domain then exact name — an unmatched customer gets an explicit proposed account `create_record` in the same plan (freemail domains never used as company domain; `createMissingAccounts: false` restores report-only). Surfaced as the `backfill stripe` verb (plan-only; `--save` → approve → `apply`).
 
 ## Multi-system operations
 

package/docs/architecture.md

@@ -72,6 +72,8 @@ 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.
+- `backfill.ts` — Stripe paid invoices → proposed closed-won deal creates
+  (domain-then-name account matching; unmatched reported, never auto-created).
 - `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

package/docs/linkedin-connector-spec.md

@@ -75,7 +75,7 @@ unstable base. Therefore:
    fake.
 2. **After the acquire workstream commits/lands:** wire `enrich acquire --source
    linkedin` end-to-end and add the dry-run integration test.
-3. **Live validation** needs a HeyReach trial API key (Ryan provides) — the fake
+3. **Live validation** needs a HeyReach trial API key supplied by the operator — the fake
    covers everything up to the real network call.
 
 ## Phase 2 (future, recorded for continuity)

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Plan/apply for your GTM stack: canonical CRM/GTM data model, deterministic
 > hygiene audits, reviewable dry-run patch plans, and approval-gated
-> write-back to HubSpot, Salesforce, and Stripe (read-only). Think
+> write-back to HubSpot and Salesforce; Stripe is read-only. Think
 > `terraform plan` for your CRM. Apache-2.0.
 
 CLI quick check: `fullstackgtm doctor --json`. Zero-credential demo:
@@ -15,7 +15,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`
-- [Recipes](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md): five composable GTM plays over the primitives (cold-start lead-fill, the trigger→judge→draft outbound loop, scheduled-continuous, ABM-from-companies, hygiene-gated outbound) — the CLI ships primitives, your agent is the orchestrator, the package never sends
+- [Recipes](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md): five composable GTM plays over the primitives (cold-start lead-fill, the trigger→judge→draft outbound loop, scheduled-continuous, ABM-from-companies, hygiene-gated outbound) — the CLI ships primitives, your agent is the orchestrator, the package never sends
 - [Architecture](https://github.com/fullstackgtm/core/blob/main/docs/architecture.md): module map + snapshot → audit → plan → apply data flow; "where do I add a rule/connector/operation"
 - [Contributing](https://github.com/fullstackgtm/core/blob/main/CONTRIBUTING.md): dev setup, the open-core mirror model, the release ritual
 - [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
@@ -202,7 +202,7 @@ outbox is the send-side mirror of the spool; the always-on sender is hosted/opt-
 --contact <id> --result replied|...` credits the contact reached so weights
 re-learn. The contact↔account join (`contact.accountId` + `account.domain`) is
 surfaced at every hop, so the loop is contact-coherent end to end — see the
-[recipes](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md).
+[recipes](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md).
 
 ## Key invariants (schedule)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.45.0",
+  "version": "0.47.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)",
@@ -25,7 +25,14 @@
   "files": [
     "dist",
     "src",
-    "docs",
+    "docs/api.md",
+    "docs/architecture.md",
+    "docs/crm-health-lifecycle.md",
+    "docs/linkedin-connector-spec.md",
+    "docs/outbox-format.md",
+    "docs/recipes.md",
+    "docs/signal-spool-format.md",
+    "docs/tam.md",
     "README.md",
     "CHANGELOG.md",
     "INSTALL_FOR_AGENTS.md",
@@ -41,7 +48,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "pretest": "test -d tests || { echo 'No tests/ in this directory. In the published mirror, tests live here and `npm test` works. In the monorepo, run package tests from the repo ROOT: `node --experimental-strip-types --test tests/fullstackgtm*.test.ts` (the tests live at the monorepo root tests/).' >&2; exit 1; }",
     "test": "node --experimental-strip-types --test tests/*.test.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm pack --dry-run && node dist/bin.js --help && node dist/mcp-bin.js --help"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/skills/fullstackgtm/SKILL.md

@@ -60,6 +60,7 @@ credentials AND stored plans per client org.
 | `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; `--assign-unowned --to <id>` backfills every ownerless record |
 | `fix --rule <id>` | audit one rule → suggest → approve at the confidence bar → apply only with `--yes` |
+| `backfill stripe\|runs [--since <iso>] [--pipeline <id\|label>]` | Paid Stripe invoices → proposed closed-won deals (amount = invoice total, close date = paid date, company matched by billing-email domain then name); deduped by a `stripe_invoice_id` deal property re-resolved at apply, so re-running never double-creates; a customer the CRM doesn't know gets a proposed account create in the same plan (freemail domains never used; `--skip-unmatched` = report-only); `--save` → approve → `apply`. `backfill runs` replays LOCAL run history + health timeline to the paired hosted app (idempotent; `--dry-run` to preview) |
 | `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 |
 | `enrich acquire [--source explorium\|pipe0\|linkedin]` | Net-new ICP-targeted lead gen: resolve-first deduped `create_record` plans, capped by a per-profile windowed meter (records + spend); owner-stamped via `acquire.assign`/`--assign-owner` (never born ownerless); links each lead to a domain-stamped, signal-watchable account; `acquire.create.company` acquires accounts (ABM); `--source linkedin --list <id>` reads a HeyReach lead list (Phase 1 discovery, read-only — never sends); never auto-writes |