fullstackgtm 0.47.0 → 0.48.0

package/src/cli/help.ts

@@ -50,6 +50,12 @@ Usage:
   fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]
                                                the create gate: exit 0 = safe to create, exit 2 = match
                                                found (exists/ambiguous) — call before ANY record creation
+  fullstackgtm route leads [source options] [--match domain|company|both] [--no-inherit-owner] [--reassign-owned] [--policy <json|path>] [--save|--json|--out <path>]
+                                               lead-to-account matching + owner routing as a governed plan
+  fullstackgtm hierarchy report [source options] [--json|--out <path>]
+                                               account hierarchy view from native parents + subdomains
+  fullstackgtm relationships account (--account-id <id>|--domain <d>) [source options] [--json|--out <path>]
+                                               relationship map from contacts, deals, and activity evidence
   fullstackgtm market init --category <name>   start a market map: vendors + claim taxonomy as reviewable config
   fullstackgtm market capture [--config <path>] [--run <label>]
   fullstackgtm market classify [--run <label>] [--vendor <id>] [--model m] [--out <path>]
@@ -420,7 +426,32 @@ export const HELP: Record<string, HelpEntry> = {
     seeAlso: ["dedupe", "audit"],
   },
 
+  hierarchy: {
+    summary: "account hierarchy report (native parents + subdomain inference)",
+    phase: "Prevent",
+    synopsis: ["fullstackgtm hierarchy report [source options] [--json|--out <path>]"],
+    detail:
+      "Builds a report-only account tree from provider-native parent ids (when present in raw payloads) and deterministic subdomain inference. It surfaces duplicate-domain and ambiguous-parent conflicts instead of guessing writes.",
+    seeAlso: ["route", "relationships"],
+  },
+  relationships: {
+    summary: "relationship map for an account from contacts/deals/activity evidence",
+    phase: "Prevent",
+    synopsis: ["fullstackgtm relationships account (--account-id <id>|--domain <d>) [source options] [--json|--out <path>]"],
+    detail:
+      "Builds a stakeholder map with inferred buyer roles, sentiment from activity subjects, open deals, and missing-role gaps. Read-only evidence surface; no CRM writes.",
+    seeAlso: ["call", "route"],
+  },
+
   // Remediate — governed writes (all produce plans; nothing writes outside approve → apply)
+  route: {
+    summary: "lead-to-account matching and owner routing plan",
+    phase: "Remediate",
+    synopsis: ["fullstackgtm route leads [source options] [--match domain|company|both] [--no-inherit-owner] [--reassign-owned] [--policy <json|path>] [--save|--json|--out <path>]"],
+    detail:
+      "Matches contact-shaped leads to accounts by domain and/or company name, inherits account owners (or applies an assignment policy), and emits every change as a dry-run patch plan for approve → apply. Ambiguous matches are surfaced, never guessed.",
+    seeAlso: ["resolve", "reassign"],
+  },
   fix: {
     summary: "one-shot composite: audit one rule → suggest → approve → apply",
     phase: "Remediate",
@@ -615,15 +646,65 @@ export const HELP: Record<string, HelpEntry> = {
 // `--help` to themselves, so commandHelp() only renders these via `help <verb>`.
 export const BESPOKE_HELP = ["init", "call", "market", "tam", "enrich", "bulk-update", "schedule", "signals", "icp", "draft"];
 
+export const GLOBAL_FLAGS = ["--help", "--full"];
+export const GLOBAL_SHORT_FLAGS = ["-h"];
+export const SOURCE_FLAGS = ["--provider", "--token-env", "--input", "--demo", "--sample", "--seed", "--today"];
+export const AUDIT_FLAGS = ["--config", "--rules", "--stale-days", "--fail-on", "--save", "--dry-run", "--json", "--out", "--full"];
+
+// Complete per-command flag registry used by runCli's fail-closed flag
+// validation. Keep this next to HELP so focused help, machine capabilities,
+// and the parser safety gate have one command inventory to reconcile against.
+export const COMMAND_FLAGS: Record<string, string[]> = {
+  init: ["--source", "--provider", "--out", "--force"],
+  login: ["--via", "--hosted", "--private-token", "--token", "--key", "--api-key", "--client-id", "--client-secret", "--scopes", "--port", "--oauth", "--device", "--instance-url", "--login-url", "--no-validate"],
+  logout: [],
+  doctor: ["--json"],
+  capabilities: ["--json"],
+  "robot-docs": [],
+  profiles: ["--json"],
+  health: ["--json"],
+  snapshot: [...SOURCE_FLAGS, "--since", "--out", "--archive"],
+  audit: [...SOURCE_FLAGS, ...AUDIT_FLAGS],
+  report: [...SOURCE_FLAGS, ...AUDIT_FLAGS, "--plan", "--client", "--title", "--prepared-by", "--format", "--max-examples"],
+  diff: ["--before", "--after", "--config", "--stale-days", "--today", "--json", "--fail-on-new-findings"],
+  rules: ["--config", "--json"],
+  resolve: [...SOURCE_FLAGS, "--name", "--domain", "--email", "--account-id", "--json"],
+  hierarchy: [...SOURCE_FLAGS, "--json", "--out"],
+  relationships: [...SOURCE_FLAGS, "--account-id", "--domain", "--json", "--out"],
+  route: [...SOURCE_FLAGS, "--match", "--no-inherit-owner", "--reassign-owned", "--policy", "--reason", "--max-operations", "--save", "--dry-run", "--json", "--out"],
+  fix: [...SOURCE_FLAGS, "--config", "--rule", "--provider", "--min-confidence", "--include-creates", "--yes", "--confirm", "--dry-run"],
+  "bulk-update": [...SOURCE_FLAGS, "--where", "--set", "--guard", "--require", "--create-task", "--archive", "--force-archive-duplicates", "--reason", "--max-operations", "--save", "--dry-run", "--json", "--out"],
+  dedupe: [...SOURCE_FLAGS, "--key", "--keep", "--reason", "--max-operations", "--save", "--dry-run", "--json", "--out"],
+  reassign: [...SOURCE_FLAGS, "--from", "--assign-unowned", "--to", "--objects", "--where", "--except-deal-stage", "--include-closed-deals", "--reason", "--max-operations", "--save", "--dry-run", "--json", "--out"],
+  backfill: [...SOURCE_FLAGS, "--since", "--pipeline", "--match-property", "--skip-unmatched", "--save", "--dry-run", "--json"],
+  enrich: [...SOURCE_FLAGS, "--config", "--source", "--icp", "--input", "--provider", "--stale-days", "--assign-owner", "--objects", "--max", "--staged-run", "--run-label", "--label", "--runs", "--save", "--dry-run", "--json", "--out"],
+  call: [...SOURCE_FLAGS, "--transcript", "--title", "--source", "--model", "--deterministic", "--heuristics", "--llm", "--json", "--ndjson", "--out", "--call", "--call-type", "--rubric", "--list", "--list-rubrics", "--attendees", "--domain", "--deal", "--save", "--dry-run"],
+  suggest: [...SOURCE_FLAGS, "--plan-id", "--plan", "--json", "--out"],
+  plans: ["--status", "--operations", "--value", "--values-from", "--min-confidence", "--include-creates", "--json"],
+  apply: ["--plan", "--plan-id", "--provider", "--channel", "--token-env", "--approve", "--value", "--json", "--config"],
+  "audit-log": ["--in", "--out", "--json"],
+  merge: ["--input", "--out", "--json"],
+  market: ["--category", "--config", "--vendor", "--snapshot", "--task-account", "--task-deal", "--capture-run", "--run", "--prior-run", "--diff", "--from", "--calls", "--anchor", "--min-mentions", "--max-claims", "--promote-lift", "--model", "--format", "--auto", "--unverified", "--save", "--dry-run", "--json", "--out"],
+  tam: [...SOURCE_FLAGS, "--source", "--name", "--icp", "--accounts", "--acv", "--acv-basis", "--acv-from-crm", "--deal-period", "--buyers-per-account", "--cross-checks", "--max", "--max-credits", "--usd-per-credit", "--dry-run", "--confirm", "--cron", "--label", "--save", "--json", "--out"],
+  icp: [...SOURCE_FLAGS, "--name", "--signals-from", "--with-history", "--prompt", "--min-score", "--from-judge", "--golden", "--against-outcomes", "--min-accuracy", "--model", "--label", "--save", "--json", "--out"],
+  signals: ["--bucket", "--source", "--connector", "--connector-opt", "--watchlist", "--keywords", "--from", "--label", "--since", "--account", "--contact", "--unjudged", "--touch", "--result", "--save", "--json", "--explain"],
+  draft: ["--from-judge", "--min-score", "--prompt", "--model", "--channel", "--save", "--dry-run", "--json", "--out"],
+  schedule: ["--cron", "--label", "--provider", "--trigger", "--runs", "--json"],
+};
+
+export const FLAGS_WITH_VALUES = new Set([
+  "--account", "--account-id", "--accounts", "--acv", "--acv-basis", "--after", "--anchor", "--api-key", "--approve", "--archive", "--assign-owner", "--attendees", "--before", "--bucket", "--buyers-per-account", "--call", "--call-type", "--calls", "--capture-run", "--category", "--channel", "--client", "--client-id", "--client-secret", "--config", "--connector", "--connector-opt", "--contact", "--cron", "--cross-checks", "--deal", "--deal-period", "--diff", "--domain", "--email", "--except-deal-stage", "--format", "--from", "--from-judge", "--golden", "--guard", "--icp", "--in", "--input", "--instance-url", "--keep", "--key", "--keywords", "--label", "--login-url", "--match", "--match-property", "--max", "--max-claims", "--max-credits", "--max-examples", "--max-operations", "--min-accuracy", "--min-confidence", "--min-mentions", "--min-score", "--model", "--name", "--objects", "--operations", "--out", "--pipeline", "--plan", "--plan-id", "--policy", "--port", "--prepared-by", "--prior-run", "--profile", "--promote-lift", "--prompt", "--provider", "--reason", "--require", "--result", "--rubric", "--rule", "--rules", "--run", "--run-label", "--runs", "--scopes", "--seed", "--set", "--signals-from", "--since", "--snapshot", "--source", "--staged-run", "--stale-days", "--status", "--task-account", "--task-deal", "--title", "--to", "--today", "--token", "--token-env", "--touch", "--transcript", "--trigger", "--usd-per-credit", "--value", "--values-from", "--vendor", "--via", "--watchlist", "--where",
+]);
+
 // Lifecycle-grouped front door. One line per verb, organized by the
 // Prevent→Detect→Remediate→Verify loop so a new user sees ~6 jobs, not 22 verbs.
 export function shortUsage() {
   const groups: Array<[string, string[]]> = [
     ["Get started", ["init"]],
     ["Setup & health", ["login", "logout", "doctor", "capabilities", "robot-docs", "profiles", "health"]],
-    ["Detect — read-only", ["audit", "report", "snapshot", "diff", "rules"]],
+    ["Detect — read-only", ["audit", "report", "snapshot", "diff", "rules", "hierarchy", "relationships"]],
     ["Prevent — gate writes", ["resolve"]],
-    ["Remediate — governed writes", ["fix", "bulk-update", "dedupe", "reassign", "enrich", "backfill"]],
+    ["Remediate — governed writes", ["fix", "bulk-update", "dedupe", "reassign", "route", "enrich", "backfill"]],
     ["Calls → evidence", ["call"]],
     ["Govern — the plan/apply spine", ["suggest", "plans", "apply", "audit-log", "merge"]],
     ["Market intelligence", ["market", "tam"]],

package/src/cli/suggest.ts

@@ -12,7 +12,14 @@
 // itself; this holds uniformly for read and write verbs, so a typo can never
 // silently change what a write-shaped invocation stages.
 
-import { HELP, usage } from "./help.ts";
+import {
+  COMMAND_FLAGS,
+  FLAGS_WITH_VALUES,
+  GLOBAL_FLAGS,
+  GLOBAL_SHORT_FLAGS,
+  HELP,
+  usage,
+} from "./help.ts";
 
 export function levenshtein(a: string, b: string): number {
   const dp = Array.from({ length: a.length + 1 }, () => Array<number>(b.length + 1).fill(0));
@@ -65,7 +72,7 @@ export function documentedFlags(): Set<string> {
 export type FlagTypo = {
   given: string;
   /** Human-readable correction, e.g. `--json` or `--rules missing-deal-owner`. */
-  suggestion: string;
+  suggestion: string | null;
   /** The argv tokens that replace `given` in the corrected command. */
   replacement: string[];
 };
@@ -108,6 +115,53 @@ export function detectFlagTypo(args: string[]): FlagTypo | null {
   return null;
 }
 
+function isFlagShaped(token: string): boolean {
+  return token !== "-" && token.startsWith("-");
+}
+
+function suggestCommandFlag(unknown: string, allowed: Set<string>): string | null {
+  const candidates = [...allowed].filter((flag) => flag.startsWith("--"));
+  const prefix = candidates
+    .filter((flag) => unknown.startsWith(`${flag}-`) || flag.startsWith(unknown))
+    .sort((a, b) => b.length - a.length)[0];
+  if (prefix) return prefix;
+  return nearest(unknown.toLowerCase().replace(/_/g, "-"), candidates, 3);
+}
+
+export function detectUnknownFlag(command: string, args: string[]): FlagTypo | null {
+  const commandFlags = COMMAND_FLAGS[command];
+  if (!commandFlags) return null;
+  const allowed = new Set([...GLOBAL_FLAGS, ...commandFlags]);
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--") break;
+    if (GLOBAL_SHORT_FLAGS.includes(token)) continue;
+    if (!token.startsWith("-")) continue;
+
+    if (!token.startsWith("--")) {
+      return { given: token, suggestion: null, replacement: [] };
+    }
+
+    const equalsIndex = token.indexOf("=");
+    const flag = equalsIndex === -1 ? token : token.slice(0, equalsIndex);
+    if (allowed.has(flag)) {
+      if (equalsIndex !== -1) {
+        const value = token.slice(equalsIndex + 1);
+        const replacement = value === "" ? [flag] : [flag, value];
+        return { given: token, suggestion: replacement.join(" "), replacement };
+      }
+      if (FLAGS_WITH_VALUES.has(flag) && args[index + 1] !== undefined && !isFlagShaped(args[index + 1])) {
+        index += 1;
+      }
+      continue;
+    }
+
+    const suggestion = suggestCommandFlag(flag, allowed);
+    return { given: flag, suggestion, replacement: suggestion ? [suggestion] : [] };
+  }
+  return null;
+}
+
 /** Nearest known command, derived from the same HELP table. */
 export function suggestCommand(command: string): string | null {
   if (!command) return null;
@@ -143,8 +197,8 @@ export function unknownFlagEnvelope(command: string, args: string[], typo: FlagT
       code: "UNKNOWN_FLAG" as const,
       message: `Unknown flag: ${typo.given}`,
       hints: [
-        `Did you mean: ${typo.suggestion}`,
-        `Try: ${correctedCommand(command, args, typo)}`,
+        ...(typo.suggestion ? [`Did you mean: ${typo.suggestion}`] : []),
+        ...(typo.replacement.length > 0 ? [`Try: ${correctedCommand(command, args, typo)}`] : []),
       ],
     },
   };

package/src/cli.ts

@@ -2,7 +2,7 @@ import { activeProfile, listProfiles, setActiveProfile } from "./credentials.ts"
 import { capabilitiesCommand, printCommandHelpJson, robotDocsCommand, unknownCommandEnvelope } from "./cli/capabilities.ts";
 import { BESPOKE_HELP, commandHelp, HELP, shortUsage, stylizeShortUsage, usage } from "./cli/help.ts";
 import { readPackageInfo } from "./cli/shared.ts";
-import { correctedCommand, detectFlagTypo, suggestCommand, unknownFlagEnvelope } from "./cli/suggest.ts";
+import { correctedCommand, detectFlagTypo, detectUnknownFlag, suggestCommand, unknownFlagEnvelope } from "./cli/suggest.ts";
 import { colorEnabled, paint } from "./cli/ui.ts";
 
 // Verb modules load lazily inside their dispatch branch below. The dispatcher
@@ -62,13 +62,19 @@ export async function runCli(argv: string[]) {
   }
   if (command === "help") {
     const [topic] = args;
-    if (topic && topic !== "--full" && !topic.startsWith("-")) {
+    if (topic && !topic.startsWith("-") && args.includes("--json")) {
       // `help <cmd> --json` → machine-readable help derived from the same
-      // HELP entry the plain text renders from. Plain output is unchanged.
-      if (args.includes("--json")) printCommandHelpJson(topic);
-      else console.log(commandHelp(topic));
+      // HELP entry the plain text renders from. JSON takes precedence over
+      // --full so automated callers get a stable shape.
+      printCommandHelpJson(topic);
+    } else if (args.includes("--full")) {
+      // --full is the global escape hatch to the complete reference, even
+      // when a topic is given (help <cmd> --full), unless --json is requested.
+      console.log(usage());
+    } else if (topic && !topic.startsWith("-")) {
+      console.log(commandHelp(topic));
     } else {
-      console.log(args.includes("--full") || topic === "--full" ? usage() : styledShortUsage());
+      console.log(styledShortUsage());
     }
     return;
   }
@@ -94,19 +100,26 @@ export async function runCli(argv: string[]) {
 
   // Flag typos used to be silently dropped by the per-verb parsers —
   // `audit --demo --jsn` exited 0 and printed markdown where the agent asked
-  // for JSON. Near-miss unknown flags (≤ 1 edit from a flag documented in
-  // help.ts) now stop with the exact corrected command. Suggest-only: never
-  // auto-execute the correction, so a typo can never change what a
-  // write-shaped invocation stages.
+  // for JSON. Every flag-shaped token is now checked against the per-command
+  // registry in help.ts, so unknown flags fail closed instead of being ignored.
+  // Suggest-only: never auto-execute the correction, so a typo can never
+  // silently change what a write-shaped invocation stages.
   if (command in HELP) {
-    const typo = detectFlagTypo(args);
+    const typo = detectUnknownFlag(command, args);
     if (typo) {
       if (args.includes("--json")) {
         console.log(JSON.stringify(unknownFlagEnvelope(command, args, typo), null, 2));
       } else {
+        console.error(`Unknown flag for ${command}: ${typo.given}`);
+        // Keep the old near-miss shape too; existing agents key off it.
         console.error(`Unknown flag: ${typo.given}`);
-        console.error(`Did you mean: ${typo.suggestion}`);
-        console.error(`Try: ${correctedCommand(command, args, typo)}`);
+        if (typo.suggestion) {
+          console.error(`Did you mean ${typo.suggestion}?`);
+          console.error(`Did you mean: ${typo.suggestion}`);
+          if (typo.replacement.length > 0) {
+            console.error(`Try: ${correctedCommand(command, args, typo)}`);
+          }
+        }
       }
       process.exitCode = 1;
       return;
@@ -165,6 +178,18 @@ export async function runCli(argv: string[]) {
     await (await import("./cli/fix.ts")).resolveCommand(args);
     return;
   }
+  if (command === "route") {
+    await (await import("./cli/fix.ts")).routeCommand(args);
+    return;
+  }
+  if (command === "hierarchy") {
+    await (await import("./cli/fix.ts")).hierarchyCommand(args);
+    return;
+  }
+  if (command === "relationships") {
+    await (await import("./cli/fix.ts")).relationshipsCommand(args);
+    return;
+  }
   if (command === "bulk-update") {
     await (await import("./cli/fix.ts")).bulkUpdateCommand(args);
     return;

package/src/connectors/hubspot.ts

@@ -24,6 +24,8 @@ import { SNAPSHOT_PULL_STAGES, type ProgressEmitter } from "../progress.ts";
 
 const DEFAULT_API_BASE_URL = "https://api.hubapi.com";
 
+export type HubspotWritableConnector = GtmConnector & Required<Pick<GtmConnector, "applyOperation" | "readField">>;
+
 export type HubspotConnectorOptions = {
   /** Returns a HubSpot access token (private app token or OAuth access token). */
   getAccessToken: () => string | Promise<string>;
@@ -71,7 +73,7 @@ const PULL_STAGE_BY_TYPE: Record<SnapshotProgress["objectType"], (typeof SNAPSHO
  * amountless deals — so audit rules can surface the gaps instead of hiding
  * them.
  */
-export function createHubspotConnector(options: HubspotConnectorOptions): GtmConnector {
+export function createHubspotConnector(options: HubspotConnectorOptions): HubspotWritableConnector {
   const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;

package/src/connectors/salesforce.ts

@@ -29,6 +29,8 @@ export type SalesforceConnection = {
   instanceUrl: string;
 };
 
+export type SalesforceWritableConnector = GtmConnector & Required<Pick<GtmConnector, "applyOperation" | "readField">>;
+
 export type SalesforceConnectorOptions = {
   /** Returns an access token plus the instance URL it belongs to. */
   getConnection: () => SalesforceConnection | Promise<SalesforceConnection>;
@@ -86,7 +88,7 @@ const PULL_STAGE_BY_TYPE: Record<SnapshotProgress["objectType"], (typeof SNAPSHO
  */
 export function createSalesforceConnector(
   options: SalesforceConnectorOptions,
-): GtmConnector {
+): SalesforceWritableConnector {
   const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;

package/src/connectors/signalSources.ts

@@ -21,6 +21,7 @@
 
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
+import { FREE_EMAIL_DOMAINS } from "../freeEmailDomains.ts";
 import type { SignalBucket, StagedSignalRow } from "../signals.ts";
 import { SIGNAL_BUCKETS } from "../signals.ts";
 import { parseSpoolText, spoolFilesIn } from "../spoolFiles.ts";
@@ -294,21 +295,10 @@ function fieldValue(values: Array<{ name?: string; value?: string }> | undefined
   return "";
 }
 
-const FREE_MAIL = new Set([
-  "gmail.com",
-  "yahoo.com",
-  "hotmail.com",
-  "outlook.com",
-  "icloud.com",
-  "aol.com",
-  "proton.me",
-  "protonmail.com",
-]);
-
 /** Company domain from an email, or "" for free-mail / no email. */
 function corporateDomain(email: string): string {
   if (!email.includes("@")) return "";
   const domain = email.split("@").at(-1)!.trim().toLowerCase();
-  if (!domain || FREE_MAIL.has(domain)) return "";
+  if (!domain || FREE_EMAIL_DOMAINS.has(domain)) return "";
   return domain;
 }

package/src/format.ts

@@ -1,10 +1,9 @@
 import type { PatchPlan, PatchPlanRun } from "./types.ts";
 
-// `summary: true` renders only the header + the Findings-by-Rule table + an
-// operation count, for read verbs like `audit` where the full per-operation
-// dump (1,400+ lines on a real portal) buries the signal. Defaults to the full
-// view so write-preview callers (bulk-update, fix, dedupe, plans show, MCP) —
-// where you approve specific operations — keep every operation's detail.
+// `summary: true` renders the compact audit view: header, findings summary,
+// assumptions/open questions, and an operation count. Defaults to the full view
+// so write-preview callers (bulk-update, fix, dedupe, plans show, MCP) — where
+// you approve specific operations — keep every operation's detail.
 export function patchPlanToMarkdown(plan: PatchPlan, opts: { summary?: boolean } = {}) {
   const lines = [
     `# ${plan.title}`,
@@ -29,6 +28,8 @@ export function patchPlanToMarkdown(plan: PatchPlan, opts: { summary?: boolean }
     lines.push("");
   }
 
+  appendAssumptionsAndDecisionPoints(lines, plan);
+
   if (opts.summary) {
     const ops = plan.operations.length;
     lines.push(
@@ -155,6 +156,33 @@ export function formatPatchPlanRun(run: PatchPlanRun) {
   return `${lines.join("\n")}\n`;
 }
 
+
+function appendAssumptionsAndDecisionPoints(lines: string[], plan: PatchPlan) {
+  const assumptions = [...(plan.assumptions ?? [])].sort((left, right) => {
+    if (left.confidence === "guess" && right.confidence !== "guess") return -1;
+    if (left.confidence !== "guess" && right.confidence === "guess") return 1;
+    return 0;
+  });
+  const openQuestions = plan.openQuestions ?? [];
+  if (assumptions.length === 0 && openQuestions.length === 0) return;
+
+  lines.push("## Assumptions & decision points", "");
+  for (const assumption of assumptions) {
+    const warning = assumption.confidence === "guess" ? "⚠️ " : "";
+    lines.push(`- ${warning}${assumption.text}${assumption.source ? ` _(source: ${assumption.source})_` : ""}`);
+  }
+
+  if (openQuestions.length > 0) {
+    if (assumptions.length > 0) lines.push("");
+    lines.push("### Open questions", "");
+    for (const question of openQuestions) {
+      lines.push(`- ${question}`);
+    }
+  }
+
+  lines.push("");
+}
+
 function formatValue(value: unknown) {
   if (value === undefined || value === null || value === "") return "unset";
   if (typeof value === "string") return value;

package/src/freeEmailDomains.ts

@@ -0,0 +1,14 @@
+// Shared free-mail domains that should never be treated as company domains.
+export const FREE_EMAIL_DOMAINS = new Set([
+  "gmail.com",
+  "googlemail.com",
+  "yahoo.com",
+  "outlook.com",
+  "hotmail.com",
+  "live.com",
+  "icloud.com",
+  "me.com",
+  "aol.com",
+  "proton.me",
+  "protonmail.com",
+]);

package/src/hierarchy.ts

@@ -0,0 +1,185 @@
+import { normalizeDomain } from "./merge.ts";
+import type { CanonicalAccount, CanonicalGtmSnapshot } from "./types.ts";
+
+export type AccountHierarchyNode = {
+  accountId: string;
+  name: string;
+  domain?: string;
+  parentAccountId?: string;
+  parentReason?: string;
+  children: AccountHierarchyNode[];
+};
+
+export type AccountHierarchyConflict = {
+  type: "duplicate_domain" | "ambiguous_parent" | "cycle";
+  accountIds: string[];
+  key: string;
+  detail: string;
+};
+
+export type AccountHierarchyReport = {
+  generatedAt: string;
+  roots: AccountHierarchyNode[];
+  orphanAccounts: string[];
+  conflicts: AccountHierarchyConflict[];
+  counts: { accounts: number; roots: number; linkedChildren: number; conflicts: number };
+};
+
+function rawString(account: CanonicalAccount, keys: string[]): string | undefined {
+  if (!account.raw || typeof account.raw !== "object") return undefined;
+  const raw = account.raw as Record<string, unknown>;
+  for (const key of keys) {
+    const value = raw[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+    if (value && typeof value === "object") {
+      const nested = value as Record<string, unknown>;
+      for (const nestedKey of ["id", "value", "name"]) {
+        if (typeof nested[nestedKey] === "string" && String(nested[nestedKey]).trim()) return String(nested[nestedKey]).trim();
+      }
+    }
+  }
+  return undefined;
+}
+
+function parentHint(account: CanonicalAccount): string | undefined {
+  return rawString(account, ["parentAccountId", "parent_account_id", "ParentId", "parentCompanyId", "hs_parent_company_id"]);
+}
+
+function cloneNode(account: CanonicalAccount): AccountHierarchyNode {
+  return { accountId: String(account.id), name: account.name, ...(account.domain ? { domain: account.domain } : {}), children: [] };
+}
+
+function looksLikePublicSuffix(domain: string): boolean {
+  const parts = domain.split(".");
+  if (parts.length !== 2) return false;
+  const [label, tld] = parts;
+  return tld.length === 2 && ["ac", "co", "com", "edu", "gov", "net", "org"].includes(label);
+}
+
+function domainParent(childDomain: string, domains: Map<string, CanonicalAccount[]>): CanonicalAccount | "ambiguous" | null {
+  const parts = childDomain.split(".");
+  for (let i = 1; i < parts.length - 1; i++) {
+    const candidate = parts.slice(i).join(".");
+    if (candidate.split(".").length < 2 || looksLikePublicSuffix(candidate)) continue;
+    const unique = new Map((domains.get(candidate) ?? []).map((account) => [String(account.id), account]));
+    if (unique.size > 1) return "ambiguous";
+    if (unique.size === 1) return [...unique.values()][0];
+  }
+  return null;
+}
+
+function detectCycles(parentByChild: Map<string, { parentId: string; reason: string }>): { accountIds: Set<string>; cycles: string[][] } {
+  const cyclic = new Set<string>();
+  const cycles: string[][] = [];
+  const emitted = new Set<string>();
+
+  for (const start of parentByChild.keys()) {
+    const path: string[] = [];
+    const indexById = new Map<string, number>();
+    let cursor: string | undefined = start;
+    while (cursor && parentByChild.has(cursor)) {
+      const seenAt = indexById.get(cursor);
+      if (seenAt !== undefined) {
+        const cycle = path.slice(seenAt);
+        for (const id of cycle) cyclic.add(id);
+        const key = [...cycle].sort().join("|");
+        if (!emitted.has(key)) {
+          emitted.add(key);
+          cycles.push(cycle);
+        }
+        break;
+      }
+      indexById.set(cursor, path.length);
+      path.push(cursor);
+      cursor = parentByChild.get(cursor)?.parentId;
+    }
+  }
+
+  return { accountIds: cyclic, cycles };
+}
+
+export function buildAccountHierarchy(snapshot: CanonicalGtmSnapshot): AccountHierarchyReport {
+  const byId = new Map(snapshot.accounts.map((account) => [String(account.id), account]));
+  const accounts = [...byId.values()];
+  const domains = new Map<string, CanonicalAccount[]>();
+  for (const account of accounts) {
+    const domain = normalizeDomain(account.domain);
+    if (domain) domains.set(domain, [...(domains.get(domain) ?? []), account]);
+  }
+
+  const conflicts: AccountHierarchyConflict[] = [];
+  for (const [domain, accounts] of domains) {
+    const ids = [...new Set(accounts.map((account) => String(account.id)))];
+    if (ids.length > 1) conflicts.push({ type: "duplicate_domain", accountIds: ids.sort(), key: domain, detail: `${ids.length} accounts share domain ${domain}; hierarchy inference will not choose between them.` });
+  }
+
+  const nodes = new Map(accounts.map((account) => [String(account.id), cloneNode(account)]));
+  const parentByChild = new Map<string, { parentId: string; reason: string }>();
+  for (const account of accounts) {
+    const id = String(account.id);
+    const hint = parentHint(account);
+    if (hint && byId.has(hint) && hint !== id) {
+      parentByChild.set(id, { parentId: hint, reason: "provider-parent" });
+      continue;
+    }
+    const domain = normalizeDomain(account.domain);
+    if (!domain) continue;
+    const inferred = domainParent(domain, domains);
+    if (inferred === "ambiguous") conflicts.push({ type: "ambiguous_parent", accountIds: [id], key: domain, detail: `Multiple possible parent accounts found for ${domain}; leaving account as a root.` });
+    else if (inferred && String(inferred.id) !== id) parentByChild.set(id, { parentId: String(inferred.id), reason: "domain-subdomain" });
+  }
+
+  const cyclicAccounts = detectCycles(parentByChild);
+  for (const cycle of cyclicAccounts.cycles) {
+    const ordered = [...cycle].sort();
+    const key = ordered.join(" -> ");
+    conflicts.push({
+      type: "cycle",
+      accountIds: ordered,
+      key,
+      detail: `Cyclic parent hints detected among ${ordered.join(", ")}; leaving those accounts as roots instead of hiding them in a loop.`,
+    });
+  }
+  for (const accountId of cyclicAccounts.accountIds) parentByChild.delete(accountId);
+
+  const roots: AccountHierarchyNode[] = [];
+  const orphanAccounts: string[] = [];
+  const linkedChildren = new Set<string>();
+  for (const account of accounts) {
+    const id = String(account.id);
+    const node = nodes.get(id)!;
+    const parent = parentByChild.get(id);
+    if (parent && nodes.has(parent.parentId)) {
+      node.parentAccountId = parent.parentId;
+      node.parentReason = parent.reason;
+      nodes.get(parent.parentId)!.children.push(node);
+      linkedChildren.add(id);
+    } else {
+      roots.push(node);
+      if (!account.domain && !parentHint(account)) orphanAccounts.push(id);
+    }
+  }
+  const sortTree = (list: AccountHierarchyNode[]) => {
+    list.sort((a, b) => a.name.localeCompare(b.name) || a.accountId.localeCompare(b.accountId));
+    for (const node of list) sortTree(node.children);
+  };
+  sortTree(roots);
+  return { generatedAt: snapshot.generatedAt, roots, orphanAccounts: orphanAccounts.sort(), conflicts, counts: { accounts: accounts.length, roots: roots.length, linkedChildren: linkedChildren.size, conflicts: conflicts.length } };
+}
+
+export function accountHierarchyToMarkdown(report: AccountHierarchyReport): string {
+  const lines = ["# Account hierarchy", "", `${report.counts.accounts} account(s), ${report.counts.roots} root(s), ${report.counts.linkedChildren} inferred child link(s), ${report.counts.conflicts} conflict(s).`, ""];
+  const walk = (nodes: AccountHierarchyNode[], depth: number) => {
+    for (const node of nodes) {
+      const suffix = [node.domain, node.parentReason ? `via ${node.parentReason}` : undefined].filter(Boolean).join("; ");
+      lines.push(`${"  ".repeat(depth)}- ${node.name} (${node.accountId}${suffix ? ` — ${suffix}` : ""})`);
+      walk(node.children, depth + 1);
+    }
+  };
+  walk(report.roots, 0);
+  if (report.conflicts.length) {
+    lines.push("", "## Conflicts");
+    for (const conflict of report.conflicts) lines.push(`- ${conflict.type} ${conflict.key}: ${conflict.detail}`);
+  }
+  return lines.join("\n");
+}