fullstackgtm 0.19.0 → 0.21.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,21 @@ 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());
+    // Bubble areas stay proportional to the metric; dividing by the max just
+    // spends the full visual range without distorting any ratio.
+    const maxShare = Math.max(1e-9, ...report.vendors.map((vendorId) => scaleIndex.get(vendorId) ?? 0));
+    const sizeOf = (vendorId) => useScale ? scaleIndex.get(vendorId) / maxShare : (loudCounts.get(vendorId) ?? 0) / maxLoud;
+    const sizeCaption = useScale
+        ? `Dot area &#8733; estimated revenue share of this vendor set (signals: ${e(scale.metricsUsed.join(", "))}; calibrated within-set, ACV-band stratified, citable but NOT audited — see \`market scale\` for estimates and spreads)`
+        : "Dot area &#8733; LOUD count";
     const breadthAxis = {
         id: "breadth",
         label: "Message breadth",
@@ -158,7 +174,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 +186,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,71 @@
+import type { MarketConfig, ScaleSignal } from "./market.ts";
+/**
+ * Relative scale estimation over the mapped vendor set — v2, dimensional.
+ *
+ * v1 normalized every signal onto [0,1] and averaged, which quietly mixed
+ * dimensions: review/customer counts proxy CUSTOMER COUNT (N), while
+ * employees and revenue proxy REVENUE (N × ACV). Averaging the two inflates
+ * many-small-customer vendors against few-big-customer ones — the SMB bias.
+ *
+ * v2 converts every signal into REVENUE SPACE before combining:
+ *
+ *   1. Signals are classed by dimension: revenue (used directly),
+ *      headcount (× revenue-per-employee), customers (× revenue-per-customer).
+ *   2. Conversion ratios are CALIBRATED within the set, per metric, as the
+ *      median ratio over vendors that have both the metric and a revenue
+ *      signal — and customer-dimension ratios are stratified by each
+ *      vendor's `acvBand` (smb / mid / enterprise), because revenue-per-
+ *      review spans ~75× between SMB tools and enterprise suites. A band
+ *      without calibration pairs falls back to the global median; a metric
+ *      with no pairs anywhere is unusable and reported as skipped.
+ *   3. A vendor's estimated revenue is the weighted geometric mean of its
+ *      per-signal estimates (revenue weight 3, headcount 2, customers 1 —
+ *      reliability order), with an uncertainty band = max/min estimate
+ *      ratio, reported, never hidden.
+ *   4. index = share of the set's summed estimated revenue; bubbles render
+ *      area-proportional to it. Labeled "estimated revenue share" with the
+ *      calibration disclosed — still never "market share" unqualified:
+ *      it is revenue share OF THE MAPPED SET, from citable-but-unaudited
+ *      signals.
+ *
+ * Deterministic and auditable end to end: same config, same estimates.
+ */
+export type ScaleDimension = "revenue" | "headcount" | "customers";
+export declare function dimensionForMetric(metric: string): ScaleDimension;
+export type SignalEstimate = {
+    metric: string;
+    dimension: ScaleDimension;
+    rawValue: number;
+    /** Revenue-per-unit ratio applied (1 for revenue signals); null = unusable. */
+    ratio: number | null;
+    estimatedRevenue: number | null;
+    /** What calibrated the ratio: "direct", "band:<name>", "global", "fallback". */
+    calibration: string;
+};
+export type VendorScale = {
+    vendorId: string;
+    acvBand?: string;
+    estimates: SignalEstimate[];
+    /** Weighted geometric mean of usable estimates; null with no usable signals. */
+    estimatedRevenue: number | null;
+    /** max/min across usable estimates — 1 = perfect agreement among signals. */
+    uncertainty: number | null;
+    /** Share of the set's summed estimated revenue; drives bubble area. */
+    index: number | null;
+    signals: ScaleSignal[];
+};
+export type ScaleReport = {
+    vendors: VendorScale[];
+    metricsUsed: string[];
+    metricsSkipped: string[];
+    /** Calibrated ratios for the appendix: metric × stratum → revenue-per-unit. */
+    calibrations: Array<{
+        metric: string;
+        stratum: string;
+        revenuePerUnit: number;
+        pairs: number;
+    }>;
+    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,168 @@
+const DIMENSION_WEIGHT = { revenue: 3, headcount: 2, customers: 1 };
+/** Used only when headcount has zero calibration pairs in the whole set. */
+const FALLBACK_REVENUE_PER_EMPLOYEE = 200_000;
+export function dimensionForMetric(metric) {
+    const name = metric.toLowerCase();
+    if (name.includes("revenue") || name.includes("arr"))
+        return "revenue";
+    if (name.includes("employee") || name.includes("headcount"))
+        return "headcount";
+    return "customers"; // reviews, customers, installs — count-of-customers proxies
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+export function computeScaleIndex(config) {
+    const rows = [];
+    for (const vendor of config.vendors) {
+        for (const signal of vendor.scaleSignals ?? []) {
+            if (!Number.isFinite(signal.value) || signal.value <= 0)
+                continue;
+            rows.push({
+                vendorId: vendor.id,
+                band: vendor.acvBand ?? "unknown",
+                metric: signal.metric,
+                dimension: signal.dimension ?? dimensionForMetric(signal.metric),
+                value: signal.value,
+            });
+        }
+    }
+    // A vendor's reference revenue for calibration: median of its revenue signals.
+    const revenueByVendor = new Map();
+    for (const vendor of config.vendors) {
+        const revenues = rows
+            .filter((row) => row.vendorId === vendor.id && row.dimension === "revenue")
+            .map((row) => row.value);
+        if (revenues.length > 0)
+            revenueByVendor.set(vendor.id, median(revenues));
+    }
+    // Per-metric calibration. Customer-dimension metrics stratify by acvBand;
+    // headcount calibrates globally (revenue-per-employee is the most stable
+    // ratio in B2B software, which is also why headcount outweighs customers).
+    const calibrations = [];
+    const ratioFor = new Map();
+    const nonRevenueMetrics = [...new Set(rows.filter((row) => row.dimension !== "revenue").map((row) => row.metric))].sort();
+    for (const metric of nonRevenueMetrics) {
+        const pairs = rows
+            .filter((row) => row.metric === metric && revenueByVendor.has(row.vendorId))
+            .map((row) => ({ band: row.band, ratio: revenueByVendor.get(row.vendorId) / row.value }));
+        const byBand = new Map();
+        if (dimensionForMetric(metric) === "customers") {
+            for (const band of [...new Set(pairs.map((pair) => pair.band))]) {
+                const bandRatios = pairs.filter((pair) => pair.band === band).map((pair) => pair.ratio);
+                if (bandRatios.length >= 1) {
+                    byBand.set(band, median(bandRatios));
+                    calibrations.push({ metric, stratum: `band:${band}`, revenuePerUnit: Math.round(median(bandRatios)), pairs: bandRatios.length });
+                }
+            }
+        }
+        const global = pairs.length > 0 ? median(pairs.map((pair) => pair.ratio)) : null;
+        if (global !== null)
+            calibrations.push({ metric, stratum: "global", revenuePerUnit: Math.round(global), pairs: pairs.length });
+        ratioFor.set(metric, { global, byBand });
+    }
+    const metricsUsed = new Set();
+    const metricsSkipped = new Set();
+    const vendors = config.vendors.map((vendor) => {
+        const vendorRows = rows.filter((row) => row.vendorId === vendor.id);
+        const estimates = vendorRows.map((row) => {
+            if (row.dimension === "revenue") {
+                metricsUsed.add(row.metric);
+                return { metric: row.metric, dimension: row.dimension, rawValue: row.value, ratio: 1, estimatedRevenue: row.value, calibration: "direct" };
+            }
+            const calibration = ratioFor.get(row.metric);
+            let ratio = null;
+            let stratum = "fallback";
+            if (calibration) {
+                if (row.dimension === "customers" && calibration.byBand.has(row.band)) {
+                    ratio = calibration.byBand.get(row.band);
+                    stratum = `band:${row.band}`;
+                }
+                else if (calibration.global !== null) {
+                    ratio = calibration.global;
+                    stratum = "global";
+                }
+            }
+            if (ratio === null && row.dimension === "headcount") {
+                ratio = FALLBACK_REVENUE_PER_EMPLOYEE;
+                stratum = "fallback";
+            }
+            if (ratio === null) {
+                metricsSkipped.add(row.metric);
+                return { metric: row.metric, dimension: row.dimension, rawValue: row.value, ratio: null, estimatedRevenue: null, calibration: "uncalibratable" };
+            }
+            metricsUsed.add(row.metric);
+            return { metric: row.metric, dimension: row.dimension, rawValue: row.value, ratio, estimatedRevenue: row.value * ratio, calibration: stratum };
+        });
+        const usable = estimates.filter((estimate) => estimate.estimatedRevenue !== null);
+        let estimatedRevenue = null;
+        let uncertainty = null;
+        if (usable.length > 0) {
+            let weightSum = 0;
+            let logSum = 0;
+            for (const estimate of usable) {
+                const weight = DIMENSION_WEIGHT[estimate.dimension];
+                weightSum += weight;
+                logSum += weight * Math.log(estimate.estimatedRevenue);
+            }
+            estimatedRevenue = Math.exp(logSum / weightSum);
+            const values = usable.map((estimate) => estimate.estimatedRevenue);
+            uncertainty = Number((Math.max(...values) / Math.min(...values)).toFixed(2));
+        }
+        return {
+            vendorId: vendor.id,
+            acvBand: vendor.acvBand,
+            estimates,
+            estimatedRevenue,
+            uncertainty,
+            index: null,
+            signals: vendor.scaleSignals ?? [],
+        };
+    });
+    const total = vendors.reduce((sum, vendor) => sum + (vendor.estimatedRevenue ?? 0), 0);
+    for (const vendor of vendors) {
+        vendor.index = vendor.estimatedRevenue !== null && total > 0 ? Number((vendor.estimatedRevenue / total).toFixed(4)) : null;
+    }
+    return {
+        vendors,
+        metricsUsed: [...metricsUsed].sort(),
+        metricsSkipped: [...metricsSkipped].filter((metric) => !metricsUsed.has(metric)).sort(),
+        calibrations,
+        complete: vendors.every((vendor) => vendor.index !== null),
+    };
+}
+function money(value) {
+    if (value >= 1e9)
+        return `$${(value / 1e9).toFixed(1)}B`;
+    if (value >= 1e6)
+        return `$${(value / 1e6).toFixed(1)}M`;
+    return `$${Math.round(value / 1e3)}K`;
+}
+export function scaleReportToText(config, report) {
+    const names = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+    const lines = [];
+    lines.push(`Estimated revenue share (of this ${config.vendors.length}-vendor set; calibrated from citable signals, NOT audited):`);
+    lines.push(`metrics: ${report.metricsUsed.join(", ") || "none"}${report.metricsSkipped.length ? ` · uncalibratable: ${report.metricsSkipped.join(", ")}` : ""}`);
+    lines.push("");
+    const ranked = [...report.vendors].sort((a, b) => (b.estimatedRevenue ?? -1) - (a.estimatedRevenue ?? -1));
+    for (const vendor of ranked) {
+        if (vendor.estimatedRevenue === null) {
+            lines.push(`   n/a  ${(names.get(vendor.vendorId) ?? vendor.vendorId).padEnd(22)} no usable signals`);
+            continue;
+        }
+        const share = `${((vendor.index ?? 0) * 100).toFixed(1)}%`.padStart(6);
+        const spread = vendor.uncertainty !== null && vendor.uncertainty > 1 ? ` (×${vendor.uncertainty.toFixed(1)} signal spread)` : "";
+        lines.push(`${share}  ${(names.get(vendor.vendorId) ?? vendor.vendorId).padEnd(22)} ~${money(vendor.estimatedRevenue)}${spread}  [${vendor.estimates
+            .filter((estimate) => estimate.estimatedRevenue !== null)
+            .map((estimate) => `${estimate.metric}→${money(estimate.estimatedRevenue)}`)
+            .join(", ")}]`);
+    }
+    lines.push("");
+    lines.push("calibrations (median revenue-per-unit):");
+    for (const calibration of report.calibrations) {
+        lines.push(`  ${calibration.metric.padEnd(26)} ${calibration.stratum.padEnd(16)} ${money(calibration.revenuePerUnit)}/unit (${calibration.pairs} pair${calibration.pairs === 1 ? "" : "s"})`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.19.0",
+  "version": "0.21.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,29 @@ 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,
+  dimensionForMetric,
+  scaleReportToText,
+  type ScaleDimension,
+  type ScaleReport,
+  type SignalEstimate,
+  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,37 @@ 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;
+  /**
+   * What the signal proxies: revenue (used directly), headcount, or
+   * customers (count-of-customers proxies like reviews). Inferred from the
+   * metric name when omitted; set explicitly for unusual metrics.
+   */
+  dimension?: "revenue" | "headcount" | "customers";
 };
 
 export type MarketVendor = {
@@ -49,6 +80,18 @@ export type MarketVendor = {
     pricing: string | null;
     product: string[];
   };
+  /** Alternate names/spellings for deterministic mention matching. */
+  aliases?: string[];
+  /** Public scale signals; see ScaleSignal. */
+  scaleSignals?: ScaleSignal[];
+  /**
+   * ACV stratum ("smb" | "mid" | "enterprise" by convention) used to
+   * calibrate customer-count → revenue conversion in the scale index.
+   * Revenue-per-customer differs ~75× between SMB tools and enterprise
+   * suites; stratifying kills the many-small-customers bias. Usually
+   * obvious from the vendor's own pricing page (which the map captures).
+   */
+  acvBand?: string;
   notes?: string;
 };