fullstackgtm 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -3,10 +3,42 @@
 All notable changes to the `fullstackgtm` package are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
-The path to 1.0 is planned in the roadmap doc in the repository.
+The path to 1.0 is planned in [docs/roadmap-to-1.0.md](https://github.com/fullstackgtm/core/blob/main/docs/roadmap-to-1.0.md).
 
 ## [Unreleased]
 
+## [0.48.0] — 2026-07-08
+
+### Added
+
+- Added `GtmAuditRule.emitsOperations` and `isFindingsOnlyRule` so hosts can derive findings-only rule behavior from the package registry instead of duplicating rule IDs.
+- **Route, hierarchy, and relationships open surfaces.** `route leads` builds governed lead-to-account/owner patch plans; `hierarchy report` and `relationships account` provide read-only planning reports for account trees and stakeholder maps.
+
+### Changed
+
+- **CLI human path now uses progressive disclosure by default.** Bare
+  `fullstackgtm`/`--help` shows a compact lifecycle-grouped command map instead
+  of the full flag wall; `help <command>` and `<command> --help` show focused
+  per-command guidance; `help --full` (including `help <command> --full`) keeps
+  the complete reference available. `audit` now defaults to a summary view with
+  `--full` for per-operation detail and prints next-step guidance on stderr for
+  human runs while keeping `--json` machine-clean. The dry-run footer now frames
+  approval/write safety as invariants rather than prototype copy.
+- **Patch-plan assumptions and open questions are canonical.** Plan exports and
+  markdown use `assumptions` plus `openQuestions`; the duplicate
+  `decisionPoints` alias was removed.
+
+### Fixed
+
+- **Route plan safety and batching.** Owner routing recognizes both canonical
+  user ids and provider CRM owner ids, skips name-only account matches as
+  ambiguous, avoids self-conflicting sibling preconditions, groups only contacts
+  with multiple operations, and uses one shared free-email domain list.
+- **Hierarchy and relationships correctness.** Hierarchy reports dedupe duplicate
+  account ids, avoid common public-suffix parent guesses, and rely on a single
+  cycle-dedupe pass. Relationship `--domain` selectors normalize domains and
+  markdown preserves zero-value deal amounts.
+
 ## [0.47.0] — 2026-07-06
 
 ### Added
@@ -117,7 +149,7 @@ The path to 1.0 is planned in the roadmap doc in the repository.
   doctor, rules, dedupe, resolve, snapshot, and error paths) and the public
   import surface of `cli.ts` is unchanged. Profiling method, opportunity
   matrix, and honest non-wins are documented in
-  [docs/perf-notes.md](./docs/perf-notes.md).
+  [docs/perf-notes.md](https://github.com/fullstackgtm/core/blob/main/docs/perf-notes.md).
 
 ## [0.45.0] — 2026-07-02
 
@@ -455,7 +487,7 @@ The path to 1.0 is planned in the roadmap doc in the repository.
   Library: `connectors/signalSources.ts` (`listSignalSources`, `getSignalSource`,
   `fileSource`, `serpapiNewsSource`, `hubspotFormsSource`), `stagedRowToSignal` +
   `StagedSignalRow` from `signals.ts`. Design:
-  [docs/spec-connectors-signals-outbound.md](../../docs/spec-connectors-signals-outbound.md)
+  [docs/spec-connectors-signals-outbound.md](https://github.com/fullstackgtm/core/blob/main/docs/spec-connectors-signals-outbound.md)
   (the connector taxonomy + the Phase 2/3 webhook-spool and governed-channel plan).
 - **Webhook spool format + conventional landing zone (signals Phase 2).**
   `--connector file` with no path now reads the conventional spool directory
@@ -844,7 +876,7 @@ The path to 1.0 is planned in the roadmap doc in the repository.
   you approve specific operations and run `apply`… These safety invariants are
   not beta."), matching the README and agent skill.
 
-See [docs/dx-punch-list.md](./docs/dx-punch-list.md) for the audit that drove this.
+See [docs/dx-punch-list.md](https://github.com/fullstackgtm/core/blob/main/docs/dx-punch-list.md) for the audit that drove this.
 
 ## [0.34.0] — 2026-06-18
 
@@ -1935,7 +1967,7 @@ milestones, not a frozen public contract. 0.10.0 continues the 0.x line
 1.2.2 plus the status/docs corrections below. `fullstackgtm@1.2.1` and
 `@1.2.2` were briefly on npm (2026-06-10) and were unpublished the same
 week; those version numbers are permanently burned per npm policy. The real
-1.0 will be declared via [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md)
+1.0 will be declared via [docs/roadmap-to-1.0.md](https://github.com/fullstackgtm/core/blob/main/docs/roadmap-to-1.0.md)
 once the API surface has survived external usage.
 
 ### Changed
@@ -2230,7 +2262,7 @@ stability commitment attached.
 
 - The hosted app's Convex plan tables are the second `PlanStore`
   implementation target; unifying them onto these types is the remaining
-  0.3.x work (see docs/roadmap-to-1.0.md).
+  0.3.x work (see https://github.com/fullstackgtm/core/blob/main/docs/roadmap-to-1.0.md).
 
 ## [0.2.0] — Unreleased
 

package/INSTALL_FOR_AGENTS.md

@@ -33,7 +33,7 @@ machine — that is normal and does not block the next step.
 fullstackgtm audit --demo --json
 ```
 
-Expect a JSON patch plan with `dryRun: true` and ~80 findings over a generated,
+Expect a JSON patch plan with `dryRun: true` and 110 findings/110 operations over a generated,
 deliberately messy CRM. Deterministic per seed: `--seed 7` is the default, so
 two runs produce identical finding and operation ids. Exit code 0.
 
@@ -131,8 +131,8 @@ the server resolves them from there (peer-dependency semantics) — so this
 works from inside existing projects too.
 
 Tools exposed over stdio — read-only: `fullstackgtm_audit`,
-`fullstackgtm_rules`, `fullstackgtm_suggest`, `fullstackgtm_call_parse`,
-`fullstackgtm_resolve`, `fullstackgtm_market_worksheet`. Gated:
+`fullstackgtm_capabilities`, `fullstackgtm_rules`, `fullstackgtm_suggest`,
+`fullstackgtm_call_parse`, `fullstackgtm_resolve`, `fullstackgtm_market_worksheet`. Gated:
 `fullstackgtm_apply` (requires explicit `approvedOperationIds`),
 `fullstackgtm_market_observe` (every quoted span is verified against the
 stored captures before anything is appended).

package/README.md

@@ -2,19 +2,21 @@
 
 [![CI](https://github.com/fullstackgtm/core/actions/workflows/ci.yml/badge.svg)](https://github.com/fullstackgtm/core/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/fullstackgtm)](https://www.npmjs.com/package/fullstackgtm) [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
 
-**Plan/apply for your GTM stack.** An open-source framework for managing disparate go-to-market data spread across third-party systems: a canonical CRM/GTM data model, deterministic hygiene audits, reviewable dry-run patch plans, and approval-gated write-back to providers.
+**Guardrails for AI agents working in your CRM.**
 
-Think `terraform plan` for your CRM: agents and scripts may *read* everything, but every proposed change becomes a typed patch operation — object, field, before, after, reason, risk — that a human approves before any provider write happens.
+Let Claude or Codex loose on Salesforce or HubSpot and it will make predictable mistakes — duplicates, bad batch edits, silent overwrites. fullstackgtm is the wrapper that knows those mistakes: every change becomes a reviewable plan before anything is written.
 
-Licensed under [Apache-2.0](./LICENSE). The boundary is deliberate and stable: the framework, CLI, and MCP server are open source; the hosted Full Stack GTM application (dashboard, sync backend, broker service, team workflows) is a separate, proprietary product built on top of this package. Features never move from open to closed. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how development and mirroring work.
+Instead of overwriting records, an agent using fullstackgtm sets out a **patch plan**: what it wants to change, field by field, with before/after values and the reason. You review it, roll it out incrementally (approve 10 operations, then 100, then all), and every write records the before value — so a mistake is visible and reversible, not silently absorbed. Think `terraform plan` for your CRM.
+
+**What it catches:** duplicates, orphaned records, bad batch edits, stale deals, missing owners — deterministic rules, not LLM guesses. Works as a CLI, a library, or an MCP server your agent calls directly.
 
-**Status: beta (0.x).** The surfaces in [docs/api.md](./docs/api.md) — the canonical model, rule interface, plan/apply contract, connector contract, merge/diff, config, CLI, and MCP tools — are settling but may still break in minor releases until 1.0. The safety invariants (read-only audits, approval-gated writes, placeholder refusal) are not beta and do not change. Connectors: HubSpot (read/write), Salesforce (read/write), Stripe (read-only billing).
+Open source (Apache-2.0), zero runtime dependencies. Beta (0.x): APIs may shift before 1.0; the safety invariants never do. Connectors: HubSpot, Salesforce (read/write), Stripe (read-only).
 
 ## Install
 
 ```bash
+npx fullstackgtm audit --demo               # zero-install try-it path
 npm install fullstackgtm                    # library + CLI in a project
-npx fullstackgtm audit --demo               # or zero-install via npx
 npm install github:fullstackgtm/core        # or straight from this repo (project-local)
 npx github:fullstackgtm/core audit --demo   # zero-install from the repo
 ```
@@ -315,7 +317,7 @@ fullstackgtm diff --before old.json --after new.json --fail-on-new-findings
 - `--demo` (with `--seed`) generates a realistic mid-market CRM with injected real-world failure modes — departed owners, unlinked deals, orphan accounts, stale pipeline — so agents and CI can exercise the full snapshot → audit → apply pipeline with zero credentials.
 - Exit codes: `0` success, `1` error, `2` findings at/above `--fail-on`.
 
-"Built for agents" is measured, not asserted: a 1,904-run benchmark (17 CRM-operations scenarios × 3 tool-surface arms × up to 4 trials, across ten models from six vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface matching or beating raw CRM-API access on completion-under-policy for every model tested — strictly better in nine of ten — and the effect is vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+"Built for agents" is measured, not asserted: a 1,904-run benchmark (17 CRM-operations scenarios × 3 tool-surface arms × up to 4 trials, across ten models from six vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface matching or beating raw CRM-API access on completion-under-policy for every model tested — strictly better in nine of ten — and the effect is vendor-independent. Full matrix and methodology: [the leaderboard](https://github.com/fullstackgtm/core/blob/main/evals/crm/leaderboard/RESULTS.md).
 
 Caveat: the leaderboard documents the Opus reduced protocol and mixed-version Informed arms; treat the headline as a pointer to those exact RESULTS.md conditions.
 
@@ -533,9 +535,9 @@ Or configure any MCP client (Cursor, Claude Desktop, …) with:
 }
 ```
 
-Eight tools are exposed over stdio.
+Nine tools are exposed over stdio.
 
-**Read-only:** `fullstackgtm_audit` (sample, demo, file, or live provider sources with optional rule scoping), `fullstackgtm_rules` (rule discovery), `fullstackgtm_suggest` (deterministic placeholder values with confidence + reasons), `fullstackgtm_call_parse` (transcripts → provenance-marked segments, insights, and evidence), `fullstackgtm_resolve` (the create gate: exists / ambiguous / safe_to_create), and `fullstackgtm_market_worksheet` (the classification packet for one vendor: claims, judging rules, captured page texts).
+**Read-only:** `fullstackgtm_audit` (sample, demo, file, or live provider sources with optional rule scoping), `fullstackgtm_capabilities` (server/tool capability manifest), `fullstackgtm_rules` (rule discovery), `fullstackgtm_suggest` (deterministic placeholder values with confidence + reasons), `fullstackgtm_call_parse` (transcripts → provenance-marked segments, insights, and evidence), `fullstackgtm_resolve` (the create gate: exists / ambiguous / safe_to_create), and `fullstackgtm_market_worksheet` (the classification packet for one vendor: claims, judging rules, captured page texts).
 
 **Gated:** `fullstackgtm_apply` (requires explicit `approvedOperationIds`; placeholders still need value overrides) and `fullstackgtm_market_observe` (verifies every quoted span against the stored captures before appending — nothing is stored unless the whole set passes).
 
@@ -547,6 +549,12 @@ Tokens stored via `fullstackgtm login` are picked up automatically — the env v
 2. Every proposed write is a typed patch operation with before/after values, a reason, and a risk level.
 3. `applyPatchPlan` enforces the contract for all connectors: only explicitly approved operation ids are written, placeholders require concrete override values, and every attempt produces a per-operation result record.
 
+## License & boundary
+
+Licensed under [Apache-2.0](./LICENSE). The boundary is deliberate and stable: the framework, CLI, and MCP server are open source; the hosted Full Stack GTM application (dashboard, sync backend, broker service, team workflows) is a separate, proprietary product built on top of this package. Features never move from open to closed. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how development and mirroring work.
+
+The surfaces in [docs/api.md](./docs/api.md) — the canonical model, rule interface, plan/apply contract, connector contract, merge/diff, config, CLI, and MCP tools — are settling but may still break in minor releases until 1.0. The safety invariants (read-only audits, approval-gated writes, placeholder refusal) are not beta and do not change.
+
 ## Development
 
 ```bash

package/dist/audit.js

@@ -33,6 +33,7 @@ export function auditSnapshot(snapshot, policy = defaultPolicy(), rules = builti
     const context = { snapshot, policy, index: buildSnapshotIndex(snapshot) };
     const findings = [];
     const operations = [];
+    const assumptionsById = new Map();
     for (const rule of rules) {
         try {
             onRule?.(rule.id, "start");
@@ -43,6 +44,10 @@ export function auditSnapshot(snapshot, policy = defaultPolicy(), rules = builti
         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);
         }
@@ -50,6 +55,7 @@ export function auditSnapshot(snapshot, policy = defaultPolicy(), rules = builti
             // progress is presentation-only
         }
     }
+    const assumptions = Array.from(assumptionsById.values());
     const evidence = buildEvidence(snapshot, findings, policy.today);
     const pipelineFindings = buildPipelineFindings(findings, operations, evidence, policy.today);
     linkOperationContext(operations, findings, evidence);
@@ -63,6 +69,7 @@ export function auditSnapshot(snapshot, policy = defaultPolicy(), rules = builti
         findings,
         pipelineFindings,
         evidence,
+        assumptions: assumptions.length > 0 ? assumptions : undefined,
         operations,
     };
 }

package/dist/backfill.js

@@ -11,6 +11,7 @@
  * connector re-resolves each invoice id (resolve-first) and creates only on
  * a confirmed miss.
  */
+import { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.js";
 import { normalizeDomain } from "./merge.js";
 // Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep backfill.ts
 // importable without pulling the audit engine (the enrich.ts precedent).
@@ -23,21 +24,6 @@ function fnv1a(value) {
     return (hash >>> 0).toString(16).padStart(8, "0");
 }
 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",
-]);
 /** `Invoice <number || id> — <customer name>` (the plan-time dedupe name). */
 function backfillDealName(invoice, companyName) {
     return `Invoice ${invoice.number ?? invoice.id} — ${invoice.customerName ?? companyName}`;
@@ -102,7 +88,7 @@ export function buildStripeBackfillPlan(invoices, snapshot, opts = {}) {
         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/dist/cli/fix.d.ts

@@ -31,3 +31,6 @@ export declare function reassignCommand(args: string[]): Promise<void>;
  */
 export declare function fixCommand(args: string[]): Promise<void>;
 export declare function suggest(args: string[]): Promise<void>;
+export declare function routeCommand(args: string[]): Promise<void>;
+export declare function hierarchyCommand(args: string[]): Promise<void>;
+export declare function relationshipsCommand(args: string[]): Promise<void>;

package/dist/cli/fix.js

@@ -1,5 +1,5 @@
 // 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.js";
 import { loadConfig, mergePolicy, resolveConfiguredRules } from "../config.js";
@@ -7,6 +7,10 @@ import { applyPatchPlan } from "../connector.js";
 import { patchPlanToMarkdown } from "../format.js";
 import { createFilePlanStore } from "../planStore.js";
 import { resolveRecord } from "../resolve.js";
+import { parseAssignmentPolicy } from "../assign.js";
+import { buildLeadRoutePlan } from "../route.js";
+import { accountHierarchyToMarkdown, buildAccountHierarchy } from "../hierarchy.js";
+import { buildRelationshipMap, relationshipMapToMarkdown } from "../relationships.js";
 import { buildBulkUpdatePlan } from "../bulkUpdate.js";
 import { buildDedupePlan } from "../dedupe.js";
 import { buildReassignPlans } from "../reassign.js";
@@ -344,3 +348,68 @@ function snapshotSourceHint(args) {
         return `--input ${input} `;
     return "";
 }
+function parseJsonOrFile(value) {
+    const candidate = resolve(process.cwd(), value);
+    const text = existsSync(candidate) ? readFileSync(candidate, "utf8") : value;
+    return JSON.parse(text);
+}
+export async function routeCommand(args) {
+    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) {
+    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) {
+    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/dist/cli/help.d.ts

@@ -10,6 +10,12 @@ export type HelpEntry = {
 };
 export declare const HELP: Record<string, HelpEntry>;
 export declare const BESPOKE_HELP: string[];
+export declare const GLOBAL_FLAGS: string[];
+export declare const GLOBAL_SHORT_FLAGS: string[];
+export declare const SOURCE_FLAGS: string[];
+export declare const AUDIT_FLAGS: string[];
+export declare const COMMAND_FLAGS: Record<string, string[]>;
+export declare const FLAGS_WITH_VALUES: Set<string>;
 export declare function shortUsage(): string;
 /**
  * Interactive-terminal styling for the short front door: a dimmed one-line

package/dist/cli/help.js

@@ -46,6 +46,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>]
@@ -386,7 +392,28 @@ export const HELP = {
         detail: "Prevention, not cleanup. Call before ANY record creation — a sync job, webhook, agent, or script. Returns exists/ambiguous/safe_to_create with matches and reasons; exit 2 = do not create.",
         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",
@@ -559,15 +586,62 @@ export const HELP = {
 // Verbs that print their own richer multi-subcommand help; runCli routes their
 // `--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 = {
+    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 = [
         ["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/dist/cli/suggest.d.ts

@@ -10,7 +10,7 @@ export declare 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[];
 };
@@ -29,6 +29,7 @@ export type FlagTypo = {
  * --jsn` exited 0 and printed markdown where the agent asked for JSON.
  */
 export declare function detectFlagTypo(args: string[]): FlagTypo | null;
+export declare function detectUnknownFlag(command: string, args: string[]): FlagTypo | null;
 /** Nearest known command, derived from the same HELP table. */
 export declare function suggestCommand(command: string): string | null;
 /**

package/dist/cli/suggest.js

@@ -11,7 +11,7 @@
 // (exit 1) that prints the exact corrected command for the agent to run
 // 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.js";
+import { COMMAND_FLAGS, FLAGS_WITH_VALUES, GLOBAL_FLAGS, GLOBAL_SHORT_FLAGS, HELP, usage, } from "./help.js";
 export function levenshtein(a, b) {
     const dp = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
     for (let i = 0; i <= a.length; i += 1)
@@ -96,6 +96,52 @@ export function detectFlagTypo(args) {
     }
     return null;
 }
+function isFlagShaped(token) {
+    return token !== "-" && token.startsWith("-");
+}
+function suggestCommandFlag(unknown, allowed) {
+    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, args) {
+    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) {
     if (!command)
@@ -127,8 +173,8 @@ export function unknownFlagEnvelope(command, args, typo) {
             code: "UNKNOWN_FLAG",
             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)}`] : []),
             ],
         },
     };