fullstackgtm 0.46.0 → 0.48.0

package/src/audit.ts

@@ -9,6 +9,7 @@ import type {
   PipelineFindingType,
   PatchOperation,
   PatchPlan,
+  PatchPlanAssumption,
   SourceFreshness,
 } from "./types.ts";
 
@@ -53,6 +54,7 @@ export function auditSnapshot(
   const context = { snapshot, policy, index: buildSnapshotIndex(snapshot) };
   const findings: AuditFinding[] = [];
   const operations: PatchOperation[] = [];
+  const assumptionsById = new Map<string, PatchPlanAssumption>();
 
   for (const rule of rules) {
     try {
@@ -63,6 +65,9 @@ export function auditSnapshot(
     const result = rule.evaluate(context);
     findings.push(...result.findings);
     operations.push(...result.operations);
+    for (const assumption of result.assumptions ?? []) {
+      if (!assumptionsById.has(assumption.id)) assumptionsById.set(assumption.id, assumption);
+    }
     try {
       onRule?.(rule.id, "done", result.findings.length);
     } catch {
@@ -70,6 +75,7 @@ export function auditSnapshot(
     }
   }
 
+  const assumptions = Array.from(assumptionsById.values());
 
   const evidence = buildEvidence(snapshot, findings, policy.today);
   const pipelineFindings = buildPipelineFindings(findings, operations, evidence, policy.today);
@@ -85,6 +91,7 @@ export function auditSnapshot(
     findings,
     pipelineFindings,
     evidence,
+    assumptions: assumptions.length > 0 ? assumptions : undefined,
     operations,
   };
 }

package/src/backfill.ts

@@ -21,6 +21,7 @@ import type {
   PatchPlan,
 } from "./types.ts";
 import type { StripePaidInvoice } from "./connectors/stripe.ts";
+import { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.ts";
 import { normalizeDomain } from "./merge.ts";
 
 // Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep backfill.ts
@@ -36,22 +37,6 @@ function fnv1a(value: string): string {
 
 export const DEFAULT_BACKFILL_MATCH_PROPERTY = "stripe_invoice_id";
 
-// Freemail domains never become a company domain: stamping "gmail.com" on an
-// account (or resolving a company BY gmail.com) would collapse unrelated
-// customers onto one record. Mirrors FREE_MAIL in connectors/signalSources.ts
-// (duplicated to keep backfill.ts importable without connector code, the
-// fnv1a precedent above).
-const FREE_MAIL = new Set([
-  "gmail.com",
-  "yahoo.com",
-  "hotmail.com",
-  "outlook.com",
-  "icloud.com",
-  "aol.com",
-  "proton.me",
-  "protonmail.com",
-]);
-
 export type StripeBackfillOptions = {
   /** Pipeline id or case-insensitive label; absent = the portal's default pipeline. */
   pipeline?: string;
@@ -183,7 +168,7 @@ export function buildStripeBackfillPlan(
     let companyDomain = normalizeDomain(account?.domain);
     let accountIsNew = false;
     if (!account && createMissingAccounts) {
-      const usableDomain = domain && !FREE_MAIL.has(domain) ? domain : undefined;
+      const usableDomain = domain && !FREE_EMAIL_DOMAINS.has(domain) ? domain : undefined;
       const name = invoice.customerName?.trim() || usableDomain;
       if (name) {
         companyName = name;

package/src/cli/fix.ts

@@ -1,6 +1,6 @@
 // Extracted verbatim from src/cli.ts (mechanical split, no behavior change).
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { auditSnapshot, defaultPolicy } from "../audit.ts";
 import { loadConfig, mergePolicy, resolveConfiguredRules } from "../config.ts";
@@ -8,6 +8,10 @@ import { applyPatchPlan } from "../connector.ts";
 import { patchPlanToMarkdown } from "../format.ts";
 import { createFilePlanStore } from "../planStore.ts";
 import { resolveRecord, type ResolveCandidate } from "../resolve.ts";
+import { parseAssignmentPolicy } from "../assign.ts";
+import { buildLeadRoutePlan } from "../route.ts";
+import { accountHierarchyToMarkdown, buildAccountHierarchy } from "../hierarchy.ts";
+import { buildRelationshipMap, relationshipMapToMarkdown } from "../relationships.ts";
 import { buildBulkUpdatePlan } from "../bulkUpdate.ts";
 import { buildDedupePlan, type DedupeOptions } from "../dedupe.ts";
 import { buildReassignPlans, type ReassignObjectType } from "../reassign.ts";
@@ -371,3 +375,66 @@ function snapshotSourceHint(args: string[]) {
   if (input) return `--input ${input} `;
   return "";
 }
+
+function parseJsonOrFile(value: string): unknown {
+  const candidate = resolve(process.cwd(), value);
+  const text = existsSync(candidate) ? readFileSync(candidate, "utf8") : value;
+  return JSON.parse(text);
+}
+
+export async function routeCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "leads") {
+    throw new Error("Usage: fullstackgtm route leads [source options] [--match domain|company|both] [--no-inherit-owner] [--reassign-owned] [--policy <json|path>] [--save] [--json] [--out <path>]");
+  }
+  const match = option(rest, "--match") ?? "domain";
+  if (!["domain", "company", "both"].includes(match)) throw new Error("--match must be domain, company, or both");
+  const policyRaw = option(rest, "--policy");
+  const snapshot = await readSnapshot(rest);
+  const result = buildLeadRoutePlan(snapshot, {
+    matchByDomain: match === "domain" || match === "both",
+    matchByCompanyName: match === "company" || match === "both",
+    inheritAccountOwner: !rest.includes("--no-inherit-owner"),
+    reassignExistingOwner: rest.includes("--reassign-owned"),
+    assignmentPolicy: policyRaw ? parseAssignmentPolicy(parseJsonOrFile(policyRaw)) : undefined,
+    maxOperations: numericOption(rest, "--max-operations"),
+    reason: option(rest, "--reason") ?? undefined,
+  });
+  if (rest.includes("--json")) {
+    const out = option(rest, "--out");
+    if (out) writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(result.plan, null, 2)}\n`);
+    if (saveRequested(rest)) await createFilePlanStore().save(result.plan);
+    console.error(`Route dry-run: ${JSON.stringify(result.counts)}`);
+    console.log(JSON.stringify({ counts: result.counts, plan: result.plan }, null, 2));
+    return;
+  }
+  console.error(
+    `Route dry-run: ${result.counts.linkOperations} link(s), ${result.counts.ownerOperations} owner assignment(s), ${result.counts.ambiguousAccountMatches} ambiguous match(es).`,
+  );
+  await emitPlan(result.plan, rest);
+}
+
+export async function hierarchyCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "report") throw new Error("Usage: fullstackgtm hierarchy report [source options] [--json|--out <path>]");
+  const snapshot = await readSnapshot(rest);
+  const report = buildAccountHierarchy(snapshot);
+  const out = option(rest, "--out");
+  const rendered = rest.includes("--json") ? `${JSON.stringify(report, null, 2)}\n` : `${accountHierarchyToMarkdown(report)}\n`;
+  if (out) writeFileSync(resolve(process.cwd(), out), rendered);
+  console.log(rendered.trimEnd());
+}
+
+export async function relationshipsCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== "account") throw new Error("Usage: fullstackgtm relationships account (--account-id <id>|--domain <d>) [source options] [--json|--out <path>]");
+  const accountId = option(rest, "--account-id") ?? undefined;
+  const domain = option(rest, "--domain") ?? undefined;
+  if (!accountId && !domain) throw new Error("relationships account needs --account-id <id> or --domain <domain>");
+  const snapshot = await readSnapshot(rest);
+  const map = buildRelationshipMap(snapshot, { accountId, domain });
+  const out = option(rest, "--out");
+  const rendered = rest.includes("--json") ? `${JSON.stringify(map, null, 2)}\n` : `${relationshipMapToMarkdown(map)}\n`;
+  if (out) writeFileSync(resolve(process.cwd(), out), rendered);
+  console.log(rendered.trimEnd());
+}

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/connector.ts

@@ -138,6 +138,17 @@ function normalizeForComparison(value: unknown): string | null {
   return String(value);
 }
 
+function isApplyBatchCandidate(operation: PatchOperation): boolean {
+  return (
+    ((operation.operation === "set_field" || operation.operation === "clear_field") && Boolean(operation.field)) ||
+    operation.operation === "archive_record"
+  );
+}
+
+function sameApplyBatchKind(a: PatchOperation, b: PatchOperation): boolean {
+  return a.operation === b.operation && a.objectType === b.objectType;
+}
+
 /**
  * Apply an approved subset of a patch plan through a connector.
  *
@@ -267,6 +278,11 @@ export async function applyPatchPlan(
   if (checkConflicts && connector.readField) {
     for (const operation of plan.operations) {
       if (!approved.has(operation.id) || conflicts.has(operation.id)) continue;
+      // Generic batch connectors (Salesforce) do their own batched CAS read for
+      // eligible field writes, so don't pre-read those one-by-one here.
+      if (connector.applyBatch && isApplyBatchCandidate(operation) && !operation.groupId && !operation.preconditions?.length) {
+        continue;
+      }
       let conflict: PatchOperationResult | null = null;
       if (operation.field && FIELD_WRITE_OPERATIONS.has(operation.operation)) {
         const current = await connector.readField(
@@ -349,31 +365,34 @@ export async function applyPatchPlan(
   let lastNotified = results.length;
   const notifyProgress = () => {
     if ((!options.onOperation && !options.progress) || results.length === lastNotified) return;
-    lastNotified = results.length;
-    const last = results[results.length - 1];
-    if (last.status === "applied") progressCounts.applied += 1;
-    else if (last.status === "failed") progressCounts.failed += 1;
-    else if (last.status === "conflict") progressCounts.conflicts += 1;
-    else progressCounts.skipped += 1;
-    // Shared vocabulary: operation id + status only — a conflict/failure
-    // detail can echo field values, which never leave the machine.
-    options.progress?.opResult(last.operationId, last.status);
-    options.progress?.items(results.length - resultsBefore, plan.operations.length);
-    if (options.onOperation) {
-      try {
-        options.onOperation({
-          completed: results.length - resultsBefore,
-          total: plan.operations.length,
-          ...progressCounts,
-        });
-      } catch {
-        // progress is presentation-only
+    while (lastNotified < results.length) {
+      const last = results[lastNotified];
+      lastNotified += 1;
+      if (last.status === "applied") progressCounts.applied += 1;
+      else if (last.status === "failed") progressCounts.failed += 1;
+      else if (last.status === "conflict") progressCounts.conflicts += 1;
+      else progressCounts.skipped += 1;
+      // Shared vocabulary: operation id + status only — a conflict/failure
+      // detail can echo field values, which never leave the machine.
+      options.progress?.opResult(last.operationId, last.status);
+      options.progress?.items(results.length - resultsBefore, plan.operations.length);
+      if (options.onOperation) {
+        try {
+          options.onOperation({
+            completed: lastNotified - resultsBefore,
+            total: plan.operations.length,
+            ...progressCounts,
+          });
+        } catch {
+          // progress is presentation-only
+        }
       }
     }
   };
 
   emitStage("operations");
-  for (const operation of plan.operations) {
+  for (let opIndex = 0; opIndex < plan.operations.length; opIndex++) {
+    const operation = plan.operations[opIndex];
     // Report the previous iteration's result (guarded: no-op if it pushed
     // nothing). One-iteration lag keeps this a two-line hook instead of a
     // notify after all ten push sites; the loop-exit call below flushes the last.
@@ -441,6 +460,61 @@ export async function applyPatchPlan(
       continue;
     }
 
+    if (connector.applyBatch && isApplyBatchCandidate(operation) && (checkConflicts || operation.operation === "archive_record") && !operation.groupId && !operation.preconditions?.length) {
+      const chunk: PatchOperation[] = [];
+      const applyBatchLimit = Math.max(1, connector.applyBatchLimit ?? 200);
+      for (let scan = opIndex; scan < plan.operations.length && chunk.length < applyBatchLimit; scan++) {
+        const candidate = plan.operations[scan];
+        if (!sameApplyBatchKind(operation, candidate) || !isApplyBatchCandidate(candidate)) break;
+        const candidateOverride = options.valueOverrides?.[candidate.id];
+        if (
+          !approved.has(candidate.id) ||
+          (requiresHumanInput(candidate.afterValue) && candidateOverride === undefined) ||
+          conflicts.has(candidate.id) ||
+          Boolean(candidate.groupId) ||
+          Boolean(candidate.preconditions?.length) ||
+          (staleByFilter && staleByFilter.has(candidate.objectId)) ||
+          irreversibleStale.has(candidate.id)
+        ) {
+          break;
+        }
+        chunk.push(candidateOverride === undefined ? candidate : { ...candidate, afterValue: candidateOverride });
+      }
+      if (chunk.length > 1) {
+        try {
+          const batchResults = await connector.applyBatch(chunk);
+          const byOperationId = new Map(batchResults.map((result) => [result.operationId, result]));
+          for (const batchOperation of chunk) {
+            const result = byOperationId.get(batchOperation.id) ?? {
+              operationId: batchOperation.id,
+              status: "failed" as const,
+              detail: "Batch connector did not return a result for this operation.",
+            };
+            results.push(result);
+            if (result.status === "applied" || result.status === "failed") attempted += 1;
+            if (result.status === "applied") applied += 1;
+          }
+          const appliedInBatch = batchResults.filter((result) => result.status === "applied").length;
+          appliedSinceRecheck += appliedInBatch;
+          if (appliedInBatch > 0 && (applied === appliedInBatch || appliedSinceRecheck >= recheckEvery)) {
+            appliedSinceRecheck = 0;
+            await refreshSnapshotChecks();
+          }
+        } catch (error) {
+          for (const batchOperation of chunk) {
+            results.push({
+              operationId: batchOperation.id,
+              status: "failed",
+              detail: error instanceof Error ? error.message : String(error),
+            });
+            attempted += 1;
+          }
+        }
+        opIndex += chunk.length - 1;
+        continue;
+      }
+    }
+
     const resolved: PatchOperation =
       override === undefined ? operation : { ...operation, afterValue: override };