fullstackgtm 0.19.0 → 0.20.0

package/dist/marketReport.js

@@ -1,5 +1,6 @@
 import { computeFrontStates } from "./market.js";
 import { assessAxes, messageBreadth } from "./marketAxes.js";
+import { computeScaleIndex } from "./marketScale.js";
 /**
  * Render a market map as a client-ready deliverable: markdown for terminals
  * and PRs, and a self-contained printable HTML "field report" — front
@@ -98,7 +99,8 @@ function svgScatter(points, ax, ay, anchor, mini) {
     const e = escapeHtml;
     const dots = points
         .map((p) => {
-        const r = mini ? 3 + p.loud * 0.8 : 6 + p.loud * 1.6;
+        // Area-proportional: perceived bubble area tracks the size metric.
+        const r = (mini ? 4 + 14 * Math.sqrt(p.size) : 8 + 26 * Math.sqrt(p.size));
         const cls = p.vendorId === anchor ? "dot-anchor" : "dot";
         return (`<circle class="${cls}" cx="${sx(p.x).toFixed(1)}" cy="${sy(p.y).toFixed(1)}" r="${r.toFixed(1)}"/>` +
             `<text class="dot-label" style="font-size:${fsLabel}px" x="${sx(p.x).toFixed(1)}" y="${(sy(p.y) - r - 4).toFixed(1)}">${e(p.name)}</text>`);
@@ -121,7 +123,18 @@ function axisSectionsHtml(config, set) {
     const e = escapeHtml;
     const report = assessAxes(config, set);
     const vendorNames = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+    // Bubble size: scale index (relative market scale from citable signals)
+    // when every placeable vendor has one; LOUD count otherwise — never mix
+    // the two semantics on one chart.
+    const scale = computeScaleIndex(config);
+    const scaleIndex = new Map(scale.vendors.map((vendor) => [vendor.vendorId, vendor.index]));
+    const useScale = report.vendors.length > 0 && report.vendors.every((vendorId) => scaleIndex.get(vendorId) !== null && scaleIndex.get(vendorId) !== undefined);
     const loudCounts = new Map(report.vendors.map((vendorId) => [vendorId, messageBreadth(vendorId, set.observations).loudCount]));
+    const maxLoud = Math.max(1, ...loudCounts.values());
+    const sizeOf = (vendorId) => useScale ? scaleIndex.get(vendorId) : (loudCounts.get(vendorId) ?? 0) / maxLoud;
+    const sizeCaption = useScale
+        ? `Dot area &#8733; relative scale index (within this vendor set, from: ${e(scale.metricsUsed.join(", "))} — citable signals, not true market share)`
+        : "Dot area &#8733; LOUD count";
     const breadthAxis = {
         id: "breadth",
         label: "Message breadth",
@@ -158,7 +171,7 @@ function axisSectionsHtml(config, set) {
             name: vendorNames.get(vendorId) ?? vendorId,
             x: xs.get(vendorId),
             y: ys.get(vendorId),
-            loud: loudCounts.get(vendorId) ?? 0,
+            size: sizeOf(vendorId),
         }));
     };
     const [px, py] = config.primaryAxes ?? [axes[0].id, axes[1]?.id ?? "breadth"];
@@ -170,7 +183,7 @@ function axisSectionsHtml(config, set) {
   <figure>${svgScatter(pointsFor(px, py), axInfo, ayInfo, config.anchorVendor, false)}
   <figcaption>Positions computed from run ${e(set.runLabel)} observations: each axis is a per-claim scoring rubric
   in the market config; a vendor sits at the intensity-weighted mean (loud=1, quiet=&#189;) of the claims it
-  voices. Dot size = LOUD count. Axis status — ${e(axInfo.label)}: ${e(statusOf(px))}; ${e(ayInfo.label)}: ${e(statusOf(py))}.</figcaption>
+  voices. ${sizeCaption}. Axis status — ${e(axInfo.label)}: ${e(statusOf(px))}; ${e(ayInfo.label)}: ${e(statusOf(py))}.</figcaption>
   </figure>
 </section>`;
     // Deliberately no axis-pairing gallery here: the report is the client-facing

package/dist/marketScale.d.ts

@@ -0,0 +1,42 @@
+import type { MarketConfig, ScaleSignal } from "./market.ts";
+/**
+ * Relative scale index over the mapped vendor set — the honest version of
+ * "bubble size = market share". True segment market share is unknowable from
+ * public data for mostly-private vendor sets, so this computes a composite
+ * index from whatever citable signals exist per vendor (review counts,
+ * headcount, disclosed revenue, self-reported customers), each of which is
+ * biased in a different direction; the composite triangulates.
+ *
+ * Method, deterministic and auditable:
+ *   1. Per metric, log10(value + 1) — these signals span orders of magnitude.
+ *   2. Normalize each metric to [0, 1] across the vendors that HAVE it
+ *      (min–max within the set; a metric only one vendor has is skipped —
+ *      it cannot rank anyone).
+ *   3. A vendor's index = arithmetic mean of its normalized metric scores
+ *      (mean-of-normalized rather than geometric-of-raw so missing signals
+ *      neither punish nor reward), reported with coverage (which metrics).
+ *
+ * Vendors with zero signals get index null — the report falls back to its
+ * LOUD-count sizing for the whole map rather than mixing semantics.
+ */
+export type VendorScale = {
+    vendorId: string;
+    /** [0, 1] within the mapped set; null when the vendor has no usable signals. */
+    index: number | null;
+    /** Metrics that contributed, with their normalized scores. */
+    coverage: Array<{
+        metric: string;
+        value: number;
+        normalized: number;
+    }>;
+    signals: ScaleSignal[];
+};
+export type ScaleReport = {
+    vendors: VendorScale[];
+    /** Metrics used (present for ≥2 vendors) and metrics skipped (singletons). */
+    metricsUsed: string[];
+    metricsSkipped: string[];
+    complete: boolean;
+};
+export declare function computeScaleIndex(config: MarketConfig): ScaleReport;
+export declare function scaleReportToText(config: MarketConfig, report: ScaleReport): string;

package/dist/marketScale.js

@@ -0,0 +1,68 @@
+export function computeScaleIndex(config) {
+    const byMetric = new Map();
+    for (const vendor of config.vendors) {
+        for (const signal of vendor.scaleSignals ?? []) {
+            if (!Number.isFinite(signal.value) || signal.value < 0)
+                continue;
+            const rows = byMetric.get(signal.metric) ?? [];
+            rows.push({ vendorId: vendor.id, value: signal.value });
+            byMetric.set(signal.metric, rows);
+        }
+    }
+    const metricsUsed = [];
+    const metricsSkipped = [];
+    const normalized = new Map();
+    for (const [metric, rows] of byMetric) {
+        // Last write wins if a vendor lists the same metric twice.
+        const perVendor = new Map(rows.map((row) => [row.vendorId, row.value]));
+        if (perVendor.size < 2) {
+            metricsSkipped.push(metric);
+            continue;
+        }
+        metricsUsed.push(metric);
+        const logs = new Map([...perVendor].map(([vendorId, value]) => [vendorId, Math.log10(value + 1)]));
+        const values = [...logs.values()];
+        const lo = Math.min(...values);
+        const hi = Math.max(...values);
+        const span = hi - lo || 1;
+        const scores = new Map();
+        for (const [vendorId, log] of logs) {
+            scores.set(vendorId, { value: perVendor.get(vendorId), normalized: (log - lo) / span });
+        }
+        normalized.set(metric, scores);
+    }
+    metricsUsed.sort();
+    metricsSkipped.sort();
+    const vendors = config.vendors.map((vendor) => {
+        const coverage = [];
+        for (const metric of metricsUsed) {
+            const score = normalized.get(metric)?.get(vendor.id);
+            if (score)
+                coverage.push({ metric, value: score.value, normalized: Number(score.normalized.toFixed(4)) });
+        }
+        const index = coverage.length > 0
+            ? Number((coverage.reduce((sum, entry) => sum + entry.normalized, 0) / coverage.length).toFixed(4))
+            : null;
+        return { vendorId: vendor.id, index, coverage, signals: vendor.scaleSignals ?? [] };
+    });
+    return {
+        vendors,
+        metricsUsed,
+        metricsSkipped,
+        complete: vendors.every((vendor) => vendor.index !== null),
+    };
+}
+export function scaleReportToText(config, report) {
+    const names = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+    const lines = [];
+    lines.push(`Scale index (relative, within this ${config.vendors.length}-vendor set — not market share):`);
+    lines.push(`metrics used: ${report.metricsUsed.join(", ") || "none"}${report.metricsSkipped.length ? ` · skipped (single-vendor): ${report.metricsSkipped.join(", ")}` : ""}`);
+    lines.push("");
+    const ranked = [...report.vendors].sort((a, b) => (b.index ?? -1) - (a.index ?? -1));
+    for (const vendor of ranked) {
+        const idx = vendor.index === null ? "  n/a" : vendor.index.toFixed(2);
+        const cov = vendor.coverage.map((entry) => `${entry.metric}=${entry.value}`).join(", ") || "no signals";
+        lines.push(`  ${idx}  ${(names.get(vendor.vendorId) ?? vendor.vendorId).padEnd(22)} ${cov}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.19.0",
+  "version": "0.20.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",

package/src/cli.ts

@@ -52,6 +52,14 @@ import {
   type ObservationSet,
 } from "./market.ts";
 import { assessAxes, axesReportToText } from "./marketAxes.ts";
+import {
+  computeDirectives,
+  computeOverlayStats,
+  directivesToPlan,
+  overlayToMarkdown,
+  type CallDocument,
+} from "./marketOverlay.ts";
+import { computeScaleIndex, scaleReportToText } from "./marketScale.ts";
 import { buildWorksheet, classifyMarket } from "./marketClassify.ts";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
@@ -118,6 +126,8 @@ Usage:
   fullstackgtm market fronts [--run <label>] [--diff <prior-run>] [--json]
   fullstackgtm market axes [--run <label>] [--json]
   fullstackgtm market report [--run <label>] [--format md|html] [--out <path>]
+  fullstackgtm market overlay --snapshot <crm.json> [--calls <files>] [--save]
+  fullstackgtm market scale [--json]
   fullstackgtm market refresh [--run <label>] [--model m]
                                                the live competitive map: capture vendor pages (content-addressed),
                                                classify intensity per claim (LLM bring-your-own-key, or fill the
@@ -875,9 +885,24 @@ market worksheet --vendor <id> [--capture-run <label>] [--out <path>]
 market observe --from <observations.json> [--unverified]
 market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
 market axes [--config <path>] [--run <label>] [--json]
+market overlay --snapshot <crm.json> [--calls <parsed.json|manifest.json>]... [--prior-run <label>]
+               [--min-mentions N] [--promote-lift X] [--json] [--save --task-account <id>|--task-deal <id>]
+market scale [--config <path>] [--json]
 market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
 market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
 
+overlay is the directive layer: joins the map to YOUR CRM ground truth and
+emits OCCUPY / PROMOTE / URGENT / RETREAT directives, each carrying ≥1
+observation and ≥1 CRM statistic with its sample size. Claim mentions are
+deterministic word-boundary matches of each claim's "terms" against call
+documents (call parse output); small samples refuse to become strategy
+(--min-mentions, default 3). --save turns directives into approval-gated
+create_task operations through the normal plans → approve → apply gate.
+
+scale prints the relative scale index that sizes the report's bubbles when
+vendors carry scaleSignals (citable review counts / headcount / revenue —
+a within-set index, never "market share" unqualified).
+
 axes runs the axis-discovery math: PCA over the vendor × claim intensity
 matrix (PC1 = the category's primary axis, PC2 = the max-differentiation
 direction orthogonal to it), triangulation of configured axes against the
@@ -1089,8 +1114,90 @@ recomputed deterministically on every invocation — never stored.`);
     return;
   }
 
+  if (subcommand === "scale") {
+    const report = computeScaleIndex(config);
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(scaleReportToText(config, report));
+    return;
+  }
+
+  if (subcommand === "overlay") {
+    const set = await loadSet();
+    const snapshotPath = option(rest, "--snapshot");
+    if (!snapshotPath) {
+      throw new Error(
+        "market overlay requires --snapshot <canonical-snapshot.json> (fullstackgtm snapshot --out it first) — directives need CRM ground truth",
+      );
+    }
+    const snapshot = JSON.parse(readFileSync(resolve(process.cwd(), snapshotPath), "utf8")) as CanonicalGtmSnapshot;
+
+    // --calls accepts ParsedCall JSON files (from `call parse --out`) and/or
+    // manifest arrays [{path, dealId?}] linking calls to deals. Repeatable.
+    const documents: CallDocument[] = [];
+    const addParsedCall = (parsedPath: string, dealId?: string) => {
+      const parsed = JSON.parse(readFileSync(resolve(process.cwd(), parsedPath), "utf8")) as ParsedCall & {
+        segments?: Array<{ text?: string }>;
+      };
+      const text = [
+        ...(parsed.segments ?? []).map((segment) => segment.text ?? ""),
+        ...(parsed.insights ?? []).map((insight) => `${insight.text ?? ""} ${insight.evidence ?? ""}`),
+      ].join("\n");
+      documents.push({ id: parsed.id ?? parsedPath, text, dealId, occurredAt: parsed.evidence?.[0]?.capturedAt });
+    };
+    for (let i = 0; i < rest.length; i += 1) {
+      if (rest[i] !== "--calls") continue;
+      const callsPath = rest[i + 1];
+      if (!callsPath) throw new Error("--calls needs a path");
+      const raw = JSON.parse(readFileSync(resolve(process.cwd(), callsPath), "utf8"));
+      if (Array.isArray(raw)) {
+        for (const entry of raw as Array<{ path: string; dealId?: string }>) addParsedCall(entry.path, entry.dealId);
+      } else {
+        addParsedCall(callsPath);
+      }
+    }
+
+    const priorLabel = option(rest, "--prior-run");
+    const priorSet = priorLabel ? await store.get(priorLabel) : null;
+    if (priorLabel && !priorSet) throw new Error(`No observation run "${priorLabel}" for URGENT drift`);
+
+    const stats = computeOverlayStats(config, snapshot, documents);
+    const directives = computeDirectives(config, set, stats, {
+      minMentions: numericOption(rest, "--min-mentions") ?? undefined,
+      promoteLift: numericOption(rest, "--promote-lift") ?? undefined,
+      priorSet: priorSet ?? undefined,
+    });
+
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify({ stats, directives }, null, 2));
+      return;
+    }
+    console.log(overlayToMarkdown(stats, directives));
+
+    if (rest.includes("--save")) {
+      const taskAccount = option(rest, "--task-account");
+      const taskDeal = option(rest, "--task-deal");
+      if (!taskAccount && !taskDeal) {
+        throw new Error(
+          "--save needs --task-account <id> or --task-deal <id>: directives become approval-gated create_task operations, and the CRM needs a record to hang them on (your own company's account record works well)",
+        );
+      }
+      const plan = directivesToPlan(
+        config,
+        set,
+        directives,
+        taskDeal ? { objectType: "deal", objectId: taskDeal } : { objectType: "account", objectId: taskAccount as string },
+      );
+      const stored = await createFilePlanStore().save(plan);
+      console.log(`Saved plan ${stored.plan.id} (${directives.length} directive task(s); approve via \`plans approve\`)`);
+    }
+    return;
+  }
+
   throw new Error(
-    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, report, refresh)`,
+    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, overlay, scale, report, refresh)`,
   );
 }
 

package/src/index.ts

@@ -161,6 +161,7 @@ export {
   type ObservationConfidence,
   type ObservationSet,
   type ObservationStore,
+  type ScaleSignal,
   type SpanVerificationFailure,
 } from "./market.ts";
 export {
@@ -182,6 +183,21 @@ export {
   type ClassifyMarketResult,
   type MarketWorksheet,
 } from "./marketClassify.ts";
+export {
+  computeDirectives,
+  computeOverlayStats,
+  directivesToPlan,
+  overlayToMarkdown,
+  type CallDocument,
+  type ClaimMentionStats,
+  type DirectiveStat,
+  type DirectiveType,
+  type MarketDirective,
+  type OverlayOptions,
+  type OverlayStats,
+  type VendorMentionStats,
+} from "./marketOverlay.ts";
+export { computeScaleIndex, scaleReportToText, type ScaleReport, type VendorScale } from "./marketScale.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {

package/src/market.ts

@@ -38,6 +38,31 @@ export type MarketClaim = {
   pricingStructure: string;
   /** Operational definition: how a reader judges LOUD vs QUIET vs ABSENT. */
   definition: string;
+  /**
+   * Exact terms buyers use for this claim, for deterministic mention
+   * matching against call transcripts (the overlay). No terms = no mention
+   * stats for this claim; matching is word-boundary, case-insensitive.
+   */
+  terms?: string[];
+};
+
+/**
+ * One public, citable scale signal for a vendor (G2 review count, LinkedIn
+ * headcount, disclosed revenue, self-reported customer count). The composite
+ * of several biased-in-different-directions signals sizes the report's
+ * bubbles — a RELATIVE scale index within the mapped set, never "market
+ * share" unqualified.
+ */
+export type ScaleSignal = {
+  /** e.g. "g2_reviews", "linkedin_employees", "revenue_usd", "self_reported_customers". */
+  metric: string;
+  value: number;
+  unit: string;
+  sourceUrl: string;
+  /** Verbatim snippet containing the number — same evidence posture as observations. */
+  quote: string;
+  asOf: string;
+  caveat?: string;
 };
 
 export type MarketVendor = {
@@ -49,6 +74,10 @@ export type MarketVendor = {
     pricing: string | null;
     product: string[];
   };
+  /** Alternate names/spellings for deterministic mention matching. */
+  aliases?: string[];
+  /** Public scale signals; see ScaleSignal. */
+  scaleSignals?: ScaleSignal[];
   notes?: string;
 };