fullstackgtm 0.44.0 → 0.46.0

package/dist/schedule.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.js";
 // Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep schedule.ts
@@ -592,3 +593,255 @@ export function replaceManagedBlock(existing, profile, block) {
         return "";
     return `${merged.join("\n")}\n`;
 }
+/**
+ * Compile a cron expression to StartCalendarInterval dicts. Full-range fields
+ * (`*`, but also spellings like `0-59`) are omitted (launchd wildcard); the
+ * rest cross-product, capped so a dense expression cannot render a megabyte
+ * plist. Vixie day semantics: when day-of-month AND day-of-week are both
+ * restricted, either may match — launchd ANDs keys within one dict, so that
+ * becomes the union of a Day dict set and a Weekday dict set. A date matching
+ * both sets makes launchd trigger twice in the same minute; the run entry
+ * point drops the second via isDuplicateCronFiring.
+ */
+export function cronToCalendarIntervals(cron, cap = 512) {
+    const full = (values, min, max) => values.length === max - min + 1;
+    const minutes = full(cron.minute, 0, 59) ? [undefined] : cron.minute;
+    const hours = full(cron.hour, 0, 23) ? [undefined] : cron.hour;
+    const months = full(cron.month, 1, 12) ? [undefined] : cron.month;
+    const domRestricted = cron.dayOfMonthRestricted && !full(cron.dayOfMonth, 1, 31);
+    const dowRestricted = cron.dayOfWeekRestricted && !full(cron.dayOfWeek, 0, 6);
+    const daySlots = [];
+    if (domRestricted)
+        for (const day of cron.dayOfMonth)
+            daySlots.push({ Day: day });
+    if (dowRestricted)
+        for (const weekday of cron.dayOfWeek)
+            daySlots.push({ Weekday: weekday });
+    if (daySlots.length === 0)
+        daySlots.push({});
+    const count = minutes.length * hours.length * daySlots.length * months.length;
+    if (count > cap) {
+        throw new Error(`Cron expression "${cron.source}" expands to ${count} launchd calendar intervals (cap ${cap}). ` +
+            "Simplify the expression or split it into separate schedules.");
+    }
+    const intervals = [];
+    for (const month of months) {
+        for (const daySlot of daySlots) {
+            for (const hour of hours) {
+                for (const minute of minutes) {
+                    const dict = {};
+                    if (minute !== undefined)
+                        dict.Minute = minute;
+                    if (hour !== undefined)
+                        dict.Hour = hour;
+                    if (daySlot.Day !== undefined)
+                        dict.Day = daySlot.Day;
+                    if (daySlot.Weekday !== undefined)
+                        dict.Weekday = daySlot.Weekday;
+                    if (month !== undefined)
+                        dict.Month = month;
+                    intervals.push(dict);
+                }
+            }
+        }
+    }
+    return intervals;
+}
+/**
+ * True when a cron-triggered run was already recorded in `firedAt`'s minute.
+ * The `schedule run` entry point checks this for trigger:cron so a launchd
+ * double-trigger (dom+dow OR corner above) records a duplicate_firing no-op
+ * instead of running the command twice. Manual runs are never deduplicated.
+ */
+export function isDuplicateCronFiring(runs, firedAt) {
+    const minute = new Date(firedAt);
+    minute.setSeconds(0, 0);
+    return runs.some((run) => {
+        if (run.trigger !== "cron")
+            return false;
+        const fired = new Date(run.firedAt);
+        fired.setSeconds(0, 0);
+        return fired.getTime() === minute.getTime();
+    });
+}
+/** Reverse-DNS namespace for one profile's agents; install/uninstall own this prefix wholesale. */
+export function launchdAgentPrefix(profile) {
+    if (!/^[A-Za-z0-9._-]+$/.test(profile)) {
+        throw new Error(`Cannot build a launchd label from profile "${profile}" — profile names in LaunchAgent labels ` +
+            "must be alphanumeric with dot/dash/underscore.");
+    }
+    return `com.fullstackgtm.${profile}.`;
+}
+export function launchdLabel(profile, scheduleEntryId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(scheduleEntryId)) {
+        throw new Error(`Cannot build a launchd label from schedule id "${scheduleEntryId}".`);
+    }
+    return `${launchdAgentPrefix(profile)}${scheduleEntryId}`;
+}
+function xmlEscape(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            default:
+                return "&apos;";
+        }
+    });
+}
+/**
+ * Render one LaunchAgent plist. ProgramArguments is an argv array — launchd
+ * execs it directly, no shell, so there is no quoting/injection surface at
+ * all (values are XML-escaped for the document, nothing more).
+ */
+export function renderLaunchdPlist(options) {
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        "\t<key>Label</key>",
+        `\t<string>${xmlEscape(options.label)}</string>`,
+        "\t<key>ProgramArguments</key>",
+        "\t<array>",
+        ...options.programArguments.map((arg) => `\t\t<string>${xmlEscape(arg)}</string>`),
+        "\t</array>",
+        "\t<key>StartCalendarInterval</key>",
+        "\t<array>",
+    ];
+    const keyOrder = ["Minute", "Hour", "Day", "Weekday", "Month"];
+    for (const interval of options.calendarIntervals) {
+        lines.push("\t\t<dict>");
+        for (const key of keyOrder) {
+            const value = interval[key];
+            if (value === undefined)
+                continue;
+            lines.push(`\t\t\t<key>${key}</key>`, `\t\t\t<integer>${value}</integer>`);
+        }
+        lines.push("\t\t</dict>");
+    }
+    lines.push("\t</array>");
+    if (options.environment && Object.keys(options.environment).length > 0) {
+        lines.push("\t<key>EnvironmentVariables</key>", "\t<dict>");
+        for (const [name, value] of Object.entries(options.environment)) {
+            lines.push(`\t\t<key>${xmlEscape(name)}</key>`, `\t\t<string>${xmlEscape(value)}</string>`);
+        }
+        lines.push("\t</dict>");
+    }
+    if (options.standardOutPath) {
+        lines.push("\t<key>StandardOutPath</key>", `\t<string>${xmlEscape(options.standardOutPath)}</string>`);
+    }
+    if (options.standardErrorPath) {
+        lines.push("\t<key>StandardErrorPath</key>", `\t<string>${xmlEscape(options.standardErrorPath)}</string>`);
+    }
+    lines.push("</dict>", "</plist>");
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * The real ~/Library/LaunchAgents + launchctl. Everything above takes a
+ * LaunchdIo so tests inject fakes and never touch the user's agents.
+ */
+export function systemLaunchdIo(agentsDirOverride) {
+    const agentsDir = agentsDirOverride ?? join(homedir(), "Library", "LaunchAgents");
+    const domain = () => {
+        const uid = typeof process.getuid === "function" ? process.getuid() : null;
+        if (uid === null)
+            throw new Error("launchd scheduling requires a POSIX user id (macOS only).");
+        return `gui/${uid}`;
+    };
+    const launchctl = (args) => {
+        const result = spawnSync("launchctl", args, { encoding: "utf8" });
+        if (result.error)
+            throw new Error(`Cannot run \`launchctl\`: ${result.error.message}`);
+        return result;
+    };
+    return {
+        list() {
+            try {
+                return readdirSync(agentsDir).filter((name) => name.endsWith(".plist"));
+            }
+            catch {
+                return [];
+            }
+        },
+        write(fileName, content) {
+            mkdirSync(agentsDir, { recursive: true });
+            // 0644 like every LaunchAgent: launchd refuses group/world-WRITABLE
+            // plists, and this file holds a dispatch line, not a secret.
+            writeFileSync(join(agentsDir, fileName), content, { mode: 0o644 });
+        },
+        remove(fileName) {
+            rmSync(join(agentsDir, fileName), { force: true });
+        },
+        bootstrap(fileName) {
+            const result = launchctl(["bootstrap", domain(), join(agentsDir, fileName)]);
+            if (result.status !== 0) {
+                throw new Error(`\`launchctl bootstrap\` failed for ${fileName}: ${(result.stderr ?? "").trim() || `exit ${result.status}`}`);
+            }
+        },
+        bootout(label) {
+            launchctl(["bootout", `${domain()}/${label}`]);
+        },
+    };
+}
+/**
+ * Materialize enabled entries as one LaunchAgent each, replacing the
+ * profile's com.fullstackgtm.<profile>.* fleet wholesale (stale agents are
+ * booted out and deleted; plists outside the prefix are never touched).
+ * `cliArgv` is the argv-array analog of the crontab invocation line.
+ */
+export function installLaunchdAgents(profile, entries, cliArgv, io, options = {}) {
+    for (const token of cliArgv) {
+        if (hasControlChar(token)) {
+            throw new Error("Refusing to render LaunchAgents: the resolved CLI invocation (node path or script path) " +
+                "contains a newline or control character.");
+        }
+    }
+    const removed = uninstallLaunchdAgents(profile, io);
+    const installed = [];
+    for (const entry of entries) {
+        assertRenderableEntry(profile, entry);
+        let intervals;
+        try {
+            intervals = cronToCalendarIntervals(parseCron(entry.cron));
+        }
+        catch (error) {
+            throw new Error(`Schedule ${entry.id} ("${entry.label}") cannot materialize as a LaunchAgent: ` +
+                `${error instanceof Error ? error.message : String(error)}`);
+        }
+        const label = launchdLabel(profile, entry.id);
+        const logPath = options.logDir ? join(options.logDir, `${label}.log`) : undefined;
+        const plist = renderLaunchdPlist({
+            label,
+            programArguments: [...cliArgv, "schedule", "run", entry.id, "--profile", profile, "--trigger", "cron"],
+            calendarIntervals: intervals,
+            environment: options.environment,
+            standardOutPath: logPath,
+            standardErrorPath: logPath,
+        });
+        const fileName = `${label}.plist`;
+        io.write(fileName, plist);
+        io.bootstrap(fileName);
+        installed.push(label);
+    }
+    return { installed, removed };
+}
+/** Boot out and delete every agent in the profile's prefix; returns the removed labels. */
+export function uninstallLaunchdAgents(profile, io) {
+    const prefix = launchdAgentPrefix(profile);
+    const removed = [];
+    for (const name of io.list()) {
+        if (!name.startsWith(prefix))
+            continue;
+        const label = name.slice(0, -".plist".length);
+        io.bootout(label);
+        io.remove(name);
+        removed.push(label);
+    }
+    return removed;
+}

package/dist/spoolFiles.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared reader for the spool container convention (docs/signal-spool-format.md):
+ * newline-delimited JSON — one object per line, append-only — with a JSON array
+ * accepted in a `.json` file for hand-staged convenience, and a DIRECTORY
+ * meaning "every `*.jsonl` / `*.json` file in it, name-sorted" so multiple
+ * receivers can each append their own file.
+ *
+ * The container is the convention; the row SCHEMA stays with each caller:
+ * `signals fetch --from` validates staged signal rows, `enrich ingest` stages
+ * enrichment rows, `market observe --from` validates observation-set envelopes.
+ * This module only parses objects out of files — it never interprets them.
+ *
+ * Extracted from the `file` signal-source connector (the Phase-2 webhook
+ * landing-zone reader), which now delegates here; error-message text is
+ * parameterized by `label` so existing connector errors are unchanged.
+ */
+/** Spool files in a landing-zone directory: `*.jsonl` / `*.json`, name-sorted. */
+export declare function spoolFilesIn(dir: string): string[];
+/** Parse a JSON-array spool file into rows. `label` prefixes error messages. */
+export declare function parseSpoolArray(raw: string, path: string, label: string): Record<string, unknown>[];
+/** Parse a JSONL spool file into rows. `label` prefixes error messages. */
+export declare function parseSpoolJsonl(raw: string, path: string, label: string): Record<string, unknown>[];
+/** Parse one spool file's text — JSON array if it opens with `[`, else JSONL. */
+export declare function parseSpoolText(raw: string, path: string, label: string): Record<string, unknown>[];
+/**
+ * Should an explicitly named intake path be read with spool semantics?
+ * True for a directory (a landing zone) or a `*.jsonl` file. Plain `.json` /
+ * `.csv` files keep each verb's original single-file handling, so existing
+ * invocations parse exactly as before.
+ */
+export declare function isSpoolPath(absPath: string): boolean;
+/** A parsed spool row plus where it came from (for error labels). */
+export type SpoolRow = {
+    file: string;
+    index: number;
+    row: Record<string, unknown>;
+};
+/**
+ * Read an explicitly named spool path — a `.jsonl` file or a directory of
+ * `*.jsonl` / `*.json` files. Unlike the webhook `file` connector (where a
+ * missing spool is an empty source), the user named this path: a missing or
+ * unreadable file is an error, and a malformed row throws with file + line.
+ */
+export declare function readSpoolPath(absPath: string, label: string): SpoolRow[];

package/dist/spoolFiles.js

@@ -0,0 +1,114 @@
+/**
+ * Shared reader for the spool container convention (docs/signal-spool-format.md):
+ * newline-delimited JSON — one object per line, append-only — with a JSON array
+ * accepted in a `.json` file for hand-staged convenience, and a DIRECTORY
+ * meaning "every `*.jsonl` / `*.json` file in it, name-sorted" so multiple
+ * receivers can each append their own file.
+ *
+ * The container is the convention; the row SCHEMA stays with each caller:
+ * `signals fetch --from` validates staged signal rows, `enrich ingest` stages
+ * enrichment rows, `market observe --from` validates observation-set envelopes.
+ * This module only parses objects out of files — it never interprets them.
+ *
+ * Extracted from the `file` signal-source connector (the Phase-2 webhook
+ * landing-zone reader), which now delegates here; error-message text is
+ * parameterized by `label` so existing connector errors are unchanged.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** Spool files in a landing-zone directory: `*.jsonl` / `*.json`, name-sorted. */
+export function spoolFilesIn(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.endsWith(".jsonl") || name.endsWith(".json"))
+        .sort()
+        .map((name) => join(dir, name));
+}
+/** Parse a JSON-array spool file into rows. `label` prefixes error messages. */
+export function parseSpoolArray(raw, path, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${label} ${path}: not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (!Array.isArray(parsed))
+        throw new Error(`${label} ${path}: expected a JSON array of staged signal rows.`);
+    return parsed.map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(`${label} ${path}: row ${index} is not an object.`);
+        }
+        return entry;
+    });
+}
+/** Parse a JSONL spool file into rows. `label` prefixes error messages. */
+export function parseSpoolJsonl(raw, path, label) {
+    const out = [];
+    const lines = raw.split("\n");
+    lines.forEach((line, index) => {
+        const t = line.trim();
+        if (!t)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(t);
+        }
+        catch (error) {
+            throw new Error(`${label} ${path}: line ${index} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`${label} ${path}: line ${index} is not a JSON object.`);
+        }
+        out.push(parsed);
+    });
+    return out;
+}
+/** Parse one spool file's text — JSON array if it opens with `[`, else JSONL. */
+export function parseSpoolText(raw, path, label) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    return trimmed.startsWith("[") ? parseSpoolArray(trimmed, path, label) : parseSpoolJsonl(trimmed, path, label);
+}
+/**
+ * Should an explicitly named intake path be read with spool semantics?
+ * True for a directory (a landing zone) or a `*.jsonl` file. Plain `.json` /
+ * `.csv` files keep each verb's original single-file handling, so existing
+ * invocations parse exactly as before.
+ */
+export function isSpoolPath(absPath) {
+    try {
+        if (statSync(absPath).isDirectory())
+            return true;
+    }
+    catch {
+        return false;
+    }
+    return absPath.endsWith(".jsonl");
+}
+/**
+ * Read an explicitly named spool path — a `.jsonl` file or a directory of
+ * `*.jsonl` / `*.json` files. Unlike the webhook `file` connector (where a
+ * missing spool is an empty source), the user named this path: a missing or
+ * unreadable file is an error, and a malformed row throws with file + line.
+ */
+export function readSpoolPath(absPath, label) {
+    const isDir = statSync(absPath).isDirectory();
+    const files = isDir ? spoolFilesIn(absPath) : [absPath];
+    if (isDir && files.length === 0) {
+        throw new Error(`${label} ${absPath}: directory contains no *.jsonl / *.json spool files.`);
+    }
+    const rows = [];
+    for (const file of files) {
+        const raw = readFileSync(file, "utf8");
+        parseSpoolText(raw, file, label).forEach((row, index) => rows.push({ file, index, row }));
+    }
+    return rows;
+}

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";
 /**
@@ -387,6 +404,17 @@ export type PatchPlanRun = {
     status: PatchPlanRunStatus;
     results: PatchOperationResult[];
 };
+/**
+ * Per-page progress during a snapshot pull, emitted by connectors that accept
+ * an `onProgress` option. `fetched` is the running total for the object type
+ * currently streaming (it resets when the pull moves on to the next type).
+ * Presentation-only: a throwing callback must never fail a pull, so emitters
+ * call it best-effort.
+ */
+export type SnapshotProgress = {
+    objectType: "user" | "account" | "contact" | "deal";
+    fetched: number;
+};
 /**
  * The provider contract. Reads produce a canonical snapshot; writes accept a
  * single patch operation and report the outcome. Connectors without

package/docs/api.md

@@ -47,9 +47,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
 
@@ -75,10 +76,41 @@ Commands: `init`, `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `me
 `icp` (`interview` / `set` / `show` / `judge` / `eval`),
 `signals` (`fetch` / `list` / `outcome` / `weights`), `draft`,
 `schedule` (`add` / `list` / `remove` / `enable` / `disable` / `run` /
-`install` / `uninstall` / `status`), `rules`, `profiles`, `doctor`.
+`install` / `uninstall` / `status`), `rules`, `profiles`, `doctor`,
+`capabilities`, `robot-docs`.
 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.
 
+Agent discovery: `capabilities` prints the machine-readable CLI contract —
+the command inventory with read-only vs write-shaped access (derived from the
+help table, not a parallel list), this exit-code contract, and safety
+defaults. `<command> --help --json` (and `help <command> --json`) prints
+per-command help as JSON. Unknown commands with `--json` return a structured
+`UNKNOWN_COMMAND` envelope with a did-you-mean hint; the plain-text path
+prints the same hint plus pointers to `--help` and `capabilities --json`.
+`robot-docs` prints the packaged agent guide (skills/fullstackgtm/SKILL.md).
+
+Intent inference: a `--flag` that is documented nowhere in the help reference
+but is within one edit of a documented flag (lowercased, `_`→`-`) is treated
+as a typo — exit 1 with `Did you mean` and the exact corrected command
+(structured `UNKNOWN_FLAG` envelope under `--json`). GNU-style `--flag=value`
+spellings of documented flags get the space-separated correction this CLI
+parses. Corrections are suggest-only, never auto-executed. Unknown flags with
+no near-miss are ignored, as before. Unknown `--provider` values and subverb
+typos on the multi-verb commands (`enrich apend` → `enrich append`) get
+nearest-match suggestions; a flag-shaped first token is diagnosed as
+flag-before-command.
+
+Triage: `doctor --json` returns environment status plus a `workspace` slice
+(`healthScore`, `scoreDelta`, `lastAuditAt`, `auditCount`, `pendingPlans`)
+and state-aware `nextSteps` — when a plan awaits approval, the exact
+`plans show <id>` → `plans approve <id> --operations <ids|all>` →
+`apply --plan-id <id> --provider <name>` chain. One call orients an agent.
+
+Reproducibility: with `SOURCE_DATE_EPOCH` set (seconds since the epoch), the
+audit plan's `createdAt` is pinned and `audit --demo --json` is
+byte-deterministic across re-runs.
+
 ### Flag lexicon: `--provider` vs `--source` vs `--connector` vs `--channel`
 
 Four flags name "where data comes from / goes to"; they are not interchangeable:
@@ -90,6 +122,25 @@ Four flags name "where data comes from / goes to"; they are not interchangeable:
 | `--connector` | A signal-intake source connector on `signals fetch`: pulls candidate signals from a connected platform or the local webhook spool into the signal ledger. | `file`, `serpapi-news`, `hubspot-forms` |
 | `--channel` | Where a plan's output is delivered. On `apply`, the delivery terminus — a plan applies to `--provider <crm>` *or* `--channel outbox` (render approved openers to a local outbox file; transmits nothing), never both. On `draft`, which outreach channel the opener is drafted for (shapes the emitted op). | `apply`: `outbox` · `draft`: `email`, `linkedin`, `task` |
 
+### Standardized flag aliases
+
+Additive; every legacy flag keeps working:
+
+- `--dry-run` — 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 are already preview-by-default
+  (plans are dry-run; nothing writes to a CRM outside approve → apply), so the
+  flag asserts that default rather than changing it: it additionally suppresses
+  `--save` (nothing is persisted to the plan store / run ledgers; a stderr note
+  is printed when both are passed) and locks `fix` to its stop-before-apply
+  path even when `--yes` is present. Omitting `--dry-run` changes nothing.
+  (`tam accounts` had `--dry-run` before this convention — there it prices the
+  credit pull; same spirit, spend nothing.)
+- `--confirm` — accepted wherever an ad-hoc confirmation flag already gates a
+  write stage: alias for `fix --yes` (`tam accounts` already used `--confirm`
+  for its spend guard). `--dry-run` beats `--confirm`/`--yes`.
+
 Credential resolution ladder: explicit `--token-env` → ambient env
 (`HUBSPOT_ACCESS_TOKEN`, `SALESFORCE_ACCESS_TOKEN`+`SALESFORCE_INSTANCE_URL`,
 `STRIPE_SECRET_KEY`) → stored login (`~/.fullstackgtm`, `FSGTM_HOME` override)
@@ -145,6 +196,13 @@ dependency-free CSV intake; the Apollo client (`createApolloClient`,
 `pullApolloRecords`, 429-aware with `Retry-After`) is the first `api`-kind
 source.
 
+Staged-file intake follows one container convention (`spoolFiles.ts`, shared
+with `signals fetch --from` and `market observe --from`): `enrich ingest`
+accepts — in addition to its original `.csv` / `.json` forms, which parse
+exactly as before — a `*.jsonl` spool file (one JSON row per line) or a
+directory of `*.jsonl` / `*.json` spool files (name-sorted), the Phase-2
+webhook landing-zone format (docs/signal-spool-format.md).
+
 ## Acquire (net-new lead generation)
 
 `buildAcquirePlan` turns sourced-but-unmatched prospects into `create_record`
@@ -226,10 +284,17 @@ firing — an unapproved plan records a `plan_not_approved` no-op run
 - 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`,
+- Local provider: `schedule install` materializes enabled entries into the
+  platform timer. crontab (Linux default, `--timer crontab`): a
+  sentinel-managed block — `crontabSentinels`, `renderManagedBlock`,
   `replaceManagedBlock`, and `systemCrontabIo` behind the injectable
-  `CrontabIo` seam (tests never touch a real crontab).
+  `CrontabIo` seam (tests never touch a real crontab). launchd (macOS
+  default, no Full Disk Access needed): one LaunchAgent per entry —
+  `cronToCalendarIntervals` (→ `LaunchdCalendarInterval[]`),
+  `renderLaunchdPlist`, `launchdLabel` / `launchdAgentPrefix`,
+  `installLaunchdAgents` / `uninstallLaunchdAgents`, and `systemLaunchdIo`
+  behind the injectable `LaunchdIo` seam (tests never touch launchctl);
+  `isDuplicateCronFiring` backs the `duplicate_firing` run no-op.
 
 ## Market map
 
@@ -261,9 +326,11 @@ the stored capture it cites before a set is accepted; failed captures read as
 
 ## MCP
 
-Tools: `fullstackgtm_audit`, `fullstackgtm_rules`, `fullstackgtm_apply`
-(requires explicit `approvedOperationIds`), `fullstackgtm_suggest`,
-`fullstackgtm_call_parse`, `fullstackgtm_resolve`,
+Tools: `fullstackgtm_capabilities` (the machine-readable server contract —
+tool inventory with per-tool CRM-write flags, derived from the server's own
+registration table), `fullstackgtm_audit`, `fullstackgtm_rules`,
+`fullstackgtm_apply` (requires explicit `approvedOperationIds`),
+`fullstackgtm_suggest`, `fullstackgtm_call_parse`, `fullstackgtm_resolve`,
 `fullstackgtm_market_worksheet`, `fullstackgtm_market_observe` (validates,
 verifies quoted spans against the stored captures, appends, returns front
 states). Input schemas are stable.

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/docs/signal-spool-format.md

@@ -154,6 +154,19 @@ connector produces, so both paths dedup against each other.
 | `quote` | `"Submitted \"<form name>\" — <email>"` |
 | `firstSeen` | submission timestamp (ISO 8601) |
 
+## One container convention across staged intake
+
+The spool CONTAINER (JSONL one-object-per-line; JSON array accepted; a
+directory means every `*.jsonl` / `*.json` file in it, name-sorted) is shared
+by every staged-file intake path, not just `--connector file`:
+
+- `signals fetch --from <path>` — rows are staged signal rows (this doc's table);
+- `enrich ingest <path> --source <id>` — rows are that source's enrichment rows;
+- `market observe --from <path>` — each object is one observation-set envelope.
+
+Each verb keeps its original single-file `.json` / `.csv` handling unchanged;
+the row schema stays the verb's own. Shared reader: `src/spoolFiles.ts`.
+
 ## See also
 
 - `docs/api.md` — the `signals` verb and the `SignalSourceConnector` contract.