fullstackgtm 0.10.1 → 0.11.1

package/dist/report.js

@@ -0,0 +1,331 @@
+import { REQUIRES_HUMAN_PREFIX } from "./rules.js";
+const SEVERITY_ORDER = ["critical", "warning", "info"];
+const SEVERITY_RANK = {
+    critical: 2,
+    warning: 1,
+    info: 0,
+};
+export function buildReportModel(plan, options = {}) {
+    const ruleMeta = new Map((options.rules ?? []).map((rule) => [rule.id, rule]));
+    const byRule = new Map();
+    for (const finding of plan.findings) {
+        const findings = byRule.get(finding.ruleId) ?? [];
+        findings.push(finding);
+        byRule.set(finding.ruleId, findings);
+    }
+    const sections = Array.from(byRule.entries())
+        .map(([ruleId, findings]) => {
+        const meta = ruleMeta.get(ruleId);
+        const severity = findings.reduce((worst, finding) => SEVERITY_RANK[finding.severity] > SEVERITY_RANK[worst] ? finding.severity : worst, "info");
+        return {
+            ruleId,
+            title: meta?.title ?? ruleId,
+            description: meta?.description,
+            category: meta?.category ?? "uncategorized",
+            severity,
+            findings,
+        };
+    })
+        .sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] ||
+        b.findings.length - a.findings.length ||
+        a.ruleId.localeCompare(b.ruleId));
+    const severityCounts = {
+        critical: 0,
+        warning: 0,
+        info: 0,
+    };
+    const affected = new Set();
+    for (const finding of plan.findings) {
+        severityCounts[finding.severity] += 1;
+        affected.add(`${finding.objectType}:${finding.objectId}`);
+    }
+    const snapshot = options.snapshot;
+    const recordCounts = snapshot
+        ? [
+            { label: "Accounts", count: snapshot.accounts.length },
+            { label: "Contacts", count: snapshot.contacts.length },
+            { label: "Deals", count: snapshot.deals.length },
+            { label: "Users", count: snapshot.users.length },
+            { label: "Activities", count: snapshot.activities.length },
+        ]
+        : undefined;
+    const totalRecords = recordCounts?.reduce((sum, entry) => sum + entry.count, 0);
+    const recordLabels = new Map();
+    if (snapshot) {
+        for (const row of snapshot.accounts)
+            recordLabels.set(`account:${row.id}`, row.name);
+        for (const row of snapshot.users)
+            recordLabels.set(`user:${row.id}`, row.name);
+        for (const row of snapshot.deals)
+            recordLabels.set(`deal:${row.id}`, row.name);
+        for (const row of snapshot.contacts) {
+            const name = [row.firstName, row.lastName].filter(Boolean).join(" ") || row.email;
+            if (name)
+                recordLabels.set(`contact:${row.id}`, name);
+        }
+    }
+    const humanInputOperationCount = plan.operations.filter((operation) => typeof operation.afterValue === "string" &&
+        operation.afterValue.startsWith(REQUIRES_HUMAN_PREFIX)).length;
+    const model = {
+        title: options.title ?? "GTM Data Health Report",
+        clientName: options.clientName,
+        preparedBy: options.preparedBy,
+        date: options.date ?? plan.createdAt.slice(0, 10),
+        provider: snapshot?.provider,
+        recordCounts,
+        totalRecords,
+        severityCounts,
+        affectedRecords: affected.size,
+        sections,
+        maxExamplesPerRule: Math.max(1, options.maxExamplesPerRule ?? 10),
+        operationCount: plan.operations.length,
+        humanInputOperationCount,
+        recordLabels,
+        summaryText: "",
+    };
+    model.summaryText = summaryText(model);
+    return model;
+}
+function summaryText(model) {
+    const subject = model.clientName ? `${model.clientName}'s CRM data` : "the CRM data";
+    if (model.sections.length === 0) {
+        return `This audit reviewed ${subject} and found no issues with the rules that ran. The checks are deterministic and can be re-run at any time to confirm the data stays healthy.`;
+    }
+    const total = model.sections.reduce((sum, section) => sum + section.findings.length, 0);
+    const severityParts = SEVERITY_ORDER.filter((severity) => model.severityCounts[severity] > 0)
+        .map((severity) => `${model.severityCounts[severity]} ${severity}`)
+        .join(", ");
+    const scope = model.totalRecords !== undefined
+        ? `${model.affectedRecords} of ${model.totalRecords} records (${percent(model.affectedRecords, model.totalRecords)}%)`
+        : `${model.affectedRecords} records`;
+    const top = model.sections[0];
+    const fixes = model.operationCount > 0
+        ? ` ${model.operationCount} of the issues have a proposed fix ready for review; nothing is changed in the CRM until each fix is explicitly approved.`
+        : "";
+    return (`This audit reviewed ${subject} and surfaced ${total} findings (${severityParts}) across ${scope}. ` +
+        `The largest issue is "${top.title}" (${top.findings.length} records).${fixes}`);
+}
+function percent(part, whole) {
+    if (whole === 0)
+        return 0;
+    return Math.round((part / whole) * 100);
+}
+function findingLabel(model, finding) {
+    const name = model.recordLabels.get(`${finding.objectType}:${finding.objectId}`);
+    return name ? `${name} (${finding.objectType})` : `${finding.objectType}/${finding.objectId}`;
+}
+export function auditReportToMarkdown(plan, options = {}) {
+    const model = buildReportModel(plan, options);
+    const lines = [];
+    lines.push(`# ${model.title}${model.clientName ? ` — ${model.clientName}` : ""}`, "");
+    const subtitle = [
+        `Prepared ${model.date}`,
+        model.provider ? `Source: ${model.provider}` : null,
+        model.preparedBy ? `By: ${model.preparedBy}` : null,
+    ].filter(Boolean);
+    lines.push(subtitle.join(" · "), "");
+    lines.push("## At a Glance", "", "| Metric | Value |", "| --- | --- |");
+    if (model.recordCounts && model.totalRecords !== undefined) {
+        lines.push(`| Records audited | ${model.totalRecords} (${model.recordCounts
+            .map((entry) => `${entry.count} ${entry.label.toLowerCase()}`)
+            .join(", ")}) |`);
+    }
+    const totalFindings = SEVERITY_ORDER.reduce((sum, severity) => sum + model.severityCounts[severity], 0);
+    lines.push(`| Findings | ${totalFindings} |`);
+    for (const severity of SEVERITY_ORDER) {
+        lines.push(`| ${capitalize(severity)} | ${model.severityCounts[severity]} |`);
+    }
+    lines.push(`| Records affected | ${model.affectedRecords}${model.totalRecords !== undefined && model.totalRecords > 0
+        ? ` (${percent(model.affectedRecords, model.totalRecords)}%)`
+        : ""} |`, `| Proposed fixes | ${model.operationCount}${model.humanInputOperationCount > 0
+        ? ` (${model.humanInputOperationCount} need a human-chosen value)`
+        : ""} |`, "");
+    lines.push("## Summary", "", model.summaryText, "");
+    if (model.sections.length > 0) {
+        lines.push("## Findings by Rule", "", "| Rule | Category | Severity | Records |", "| --- | --- | --- | --- |");
+        for (const section of model.sections) {
+            lines.push(`| ${section.title} | ${section.category} | ${section.severity} | ${section.findings.length} |`);
+        }
+        lines.push("", "## Details", "");
+        for (const section of model.sections) {
+            lines.push(`### ${section.title} (${section.findings.length} ${section.findings.length === 1 ? "record" : "records"}, ${section.severity})`, "");
+            if (section.description)
+                lines.push(section.description, "");
+            const shown = section.findings.slice(0, model.maxExamplesPerRule);
+            for (const finding of shown) {
+                lines.push(`- **${findingLabel(model, finding)}** — ${finding.summary}`);
+                lines.push(`  - Recommendation: ${finding.recommendation}`);
+            }
+            const hidden = section.findings.length - shown.length;
+            if (hidden > 0)
+                lines.push(`- … and ${hidden} more.`);
+            lines.push("");
+        }
+        lines.push("## Recommended Next Steps", "");
+        if (model.operationCount > 0) {
+            lines.push(`1. Review the ${model.operationCount} proposed fixes (\`fullstackgtm audit --save\`, then \`fullstackgtm plans show <id>\`).`, `2. Approve the operations to apply${model.humanInputOperationCount > 0
+                ? `, supplying values for the ${model.humanInputOperationCount} that need a human decision`
+                : ""} (\`fullstackgtm plans approve\`). Nothing is written without explicit approval.`, "3. Re-run the audit after applying to confirm the findings clear, and schedule it recurring to catch regressions.");
+        }
+        else {
+            lines.push("1. Address the findings above in the CRM (no automated fixes are available for them yet).", "2. Re-run the audit to confirm the findings clear, and schedule it recurring to catch regressions.");
+        }
+        lines.push("");
+    }
+    lines.push("---", "", `Generated by the fullstackgtm CLI on ${model.date}.` +
+        (model.preparedBy ? ` Prepared by ${model.preparedBy}.` : "") +
+        " Findings are deterministic and re-runnable; no CRM data was modified to produce this report.");
+    return `${lines.join("\n")}\n`;
+}
+const SEVERITY_COLORS = {
+    critical: { fg: "#991b1b", bg: "#fee2e2" },
+    warning: { fg: "#92400e", bg: "#fef3c7" },
+    info: { fg: "#1e40af", bg: "#dbeafe" },
+};
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function severityBadge(severity) {
+    const colors = SEVERITY_COLORS[severity];
+    return `<span class="badge" style="color:${colors.fg};background:${colors.bg}">${severity}</span>`;
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/**
+ * Self-contained HTML (inline styles, no external assets) so the file can be
+ * emailed or dropped into a shared drive and render anywhere, including
+ * print-to-PDF.
+ */
+export function auditReportToHtml(plan, options = {}) {
+    const model = buildReportModel(plan, options);
+    const totalFindings = SEVERITY_ORDER.reduce((sum, severity) => sum + model.severityCounts[severity], 0);
+    const glanceRows = [];
+    if (model.recordCounts && model.totalRecords !== undefined) {
+        glanceRows.push(row("Records audited", `${model.totalRecords} (${model.recordCounts
+            .map((entry) => `${entry.count} ${entry.label.toLowerCase()}`)
+            .join(", ")})`));
+    }
+    glanceRows.push(row("Findings", String(totalFindings)));
+    for (const severity of SEVERITY_ORDER) {
+        glanceRows.push(`<tr><th>${capitalize(severity)}</th><td>${model.severityCounts[severity]} ${severityBadge(severity)}</td></tr>`);
+    }
+    glanceRows.push(row("Records affected", `${model.affectedRecords}${model.totalRecords !== undefined && model.totalRecords > 0
+        ? ` (${percent(model.affectedRecords, model.totalRecords)}%)`
+        : ""}`), row("Proposed fixes", `${model.operationCount}${model.humanInputOperationCount > 0
+        ? ` (${model.humanInputOperationCount} need a human-chosen value)`
+        : ""}`));
+    const ruleRows = model.sections
+        .map((section) => `<tr><td>${escapeHtml(section.title)}</td><td>${escapeHtml(section.category)}</td>` +
+        `<td>${severityBadge(section.severity)}</td><td class="num">${section.findings.length}</td></tr>`)
+        .join("\n");
+    const detailSections = model.sections
+        .map((section) => {
+        const shown = section.findings.slice(0, model.maxExamplesPerRule);
+        const hidden = section.findings.length - shown.length;
+        const items = shown
+            .map((finding) => `<li><strong>${escapeHtml(findingLabel(model, finding))}</strong> — ${escapeHtml(finding.summary)}` +
+            `<div class="rec">Recommendation: ${escapeHtml(finding.recommendation)}</div></li>`)
+            .join("\n");
+        return [
+            `<section>`,
+            `<h3>${escapeHtml(section.title)} <span class="count">${section.findings.length} ${section.findings.length === 1 ? "record" : "records"}</span> ${severityBadge(section.severity)}</h3>`,
+            section.description ? `<p>${escapeHtml(section.description)}</p>` : "",
+            `<ul>`,
+            items,
+            hidden > 0 ? `<li class="more">… and ${hidden} more.</li>` : "",
+            `</ul>`,
+            `</section>`,
+        ]
+            .filter(Boolean)
+            .join("\n");
+    })
+        .join("\n");
+    const nextSteps = model.sections.length === 0
+        ? ""
+        : model.operationCount > 0
+            ? `<ol>
+<li>Review the ${model.operationCount} proposed fixes (<code>fullstackgtm audit --save</code>, then <code>fullstackgtm plans show &lt;id&gt;</code>).</li>
+<li>Approve the operations to apply${model.humanInputOperationCount > 0
+                ? `, supplying values for the ${model.humanInputOperationCount} that need a human decision`
+                : ""} (<code>fullstackgtm plans approve</code>). Nothing is written without explicit approval.</li>
+<li>Re-run the audit after applying to confirm the findings clear, and schedule it recurring to catch regressions.</li>
+</ol>`
+            : `<ol>
+<li>Address the findings above in the CRM (no automated fixes are available for them yet).</li>
+<li>Re-run the audit to confirm the findings clear, and schedule it recurring to catch regressions.</li>
+</ol>`;
+    const subtitle = [
+        `Prepared ${model.date}`,
+        model.provider ? `Source: ${escapeHtml(model.provider)}` : null,
+        model.preparedBy ? `By: ${escapeHtml(model.preparedBy)}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(model.title)}${model.clientName ? ` — ${escapeHtml(model.clientName)}` : ""}</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+         color: #1f2937; max-width: 860px; margin: 0 auto; padding: 2rem 1.5rem; line-height: 1.55; }
+  h1 { font-size: 1.6rem; margin-bottom: 0.25rem; }
+  h2 { font-size: 1.2rem; margin-top: 2rem; border-bottom: 1px solid #e5e7eb; padding-bottom: 0.3rem; }
+  h3 { font-size: 1.05rem; margin-top: 1.5rem; }
+  .subtitle { color: #6b7280; margin-top: 0; }
+  table { border-collapse: collapse; width: 100%; margin: 0.75rem 0; }
+  th, td { text-align: left; padding: 0.4rem 0.6rem; border-bottom: 1px solid #e5e7eb; font-size: 0.95rem; }
+  th { color: #374151; font-weight: 600; }
+  td.num { text-align: right; }
+  .badge { display: inline-block; padding: 0.05rem 0.5rem; border-radius: 999px;
+           font-size: 0.78rem; font-weight: 600; vertical-align: middle; }
+  .count { color: #6b7280; font-weight: 400; font-size: 0.9rem; }
+  ul { padding-left: 1.2rem; }
+  li { margin-bottom: 0.5rem; }
+  .rec { color: #4b5563; font-size: 0.92rem; }
+  .more { color: #6b7280; list-style: none; }
+  code { background: #f3f4f6; padding: 0.1rem 0.3rem; border-radius: 4px; font-size: 0.88rem; }
+  footer { margin-top: 2.5rem; padding-top: 1rem; border-top: 1px solid #e5e7eb;
+           color: #6b7280; font-size: 0.85rem; }
+  @media print { body { padding: 0; } }
+</style>
+</head>
+<body>
+<h1>${escapeHtml(model.title)}${model.clientName ? ` — ${escapeHtml(model.clientName)}` : ""}</h1>
+<p class="subtitle">${subtitle}</p>
+
+<h2>At a Glance</h2>
+<table>
+${glanceRows.join("\n")}
+</table>
+
+<h2>Summary</h2>
+<p>${escapeHtml(model.summaryText)}</p>
+${model.sections.length > 0
+        ? `
+<h2>Findings by Rule</h2>
+<table>
+<tr><th>Rule</th><th>Category</th><th>Severity</th><th class="num">Records</th></tr>
+${ruleRows}
+</table>
+
+<h2>Details</h2>
+${detailSections}
+
+<h2>Recommended Next Steps</h2>
+${nextSteps}`
+        : ""}
+<footer>Generated by the fullstackgtm CLI on ${model.date}.${model.preparedBy ? ` Prepared by ${escapeHtml(model.preparedBy)}.` : ""} Findings are deterministic and re-runnable; no CRM data was modified to produce this report.</footer>
+</body>
+</html>
+`;
+}
+function row(label, value) {
+    return `<tr><th>${escapeHtml(label)}</th><td>${escapeHtml(value)}</td></tr>`;
+}

package/dist/rules.d.ts

@@ -18,6 +18,7 @@ export declare const staleDealRule: GtmAuditRule;
 export declare const missingDealAmountRule: GtmAuditRule;
 export declare const duplicateAccountDomainRule: GtmAuditRule;
 export declare const duplicateContactEmailRule: GtmAuditRule;
+export declare const duplicateOpenDealRule: GtmAuditRule;
 export declare const activeDealAccountWithoutContactsRule: GtmAuditRule;
 export declare const closingSoonInactiveRule: GtmAuditRule;
 export declare const accountSingleSourceRule: GtmAuditRule;

package/dist/rules.js

@@ -1,3 +1,4 @@
+import { normalizeDomain } from "./merge.js";
 /**
  * Placeholder used as `afterValue` when the right value is a human decision
  * (e.g. which owner to assign). Apply orchestration refuses to write these
@@ -316,7 +317,7 @@ export const duplicateAccountDomainRule = {
     evaluate: ({ snapshot }) => {
         const findings = [];
         const operations = [];
-        for (const [domain, accounts] of duplicateGroups(snapshot.accounts, (account) => account.domain)) {
+        for (const [domain, accounts] of duplicateGroups(snapshot.accounts, (account) => normalizeDomain(account.domain))) {
             const anchor = accounts[0];
             findings.push({
                 id: auditFindingId("duplicate-account-domain", anchor.id),
@@ -380,6 +381,52 @@ export const duplicateContactEmailRule = {
         return { findings, operations };
     },
 };
+export const duplicateOpenDealRule = {
+    id: "duplicate-open-deal",
+    title: "Open deals duplicate the same opportunity",
+    description: "Flags multiple open deals carrying the same name (scoped to the account when linked) — " +
+        "usually an integration re-creating deals instead of upserting, which counts the same " +
+        "revenue several times in pipeline and forecast.",
+    category: "data-quality",
+    evaluate: ({ snapshot }) => {
+        const findings = [];
+        const operations = [];
+        const keyOf = (deal) => {
+            if (!isOpen(deal))
+                return undefined;
+            const name = deal.name?.trim().toLowerCase().replace(/\s+/g, " ");
+            if (!name)
+                return undefined;
+            return `${deal.accountId ?? "unlinked"}:${name}`;
+        };
+        for (const [, deals] of duplicateGroups(snapshot.deals, keyOf)) {
+            const anchor = deals[0];
+            findings.push({
+                id: auditFindingId("duplicate-open-deal", anchor.id),
+                objectType: "deal",
+                objectId: anchor.id,
+                ruleId: "duplicate-open-deal",
+                title: "Open deals duplicate the same opportunity",
+                severity: "warning",
+                summary: `${deals.length} open deals named "${anchor.name}"${anchor.accountId ? " on the same account" : ""}: ${deals.map((deal) => deal.id).join(", ")}.`,
+                recommendation: "Keep one deal, archive the copies, and fix the integration that is re-creating them.",
+            });
+            operations.push({
+                id: patchOperationId("duplicate-open-deal", anchor.id),
+                objectType: "deal",
+                objectId: anchor.id,
+                operation: "create_task",
+                field: "merge_review_task",
+                beforeValue: null,
+                afterValue: `Review ${deals.length} duplicate open deals named "${anchor.name}" — keep one, archive ${deals.length - 1}`,
+                reason: "Duplicate open deals inflate pipeline and forecast the same revenue more than once.",
+                riskLevel: "medium",
+                approvalRequired: true,
+            });
+        }
+        return { findings, operations };
+    },
+};
 export const activeDealAccountWithoutContactsRule = {
     id: "active-deal-account-without-contacts",
     title: "Account with open pipeline has no contacts",
@@ -506,6 +553,7 @@ export const builtinAuditRules = [
     missingDealAmountRule,
     duplicateAccountDomainRule,
     duplicateContactEmailRule,
+    duplicateOpenDealRule,
     activeDealAccountWithoutContactsRule,
     closingSoonInactiveRule,
     accountSingleSourceRule,

package/dist/suggest.d.ts

@@ -0,0 +1,31 @@
+import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+/**
+ * Deterministic value suggestions for `requires_human_*` placeholder
+ * operations. The engine never invents data: every suggestion is derived
+ * from evidence already in the snapshot (account names, contact→account
+ * associations, the org's user list) and carries a confidence level plus a
+ * human-readable reason, so a reviewer — or an agent driving the CLI — can
+ * approve in bulk at a chosen confidence threshold.
+ *
+ * Born from dogfooding: an audit of a real portal produced 30
+ * `requires_human_account_selection` placeholders whose answers were all
+ * derivable from the snapshot itself.
+ */
+export type SuggestionConfidence = "high" | "low" | "create" | "none";
+export type ValueSuggestion = {
+    operationId: string;
+    objectType: string;
+    objectId: string;
+    /** Display name of the object the operation targets (e.g. the deal name). */
+    objectName?: string;
+    /** The requires_human_* placeholder being filled. */
+    placeholder: string;
+    /**
+     * The value to approve with, or null when no evidence supports one.
+     * `create:<Name>` proposes creating the missing record on apply.
+     */
+    suggestedValue: string | null;
+    confidence: SuggestionConfidence;
+    reason: string;
+};
+export declare function suggestValues(plan: PatchPlan, snapshot: CanonicalGtmSnapshot): ValueSuggestion[];

package/dist/suggest.js

@@ -0,0 +1,148 @@
+import { requiresHumanInput } from "./rules.js";
+export function suggestValues(plan, snapshot) {
+    const accountsByNorm = new Map();
+    for (const account of snapshot.accounts) {
+        accountsByNorm.set(normalize(account.name), { id: account.id, name: account.name });
+    }
+    const accountsById = new Map(snapshot.accounts.map((a) => [a.id, a]));
+    const contactsByName = new Map();
+    for (const contact of snapshot.contacts) {
+        const name = normalize(`${contact.firstName ?? ""} ${contact.lastName ?? ""}`);
+        if (name)
+            contactsByName.set(name, { id: contact.id, accountId: contact.accountId, name });
+    }
+    const dealsById = new Map(snapshot.deals.map((d) => [d.id, d]));
+    const activeUsers = snapshot.users.filter((user) => user.active !== false);
+    const suggestions = [];
+    for (const operation of plan.operations) {
+        if (!requiresHumanInput(operation.afterValue))
+            continue;
+        const placeholder = String(operation.afterValue);
+        if (placeholder === "requires_human_account_selection" && operation.objectType === "deal") {
+            suggestions.push(suggestDealAccount(operation, dealsById, accountsByNorm, accountsById, contactsByName));
+            continue;
+        }
+        if (placeholder === "requires_human_owner_selection" && activeUsers.length === 1) {
+            suggestions.push({
+                operationId: operation.id,
+                objectType: operation.objectType,
+                objectId: operation.objectId,
+                objectName: dealsById.get(operation.objectId)?.name,
+                placeholder,
+                suggestedValue: activeUsers[0].id,
+                confidence: "high",
+                reason: `${activeUsers[0].name} is the only active user in the org.`,
+            });
+            continue;
+        }
+        suggestions.push({
+            operationId: operation.id,
+            objectType: operation.objectType,
+            objectId: operation.objectId,
+            objectName: dealsById.get(operation.objectId)?.name,
+            placeholder,
+            suggestedValue: null,
+            confidence: "none",
+            reason: `No deterministic heuristic for ${placeholder}; supply --value ${operation.id}=<value>.`,
+        });
+    }
+    return suggestions;
+}
+function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById, contactsByName) {
+    const deal = dealsById.get(operation.objectId);
+    const base = {
+        operationId: operation.id,
+        objectType: operation.objectType,
+        objectId: operation.objectId,
+        objectName: deal?.name,
+        placeholder: "requires_human_account_selection",
+    };
+    if (!deal) {
+        return { ...base, suggestedValue: null, confidence: "none", reason: "Deal not found in the snapshot." };
+    }
+    // Convention: "Contact Name - Company Name". Both signals below are
+    // independent; agreement upgrades confidence, conflict downgrades it.
+    const separatorIndex = deal.name.indexOf(" - ");
+    const left = separatorIndex >= 0 ? deal.name.slice(0, separatorIndex) : deal.name;
+    const right = separatorIndex >= 0 ? deal.name.slice(separatorIndex + 3).trim() : "";
+    // Signal 1: company-name match against account names.
+    let nameMatch = null;
+    let nameMatchKind = "";
+    if (right) {
+        nameMatch = accountsByNorm.get(normalize(right)) ?? null;
+        nameMatchKind = nameMatch ? "exact name match" : "";
+        if (!nameMatch) {
+            const rightNorm = normalize(right);
+            const candidates = [...accountsByNorm.entries()].filter(([norm]) => norm.includes(rightNorm) || rightNorm.includes(norm));
+            if (candidates.length === 1) {
+                nameMatch = candidates[0][1];
+                nameMatchKind = "partial name match";
+            }
+            else if (candidates.length > 1) {
+                return {
+                    ...base,
+                    suggestedValue: null,
+                    confidence: "none",
+                    reason: `"${right}" matches ${candidates.length} accounts ambiguously: ${candidates.slice(0, 4).map(([, a]) => a.name).join(", ")}.`,
+                };
+            }
+        }
+    }
+    // Signal 2: the deal's named contact already belongs to an account.
+    const contact = contactsByName.get(normalize(left));
+    const contactAccount = contact?.accountId ? accountsById.get(contact.accountId) ?? null : null;
+    if (nameMatch && contactAccount) {
+        if (nameMatch.id === contactAccount.id) {
+            return {
+                ...base,
+                suggestedValue: nameMatch.id,
+                confidence: "high",
+                reason: `${nameMatchKind} on "${nameMatch.name}", confirmed by contact "${left}"'s account association.`,
+            };
+        }
+        return {
+            ...base,
+            suggestedValue: null,
+            confidence: "none",
+            reason: `Signals conflict: name matches "${nameMatch.name}" but contact "${left}" belongs to "${contactAccount.name}".`,
+        };
+    }
+    if (nameMatch) {
+        return {
+            ...base,
+            suggestedValue: nameMatch.id,
+            confidence: nameMatchKind === "exact name match" ? "high" : "low",
+            reason: `${nameMatchKind} on "${nameMatch.name}" (no contact signal to confirm).`,
+        };
+    }
+    if (contactAccount) {
+        return {
+            ...base,
+            suggestedValue: contactAccount.id,
+            confidence: "low",
+            reason: `Contact "${left}" belongs to "${contactAccount.name}" (no account-name match to confirm).`,
+        };
+    }
+    if (contact && !contact.accountId && right) {
+        return {
+            ...base,
+            suggestedValue: `create:${right}`,
+            confidence: "create",
+            reason: `No account named "${right}" exists and contact "${left}" has none — approving creates the company, then links.`,
+        };
+    }
+    return {
+        ...base,
+        suggestedValue: null,
+        confidence: "none",
+        reason: right
+            ? `No account matches "${right}" and "${left}" is not a known contact. Supply --value ${operation.id}=<accountId> or --value ${operation.id}=create:<Company Name>.`
+            : `Deal name "${deal.name}" has no "Contact - Company" pattern to derive a company from. Supply --value ${operation.id}=<accountId> or create:<Company Name>.`,
+    };
+}
+function normalize(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}

package/docs/api.md

@@ -57,7 +57,8 @@ release.
 
 ## CLI
 
-Commands: `login` / `logout`, `snapshot`, `audit`, `diff`, `merge`, `plans`, `apply`, `rules`.
+Commands: `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
+`apply`, `rules`, `profiles`, `doctor`.
 Exit codes: `0` success · `1` error · `2` findings/regressions at the requested gate
 (`--fail-on`, `--fail-on-new-findings`). `--json` everywhere; JSON output shapes are stable.
 
@@ -66,6 +67,17 @@ Credential resolution ladder: explicit `--token-env` → ambient env
 `STRIPE_SECRET_KEY`) → stored login (`~/.fullstackgtm`, `FSGTM_HOME` override)
 → broker pairing (`login --via`).
 
+Profiles: the global `--profile <name>` flag (or `FULLSTACKGTM_PROFILE`) scopes
+stored logins and stored plans to `profiles/<name>/` under the home directory,
+so one operator can work across several organizations' CRMs without mixing
+credentials or applying one org's plan through another's connection. The
+default profile keeps the historical flat layout.
+
+`report` renders an audit (or an existing plan via `--plan`) as a client-ready
+deliverable in markdown or self-contained HTML: severity counts, prose summary,
+per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
+`auditReportToHtml` expose the same rendering programmatically.
+
 ## MCP
 
 Tools: `fullstackgtm_audit`, `fullstackgtm_rules`, `fullstackgtm_apply`