@flowapt/flowiq-cli 0.7.1 → 0.7.3

package/README.md

@@ -188,6 +188,7 @@ flowiq ct list
 - **Always `--dry-run` first** on a production agent — it prints added/removed/changed tool names before you commit.
 - **Destructive pushes are blocked by default**: a push that removes a tool, disables one, or sends an empty `tools[]` (wiping everything) writes nothing and shows you exactly what it would strip — re-run with `--confirm` if intentional. Additive/no-op pushes are unaffected.
 - Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates or built-in collisions), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, scalar headers, object-typed `parameters`/`injected_parameters`, valid auth/channels, timeout and response caps. Recursive schemas support strict nested objects, typed arrays, enums and numeric/string/item limits. Unknown tool/schema keys are rejected before anything writes.
+- **`display_name` (optional, 10 Sep 2026):** the label the TEAM sees on the inbox tool-activity card (e.g. `Checked loyalty points`) — plain string, ≤80 chars, never sent to the AI. Leave it out and the card derives a label from the tool name.
 - **Warnings (non-blocking):** an object with properties but no required fields. Unknown `{{placeholder}}` values are hard errors; injected parameters may additionally reference a declared top-level model parameter. Known runtime values include `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `whatsapp_message_id`, `text`, `unique_message_id`, `unix_timestamp`, `operation_idempotency_key`, `supabase_anon_key`, and `openai_api_key`.
 - **Retailer gateway credential:** `{{retailer_tools_internal_key}}` is super-admin-only and resolves only as the `x-api-key` value for `https://express.chatcart.io/retailer-tools/*` (or loopback in local tests). Validation and runtime both reject putting it in a body or sending it to any other host.
 - `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
@@ -1054,7 +1055,9 @@ flowiq hours summary                          # every org with logged work this
 
 ### Client deck — `flowiq report deck status|build|narrate|generate|inputs|approve|unapprove|send|print|pull` (v0.6.5)
 
-The monthly 10-slide client deck (`/reporting/deck` in the app), driven from the
+The monthly client deck (`/reporting/deck` in the app; 10 slides, 11 for a store
+org — slide 8 is store health: cart abandonment, returning buyers and opt-in
+growth, online store only), driven from the
 terminal. Everything runs server-side through the `flowiq-reporting-deck` edge
 function: the metrics are built from the FROZEN month snapshot, the copy is
 written by the model under the report rules and a numeric guard (every figure
@@ -1077,11 +1080,15 @@ flowiq report deck pull <org_id> 2026-08                   # → ./.flowiq/repor
 ```
 
 - Months freeze on the 1st (cron 82); a month with no snapshot cannot be built.
-  Comparisons need the prior month's deck, which `build` creates on the fly.
+  Comparisons need the prior month's deck, which `build` creates on the fly (and rebuilds when it
+  predates the current build logic, unless it is approved, sent or held).
+- Send fees are estimated at the category each template had on its send day. A send whose category
+  cannot be known shows no fee and is left out of the broadcast return (`totals.unpriced_sends`).
 - `inputs.json` shape: `{ "changes": { "<update_id>": { "hidden": false, "tag": "client_raised|flowapt_shipped", "title": "…", "description": "…" } }, "changes_reviewed": true, "action_points": { "<title>": "done|in_progress|waiting_on_you|ongoing|dropped" }, "waiting_on_you": [{ "title": "…", "unlocks": "…" }], "recipients_confirmed": true }`.
   Free text (milestone, the four plan fields) is edited in the app; it is stored as overrides that survive `narrate`.
 - `send --client` needs an approved deck AND `report.email.recipients` in the org's reporting config (Control center → Report delivery); it marks the deck `sent`. `--test-to` never changes status. Fees on the slides are the org's actual Meta billing when the token can read it, otherwise the rate-card estimate, and the footnote says which.
 - Non-store orgs need `config.deck.outcome` (`source: handover | ticket_status | tag | keyword`, labels) — the revenue slides become outcome slides. Every verb except `status` and `pull` is audited.
+- Store orgs get slide 8, "Store health": cart abandonment (online checkouts started, bought, abandoned), first-time vs returning buyers and opt-in growth, each with a twelve-month strip and measured on the online store checkout only (till and other channels are named in the footer). `status --json` carries the headline figures under `store`; `config.deck.channel_labels {"<source_name>": "Label"}` renames a sales channel on the slide.
 
 ### Insights — `flowiq insights status|enable|disable|run` (v0.7.0)
 
@@ -1435,7 +1442,10 @@ flowiq org flags keys --section "members"
   response prints before → after plus the exact undo command.
 - A key that is on the org but not in the registry is shown by `show` (and
   `--json`) but cannot be set here — it is DB-only by design; add it to the
-  Profile tab first.
+  Profile tab first. **The registry is ONE shared file** (`api/_shared/feature-flag-registry.js`)
+  that the Profile tab imports too, and every build checks the two agree — so a
+  new Profile-tab switch is settable from the CLI the moment it deploys, with no
+  npm publish.
 
 ### Agents — `flowiq agent list|create <org>`
 
@@ -1576,6 +1586,38 @@ flowiq au resolve <update_id> --status declined --internal "duplicate of …"
 - An interactive confirm shows exactly what the client will read; `--yes`
   skips the confirm (but never the `--note` requirement).
 
+### Broadcast planning — `flowiq plans list|show|status` (alias `planning`) (v0.7.3)
+
+The Broadcast → Planning board in the app (the campaign plans clients submit
+and Flowapt reviews), from the terminal.
+
+```bash
+flowiq plans list                                        # open plans across every ACTIVE client
+flowiq plans list --status pending_review                # waiting for Flowapt review
+flowiq plans list <organization_id> --status all --since 2026-09-01
+flowiq plans show <plan_id>                              # copy, second message, buttons, creative, audience, notes
+flowiq plans show <plan_id> --json --out plan.json
+flowiq plans status <plan_id> --to approved              # dry run
+flowiq plans status <plan_id> --to rejected --comment "Please send the image as a PNG" --commit
+flowiq plans status <plan_id> --to sent --commit
+```
+
+- **`list`** defaults to open plans (`draft`, `pending_review`, `approved`,
+  `scheduled`) across all active orgs; pass an org id for one client,
+  `--status all` / a status / a comma list to widen or narrow, `--since` to
+  filter by send date, `--include-inactive` for inactive orgs. The header
+  shows the totals for every status, and each row prints the full plan id.
+- **`show`** prints the plan the way the dialog does: message copy, the
+  second message sent when a button is tapped, buttons with their URLs, the
+  creative (file name + link), audience, template link, the response to the
+  client, internal notes and the notes thread.
+- **`status`** is a dry run until `--commit`. `--comment` is the response the
+  **client reads**; `--internal` is staff-only. `approved` and `rejected`
+  record you as the reviewer; `rejected` requires `--comment`. Every commit is
+  in `flowiq audit --endpoint plans`.
+- Editing a plan's copy, buttons or links is not in the CLI yet; do that in
+  the app.
+
 ### Chat export — `flowiq export chats <organization_id> [--out <path>]`
 
 Full chat history → TXT, byte-identical to the in-app "Export Settings TXT"

package/TEAM-GUIDE.md

@@ -81,11 +81,15 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Edit the text knowledge sources (get_more_answers playbooks) | `flowiq kn pull <org_id>` → edit `sources[]` → `flowiq kn push <slug>` |
 | Edit the custom tools (API-call tools) | `flowiq ct pull <org_id>` → edit `tools[]` → `flowiq ct push <slug> --dry-run` → `flowiq ct push <slug>` |
 | Turn one custom tool on/off | `flowiq ct enable\|disable <org_id> <tool_name>` |
+| Give a custom tool a friendly name on the inbox tool-activity card | add `"display_name": "Checked loyalty points"` to that tool in `tools[]` → `flowiq ct push` (≤80 chars, never shown to the AI; empty = derived from the tool name) |
 | Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>` |
 | Send a **different auto-reply depending on the contact** (e.g. "we already have your email" vs "send us your email") | add `"when": {"field":"email","op":"is_not_empty"}` to one action and `is_empty` to the other — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | Make a follow-up button **close the customer's ticket** ("Query solved") or **re-alert the team** ("I still need help") | keyword action `{"type":"update_ticket_status","status":"resolved"}` / `{"type":"renotify_ticket"}` — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | Make a keyword/button **hand the chat to a team or person** (assign in the inbox + email/WhatsApp them) | keyword action `{"type":"assign_chat","team_id":"…","assignee_user_id":"…","notify_member":true}` — see *Keywords* in `flowiq guide --reference`. Also in the dashboard (action type "Assign Chat") |
 | **Find an org's ID** (needed by nearly every command) | `flowiq org list` — or `flowiq org list african` to filter |
+| See broadcast plans waiting for Flowapt review, across every client | `flowiq plans list --status pending_review`, then `flowiq plans show <plan_id>` for the copy, second message, buttons, creative and audience |
+| See one client's broadcast plans | `flowiq plans list <org_id>` (open plans) or `flowiq plans list <org_id> --status all --since 2026-09-01` |
+| Mark a broadcast plan approved, scheduled or sent | `flowiq plans status <plan_id> --to sent` (a dry run), then add `--commit`. Rejecting needs `--comment "..."`, which the client reads |
 | What's the stock on a product, per branch? | `flowiq shopify stock <org_id> "olive oil"` — shows each location by NAME, and says "not tracked" rather than a confusing 0 |
 | Has this order shipped? What's the tracking? | `flowiq shopify order <org_id> '#14728'` — status, courier, tracking number + link |
 | **Size a customer cohort** | Use `customers(first:250, query:…)` and paginate — **NOT `customersCount(query:…)`, which Shopify ignores the filter on** and answers 10,000 every time. Any count showing `precision: AT_LEAST` is a cap, not a total; the CLI warns you. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/plans.js

@@ -0,0 +1,258 @@
+// `flowiq plans list|show|status` — Broadcast Planning (the Broadcast → Planning
+// board in the app, table broadcast_planning), via /cli/plans.
+//   list   read: open plans across all active orgs, or one org
+//   show   read: one plan in full (copy, second message, buttons, creative, notes)
+//   status write: dry run unless --commit; audited server-side
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const STATUSES = ["draft", "pending_review", "approved", "rejected", "scheduled", "sent", "cancelled"];
+const STATUS_ORDER = ["pending_review", "approved", "scheduled", "draft", "rejected", "sent", "cancelled"];
+const STATUS_LABEL = {
+  pending_review: "PENDING REVIEW",
+  approved: "APPROVED",
+  scheduled: "SCHEDULED",
+  draft: "DRAFT",
+  rejected: "REJECTED",
+  sent: "SENT",
+  cancelled: "CANCELLED",
+};
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+function sastParts(ts) {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Africa/Johannesburg",
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(new Date(ts));
+  return Object.fromEntries(parts.map((p) => [p.type, p.value]));
+}
+
+function fmtTs(ts) {
+  if (!ts) return "-";
+  const p = sastParts(ts);
+  const hour = p.hour === "24" ? "00" : p.hour;
+  return `${Number(p.day)} ${MONTHS[Number(p.month) - 1]} ${p.year} ${hour}:${p.minute}`;
+}
+
+function fmtDate(dateStr, timeStr) {
+  if (!dateStr) return "no date";
+  const [y, m, d] = String(dateStr).split("-");
+  return `${Number(d)} ${MONTHS[Number(m) - 1]} ${y} ${timeStr ? String(timeStr).slice(0, 5) : "--:--"}`;
+}
+
+function indent(text, pad = "  ") {
+  const t = String(text ?? "").trim();
+  if (!t) return `${pad}(empty)`;
+  return t.split("\n").map((line) => `${pad}${line}`).join("\n");
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  if (e.body?.error && !String(e.message).includes(e.body.error)) console.error(`  ${e.body.error}`);
+  process.exit(1);
+}
+
+export async function list(orgId, opts = {}) {
+  if (orgId && !UUID_RE.test(orgId)) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list\`).`);
+    process.exit(1);
+  }
+  const query = {};
+  if (orgId) query.organization_id = orgId;
+  if (opts.status) query.status = opts.status;
+  if (opts.since) query.since = opts.since;
+  if (opts.includeInactive) query.include_inactive = "1";
+  if (opts.limit != null) query.limit = String(opts.limit);
+
+  let resp;
+  try {
+    resp = await http.get("plans", query);
+  } catch (e) {
+    fail("List failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const scope = resp.organization_name
+    ? resp.organization_name
+    : `all ${resp.include_inactive ? "" : "active "}orgs`;
+  const totals = STATUS_ORDER.filter((s) => resp.counts?.[s]).map((s) => `${s} ${resp.counts[s]}`).join(" · ");
+  console.log(`Broadcast plans · ${scope} · status ${resp.status_filter}${resp.since ? ` · from ${resp.since}` : ""}`);
+  console.log(`  every status in this scope: ${totals || "none"}`);
+
+  const plans = resp.plans || [];
+  if (!plans.length) {
+    console.log("  (no matching plans)");
+    return;
+  }
+
+  for (const s of STATUS_ORDER) {
+    const group = plans.filter((p) => p.status === s);
+    if (!group.length) continue;
+    console.log(`\n${STATUS_LABEL[s]} (${group.length})`);
+    for (const p of group) {
+      const flag = p.date_passed ? " (date passed)" : p.scheduled_date === resp.today ? " (today)" : "";
+      console.log(`  ${fmtDate(p.scheduled_date, p.scheduled_time)}${flag}  ${p.organization_name ?? p.organization_id}  ·  ${p.topic}`);
+      const bits = [
+        p.type || "type not set",
+        p.audience,
+        p.origin === "flowapt" ? `Flowapt suggestion (client: ${p.client_status ?? "-"})` : null,
+        p.creative_file ? `creative ${p.creative_file}` : null,
+        p.template_id ? "template linked" : null,
+        p.has_client_comment ? "has response to client" : null,
+        p.notes_count ? `${p.notes_count} note(s)` : null,
+      ].filter(Boolean);
+      console.log(`    ${bits.join(" · ")}`);
+      const reviewed = p.reviewed_at
+        ? ` · reviewed ${fmtTs(p.reviewed_at)}${p.reviewed_by_name ? ` by ${p.reviewed_by_name}` : ""}`
+        : "";
+      console.log(`    submitted ${fmtTs(p.created_at)}${p.created_by_name ? ` by ${p.created_by_name}` : ""}${reviewed}`);
+      console.log(`    id ${p.id}`);
+    }
+  }
+  if (resp.truncated) {
+    console.log(`\n⚠ ${plans.length} shown and the limit (${resp.limit}) was reached: pass --limit, or narrow with --status / --since.`);
+  }
+  console.log("\nFull plan: flowiq plans show <plan_id>");
+}
+
+export async function show(planId, opts = {}) {
+  if (!UUID_RE.test(planId)) {
+    console.error(`Error: "${planId}" is not a valid plan UUID (get it from \`flowiq plans list\`).`);
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.get("plans", { plan_id: planId });
+  } catch (e) {
+    fail("Show failed", e);
+  }
+  if (opts.out) {
+    const out = path.resolve(process.cwd(), opts.out);
+    await fs.mkdir(path.dirname(out), { recursive: true });
+    await fs.writeFile(out, JSON.stringify(resp, null, 2) + "\n", "utf8");
+    console.error(`Wrote ${out}`);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const p = resp.plan;
+  const more = p.more && typeof p.more === "object" ? p.more : {};
+  const creative = p.creative && typeof p.creative === "object" ? p.creative : {};
+  const flag = p.scheduled_date && p.scheduled_date < resp.today
+    ? " (date passed)"
+    : p.scheduled_date === resp.today ? " (today)" : "";
+
+  console.log(p.topic);
+  console.log(`  org:        ${p.organization_name ?? "?"} (${p.organization_id})${p.organization_inactive ? " [inactive org]" : ""}`);
+  console.log(`  status:     ${p.status}${p.origin === "flowapt" ? ` · Flowapt suggestion, client: ${p.client_status ?? "-"}` : ""}`);
+  console.log(`  send:       ${fmtDate(p.scheduled_date, p.scheduled_time)}${flag}`);
+  console.log(`  type:       ${more.type ?? "-"}`);
+  console.log(`  audience:   ${p.has_segment ? (p.segment_details || "segment (no details given)") : "whole list"}`);
+  if (p.shopify_segment_formula) console.log(`  formula:    ${p.shopify_segment_formula}`);
+  if (p.product_focus) console.log(`  product:    ${p.product_focus}`);
+  if (p.landing_page_url) console.log(`  landing:    ${p.landing_page_url}`);
+  console.log(`  submitted:  ${fmtTs(p.created_at)}${p.created_by_name ? ` by ${p.created_by_name}` : ""}`);
+  if (p.reviewed_at) console.log(`  reviewed:   ${fmtTs(p.reviewed_at)}${p.reviewed_by_name ? ` by ${p.reviewed_by_name}` : ""}`);
+  if (p.client_approved_at) console.log(`  client OK:  ${fmtTs(p.client_approved_at)}${p.client_approved_by_name ? ` by ${p.client_approved_by_name}` : ""}`);
+  console.log(`  id:         ${p.id}`);
+
+  console.log("\nMessage copy");
+  console.log(indent(p.copy_text));
+
+  if (more.slide2?.message) {
+    console.log("\nSecond message (sent when a button is tapped)");
+    console.log(indent(more.slide2.message));
+  }
+  if (more.slides && typeof more.slides === "object") {
+    for (const [key, slide] of Object.entries(more.slides)) {
+      if (!slide || typeof slide !== "object") continue;
+      console.log(`\n${key}${slide.triggered_by ? ` (after ${slide.triggered_by})` : ""}`);
+      if (slide.message) console.log(indent(slide.message));
+      if (slide.media_url) console.log(`  media: ${slide.media_url}`);
+    }
+  }
+
+  const buttons = Array.isArray(more.buttons) ? more.buttons : [];
+  if (buttons.length) {
+    console.log("\nButtons");
+    for (const b of buttons) console.log(`  [${b?.type ?? "?"}] ${b?.text ?? ""}${b?.url ? ` → ${b.url}` : ""}`);
+  }
+
+  console.log("\nCreative");
+  if (creative.original_filename || creative.file_url) {
+    const size = creative.file_size ? ` · ${(creative.file_size / 1024 / 1024).toFixed(1)} MB` : "";
+    console.log(`  ${creative.original_filename ?? "(unnamed)"} · ${creative.file_type ?? "type ?"}${size} · supplied by ${creative.supplier ?? "?"}`);
+    if (creative.file_url) console.log(`  ${creative.file_url}`);
+  } else {
+    console.log(`  none attached${creative.supplier ? ` (supplied by ${creative.supplier})` : ""}`);
+  }
+
+  if (p.template) console.log(`\nTemplate: ${p.template.template_name} (${p.template.status ?? "status ?"}, ${p.template.category ?? "category ?"})`);
+  else if (p.template_id) console.log(`\nTemplate id: ${p.template_id}`);
+  if (p.send_draft_id) console.log(`Send draft id: ${p.send_draft_id}`);
+
+  if (p.superadmin_comment) {
+    console.log("\nResponse to client");
+    console.log(indent(p.superadmin_comment));
+  }
+  if (p.internal_notes) {
+    console.log("\nInternal notes (staff only)");
+    console.log(indent(p.internal_notes));
+  }
+  const notes = resp.notes || [];
+  if (notes.length) {
+    console.log(`\nNotes (${notes.length})`);
+    for (const n of notes) console.log(`  ${fmtTs(n.created_at)} ${n.author_name ?? "?"} [${n.kind ?? "note"}]: ${String(n.body ?? "").replace(/\s+/g, " ").trim()}`);
+  }
+
+  console.log(`\nChange status: flowiq plans status ${p.id} --to <status> [--comment "..."] [--commit]`);
+}
+
+export async function status(planId, opts = {}) {
+  if (!UUID_RE.test(planId)) {
+    console.error(`Error: "${planId}" is not a valid plan UUID (get it from \`flowiq plans list\`).`);
+    process.exit(1);
+  }
+  const to = String(opts.to || "").toLowerCase();
+  if (!STATUSES.includes(to)) {
+    console.error(`Error: --to must be one of ${STATUSES.join(" | ")} (got "${opts.to}").`);
+    process.exit(1);
+  }
+  if (to === "rejected" && !(opts.comment && opts.comment.trim())) {
+    console.error("Refusing to reject without --comment: the client reads it as the response to their plan.");
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("plans", {
+      action: "status",
+      plan_id: planId,
+      status: to,
+      superadmin_comment: opts.comment ?? null,
+      internal_notes: opts.internal ?? null,
+      dry_run: !opts.commit,
+    });
+  } catch (e) {
+    fail("Status change failed", e);
+  }
+
+  const prev = resp.previous || {};
+  const next = resp.next || {};
+  console.log(`${resp.dry_run ? "DRY RUN" : "Updated"} · ${resp.topic}`);
+  console.log(`  org:       ${resp.organization_name ?? resp.organization_id}`);
+  console.log(`  status:    ${prev.status} → ${next.status}`);
+  if (next.superadmin_comment !== prev.superadmin_comment) console.log(`  client reads: ${next.superadmin_comment}`);
+  if (next.internal_notes !== prev.internal_notes) console.log(`  internal:  ${next.internal_notes}`);
+  if (resp.reviewer_email) console.log(`  reviewer:  ${resp.reviewer_email} (reviewed_at ${fmtTs(next.reviewed_at)})`);
+  if (resp.dry_run) console.log("\nNothing written. Re-run with --commit to apply.");
+}

package/src/index.js

@@ -25,6 +25,7 @@ import * as teamUpdatesCmd from "./commands/team-updates.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
 import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
+import * as plansCmd from "./commands/plans.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
@@ -411,7 +412,7 @@ export function run(argv) {
     .option("--model <model>", "settings.model (e.g. gpt-5.4-mini)")
     .option("--reasoning-effort <level>", "settings.reasoning_effort — low|medium|high (\"\" clears it); pairs with reasoning models (e.g. gpt-5.6-luna + high)")
     .option("--rename <name>", "rename the agent")
-    .option("--tool <flag=bool>", "toggle a tool flag (repeatable): woo_order_build/woo_tip_field/woo_order_note_field/view_cart_tool/restock_tool/block_tool_status/postal_code_tool_status/shopify_products_web_chat/ticket_tool_status/collapse_product_variants", agentConfigCmd.collectTool, [])
+    .option("--tool <flag=bool>", "toggle a tool flag (repeatable): woo_order_build/woo_tip_field/woo_order_note_field/view_cart_tool/restock_tool/block_tool_status/postal_code_tool_status/shopify_products_web_chat/ticket_tool_status/product_lookup/email_request_tool/collapse_product_variants", agentConfigCmd.collectTool, [])
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
     .option("--test-contact-number <number>", "settings.test_contact_number — the contact `flowiq test` uses (use a FAKE number; \"\" clears it → synthetic fallback)")
     .option("--test-contact-name <name>", "settings.test_contact_name — display name for the test contact (\"\" clears it)")
@@ -445,6 +446,31 @@ export function run(argv) {
     .option("--yes", "skip the interactive confirm gate (the --note requirement still applies)")
     .action((updateId, opts) => agentUpdatesCmd.resolve(updateId, opts));
 
+  // plans (Broadcast Planning board: list across orgs, show one plan, change status)
+  const plans = program.command("plans")
+    .alias("planning")
+    .description("Broadcast Planning (Broadcast → Planning): list plans across orgs, show one in full, change a plan's status");
+  plans.command("list [organization_id]")
+    .description("List plans, default open (draft, pending_review, approved, scheduled), across all active orgs or one org")
+    .option("--status <status>", "open (default) | all | pending_review | draft | approved | rejected | scheduled | sent | cancelled (comma-separated allowed)")
+    .option("--since <date>", "only plans scheduled on or after YYYY-MM-DD")
+    .option("--include-inactive", "include plans from inactive orgs (cross-org listing)")
+    .option("--limit <n>", "max plans returned (default 100, max 500)")
+    .option("--json", "print the raw response")
+    .action((orgId, opts) => plansCmd.list(orgId, opts));
+  plans.command("show <plan_id>")
+    .description("Show one plan in full: copy, second message, buttons, creative, audience, notes")
+    .option("--json", "print the raw response")
+    .option("--out <file>", "also write the full plan JSON to a file")
+    .action((planId, opts) => plansCmd.show(planId, opts));
+  plans.command("status <plan_id>")
+    .description("Change a plan's status (dry run unless --commit); approved/rejected also record you as the reviewer")
+    .requiredOption("--to <status>", "draft | pending_review | approved | rejected | scheduled | sent | cancelled")
+    .option("--comment <text>", "response to the client, shown on their plan (required for rejected)")
+    .option("--internal <text>", "staff-only internal notes (replaces the current internal notes)")
+    .option("--commit", "apply the change (default is a dry run)")
+    .action((planId, opts) => plansCmd.status(planId, opts));
+
   // audit (who did what, when — with the full before/after content)
   const audit = program.command("audit")
     .description("Staff-CLI audit trail: who changed what, when — with full before/after content")