fullstackgtm 0.17.0 → 0.18.0

package/docs/api.md

@@ -58,7 +58,9 @@ release.
 ## CLI
 
 Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
-`apply`, `rules`, `profiles`, `doctor`.
+`apply`, `suggest`, `call` (`parse` / `score` / `link` / `plan`), `resolve`,
+`market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
+`axes` / `report` / `refresh`), `rules`, `profiles`, `doctor`.
 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.
 
@@ -78,7 +80,32 @@ deliverable in markdown or self-contained HTML: severity counts, prose summary,
 per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
 `auditReportToHtml` expose the same rendering programmatically.
 
+## Market map
+
+Newer surface (0.16–0.18); shapes are settling toward the 1.0 contract. A live
+model of the competitive category: claim taxonomy + vendor registry as a
+reviewable `market.config.json` (`MarketConfig`, `MarketClaim`, `MarketVendor`,
+`MarketAxis`), content-addressed page captures (`captureMarket`,
+`loadCaptureTexts`), append-only observations (`ObservationSet`,
+`MarketObservation`, `ObservationStore` / `createFileObservationStore` —
+profile-scoped under `<home>/market/<category>`), and deterministic
+derivations: `computeFrontStates` / `diffFrontStates` (front rule v1),
+`assessAxes` / `pcaTop2` / `axisPosition` (axis discovery), and
+`marketMapToMarkdown` / `marketMapToHtml` (the field report; renders the
+primary strategic 2×2 when `axes` / `primaryAxes` are configured).
+
+Intensity readings are proposals: `classifyMarket` (LLM, bring-your-own-key,
+provenance-marked) or `buildWorksheet` + `market observe` (agent/human). Every
+quoted evidence span is mechanically verified verbatim
+(`verifyEvidenceSpans`; whitespace and punctuation-spacing normalized) against
+the stored capture it cites before a set is accepted; failed captures read as
+`unobservable`, never `absent`.
+
 ## MCP
 
 Tools: `fullstackgtm_audit`, `fullstackgtm_rules`, `fullstackgtm_apply`
-(requires explicit `approvedOperationIds`). Input schemas are stable.
+(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/llms.txt

@@ -31,6 +31,22 @@ coaching scorecards; `call link` suggests the deal with confidence + reason;
 `call plan` proposes governed next-step writes through the standard
 approve/apply lifecycle.
 
+## Key invariants (market map)
+
+`fullstackgtm market` models the competitive category: vendors + claim
+taxonomy in `market.config.json`; `capture` stores vendor pages
+content-addressed; `classify` (BYO key, same ladder as calls) or
+`worksheet` + `observe` (agent/human channel) propose LOUD/QUIET/ABSENT
+intensity readings per vendor × claim. Every quoted evidence span is
+mechanically verified verbatim against the stored capture it cites;
+unverifiable quotes are rejected (`--unverified` only when captures live
+elsewhere). Failed captures read UNOBSERVABLE, never ABSENT. `fronts --diff`
+= deterministic front states + drift between runs; `axes` = PCA axis
+discovery + orthogonality screen; `report` = self-contained HTML field
+report; `refresh` = capture → classify → drift → report in one command.
+Storage is profile-scoped under `<home>/market/<category>`. MCP:
+`fullstackgtm_market_worksheet`, `fullstackgtm_market_observe`.
+
 ## Key invariants
 
 - Reads are safe by default; nothing is written without explicit `--approve`

package/package.json

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

@@ -51,6 +51,7 @@ import {
   verifyEvidenceSpans,
   type ObservationSet,
 } from "./market.ts";
+import { assessAxes, axesReportToText } from "./marketAxes.ts";
 import { buildWorksheet, classifyMarket } from "./marketClassify.ts";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
@@ -114,6 +115,7 @@ Usage:
   fullstackgtm market worksheet --vendor <id> [--out <path>]
   fullstackgtm market observe --from <observations.json> [--unverified]
   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 refresh [--run <label>] [--model m]
                                                the live competitive map: capture vendor pages (content-addressed),
@@ -857,9 +859,17 @@ market classify [--run <label>] [--capture-run <label>] [--vendor <id>] [--model
 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 report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
 market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
 
+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
+PCs, and an orthogonality screen (|r|>0.75 = one axis twice). Axes live in
+the config as claim-scoring rubrics; the report's strategic map and axis
+lab render from them.
+
 classify uses your Anthropic/OpenAI key (like call parse) to read the stored
 captures and propose intensity readings; worksheet is the no-key path (an
 agent or human fills it, submits via observe). Either way, every quoted span
@@ -1053,8 +1063,19 @@ recomputed deterministically on every invocation — never stored.`);
     return;
   }
 
+  if (subcommand === "axes") {
+    const set = await loadSet();
+    const report = assessAxes(config, set);
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(axesReportToText(report));
+    return;
+  }
+
   throw new Error(
-    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, report, refresh)`,
+    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, report, refresh)`,
   );
 }
 

package/src/index.ts

@@ -151,6 +151,7 @@ export {
   type ClaimIntensity,
   type FrontDrift,
   type FrontState,
+  type MarketAxis,
   type MarketClaim,
   type MarketConfig,
   type MarketObservation,
@@ -160,6 +161,18 @@ export {
   type ObservationStore,
   type SpanVerificationFailure,
 } from "./market.ts";
+export {
+  assessAxes,
+  axesReportToText,
+  axisPosition,
+  messageBreadth,
+  pcaTop2,
+  pearson,
+  type AxesReport,
+  type AxisAssessment,
+  type AxisPairing,
+  type PrincipalComponent,
+} from "./marketAxes.ts";
 export {
   buildWorksheet,
   classifyMarket,

package/src/market.ts

@@ -52,6 +52,19 @@ export type MarketVendor = {
   notes?: string;
 };
 
+export type MarketAxis = {
+  id: string;
+  label: string;
+  negativePole: string;
+  positivePole: string;
+  /** How a human scores a claim on this axis — the axis IS this rubric. */
+  rubric: string;
+  /** e.g. "validated", "proposal", "proposal (PC2-validated)". Reviewer-facing. */
+  status?: string;
+  /** claimId → score in [-1, 1]; null = the axis does not apply to this claim. */
+  claimScores: Record<string, number | null>;
+};
+
 export type MarketConfig = {
   category: string;
   anchorVendor?: string;
@@ -59,6 +72,10 @@ export type MarketConfig = {
   claims: MarketClaim[];
   /** The LOUD/QUIET/ABSENT/UNOBSERVABLE judging rule, stated for reviewers. */
   surfaceRule?: string;
+  /** Strategic axes as claim-scoring rubrics — config, not code. */
+  axes?: MarketAxis[];
+  /** [xAxisId, yAxisId] for the report's strategic map. */
+  primaryAxes?: [string, string];
 };
 
 export type MarketObservation = {
@@ -148,6 +165,27 @@ export function parseMarketConfig(raw: string): MarketConfig {
   if (config.anchorVendor && !config.vendors.some((v) => v.id === config.anchorVendor)) {
     throw new Error(`market config: anchorVendor "${config.anchorVendor}" is not in vendors`);
   }
+  if (config.axes) {
+    const claimIds = new Set(config.claims.map((claim) => claim.id));
+    const axisIds = new Set<string>();
+    for (const axis of config.axes) {
+      if (!axis.id) throw new Error("market config: axis missing id");
+      if (axisIds.has(axis.id)) throw new Error(`market config: duplicate axis id "${axis.id}"`);
+      axisIds.add(axis.id);
+      for (const claimId of Object.keys(axis.claimScores ?? {})) {
+        if (!claimIds.has(claimId)) {
+          throw new Error(`market config: axis "${axis.id}" scores unknown claim "${claimId}"`);
+        }
+      }
+    }
+    if (config.primaryAxes) {
+      if (config.primaryAxes.length !== 2 || config.primaryAxes.some((id) => !axisIds.has(id))) {
+        throw new Error(`market config: primaryAxes must name two configured axes (got ${JSON.stringify(config.primaryAxes)})`);
+      }
+    }
+  } else if (config.primaryAxes) {
+    throw new Error("market config: primaryAxes set but no axes configured");
+  }
   return config;
 }
 

package/src/marketAxes.ts

@@ -0,0 +1,268 @@
+import type { MarketAxis, MarketConfig, MarketObservation, ObservationSet } from "./market.ts";
+
+/**
+ * Axis discovery for a market map — the method that earns a strategic 2x2
+ * instead of asserting one. Axes are claim-scoring rubrics in the config
+ * (reviewable, versioned); a vendor's position on an axis is the
+ * intensity-weighted mean of the scores of claims it voices. Two checks keep
+ * axes honest, both computed deterministically from the stored observations:
+ *
+ *  1. Triangulation — PCA over the vendor × claim intensity matrix gives the
+ *     category's own top variance directions; a real axis correlates with a
+ *     principal component (it is derivable from the data, not just felt).
+ *  2. Orthogonality — two configured axes that correlate ≥ ~0.75 at the
+ *     vendor level are one axis twice. Sometimes that redundancy is the
+ *     finding: the category couples the two ideas, and the empty quadrant is
+ *     the strategic white space.
+ *
+ * Everything here is pure math over the store: same observations, same map.
+ */
+
+export const VOICE_WEIGHT: Record<string, number> = { loud: 1.0, quiet: 0.5 };
+
+/**
+ * Intensity-weighted mean of claim scores over claims the vendor voices.
+ * Claims scored null on the axis are excluded; returns null if the vendor
+ * voices nothing scoreable (e.g. fully unobservable).
+ */
+export function axisPosition(
+  vendorId: string,
+  claimScores: Record<string, number | null>,
+  observations: MarketObservation[],
+): number | null {
+  let num = 0;
+  let den = 0;
+  for (const obs of observations) {
+    if (obs.vendorId !== vendorId) continue;
+    const score = claimScores[obs.claimId];
+    if (score === null || score === undefined) continue;
+    const weight = VOICE_WEIGHT[obs.intensity] ?? 0;
+    if (weight > 0) {
+      num += score * weight;
+      den += weight;
+    }
+  }
+  return den > 0 ? num / den : null;
+}
+
+/** Share of the claim space voiced (loud + half-weight quiet) over observable claims. */
+export function messageBreadth(
+  vendorId: string,
+  observations: MarketObservation[],
+): { breadth: number | null; loudCount: number } {
+  let voiced = 0;
+  let observable = 0;
+  let loudCount = 0;
+  for (const obs of observations) {
+    if (obs.vendorId !== vendorId) continue;
+    if (obs.intensity === "unobservable") continue;
+    observable += 1;
+    voiced += VOICE_WEIGHT[obs.intensity] ?? 0;
+    if (obs.intensity === "loud") loudCount += 1;
+  }
+  return { breadth: observable > 0 ? voiced / observable : null, loudCount };
+}
+
+export function pearson(xs: number[], ys: number[]): number {
+  const n = xs.length;
+  if (n < 3) return 0;
+  const mx = xs.reduce((sum, x) => sum + x, 0) / n;
+  const my = ys.reduce((sum, y) => sum + y, 0) / n;
+  const sx = Math.sqrt(xs.reduce((sum, x) => sum + (x - mx) ** 2, 0));
+  const sy = Math.sqrt(ys.reduce((sum, y) => sum + (y - my) ** 2, 0));
+  if (!sx || !sy) return 0;
+  return xs.reduce((sum, x, i) => sum + (x - mx) * (ys[i] - my), 0) / (sx * sy);
+}
+
+// ---------------------------------------------------------------------------
+// PCA — power iteration over the column-centered vendor × claim weight
+// matrix. Pure and dependency-free; two components are all the canvas needs
+// (PC1 should recover the category's primary axis; PC2 is the
+// maximum-differentiation direction orthogonal to it).
+
+export type PrincipalComponent = {
+  /** claimId → loading. Sign is arbitrary; read poles from the extremes. */
+  loadings: Array<{ claimId: string; loading: number }>;
+  /** vendorId → score on this component. */
+  scores: Array<{ vendorId: string; score: number }>;
+};
+
+export function pcaTop2(
+  config: MarketConfig,
+  set: ObservationSet,
+): { vendors: string[]; pc1: PrincipalComponent; pc2: PrincipalComponent } {
+  const claimIds = config.claims.map((claim) => claim.id);
+  const byCell = new Map(set.observations.map((obs) => [`${obs.vendorId}|${obs.claimId}`, obs]));
+  // Exclude fully-unobservable vendors: they carry no information, only zeros.
+  const vendors = config.vendors
+    .map((vendor) => vendor.id)
+    .filter((vendorId) =>
+      claimIds.some((claimId) => {
+        const obs = byCell.get(`${vendorId}|${claimId}`);
+        return obs !== undefined && obs.intensity !== "unobservable";
+      }),
+    );
+
+  const matrix = vendors.map((vendorId) =>
+    claimIds.map((claimId) => VOICE_WEIGHT[byCell.get(`${vendorId}|${claimId}`)?.intensity ?? ""] ?? 0),
+  );
+  const means = claimIds.map((_, j) => matrix.reduce((sum, row) => sum + row[j], 0) / vendors.length);
+  const centered = matrix.map((row) => row.map((value, j) => value - means[j]));
+
+  const component = (deflate?: number[]): { loadings: number[]; scores: number[] } => {
+    let v = new Array<number>(claimIds.length).fill(1 / Math.sqrt(claimIds.length));
+    for (let iteration = 0; iteration < 300; iteration += 1) {
+      if (deflate) {
+        const dot = v.reduce((sum, x, k) => sum + x * deflate[k], 0);
+        v = v.map((x, k) => x - dot * deflate[k]);
+      }
+      const scores = centered.map((row) => row.reduce((sum, x, j) => sum + x * v[j], 0));
+      v = claimIds.map((_, j) => centered.reduce((sum, row, i) => sum + row[j] * scores[i], 0));
+      const norm = Math.sqrt(v.reduce((sum, x) => sum + x * x, 0)) || 1;
+      v = v.map((x) => x / norm);
+    }
+    return { loadings: v, scores: centered.map((row) => row.reduce((sum, x, j) => sum + x * v[j], 0)) };
+  };
+
+  const first = component();
+  const second = component(first.loadings);
+  const shape = (raw: { loadings: number[]; scores: number[] }): PrincipalComponent => ({
+    loadings: claimIds.map((claimId, j) => ({ claimId, loading: raw.loadings[j] })),
+    scores: vendors.map((vendorId, i) => ({ vendorId, score: raw.scores[i] })),
+  });
+  return { vendors, pc1: shape(first), pc2: shape(second) };
+}
+
+// ---------------------------------------------------------------------------
+// The axes report: positions, triangulation vs PCA, orthogonality screen.
+
+export type AxisVendorPosition = { vendorId: string; position: number | null };
+
+export type AxisAssessment = {
+  axis: MarketAxis;
+  positions: AxisVendorPosition[];
+  /** Standard deviation of placeable vendor positions — does the axis separate anyone? */
+  spread: number;
+  rVsPc1: number;
+  rVsPc2: number;
+};
+
+export type AxisPairing = {
+  aId: string;
+  bId: string;
+  r: number;
+  verdict: "near-orthogonal" | "correlated — weak pair" | "redundant — same axis twice";
+};
+
+export type AxesReport = {
+  vendors: string[];
+  pc1: PrincipalComponent;
+  pc2: PrincipalComponent;
+  assessments: AxisAssessment[];
+  /** Includes the derived breadth axis in pairings. */
+  pairings: AxisPairing[];
+};
+
+export function pairingVerdict(r: number): AxisPairing["verdict"] {
+  const magnitude = Math.abs(r);
+  if (magnitude < 0.4) return "near-orthogonal";
+  if (magnitude < 0.75) return "correlated — weak pair";
+  return "redundant — same axis twice";
+}
+
+export function assessAxes(config: MarketConfig, set: ObservationSet): AxesReport {
+  const { vendors, pc1, pc2 } = pcaTop2(config, set);
+  const pcScore = (pc: PrincipalComponent) => new Map(pc.scores.map((entry) => [entry.vendorId, entry.score]));
+  const pc1ByVendor = pcScore(pc1);
+  const pc2ByVendor = pcScore(pc2);
+
+  const axes = config.axes ?? [];
+  const positionsById = new Map<string, Map<string, number>>();
+  const assessments: AxisAssessment[] = axes.map((axis) => {
+    const positions: AxisVendorPosition[] = vendors.map((vendorId) => ({
+      vendorId,
+      position: axisPosition(vendorId, axis.claimScores, set.observations),
+    }));
+    const placeable = positions.filter((entry): entry is { vendorId: string; position: number } => entry.position !== null);
+    positionsById.set(axis.id, new Map(placeable.map((entry) => [entry.vendorId, entry.position])));
+    const values = placeable.map((entry) => entry.position);
+    const mean = values.reduce((sum, x) => sum + x, 0) / Math.max(values.length, 1);
+    const spread = Math.sqrt(values.reduce((sum, x) => sum + (x - mean) ** 2, 0) / Math.max(values.length, 1));
+    const aligned = placeable.filter((entry) => pc1ByVendor.has(entry.vendorId));
+    return {
+      axis,
+      positions,
+      spread,
+      rVsPc1: pearson(aligned.map((entry) => entry.position), aligned.map((entry) => pc1ByVendor.get(entry.vendorId) as number)),
+      rVsPc2: pearson(aligned.map((entry) => entry.position), aligned.map((entry) => pc2ByVendor.get(entry.vendorId) as number)),
+    };
+  });
+
+  // Derived breadth axis joins the orthogonality screen (it's free and often
+  // the only near-orthogonal partner early on).
+  const breadthPositions = new Map<string, number>();
+  for (const vendorId of vendors) {
+    const { breadth } = messageBreadth(vendorId, set.observations);
+    if (breadth !== null) breadthPositions.set(vendorId, breadth);
+  }
+  positionsById.set("breadth", breadthPositions);
+
+  const ids = [...axes.map((axis) => axis.id), "breadth"];
+  const pairings: AxisPairing[] = [];
+  for (let i = 0; i < ids.length; i += 1) {
+    for (let j = i + 1; j < ids.length; j += 1) {
+      const a = positionsById.get(ids[i]) as Map<string, number>;
+      const b = positionsById.get(ids[j]) as Map<string, number>;
+      const shared = vendors.filter((vendorId) => a.has(vendorId) && b.has(vendorId));
+      const r = pearson(shared.map((vendorId) => a.get(vendorId) as number), shared.map((vendorId) => b.get(vendorId) as number));
+      pairings.push({ aId: ids[i], bId: ids[j], r, verdict: pairingVerdict(r) });
+    }
+  }
+
+  return { vendors, pc1, pc2, assessments, pairings };
+}
+
+export function axesReportToText(report: AxesReport): string {
+  const lines: string[] = [];
+  for (const [label, pc] of [
+    ["PC1", report.pc1],
+    ["PC2", report.pc2],
+  ] as const) {
+    lines.push(`=== ${label} — claim loadings (extremes; sign is arbitrary, read the poles) ===`);
+    const ordered = [...pc.loadings].sort((a, b) => a.loading - b.loading);
+    for (const entry of ordered.slice(0, 5)) {
+      lines.push(`  ${entry.loading >= 0 ? "+" : ""}${entry.loading.toFixed(2)}  ${entry.claimId}`);
+    }
+    lines.push("   ...");
+    for (const entry of ordered.slice(-5)) {
+      lines.push(`  ${entry.loading >= 0 ? "+" : ""}${entry.loading.toFixed(2)}  ${entry.claimId}`);
+    }
+    lines.push(
+      `  vendor scores: ${[...pc.scores]
+        .sort((a, b) => a.score - b.score)
+        .map((entry) => `${entry.vendorId}=${entry.score >= 0 ? "+" : ""}${entry.score.toFixed(2)}`)
+        .join("  ")}`,
+    );
+    lines.push("");
+  }
+  if (report.assessments.length > 0) {
+    lines.push("=== configured axes vs PCA (triangulation: a real axis is derivable from the data) ===");
+    for (const assessment of report.assessments) {
+      lines.push(
+        `  ${assessment.axis.id.padEnd(20)} spread=${assessment.spread.toFixed(3)}  r(PC1)=${assessment.rVsPc1 >= 0 ? "+" : ""}${assessment.rVsPc1.toFixed(2)}  r(PC2)=${assessment.rVsPc2 >= 0 ? "+" : ""}${assessment.rVsPc2.toFixed(2)}  [${assessment.axis.status ?? ""}]`,
+      );
+    }
+    lines.push("");
+    lines.push("=== orthogonality screen (|r|>0.75 = redundant pair) ===");
+    for (const pairing of report.pairings) {
+      const flag = pairing.verdict === "redundant — same axis twice" ? "  <-- redundant" : "";
+      lines.push(
+        `  ${pairing.aId.padEnd(18)} x ${pairing.bId.padEnd(18)} r=${pairing.r >= 0 ? "+" : ""}${pairing.r.toFixed(2)}${flag}`,
+      );
+    }
+  } else {
+    lines.push("No axes configured. Read the PC loadings above, name the two directions, and add them");
+    lines.push("to market.config.json as axes: [{ id, label, negativePole, positivePole, rubric, claimScores }].");
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/marketReport.ts

@@ -6,6 +6,7 @@ import type {
   ObservationSet,
 } from "./market.ts";
 import { computeFrontStates } from "./market.ts";
+import { assessAxes, messageBreadth, type AxesReport } from "./marketAxes.ts";
 
 /**
  * Render a market map as a client-ready deliverable: markdown for terminals
@@ -104,6 +105,127 @@ export function marketMapToMarkdown(config: MarketConfig, set: ObservationSet):
   return `${lines.join("\n")}\n`;
 }
 
+type ScatterPoint = { vendorId: string; name: string; x: number; y: number; loud: number };
+type ScatterAxis = { label: string; negativePole: string; positivePole: string; signed: boolean };
+
+function svgScatter(
+  points: ScatterPoint[],
+  ax: ScatterAxis,
+  ay: ScatterAxis,
+  anchor: string | undefined,
+  mini: boolean,
+): string {
+  const W = mini ? 330 : 700;
+  const H = mini ? 250 : 460;
+  const PAD = mini ? 34 : 56;
+  const range = (axis: ScatterAxis, values: number[]): [number, number] => {
+    if (axis.signed) return [-1.1, 1.1];
+    if (values.length === 0) return [0, 1];
+    return [Math.min(0, Math.min(...values) - 0.05), Math.max(...values) + 0.08];
+  };
+  const [xLo, xHi] = range(ax, points.map((p) => p.x));
+  const [yLo, yHi] = range(ay, points.map((p) => p.y));
+  const sx = (x: number) => PAD + ((x - xLo) / (xHi - xLo)) * (W - 2 * PAD);
+  const sy = (y: number) => H - PAD - ((y - yLo) / (yHi - yLo)) * (H - 2 * PAD);
+  const fsLabel = mini ? 8.5 : 10.5;
+  const fsAx = mini ? 8 : 10;
+  const e = escapeHtml;
+  const dots = points
+    .map((p) => {
+      const r = mini ? 3 + p.loud * 0.8 : 6 + p.loud * 1.6;
+      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>`
+      );
+    })
+    .join("");
+  const midX = ax.signed ? `<line class="axis-mid" x1="${sx(0).toFixed(0)}" y1="${PAD}" x2="${sx(0).toFixed(0)}" y2="${H - PAD}"/>` : "";
+  const midY = ay.signed ? `<line class="axis-mid" x1="${PAD}" y1="${sy(0).toFixed(0)}" x2="${W - PAD}" y2="${sy(0).toFixed(0)}"/>` : "";
+  return `<svg viewBox="0 0 ${W} ${H}" role="img" aria-label="${e(ax.label)} vs ${e(ay.label)}">
+    <line class="axis" x1="${PAD}" y1="${H - PAD}" x2="${W - PAD}" y2="${H - PAD}"/>
+    <line class="axis" x1="${PAD}" y1="${PAD}" x2="${PAD}" y2="${H - PAD}"/>${midX}${midY}
+    <text class="ax-label" style="font-size:${fsAx}px" x="${PAD}" y="${H - 14}">&#8592; ${e(ax.negativePole)}</text>
+    <text class="ax-label" style="font-size:${fsAx}px" x="${W - PAD}" y="${H - 14}" text-anchor="end">${e(ax.positivePole)} &#8594;</text>
+    <text class="ax-label" style="font-size:${fsAx}px" x="${PAD}" y="${PAD - 10}">&#8593; ${e(ay.positivePole)}${ay.signed ? ` &#183; &#8595; ${e(ay.negativePole)}` : ""}</text>
+    ${dots}</svg>`;
+}
+
+function axisSectionsHtml(
+  config: MarketConfig,
+  set: ObservationSet,
+): { strategicMap: string; report: AxesReport | null } {
+  const axes = config.axes ?? [];
+  if (axes.length === 0) return { strategicMap: "", report: null };
+  const e = escapeHtml;
+  const report = assessAxes(config, set);
+  const vendorNames = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+  const loudCounts = new Map(report.vendors.map((vendorId) => [vendorId, messageBreadth(vendorId, set.observations).loudCount]));
+
+  const breadthAxis: ScatterAxis & { id: string } = {
+    id: "breadth",
+    label: "Message breadth",
+    negativePole: "FOCUSED",
+    positivePole: "BROAD (share of claims voiced)",
+    signed: false,
+  };
+  const axisInfo = new Map<string, ScatterAxis & { id: string }>([
+    ...axes.map((axis) => [axis.id, { id: axis.id, label: axis.label, negativePole: axis.negativePole, positivePole: axis.positivePole, signed: true }] as const),
+    [breadthAxis.id, breadthAxis],
+  ]);
+  const positions = new Map<string, Map<string, number>>();
+  for (const assessment of report.assessments) {
+    positions.set(
+      assessment.axis.id,
+      new Map(
+        assessment.positions
+          .filter((entry): entry is { vendorId: string; position: number } => entry.position !== null)
+          .map((entry) => [entry.vendorId, entry.position]),
+      ),
+    );
+  }
+  const breadthMap = new Map<string, number>();
+  for (const vendorId of report.vendors) {
+    const { breadth } = messageBreadth(vendorId, set.observations);
+    if (breadth !== null) breadthMap.set(vendorId, breadth);
+  }
+  positions.set("breadth", breadthMap);
+
+  const pointsFor = (xId: string, yId: string): ScatterPoint[] => {
+    const xs = positions.get(xId);
+    const ys = positions.get(yId);
+    if (!xs || !ys) return [];
+    return report.vendors
+      .filter((vendorId) => xs.has(vendorId) && ys.has(vendorId))
+      .map((vendorId) => ({
+        vendorId,
+        name: vendorNames.get(vendorId) ?? vendorId,
+        x: xs.get(vendorId) as number,
+        y: ys.get(vendorId) as number,
+        loud: loudCounts.get(vendorId) ?? 0,
+      }));
+  };
+
+  const [px, py] = config.primaryAxes ?? [axes[0].id, axes[1]?.id ?? "breadth"];
+  const axInfo = axisInfo.get(px) as ScatterAxis & { id: string };
+  const ayInfo = axisInfo.get(py) as ScatterAxis & { id: string };
+  const statusOf = (id: string) => axes.find((axis) => axis.id === id)?.status ?? (id === "breadth" ? "derived" : "");
+  const strategicMap = `<section>
+  <h2><span class="no">03</span> Strategic map — ${e(axInfo.label)} &#215; ${e(ayInfo.label)}</h2>
+  <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>
+  </figure>
+</section>`;
+
+  // Deliberately no axis-pairing gallery here: the report is the client-facing
+  // artifact, best foot forward — one earned 2x2. Axis exploration (PCA,
+  // triangulation, the orthogonality screen over every pairing) lives in
+  // `market axes` for the analyst or agent doing the iterating.
+  return { strategicMap, report };
+}
+
 export function marketMapToHtml(config: MarketConfig, set: ObservationSet): string {
   const model = buildModel(config, set);
   const stateByClaim = new Map(model.fronts.map((front) => [front.claimId, front.state]));
@@ -113,6 +235,8 @@ export function marketMapToHtml(config: MarketConfig, set: ObservationSet): stri
   const unobservable = set.observations.filter((obs) => obs.intensity === "unobservable").length;
   const anchor = config.anchorVendor;
   const e = escapeHtml;
+  const axisHtml = axisSectionsHtml(config, set);
+  const appendixNo = axisHtml.report ? "04" : "03";
 
   const matrixRows = model.orderedClaimIds
     .map((claimId) => {
@@ -223,6 +347,14 @@ tr.front-open th .claim-cap { color:var(--accent); font-weight:600; }
 .ev-head { font-size:10.5px; letter-spacing:.1em; color:var(--accent); }
 .ev blockquote { font-style:italic; margin:6px 0; font-size:13.5px; line-height:1.5; }
 .ev-src { font-size:10px; color:var(--ink-soft); word-break:break-all; }
+figure { margin-top:22px; border:1px solid var(--line); background:rgba(255,255,255,.35); }
+.axis { stroke:var(--ink); stroke-width:1.5; }
+.axis-mid { stroke:var(--line); stroke-dasharray:3 5; }
+.ax-label { letter-spacing:.16em; fill:var(--ink-soft); font-family:"SF Mono",Menlo,Consolas,monospace; }
+.dot { fill:rgba(33,29,22,.78); }
+.dot-anchor { fill:var(--green); stroke:var(--ink); stroke-width:1.5; }
+.dot-label { fill:var(--ink); text-anchor:middle; letter-spacing:.04em; font-family:"SF Mono",Menlo,Consolas,monospace; }
+figcaption { font-size:12px; color:var(--ink-soft); padding:12px 16px 14px; font-style:italic; border-top:1px solid var(--line); line-height:1.5; }
 footer { margin-top:72px; border-top:3px double var(--ink); padding-top:14px; font-size:11px; color:var(--ink-soft);
   display:flex; justify-content:space-between; gap:20px; flex-wrap:wrap; }
 @media print { body { max-width:none; padding:0 8mm; background:white; } section { break-inside:avoid-page; } tr { break-inside:avoid; } }
@@ -260,8 +392,9 @@ footer { margin-top:72px; border-top:3px double var(--ink); padding-top:14px; fo
     <tbody>${matrixRows}</tbody>
   </table>
 </section>
+${axisHtml.strategicMap}
 <section>
-  <h2><span class="no">03</span> Evidence appendix</h2>
+  <h2><span class="no">${appendixNo}</span> Evidence appendix</h2>
   ${appendix}
 </section>
 <footer>