fullstackgtm 0.10.1 → 0.11.1

package/docs/crm-health-lifecycle.md

@@ -0,0 +1,135 @@
+# The CRM-health CRUD lifecycle: no new dupes
+
+How fullstackgtm keeps a CRM healthy over time — not just episodically
+audited. Grounded in dogfooding against a real portal (an outreach sync
+tripled five open deals; our own `create:` path nearly minted a duplicate
+company) and in what the platforms actually support today (verified 2026-06).
+
+## The model: Prevent → Detect → Remediate → Verify/Attribute
+
+Every mature dedupe stack (RingLead/ZoomInfo Ops, Insycle, Openprise,
+Dedupely) converged on three layers, because each one leaks:
+
+1. **Prevent** at write time — unique keys, upserts, point-of-entry gates.
+   Leaks because: HubSpot does not dedupe companies created via API at all,
+   deals have no native dedupe on any platform, and Salesforce duplicate
+   rules skip standard lead conversion.
+2. **Detect** continuously — scheduled scans, because prevention leaked.
+3. **Remediate** via survivor-rule-driven merge — irreversible on both
+   platforms, which is why preview/dry-run is table stakes.
+
+fullstackgtm adds the layer the industry mostly lacks: **Verify/Attribute** —
+typed, approved operations with compare-and-set, readback, drift diffs, and
+record-source provenance that names *which writer* created the mess, so you
+fix the faucet instead of mopping the puddle.
+
+## C — Create: gate the faucet
+
+**Platform facts to exploit before building anything:**
+
+| | HubSpot | Salesforce |
+| --- | --- | --- |
+| Contacts | API create with existing email → **409 with existing ID** (a free find-or-create) | Duplicate Rules fire on API writes (`DUPLICATES_DETECTED`); Alert-action rules bypassable via `DuplicateRuleHeader`, Block never |
+| Companies/Accounts | **No API dedupe** (UI/import domain-dedupe does not apply to API) | Same duplicate-rule machinery |
+| Deals/Opps | **No native dedupe anywhere** | No standard duplicate rule shipped |
+| Idempotent writes | `batch/upsert` keyed on unique-value custom properties (≤10/object) | Upsert by External ID field — explicitly idempotent |
+| Leak paths | API company creates; anything without email | Standard lead conversion, Quick Create, undelete |
+
+**Our primitives and their duties:**
+- `create:<Name>` link values must be **resolve-first**: search the live CRM
+  (and the current plan run) for an existing record before creating; link to
+  a unique match, refuse on ambiguity, create only on a confirmed miss.
+  HubSpot's search API is eventually consistent (~5–10s), so same-run
+  creations are deduped in memory, not via search.
+- A standalone **`resolve` gate** (planned, 0.13): given a candidate
+  record, return existing match(es) or "safe to create" — for the CLI, the
+  library, MCP, and any external writer (sync jobs, agents, webhook
+  handlers). Identity keys are the ones the package already uses:
+  contact email, normalized account domain, and the open-deal key
+  (account + normalized name).
+- **Stamp provenance on our own creates** (HubSpot allows integrations to
+  set `hs_object_source_detail_2/3` at create time).
+- Recommend native config in `doctor`/audit: Salesforce duplicate rules
+  active? HubSpot unique-value properties defined? Prevention posture is
+  auditable configuration, not just record state.
+
+## R — Read: watch continuously, attribute the source
+
+- The regression primitive exists: `fullstackgtm diff --before a.json
+  --after b.json --fail-on-new-findings` exits 2 when a (rule, record) pair
+  fires that didn't before. "New" is a stable finding id — the hash of
+  (ruleId, objectId).
+- **The nightly watch recipe** ("CRM CI"): scheduled
+  `snapshot → audit → diff` against yesterday's snapshot, alert on exit 2.
+- **Attribution** (planned, 0.13): capture HubSpot's read-only
+  `hs_object_source`, `hs_object_source_label`, `hs_object_source_id` into
+  the canonical model so duplicate findings can say *"all five created by
+  integration X"*. The fix for recurring dupes is upstream, in the writer.
+- Incremental reads (`snapshot --since`) exist for all three connectors;
+  caveats: HubSpot deltas carry no associations and cap at 10k per object,
+  Stripe deltas catch creations only.
+
+## U — Update: governed merge
+
+**Platform facts:** HubSpot's v3 merge endpoint
+(`POST /crm/v3/objects/{type}/merge`) supports contacts, companies,
+**deals**, and tickets today (the 2019 "no deal merge API" changelog is
+obsolete). Merges are pairwise, the loser is auto-archived, primary's
+values win, **merges cannot be undone**, and a record stops merging after
+250 cumulative merges. Salesforce merge is SOAP/Apex only (no REST), only
+Lead/Contact/Account/Case, max 3 records per call.
+
+**The gap:** our three duplicate rules (`duplicate-account-domain`,
+`duplicate-contact-email`, `duplicate-open-deal`) detect groups but emit
+only merge-review *tasks* — detection without remediation.
+
+**The plan (0.12):** a `merge_records` operation type —
+`requires_human_survivor_selection` placeholder, survivor heuristics in
+`suggest` (ordered, evidence-based: most engagements → oldest → most
+complete, each with a written reason), high risk, approval required, with
+the irreversibility called out in the plan text. The dry-run plan is the
+preview every commercial tool charges for; the pre-apply snapshot is the
+loser-record archive. HubSpot first; Salesforce merge documented as
+unsupported until an Apex path justifies itself.
+
+## D — Delete/Archive: the exit ramp
+
+- `archive_record` exists in both connectors (HubSpot DELETE = archive,
+  restorable ~90 days; Salesforce DELETE = recycle bin) but no built-in
+  rule emits it. It is the endpoint for reviewed orphans; merge losers are
+  archived by the merge APIs themselves.
+- All destructive operations stay high-risk, approval-required, and behind
+  compare-and-set where the platform exposes a readable before-value.
+
+## Write-path integrity rules (our own faucet)
+
+Lessons from auditing our own apply path:
+
+1. Field writes (`set_field`/`clear_field`/`link_record`) are protected by
+   compare-and-set: the live value is read back and a drifted value returns
+   `conflict` without writing.
+2. CAS is only as good as `readField` — for HubSpot deals, `accountId` is
+   an association, not a property, and must be read via the associations
+   API or CAS silently passes on replay (fixed in 0.11.1).
+3. `create:` values are resolve-first and deduped within a plan run
+   (0.11.1); `create_task` operations carry an idempotency token in the
+   task body and pre-check for it (0.11.1, fail-open on search errors).
+4. Plan replays are blocked at the store (`--plan-id` of an applied plan
+   refuses); the `--plan <file>` path relies on CAS — prefer the store.
+
+## The operating cadence
+
+**Gate** creates (resolve-first, upserts, native rules on) →
+**Watch** nightly (snapshot, diff, exit-2 alert) →
+**Fix** governed (audit → suggest → approve → apply, incl. merge) →
+**Verify** (readback, re-audit, drift report) →
+**Attribute** (provenance names the writer; fix the faucet).
+
+## Build order
+
+| Release | Scope |
+| --- | --- |
+| 0.11.1 | Fix our own faucet: resolve-first `create:` + plan-scoped dedup, HubSpot association-aware CAS for `link_record`, domain normalization in `duplicate-account-domain`, `create_task` idempotency token |
+| 0.12 | `merge_records` (HubSpot contacts/companies/deals) + survivor suggestions; rules emit governed merges for dupe groups |
+| 0.13 | `resolve` gate (CLI/lib/MCP), provenance capture + attribution in findings, prevention-posture checks |
+| docs | The nightly watch recipe (existing flags, documented as CRM CI) |

package/llms.txt

@@ -15,6 +15,7 @@ at/above `--fail-on`.
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
+- [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history
 
 ## Key invariants

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",

package/src/cli.ts

@@ -19,11 +19,15 @@ import {
   validateSalesforceToken,
 } from "./connectors/salesforceAuth.ts";
 import {
+  activeProfile,
   credentialsPath,
+  DEFAULT_PROFILE,
   deleteCredential,
   getCredential,
+  listProfiles,
   resolveHubspotConnection,
   resolveSalesforceConnection,
+  setActiveProfile,
   storeCredential,
   type StoredCredential,
 } from "./credentials.ts";
@@ -31,8 +35,10 @@ import { generateDemoSnapshot } from "./demo.ts";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 import { mergeSnapshots } from "./merge.ts";
 import { createFilePlanStore } from "./planStore.ts";
+import { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
+import { suggestValues, type ValueSuggestion } from "./suggest.ts";
 import type { FieldMappings } from "./mappings.ts";
 import type {
   AuditFindingSeverity,
@@ -60,14 +66,28 @@ Usage:
     echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot
   fullstackgtm snapshot [source options] [--since <iso>] [--out <path> | --archive <dir>]
   fullstackgtm audit [source options] [audit options] [--save]
+  fullstackgtm report [source options] [audit options] [report options]
   fullstackgtm diff --before <a.json> --after <b.json> [--json] [--fail-on-new-findings]
   fullstackgtm merge --input <a.json> --input <b.json> [...] --out <merged.json> [--json]
-  fullstackgtm plans list [--status <s>] | show <id> | approve <id> --operations <ids|all> | reject <id>
+  fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
+                                               derive values for requires_human_* placeholders
+                                               from snapshot evidence, with confidence + reasons
+  fullstackgtm plans list [--status <s>] | show <id> | reject <id>
+  fullstackgtm plans approve <id> --operations <ids|all> [--value <opId>=<v>]
+  fullstackgtm plans approve <id> --values-from <suggestions.json> [--min-confidence high|low] [--include-creates]
   fullstackgtm apply --plan-id <id> --provider <name>
   fullstackgtm apply --plan <path> --provider <name> --approve <ids|all> [options]
   fullstackgtm rules [--json]
+  fullstackgtm profiles [--json]               list credential profiles
   fullstackgtm doctor [--json]                 check install, credentials, and next step
 
+Profiles (multi-organization use):
+  --profile <name>       Scope credentials AND stored plans to a named profile
+                         (also: FULLSTACKGTM_PROFILE). One profile per client
+                         org keeps logins isolated and prevents a plan proposed
+                         against one CRM from being applied through another's
+                         credentials. Omitted = the default profile.
+
 Plan lifecycle:
   audit --save persists the dry-run plan to ~/.fullstackgtm/plans. Approve
   specific operations (optionally with --value <opId>=<v> for placeholders),
@@ -104,6 +124,17 @@ Audit options:
   --stale-days <n>       Days without activity before an open deal is stale
   --fail-on <severity>   Exit 2 if any finding is at or above info|warning|critical
 
+Report options (report renders the audit as a client-ready deliverable):
+  --plan <path>          Render an existing plan JSON instead of re-auditing
+                         (add --input <snapshot.json> for record counts)
+  --client <name>        Organization name shown in the heading and summary
+  --title <text>         Report heading (default "GTM Data Health Report")
+  --prepared-by <name>   Attribution shown in the footer
+  --format <fmt>         markdown (default) or html (self-contained, printable;
+                         inferred from an --out path ending in .html)
+  --max-examples <n>     Example records listed per rule (default 10)
+  --out <path>           Write the report to a file instead of stdout
+
 Apply options:
   --plan <path>          Patch plan JSON produced by \`audit --out\`
   --provider hubspot     Connector to apply through
@@ -334,6 +365,64 @@ async function audit(args: string[]) {
   }
 }
 
+/**
+ * Render an audit as a client-facing deliverable. Same sources and audit
+ * options as `audit`; `--plan` instead renders an existing plan JSON without
+ * re-fetching (useful for a plan produced earlier or by another machine).
+ */
+async function reportCommand(args: string[]) {
+  const loaded = loadConfig(option(args, "--config") ?? undefined);
+  const configuredRules = await resolveConfiguredRules(loaded);
+
+  let plan: PatchPlan;
+  let snapshot: CanonicalGtmSnapshot | undefined;
+  const planPath = option(args, "--plan");
+  if (planPath) {
+    plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8")) as PatchPlan;
+    const input = option(args, "--input");
+    if (input) {
+      snapshot = JSON.parse(
+        readFileSync(resolve(process.cwd(), input), "utf8"),
+      ) as CanonicalGtmSnapshot;
+    }
+  } else {
+    snapshot = await readSnapshot(args);
+    const policy = mergePolicy(defaultPolicy(), loaded?.config);
+    const today = option(args, "--today");
+    if (today) policy.today = today;
+    const staleDealDays = numericOption(args, "--stale-days");
+    if (staleDealDays !== undefined) policy.staleDealDays = staleDealDays;
+    plan = auditSnapshot(snapshot, policy, selectedRules(args, configuredRules));
+  }
+
+  const reportOptions: ReportOptions = {
+    title: option(args, "--title") ?? undefined,
+    clientName: option(args, "--client") ?? undefined,
+    preparedBy: option(args, "--prepared-by") ?? undefined,
+    date: option(args, "--today") ?? undefined,
+    maxExamplesPerRule: numericOption(args, "--max-examples"),
+    rules: configuredRules,
+    snapshot,
+  };
+
+  const out = option(args, "--out");
+  const format = option(args, "--format") ?? (out?.endsWith(".html") ? "html" : "markdown");
+  if (format !== "markdown" && format !== "html") {
+    throw new Error("--format must be markdown or html");
+  }
+  const rendered =
+    format === "html"
+      ? auditReportToHtml(plan, reportOptions)
+      : auditReportToMarkdown(plan, reportOptions);
+
+  if (out) {
+    writeFileSync(resolve(process.cwd(), out), rendered);
+    console.log(`Wrote ${format} report (${plan.findings.length} findings) to ${out}`);
+  } else {
+    console.log(rendered.trimEnd());
+  }
+}
+
 async function rulesCommand(args: string[]) {
   const loaded = loadConfig(option(args, "--config") ?? undefined);
   const rules = await resolveConfiguredRules(loaded);
@@ -376,6 +465,83 @@ function parseValueOverrides(args: string[]) {
   return valueOverrides;
 }
 
+async function suggest(args: string[]) {
+  const planId = option(args, "--plan-id");
+  const planPath = option(args, "--plan");
+  if (!planId && !planPath) throw new Error("suggest requires --plan <path> or --plan-id <id>");
+  let plan: PatchPlan;
+  if (planId) {
+    const stored = await createFilePlanStore().get(planId);
+    if (!stored) throw new Error(`No stored plan with id ${planId}.`);
+    plan = stored.plan;
+  } else {
+    plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath!), "utf8")) as PatchPlan;
+  }
+
+  const snapshot = await readSnapshot(args);
+  const suggestions = suggestValues(plan, snapshot);
+  const payload = { planId: planId ?? planPath, suggestions };
+
+  const outPath = option(args, "--out");
+  if (outPath) writeFileSync(resolve(process.cwd(), outPath), `${JSON.stringify(payload, null, 2)}\n`);
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (suggestions.length === 0) {
+    console.log("No requires_human_* placeholder operations in this plan — nothing to suggest.");
+    return;
+  }
+  const byConfidence: Record<string, number> = {};
+  for (const s of suggestions) byConfidence[s.confidence] = (byConfidence[s.confidence] ?? 0) + 1;
+  console.log(`Suggestions for ${suggestions.length} placeholder operation(s):\n`);
+  for (const s of suggestions) {
+    const marker =
+      s.confidence === "high" ? "✓" : s.confidence === "low" ? "~" : s.confidence === "create" ? "+" : "✗";
+    console.log(`${marker} [${s.confidence}] ${s.operationId} ${s.objectName ?? s.objectId}`);
+    console.log(`    ${s.suggestedValue ? `→ ${s.suggestedValue}` : "(no suggestion)"} — ${s.reason}`);
+  }
+  console.log(`\n${Object.entries(byConfidence).map(([k, v]) => `${k}: ${v}`).join(" · ")}`);
+  if (planId && (byConfidence.high ?? 0) > 0 && !outPath) {
+    console.log(
+      `\nChain it:\n  fullstackgtm suggest --plan-id ${planId} ${snapshotSourceHint(args)}--out suggestions.json\n  fullstackgtm plans approve ${planId} --values-from suggestions.json\n  fullstackgtm apply --plan-id ${planId} --provider <name>`,
+    );
+  }
+}
+
+function snapshotSourceHint(args: string[]) {
+  const provider = option(args, "--provider");
+  if (provider) return `--provider ${provider} `;
+  const input = option(args, "--input");
+  if (input) return `--input ${input} `;
+  return "";
+}
+
+function readSuggestionValues(path: string, minConfidence: string, includeCreates: boolean) {
+  const raw = JSON.parse(readFileSync(resolve(process.cwd(), path), "utf8")) as {
+    suggestions?: ValueSuggestion[];
+  };
+  if (!Array.isArray(raw.suggestions)) {
+    throw new Error(
+      `${path} is not a suggestions file (expected { suggestions: [...] } from \`fullstackgtm suggest --out\`).`,
+    );
+  }
+  const accepted = new Set(minConfidence === "low" ? ["high", "low"] : ["high"]);
+  const overrides: Record<string, string> = {};
+  let skipped = 0;
+  for (const s of raw.suggestions) {
+    if (!s.suggestedValue) continue;
+    if (accepted.has(s.confidence) || (includeCreates && s.confidence === "create")) {
+      overrides[s.operationId] = s.suggestedValue;
+    } else {
+      skipped += 1;
+    }
+  }
+  return { overrides, skipped };
+}
+
 async function apply(args: string[]) {
   const provider = option(args, "--provider");
   if (!provider) throw new Error("apply requires --provider <name>");
@@ -565,16 +731,50 @@ async function plansCommand(args: string[]) {
 
   if (subcommand === "approve") {
     const planId = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
-    if (!planId) throw new Error("Usage: fullstackgtm plans approve <planId> --operations <ids|all>");
+    if (!planId) throw new Error("Usage: fullstackgtm plans approve <planId> --operations <ids|all> | --values-from <suggestions.json>");
     const operations = option(rest, "--operations");
-    if (!operations) throw new Error("plans approve requires --operations <ids|all>");
+    const valuesFrom = option(rest, "--values-from");
+    if (!operations && !valuesFrom) {
+      throw new Error("plans approve requires --operations <ids|all> and/or --values-from <suggestions.json>");
+    }
     const stored = await store.get(planId);
     if (!stored) throw new Error(`No stored plan with id ${planId}.`);
+
+    // Values from a `fullstackgtm suggest --out` file. High-confidence only by
+    // default; widen with --min-confidence low, opt into record-creating
+    // values (create:<Name>) with --include-creates. Explicit --value wins.
+    let fileOverrides: Record<string, string> = {};
+    if (valuesFrom) {
+      const minConfidence = option(rest, "--min-confidence") ?? "high";
+      if (!["high", "low"].includes(minConfidence)) {
+        throw new Error("--min-confidence must be high or low");
+      }
+      const { overrides, skipped } = readSuggestionValues(
+        valuesFrom,
+        minConfidence,
+        rest.includes("--include-creates"),
+      );
+      fileOverrides = overrides;
+      if (Object.keys(overrides).length === 0) {
+        throw new Error(
+          `No suggestions in ${valuesFrom} meet the confidence bar (${skipped} below it). Re-run with --min-confidence low or --include-creates, or pass explicit --value overrides.`,
+        );
+      }
+      if (skipped > 0) {
+        console.log(`Skipped ${skipped} suggestion(s) below the confidence bar (widen with --min-confidence low / --include-creates).`);
+      }
+    }
+    const explicitOverrides = parseValueOverrides(rest);
     const operationIds =
       operations === "all"
         ? stored.plan.operations.map((operation) => operation.id)
-        : operations.split(",").map((id) => id.trim()).filter(Boolean);
-    const updated = await store.approveOperations(planId, operationIds, parseValueOverrides(rest));
+        : operations
+          ? operations.split(",").map((id) => id.trim()).filter(Boolean)
+          : Object.keys(fileOverrides);
+    const updated = await store.approveOperations(planId, operationIds, {
+      ...fileOverrides,
+      ...explicitOverrides,
+    });
     console.log(
       `Approved ${updated.approvedOperationIds.length} operation(s) on ${planId}. Apply with \`fullstackgtm apply --plan-id ${planId} --provider <name>\`.`,
     );
@@ -656,11 +856,17 @@ async function brokerLogin(baseUrl: string) {
   // Self-reported, shown to the approver so they can recognize this request
   // and refuse one they didn't initiate.
   const requesterLabel = `${os.hostname()} (${process.platform}, ${os.userInfo().username})`;
-  const startResponse = await fetch(`${base}/api/cli/auth/start`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ requesterLabel }),
-  });
+  let startResponse: Response;
+  try {
+    startResponse = await fetch(`${base}/api/cli/auth/start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ requesterLabel }),
+    });
+  } catch (error) {
+    const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+    throw new Error(`Cannot reach the hosted deployment at ${base}${cause}. Check the --via URL and network access.`);
+  }
   if (!startResponse.ok) {
     throw new Error(
       `Could not start pairing with ${base} (${startResponse.status}). Is this a FullStackGTM deployment?`,
@@ -926,6 +1132,7 @@ export function doctorReport(env: Record<string, string | undefined> = process.e
   return {
     package: packageInfo,
     node: { version: process.versions.node, ok: nodeMajor >= 20, required: ">=20" },
+    profile: activeProfile(),
     credentialStore: { path: storePath, exists: existsSync(storePath) },
     config: { path: configPath, exists: existsSync(configPath) },
     providers,
@@ -967,6 +1174,7 @@ function doctorCommand(args: string[]) {
   const lines = [
     `Package:    ${report.package.name} ${report.package.version}`,
     `Node:       v${report.node.version} (${report.node.required} required) ${mark(report.node.ok)}`,
+    `Profile:    ${report.profile}${report.profile === DEFAULT_PROFILE ? "" : " (named profile — credentials and plans are scoped to it)"}`,
     `Cred store: ${report.credentialStore.path} (${report.credentialStore.exists ? "present" : "not created yet — created on first login"})`,
     `Config:     ${report.config.exists ? report.config.path : "none — defaults apply"}`,
     "",
@@ -987,8 +1195,41 @@ function doctorCommand(args: string[]) {
   if (!report.node.ok) process.exitCode = 1;
 }
 
+/**
+ * Pull the global `--profile <name>` flag out of argv (it may appear before
+ * or after the command) and activate it. Stripping it keeps positional
+ * detection in subcommands — `login <provider>`, `plans show <id>` — simple.
+ */
+function extractProfile(argv: string[]): string[] {
+  const index = argv.indexOf("--profile");
+  if (index === -1) return argv;
+  const name = argv[index + 1];
+  if (!name) throw new Error("--profile requires a name, e.g. --profile acme");
+  setActiveProfile(name);
+  return [...argv.slice(0, index), ...argv.slice(index + 2)];
+}
+
+function profilesCommand(args: string[]) {
+  const profiles = listProfiles();
+  const current = activeProfile();
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ active: current, profiles }, null, 2));
+    return;
+  }
+  for (const profile of profiles) {
+    console.log(`${profile === current ? "*" : " "} ${profile}`);
+  }
+  if (!profiles.includes(current)) {
+    console.log(`* ${current} (selected; created on first login)`);
+  }
+  console.log(
+    "\nSelect with --profile <name> on any command, or set FULLSTACKGTM_PROFILE. " +
+      "Each profile keeps its own credentials and stored plans.",
+  );
+}
+
 export async function runCli(argv: string[]) {
-  const [command, ...args] = argv;
+  const [command, ...args] = extractProfile(argv);
   if (!command || command === "--help" || command === "-h") {
     console.log(usage());
     return;
@@ -1014,6 +1255,10 @@ export async function runCli(argv: string[]) {
     await audit(args);
     return;
   }
+  if (command === "report") {
+    await reportCommand(args);
+    return;
+  }
   if (command === "rules") {
     await rulesCommand(args);
     return;
@@ -1022,6 +1267,14 @@ export async function runCli(argv: string[]) {
     doctorCommand(args);
     return;
   }
+  if (command === "suggest") {
+    await suggest(args);
+    return;
+  }
+  if (command === "profiles") {
+    profilesCommand(args);
+    return;
+  }
   if (command === "diff") {
     await diffCommand(args);
     return;