fullstackgtm 0.18.0 → 0.20.0

package/src/bulkUpdate.ts

@@ -0,0 +1,375 @@
+/**
+ * Governed generic writes: `bulk-update` builds a dry-run patch plan from a
+ * filter over the canonical snapshot plus an action (field assignments, an
+ * archive directive, or a task to create). It NEVER writes — the plan flows
+ * through the same plans-approve → apply gate as audit plans.
+ *
+ * Safety model, in layers:
+ *  - every set_field captures the record's live value as `beforeValue`
+ *    (apply refuses the write if the written field drifted);
+ *  - every equality filter on a real record field becomes an automatic
+ *    PRECONDITION, re-verified at apply time (the plan's premise must still
+ *    hold — guards against drift on fields other than the one written);
+ *  - `--require field=value` adds explicit preconditions on top;
+ *  - all operations for one record share a groupId, so multi-field updates
+ *    are all-or-nothing per record.
+ *
+ * Filter grammar (each --where is AND-ed):
+ *   field=value     case-insensitive equality
+ *   field!=value    case-insensitive inequality
+ *   field~value     case-insensitive substring
+ *   field:empty     unset or empty string
+ *   field:notempty  set and non-empty
+ *
+ * Fields are canonical (ownerId, stage, closeDate, amount, domain, name,
+ * email, isClosed, accountId, …). Relational pseudo-fields are available in
+ * filters: deals and contacts get `account.name`, `account.domain`,
+ * `account.ownerId`, `account.contactCount`; accounts get `contactCount`
+ * and `openDealCount`.
+ */
+import { stableHash } from "./rules.ts";
+import type {
+  CanonicalGtmSnapshot,
+  GtmObjectType,
+  PatchOperation,
+  PatchPlan,
+  PlanGuard,
+} from "./types.ts";
+
+export type BulkUpdateOptions = {
+  objectType: "account" | "contact" | "deal";
+  /** raw --where expressions, AND-ed together; at least one is required */
+  where: string[];
+  /** canonical field → new value; one action only */
+  set?: Record<string, string>;
+  /** propose archive_record instead of field writes */
+  archive?: boolean;
+  /** propose create_task on each matched record with this subject/body text */
+  createTask?: string;
+  /** explicit preconditions (field=value), re-verified at apply time */
+  require?: string[];
+  /**
+   * plan-level guards, raw form "<objectType>:<where>[;<where>…]:<none|some>",
+   * re-evaluated against a fresh snapshot at apply time; failure aborts the
+   * entire plan
+   */
+  guard?: string[];
+  reason?: string;
+  /** refuse to build plans larger than this (default 500 operations) */
+  maxOperations?: number;
+};
+
+type WhereClause = {
+  field: string;
+  op: "eq" | "neq" | "contains" | "notcontains" | "empty" | "notempty";
+  value?: string;
+  raw: string;
+};
+
+const FIELD_PATTERN = "[a-zA-Z][a-zA-Z0-9_]*(?:\\.[a-zA-Z][a-zA-Z0-9_]*)?";
+
+export function parseWhere(expr: string): WhereClause {
+  const empty = expr.match(new RegExp(`^(${FIELD_PATTERN}):(empty|notempty)$`));
+  if (empty) return { field: empty[1], op: empty[2] as "empty" | "notempty", raw: expr };
+  const neq = expr.match(new RegExp(`^(${FIELD_PATTERN})!=(.*)$`));
+  if (neq) return { field: neq[1], op: "neq", value: neq[2], raw: expr };
+  const notContains = expr.match(new RegExp(`^(${FIELD_PATTERN})!~(.*)$`));
+  if (notContains) return { field: notContains[1], op: "notcontains", value: notContains[2], raw: expr };
+  const contains = expr.match(new RegExp(`^(${FIELD_PATTERN})~(.*)$`));
+  if (contains) return { field: contains[1], op: "contains", value: contains[2], raw: expr };
+  const eq = expr.match(new RegExp(`^(${FIELD_PATTERN})=(.*)$`));
+  if (eq) return { field: eq[1], op: "eq", value: eq[2], raw: expr };
+  throw new Error(
+    `Cannot parse --where "${expr}". Use field=value, field!=value, field~substring, field!~substring, field:empty, or field:notempty.`,
+  );
+}
+
+function fieldValue(view: Record<string, unknown>, field: string): string {
+  const value = view[field];
+  if (value === undefined || value === null) return "";
+  return String(value);
+}
+
+function matches(view: Record<string, unknown>, clause: WhereClause): boolean {
+  const actual = fieldValue(view, clause.field).toLowerCase();
+  // `|` alternation: eq/contains match ANY alternative; neq/notcontains
+  // must hold against ALL alternatives.
+  const alternatives = (clause.value ?? "").toLowerCase().split("|");
+  switch (clause.op) {
+    case "eq":
+      return alternatives.some((a) => actual === a);
+    case "neq":
+      return alternatives.every((a) => actual !== a);
+    case "contains":
+      return alternatives.some((a) => actual.includes(a));
+    case "notcontains":
+      return alternatives.every((a) => !actual.includes(a));
+    case "empty":
+      return actual === "";
+    case "notempty":
+      return actual !== "";
+  }
+}
+
+const COLLECTIONS: Record<BulkUpdateOptions["objectType"], keyof CanonicalGtmSnapshot> = {
+  account: "accounts",
+  contact: "contacts",
+  deal: "deals",
+};
+
+const RELATIONAL_FIELDS = ["account.name", "account.domain", "account.ownerId", "account.contactCount", "account.openDealStages"];
+/**
+ * Filterable fields per object type. Filters/requires/guards referencing any
+ * other field are rejected at plan time: a typo'd field silently evaluating
+ * to empty would make a ":none" guard pass vacuously — a safety assertion
+ * that never fires. Strictness turns typos into immediate, correctable
+ * errors.
+ */
+const VALID_FIELDS: Record<BulkUpdateOptions["objectType"], Set<string>> = {
+  account: new Set(["id", "crmId", "name", "domain", "industry", "ownerId", "employeeCount", "annualRevenue", "lastActivityAt", "lastSyncAt", "contactCount", "openDealCount", "openDealStages"]),
+  contact: new Set(["id", "crmId", "accountId", "firstName", "lastName", "email", "phone", "title", "ownerId", "lastSyncAt", ...RELATIONAL_FIELDS]),
+  deal: new Set(["id", "crmId", "accountId", "ownerId", "name", "amount", "currency", "stage", "closeDate", "dealType", "forecastCategory", "nextStep", "probability", "isClosed", "isWon", "lastActivityAt", "lastSyncAt", ...RELATIONAL_FIELDS]),
+};
+
+function assertValidFields(objectType: BulkUpdateOptions["objectType"], clauses: WhereClause[], context: string): void {
+  for (const clause of clauses) {
+    if (!VALID_FIELDS[objectType].has(clause.field)) {
+      throw new Error(
+        `Unknown field "${clause.field}" in ${context} "${clause.raw}" for ${objectType}s. Valid fields: ${[...VALID_FIELDS[objectType]].join(", ")}.`,
+      );
+    }
+  }
+}
+
+/**
+ * Fields that are derived in the canonical model (no provider property to
+ * re-read at apply time) or relational — excluded from auto-preconditions.
+ */
+const NON_READABLE_FIELDS = new Set([
+  // derived in the canonical model — no provider property to re-read
+  "isClosed", "isWon", "forecastCategory", "probability", "lastActivityAt", "lastSyncAt",
+  // identity/bookkeeping fields — preconditions on these are meaningless
+  "id", "crmId", "provider", "identities",
+]);
+
+/** Build the filter-evaluation view: record fields + relational pseudo-fields. */
+function buildViews(
+  snapshot: CanonicalGtmSnapshot,
+  objectType: BulkUpdateOptions["objectType"],
+): Array<{ record: Record<string, unknown>; view: Record<string, unknown> }> {
+  const accountsById = new Map(snapshot.accounts.map((a) => [a.id, a]));
+  const contactCountByAccount = new Map<string, number>();
+  for (const c of snapshot.contacts) {
+    if (c.accountId) contactCountByAccount.set(c.accountId, (contactCountByAccount.get(c.accountId) ?? 0) + 1);
+  }
+  const openDealCountByAccount = new Map<string, number>();
+  const openDealStagesByAccount = new Map<string, string[]>();
+  for (const d of snapshot.deals) {
+    if (d.accountId && !d.isClosed) {
+      openDealCountByAccount.set(d.accountId, (openDealCountByAccount.get(d.accountId) ?? 0) + 1);
+      const stages = openDealStagesByAccount.get(d.accountId) ?? [];
+      if (d.stage) stages.push(d.stage);
+      openDealStagesByAccount.set(d.accountId, stages);
+    }
+  }
+  const records = snapshot[COLLECTIONS[objectType]] as Array<Record<string, unknown>>;
+  return records.map((record) => {
+    const view: Record<string, unknown> = { ...record };
+    if (objectType === "account") {
+      view.contactCount = contactCountByAccount.get(String(record.id)) ?? 0;
+      view.openDealCount = openDealCountByAccount.get(String(record.id)) ?? 0;
+      view.openDealStages = (openDealStagesByAccount.get(String(record.id)) ?? []).join(",");
+    } else {
+      const account = record.accountId ? accountsById.get(String(record.accountId)) : undefined;
+      view["account.name"] = account?.name ?? "";
+      view["account.domain"] = account?.domain ?? "";
+      view["account.ownerId"] = account?.ownerId ?? "";
+      view["account.contactCount"] = account ? (contactCountByAccount.get(account.id) ?? 0) : 0;
+      view["account.openDealStages"] = account ? (openDealStagesByAccount.get(account.id) ?? []).join(",") : "";
+    }
+    return { record, view };
+  });
+}
+
+export function parseGuard(raw: string): PlanGuard {
+  const first = raw.indexOf(":");
+  const last = raw.lastIndexOf(":");
+  if (first === -1 || last === first) {
+    throw new Error(`Cannot parse --guard "${raw}". Use <account|contact|deal>:<where>[;<where>…]:<none|some>.`);
+  }
+  const objectType = raw.slice(0, first);
+  const expect = raw.slice(last + 1);
+  const where = raw.slice(first + 1, last).split(";").map((s) => s.trim()).filter(Boolean);
+  if (!["account", "contact", "deal"].includes(objectType) || !["none", "some"].includes(expect) || where.length === 0) {
+    throw new Error(`Cannot parse --guard "${raw}". Use <account|contact|deal>:<where>[;<where>…]:<none|some>.`);
+  }
+  // validate eagerly at plan time: a typo'd guard must fail loudly, never
+  // pass vacuously at apply time
+  assertValidFields(objectType as BulkUpdateOptions["objectType"], where.map(parseWhere), "--guard");
+  return { objectType: objectType as PlanGuard["objectType"], where, expect: expect as PlanGuard["expect"], description: raw };
+}
+
+/** Ids of records matching a filter — used for apply-time filter re-verification. */
+export function eligibleIds(
+  snapshot: CanonicalGtmSnapshot,
+  objectType: BulkUpdateOptions["objectType"],
+  where: string[],
+): Set<string> {
+  const clauses = where.map(parseWhere);
+  const views = buildViews(snapshot, objectType);
+  return new Set(
+    views.filter(({ view }) => clauses.every((c) => matches(view, c))).map(({ record }) => String(record.id)),
+  );
+}
+
+/** Evaluate a plan guard against a snapshot. Returns null when satisfied, else a failure detail. */
+export function evaluateGuard(snapshot: CanonicalGtmSnapshot, guard: PlanGuard): string | null {
+  const clauses = guard.where.map(parseWhere);
+  const views = buildViews(snapshot, guard.objectType);
+  const matchCount = views.filter(({ view }) => clauses.every((c) => matches(view, c))).length;
+  const ok = guard.expect === "none" ? matchCount === 0 : matchCount > 0;
+  if (ok) return null;
+  return `Guard failed: expected ${guard.expect === "none" ? "no" : "at least one"} ${guard.objectType}(s) matching [${guard.where.join(" AND ")}], found ${matchCount}.`;
+}
+
+export function buildBulkUpdatePlan(
+  snapshot: CanonicalGtmSnapshot,
+  options: BulkUpdateOptions,
+): PatchPlan {
+  const maxOperations = options.maxOperations ?? 500;
+  if (options.where.length === 0) {
+    throw new Error(
+      "bulk-update requires at least one --where filter — refusing to build an unscoped mass write.",
+    );
+  }
+  const hasSet = options.set && Object.keys(options.set).length > 0;
+  const actions = [hasSet, options.archive, options.createTask !== undefined].filter(Boolean).length;
+  if (actions !== 1) {
+    throw new Error("bulk-update needs exactly one action: --set <field>=<value> (repeatable), --archive, or --create-task <text>.");
+  }
+
+  const clauses = options.where.map(parseWhere);
+  assertValidFields(options.objectType, clauses, "--where");
+  const WRITABLE_BLOCKLIST = new Set(["id", "crmId", "contactCount", "openDealCount", "openDealStages"]);
+  for (const field of Object.keys(options.set ?? {})) {
+    if (!VALID_FIELDS[options.objectType].has(field) || WRITABLE_BLOCKLIST.has(field) || field.includes(".")) {
+      throw new Error(`Cannot --set "${field}" on ${options.objectType}s — not a writable canonical field.`);
+    }
+  }
+  const views = buildViews(snapshot, options.objectType);
+  const matched = views.filter(({ view }) => clauses.every((c) => matches(view, c)));
+  if (matched.length > maxOperations) {
+    throw new Error(
+      `Filter matched ${matched.length} ${COLLECTIONS[options.objectType]} — above the ${maxOperations}-record safety cap. Narrow the --where filter or raise --max-operations explicitly.`,
+    );
+  }
+
+  // Preconditions: explicit --require, plus every equality filter on a real
+  // (re-readable, non-relational) field. The premise the plan was built on
+  // is re-verified per record at apply time.
+  const writtenFields = new Set(Object.keys(options.set ?? {}));
+  const preconditionSpecs: Array<{ field: string; expectedValue: string }> = [];
+  for (const raw of options.require ?? []) {
+    const clause = parseWhere(raw);
+    if (clause.op !== "eq" || clause.field.includes(".") || (clause.value ?? "").includes("|")) {
+      throw new Error(`--require must be a direct single-value field equality (field=value), got "${raw}".`);
+    }
+    assertValidFields(options.objectType, [clause], "--require");
+    preconditionSpecs.push({ field: clause.field, expectedValue: clause.value ?? "" });
+  }
+  for (const clause of clauses) {
+    if (clause.op !== "eq") continue;
+    if ((clause.value ?? "").includes("|")) continue; // alternations are not single-value preconditions
+    if (clause.field.includes(".") || NON_READABLE_FIELDS.has(clause.field)) continue;
+    if (writtenFields.has(clause.field)) continue; // beforeValue already guards it
+    if (preconditionSpecs.some((p) => p.field === clause.field)) continue;
+    preconditionSpecs.push({ field: clause.field, expectedValue: clause.value ?? "" });
+  }
+
+  const whereText = options.where.join(" AND ");
+  const action = options.archive
+    ? `archive`
+    : options.createTask !== undefined
+      ? `create task "${options.createTask}"`
+      : `set ${Object.entries(options.set!).map(([k, v]) => `${k}=${v}`).join(", ")}`;
+  const reason = options.reason ?? `bulk-update: ${action} where ${whereText}`;
+
+  const operations: PatchOperation[] = [];
+  for (const { record } of matched) {
+    const objectId = String(record.id);
+    const groupId = `grp_${options.objectType}_${objectId}`;
+    const preconditions = preconditionSpecs.map((p) => ({
+      field: p.field,
+      // expected value is the record's CURRENT canonical value, not the
+      // filter literal — preserves casing/format the provider will echo back
+      expectedValue: record[p.field] ?? p.expectedValue,
+    }));
+    const shared = {
+      objectType: options.objectType as GtmObjectType,
+      objectId,
+      reason,
+      approvalRequired: true as const,
+      sourceRuleOrPolicy: "bulk-update",
+      ...(preconditions.length > 0 ? { preconditions } : {}),
+      groupId,
+    };
+    if (options.archive) {
+      operations.push({
+        ...shared,
+        id: `op_${stableHash(`bulk-archive:${options.objectType}:${objectId}:${whereText}`)}`,
+        operation: "archive_record",
+        beforeValue: null,
+        afterValue: null,
+        riskLevel: "high",
+        rollback: "Archived records can be restored from the provider's recycle bin within its retention window.",
+      });
+      continue;
+    }
+    if (options.createTask !== undefined) {
+      operations.push({
+        ...shared,
+        id: `op_${stableHash(`bulk-task:${options.objectType}:${objectId}:${options.createTask}`)}`,
+        operation: "create_task",
+        field: "follow_up_task",
+        beforeValue: null,
+        afterValue: options.createTask,
+        riskLevel: "low",
+        rollback: "Delete the created task.",
+      });
+      continue;
+    }
+    for (const [field, value] of Object.entries(options.set!)) {
+      operations.push({
+        ...shared,
+        id: `op_${stableHash(`bulk-set:${options.objectType}:${objectId}:${field}:${value}`)}`,
+        operation: "set_field",
+        field,
+        beforeValue: record[field] ?? null,
+        afterValue: value,
+        riskLevel: "medium",
+        rollback: `Set ${field} back to ${JSON.stringify(record[field] ?? null)}.`,
+      });
+    }
+  }
+
+  const guards = (options.guard ?? []).map(parseGuard);
+  // guards must hold at plan time too — building a plan whose guard already
+  // fails is a footgun, surface it immediately
+  for (const guard of guards) {
+    const failure = evaluateGuard(snapshot, guard);
+    if (failure) throw new Error(`${failure} The guard already fails against the current snapshot — the plan would never apply.`);
+  }
+
+  return {
+    id: `patch_plan_${stableHash(`bulk:${snapshot.provider}:${snapshot.generatedAt}:${whereText}:${action}:${operations.length}`)}`,
+    title: `Bulk update: ${options.objectType}s where ${whereText}`,
+    createdAt: snapshot.generatedAt,
+    status: operations.length > 0 ? "needs_approval" : "draft",
+    dryRun: true,
+    summary: `${matched.length} ${COLLECTIONS[options.objectType]} matched (${whereText}); ${operations.length} proposed dry-run operations (${action}).${guards.length > 0 ? ` ${guards.length} apply-time guard(s).` : ""}`,
+    findings: [],
+    operations,
+    filter: { objectType: options.objectType, where: options.where },
+    ...(guards.length > 0 ? { guards } : {}),
+  };
+}

package/src/cli.ts

@@ -52,6 +52,14 @@ import {
   type ObservationSet,
 } from "./market.ts";
 import { assessAxes, axesReportToText } from "./marketAxes.ts";
+import {
+  computeDirectives,
+  computeOverlayStats,
+  directivesToPlan,
+  overlayToMarkdown,
+  type CallDocument,
+} from "./marketOverlay.ts";
+import { computeScaleIndex, scaleReportToText } from "./marketScale.ts";
 import { buildWorksheet, classifyMarket } from "./marketClassify.ts";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 import {
@@ -66,6 +74,7 @@ import {
   type LlmProvider,
 } from "./llm.ts";
 import { resolveRecord, type ResolveCandidate } from "./resolve.ts";
+import { buildBulkUpdatePlan } from "./bulkUpdate.ts";
 import { suggestValues, type ValueSuggestion } from "./suggest.ts";
 import type { FieldMappings } from "./mappings.ts";
 import type {
@@ -117,6 +126,8 @@ Usage:
   fullstackgtm market fronts [--run <label>] [--diff <prior-run>] [--json]
   fullstackgtm market axes [--run <label>] [--json]
   fullstackgtm market report [--run <label>] [--format md|html] [--out <path>]
+  fullstackgtm market overlay --snapshot <crm.json> [--calls <files>] [--save]
+  fullstackgtm market scale [--json]
   fullstackgtm market refresh [--run <label>] [--model m]
                                                the live competitive map: capture vendor pages (content-addressed),
                                                classify intensity per claim (LLM bring-your-own-key, or fill the
@@ -124,6 +135,18 @@ Usage:
                                                against the stored capture it cites before it's accepted — then
                                                compute deterministic front states and drift, render the field
                                                report. refresh = capture → classify → drift → report in one step
+  fullstackgtm bulk-update <account|contact|deal> --where <expr> [--where …] (--set <field>=<value> [--set …] | --archive | --create-task <text>) [--require <field>=<value> …] [--guard <object>:<where>[;<where>]:<none|some> …] [source options] [--save] [--json] [--out <path>]
+                                               governed generic writes: filter the snapshot
+                                               (field=value, field!=value, field~substr, field!~substr,
+                                               field:empty, field:notempty, '|' = any-of; canonical fields
+                                               like ownerId, stage, closeDate, amount; relational
+                                               pseudo-fields account.name/domain/ownerId/contactCount/
+                                               openDealStages on deals and contacts, contactCount/
+                                               openDealCount/openDealStages on accounts) into a dry-run
+                                               patch plan. The full filter is re-verified per record at
+                                               apply time (incl. mid-apply rechecks); equality filters
+                                               double as preconditions; per-record ops apply
+                                               all-or-nothing; guards assert cross-record conditions.
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -851,7 +874,9 @@ async function marketCommand(args: string[]) {
   const [subcommand, ...rest] = args;
   const configPath = () => resolve(process.cwd(), option(rest, "--config") ?? "market.config.json");
 
-  if (!subcommand || subcommand === "--help") {
+  // Catch --help anywhere before loadMarketConfig/credential checks run —
+  // several subcommands (capture, refresh) have side effects on bare invocation.
+  if (!subcommand || subcommand === "--help" || subcommand === "-h" || rest.includes("--help") || rest.includes("-h")) {
     console.log(`Usage:
 market init --category <name> [--out <path>]   write a starter market.config.json
 market capture [--config <path>] [--run <label>]
@@ -860,9 +885,24 @@ market worksheet --vendor <id> [--capture-run <label>] [--out <path>]
 market observe --from <observations.json> [--unverified]
 market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
 market axes [--config <path>] [--run <label>] [--json]
+market overlay --snapshot <crm.json> [--calls <parsed.json|manifest.json>]... [--prior-run <label>]
+               [--min-mentions N] [--promote-lift X] [--json] [--save --task-account <id>|--task-deal <id>]
+market scale [--config <path>] [--json]
 market report [--config <path>] [--run <label>] [--format md|html] [--out <path>]
 market refresh [--run <label>] [--model m]     capture → classify → fronts drift → HTML report
 
+overlay is the directive layer: joins the map to YOUR CRM ground truth and
+emits OCCUPY / PROMOTE / URGENT / RETREAT directives, each carrying ≥1
+observation and ≥1 CRM statistic with its sample size. Claim mentions are
+deterministic word-boundary matches of each claim's "terms" against call
+documents (call parse output); small samples refuse to become strategy
+(--min-mentions, default 3). --save turns directives into approval-gated
+create_task operations through the normal plans → approve → apply gate.
+
+scale prints the relative scale index that sizes the report's bubbles when
+vendors carry scaleSignals (citable review counts / headcount / revenue —
+a within-set index, never "market share" unqualified).
+
 axes runs the axis-discovery math: PCA over the vendor × claim intensity
 matrix (PC1 = the category's primary axis, PC2 = the max-differentiation
 direction orthogonal to it), triangulation of configured axes against the
@@ -1074,8 +1114,90 @@ recomputed deterministically on every invocation — never stored.`);
     return;
   }
 
+  if (subcommand === "scale") {
+    const report = computeScaleIndex(config);
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(scaleReportToText(config, report));
+    return;
+  }
+
+  if (subcommand === "overlay") {
+    const set = await loadSet();
+    const snapshotPath = option(rest, "--snapshot");
+    if (!snapshotPath) {
+      throw new Error(
+        "market overlay requires --snapshot <canonical-snapshot.json> (fullstackgtm snapshot --out it first) — directives need CRM ground truth",
+      );
+    }
+    const snapshot = JSON.parse(readFileSync(resolve(process.cwd(), snapshotPath), "utf8")) as CanonicalGtmSnapshot;
+
+    // --calls accepts ParsedCall JSON files (from `call parse --out`) and/or
+    // manifest arrays [{path, dealId?}] linking calls to deals. Repeatable.
+    const documents: CallDocument[] = [];
+    const addParsedCall = (parsedPath: string, dealId?: string) => {
+      const parsed = JSON.parse(readFileSync(resolve(process.cwd(), parsedPath), "utf8")) as ParsedCall & {
+        segments?: Array<{ text?: string }>;
+      };
+      const text = [
+        ...(parsed.segments ?? []).map((segment) => segment.text ?? ""),
+        ...(parsed.insights ?? []).map((insight) => `${insight.text ?? ""} ${insight.evidence ?? ""}`),
+      ].join("\n");
+      documents.push({ id: parsed.id ?? parsedPath, text, dealId, occurredAt: parsed.evidence?.[0]?.capturedAt });
+    };
+    for (let i = 0; i < rest.length; i += 1) {
+      if (rest[i] !== "--calls") continue;
+      const callsPath = rest[i + 1];
+      if (!callsPath) throw new Error("--calls needs a path");
+      const raw = JSON.parse(readFileSync(resolve(process.cwd(), callsPath), "utf8"));
+      if (Array.isArray(raw)) {
+        for (const entry of raw as Array<{ path: string; dealId?: string }>) addParsedCall(entry.path, entry.dealId);
+      } else {
+        addParsedCall(callsPath);
+      }
+    }
+
+    const priorLabel = option(rest, "--prior-run");
+    const priorSet = priorLabel ? await store.get(priorLabel) : null;
+    if (priorLabel && !priorSet) throw new Error(`No observation run "${priorLabel}" for URGENT drift`);
+
+    const stats = computeOverlayStats(config, snapshot, documents);
+    const directives = computeDirectives(config, set, stats, {
+      minMentions: numericOption(rest, "--min-mentions") ?? undefined,
+      promoteLift: numericOption(rest, "--promote-lift") ?? undefined,
+      priorSet: priorSet ?? undefined,
+    });
+
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify({ stats, directives }, null, 2));
+      return;
+    }
+    console.log(overlayToMarkdown(stats, directives));
+
+    if (rest.includes("--save")) {
+      const taskAccount = option(rest, "--task-account");
+      const taskDeal = option(rest, "--task-deal");
+      if (!taskAccount && !taskDeal) {
+        throw new Error(
+          "--save needs --task-account <id> or --task-deal <id>: directives become approval-gated create_task operations, and the CRM needs a record to hang them on (your own company's account record works well)",
+        );
+      }
+      const plan = directivesToPlan(
+        config,
+        set,
+        directives,
+        taskDeal ? { objectType: "deal", objectId: taskDeal } : { objectType: "account", objectId: taskAccount as string },
+      );
+      const stored = await createFilePlanStore().save(plan);
+      console.log(`Saved plan ${stored.plan.id} (${directives.length} directive task(s); approve via \`plans approve\`)`);
+    }
+    return;
+  }
+
   throw new Error(
-    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, report, refresh)`,
+    `Unknown market subcommand: ${subcommand} (try: init, capture, classify, worksheet, observe, fronts, axes, overlay, scale, report, refresh)`,
   );
 }
 
@@ -1110,6 +1232,54 @@ async function resolveCommand(args: string[]) {
   if (result.verdict !== "safe_to_create") process.exitCode = 2;
 }
 
+/**
+ * Governed generic writes: build a dry-run patch plan from a snapshot filter
+ * plus field assignments (or --archive). Never writes — approve and apply the
+ * plan like any audit plan; compare-and-set protects every operation.
+ */
+async function bulkUpdateCommand(args: string[]) {
+  const [objectType, ...rest] = args;
+  if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+    throw new Error(
+      "Usage: fullstackgtm bulk-update <account|contact|deal> --where <field=value|field!=value|field~substr|field:empty|field:notempty> [--where …] (--set <field>=<value> [--set …] | --archive) [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]",
+    );
+  }
+  const where = repeatedOption(rest, "--where");
+  const set: Record<string, string> = {};
+  for (const pair of repeatedOption(rest, "--set")) {
+    const separator = pair.indexOf("=");
+    if (separator === -1) throw new Error(`--set must look like <field>=<value>, got "${pair}"`);
+    set[pair.slice(0, separator)] = pair.slice(separator + 1);
+  }
+  const snapshot = await readSnapshot(rest);
+  const plan = buildBulkUpdatePlan(snapshot, {
+    objectType: objectType as "account" | "contact" | "deal",
+    where,
+    set: Object.keys(set).length > 0 ? set : undefined,
+    archive: rest.includes("--archive"),
+    createTask: option(rest, "--create-task") ?? undefined,
+    require: repeatedOption(rest, "--require"),
+    guard: repeatedOption(rest, "--guard"),
+    reason: option(rest, "--reason") ?? undefined,
+    maxOperations: numericOption(rest, "--max-operations"),
+  });
+  const out = option(rest, "--out");
+  if (out) {
+    writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(plan, null, 2)}\n`);
+  }
+  if (rest.includes("--save")) {
+    await createFilePlanStore().save(plan);
+    console.error(
+      `Saved plan ${plan.id} (${plan.operations.length} operations). Review with \`fullstackgtm plans show ${plan.id}\`, approve with \`fullstackgtm plans approve ${plan.id} --operations <ids|all>\`, then \`fullstackgtm apply --plan-id ${plan.id} --provider <name>\`.`,
+    );
+  }
+  if (rest.includes("--json")) {
+    console.log(JSON.stringify(plan, null, 2));
+  } else {
+    console.log(patchPlanToMarkdown(plan));
+  }
+}
+
 async function suggest(args: string[]) {
   const planId = option(args, "--plan-id");
   const planPath = option(args, "--plan");
@@ -1902,6 +2072,13 @@ export async function runCli(argv: string[]) {
     console.log(readPackageInfo().version);
     return;
   }
+  // Commands without bespoke help fall back to the top-level usage on --help
+  // instead of executing (audit used to silently run the sample audit).
+  // call/market/bulk-update print their own richer help.
+  if (!["call", "market", "bulk-update"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(usage());
+    return;
+  }
 
   if (command === "login") {
     await login(args);
@@ -1943,6 +2120,10 @@ export async function runCli(argv: string[]) {
     await resolveCommand(args);
     return;
   }
+  if (command === "bulk-update") {
+    await bulkUpdateCommand(args);
+    return;
+  }
   if (command === "market") {
     await marketCommand(args);
     return;