@flowapt/flowiq-cli 0.7.0 → 0.7.2

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)
 
@@ -1131,6 +1138,54 @@ flowiq insights run <organization_id> --from 2026-09-01 --to 2026-09-07 --store-
   schedule for that period, else standard.
 - `enable` / `disable` / `run` are audited (`flowiq audit --endpoint insights`).
 
+### Team updates — `flowiq updates status|uncovered|draft|asset|preview|send` (v0.7.1)
+
+The **"what changed in FlowIQ" email to the Flowapt team** — every super admin
+gets it. An *issue* is a JSON file composed from `platform_changelog` rows:
+headline sections (a screenshot straight from the app, what it does, and a
+**For the team** note: how we use it, what to tell clients), an *Also shipped*
+list, and a *CLI and MCP* block. The renderer, the send (from
+flowiq@flowapt.com, reply-to Matt) and the record (`team_updates`, with the exact
+HTML that went out) live server-side in the `team-update-email` edge function.
+
+```bash
+flowiq updates status                                   # uncovered changelog rows · recent sends · recipients
+flowiq updates uncovered                                # the rows no issue has emailed yet
+flowiq updates draft                                    # → ./.flowiq/updates/<date>.json, a default issue to enrich
+flowiq updates draft --since 2026-09-07T22:00:00+02:00  # compose from a period instead of the last covered point
+flowiq updates asset ./api-keys-card.png                # host a screenshot, prints the https URL for image.url
+flowiq updates preview .flowiq/updates/2026-09-10.json --open   # render to .html exactly as emailed
+flowiq updates send .flowiq/updates/2026-09-10.json --test      # one copy to YOU; nothing marked covered
+flowiq updates send .flowiq/updates/2026-09-10.json --test --to kiah@flowapt.com
+flowiq updates send .flowiq/updates/2026-09-10.json --yes       # the real send, to every super admin
+```
+
+- **Issue shape** (`issue` key in the file): `subject`, `preheader`, `title`,
+  `intro`, `date_label`, `headlines[]`, `also[]`, `tools[]`, `closing`,
+  `changelog_ids[]`. A headline/tool section: `type` (feature | improvement |
+  fix | ui | agent | cli | infra | db | mcp — the chip is the app's own), `major`,
+  `title`, `what[]` (paragraphs), `team[]` (bullets), `image{url,alt,caption}`,
+  `terminal{command,output}`, `link{label,url}`, `org_name`, `version`. An
+  `also[]` item: `type`, `title`, `note`, `link`. Inline markup anywhere:
+  `**bold**`, `` `code` ``, `[label](https://…)`.
+- **`preview` and `send` lint the file first** (required fields, unknown types,
+  non-https images, em dashes) and stop with line-level help.
+- **`send` without `--test` needs `--yes`**: it emails the whole team AND moves
+  the covered-up-to mark, so those changelog rows will never be auto-digested.
+  `--test` sends to you (or `--to`) and marks nothing.
+- **The safety net:** pg_cron `team-update-email-daily` (08:30 SAST) emails a
+  default digest of any changelog row that has gone un-emailed for 20h+, so a
+  ship is never silently missed. The curated `send` is what stops it firing —
+  compose the issue the same day you ship.
+- **Who may do what:** everyone with a staff key can `status`, `uncovered`,
+  `draft`, `asset`, `preview` and `send --test` (a copy to yourself, nothing
+  marked covered). **The real send is Matt only** — any other key gets
+  `403 Only matt@flowapt.com may post the team update` and the attempt is
+  audited (`ALLOWED_SENDERS` in `api/cli/team-updates.js`).
+- Every link in the email opens the app's Changelog at that entry
+  (`app.flowiq.live/?changelog=1&entry=<id>`). `send` and `asset` are audited
+  (`flowiq audit --endpoint team-updates`).
+
 ### WhatsApp templates — `flowiq templates pull|list|show|create|status` (alias `tpl`)
 
 Read an org's live templates straight from Meta (read-only), render any single
@@ -1387,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>`
 

package/TEAM-GUIDE.md

@@ -81,6 +81,7 @@ 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 |
@@ -103,6 +104,9 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Agent can't quote ANY price / "I can't pull the live menu" | `flowiq agent config <org_id> --tool product_lookup=true` — name-based fuzzy lookup that works without embeddings or a live OpenAI key (semantic `get_product_info` needs both) |
 | Client wants leads/requests emailed to their team instead of a human escalation | `flowiq agent config <org_id> --tool email_request_tool=true`, then set the recipient list in Agents → Tool Library → Email Request to Team (no CLI path for the addresses yet) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
+| **Tell the team what shipped** (the FlowIQ team update email) | `flowiq updates draft` → enrich the JSON (screenshots via `flowiq updates asset`, a *For the team* note per headline) → `flowiq updates preview <file> --open` → `flowiq updates send <file> --test` → `flowiq updates send <file> --yes` |
+| Can I use `flowiq updates`? | Yes: `status`, `uncovered`, `draft`, `preview` and `send --test` (a copy to yourself) work for everyone. Only the real `send --yes` to the whole team is Matt's; anyone else gets a 403 there |
+| Which changelog rows has nobody emailed the team about yet? | `flowiq updates status` / `flowiq updates uncovered` — anything left 20h+ goes out automatically at 08:30 SAST as a plain digest |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 > **Publishing the CLI (maintainers only):** publish from a clean clone, never
 > from your working tree — `npm publish` packs whatever is on disk. A

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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/team-updates.js

@@ -0,0 +1,169 @@
+// `flowiq updates <verb>` — the "what changed in FlowIQ" email to the Flowapt team.
+//   status               uncovered changelog rows, last sends, who receives it
+//   uncovered            list the changelog rows no issue has covered yet
+//   draft [--out f]      write ./.flowiq/updates/<date>.json — a default issue
+//                        composed from the uncovered rows, ready to enrich
+//                        (screenshots, "for the team" notes, a CLI block)
+//   asset <file>         host an image for the email; prints the public URL
+//   preview <file>       render the issue to <file>.html (--open shows it)
+//   send <file>          --test → one copy to you (or --to a@b) without
+//                        marking anything covered; without --test the issue
+//                        goes to every super admin and needs --yes
+// The renderer, the send and the record all live server-side
+// (/cli/team-updates → the team-update-email edge fn); every send is audited.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { http } from "../http.js";
+
+const DIR = path.resolve(process.cwd(), ".flowiq", "updates");
+const TYPES = ["feature", "improvement", "fix", "ui", "agent", "cli", "infra", "db", "mcp"];
+
+function sastStamp() {
+  return new Date().toLocaleDateString("en-CA", { timeZone: "Africa/Johannesburg" }); // YYYY-MM-DD
+}
+
+async function readIssue(file) {
+  const p = path.resolve(process.cwd(), file);
+  let raw;
+  try { raw = await fs.readFile(p, "utf8"); }
+  catch { console.error(`Error: cannot read ${p}`); process.exit(1); }
+  let doc;
+  try { doc = JSON.parse(raw); }
+  catch (e) { console.error(`Error: ${p} is not valid JSON (${e.message})`); process.exit(1); }
+  const issue = doc.issue && typeof doc.issue === "object" ? doc.issue : doc;
+  const problems = lint(issue);
+  if (problems.length) {
+    console.error(`Error: ${p} has ${problems.length} problem(s):`);
+    for (const m of problems) console.error(`  - ${m}`);
+    process.exit(1);
+  }
+  return { issue, file: p };
+}
+
+/** The same checks the server applies, so a bad file fails here with line-level help. */
+function lint(issue) {
+  const out = [];
+  if (!issue.subject) out.push("subject is required");
+  if (!issue.title) out.push("title is required");
+  const secs = [...(issue.headlines ?? []).map((s, i) => [`headlines[${i}]`, s]), ...(issue.tools ?? []).map((s, i) => [`tools[${i}]`, s])];
+  for (const [where, s] of secs) {
+    if (!s.title) out.push(`${where}: title is required`);
+    if (s.type && !TYPES.includes(s.type)) out.push(`${where}: type '${s.type}' is not one of ${TYPES.join("|")}`);
+    if (s.image && !/^https:\/\//.test(s.image.url || "")) out.push(`${where}: image.url must be https (host it with \`flowiq updates asset\`)`);
+    if (s.what && !Array.isArray(s.what)) out.push(`${where}: what must be an array of paragraphs`);
+    if (s.team && !Array.isArray(s.team)) out.push(`${where}: team must be an array of bullets`);
+  }
+  (issue.also ?? []).forEach((a, i) => {
+    if (!a.title) out.push(`also[${i}]: title is required`);
+    if (a.type && !TYPES.includes(a.type)) out.push(`also[${i}]: type '${a.type}' is not valid`);
+  });
+  const text = JSON.stringify(issue);
+  if (/—/.test(text)) out.push("contains an em dash (—) — house style is no em dashes in anything a teammate reads");
+  return out;
+}
+
+function fmtWhen(iso) {
+  return new Date(iso).toLocaleString("en-GB", { timeZone: "Africa/Johannesburg", day: "numeric", month: "short", hour: "2-digit", minute: "2-digit" });
+}
+
+export async function status(opts) {
+  let r;
+  try { r = await http.get("team-updates"); }
+  catch (e) { console.error(`Status failed: ${e.message}`); process.exit(1); }
+  if (opts?.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`Team updates`);
+  console.log(`  uncovered:  ${r.uncovered} changelog row(s) not yet emailed${r.covered_until ? ` (covered up to ${fmtWhen(r.covered_until)} SAST)` : " (nothing has ever been sent)"}`);
+  console.log(`  recipients: ${(r.recipients ?? []).map((x) => x.email).join(", ") || "none"}`);
+  if (Array.isArray(r.recent) && r.recent.length) {
+    console.log(`  recent:`);
+    for (const s of r.recent) console.log(`    ${fmtWhen(s.created_at)}  ${s.status.padEnd(6)} ${s.source.padEnd(9)} ${String(s.subject).slice(0, 70)}  → ${s.recipients?.length ?? 0}`);
+  }
+}
+
+export async function uncovered(opts) {
+  let r;
+  try { r = await http.get("team-updates", { uncovered: 1, limit: opts?.limit ?? 60 }); }
+  catch (e) { console.error(`Failed: ${e.message}`); process.exit(1); }
+  if (opts?.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  if (!r.rows?.length) { console.log("Nothing uncovered — every changelog row has been emailed."); return; }
+  console.log(`${r.rows.length} uncovered row(s)${r.since ? ` since ${fmtWhen(r.since)} SAST` : ""}:`);
+  for (const row of r.rows) console.log(`  ${fmtWhen(row.created_at)}  ${row.type.padEnd(11)} ${row.is_major ? "MAJOR " : "      "} ${row.title}${row.org_name ? `  [${row.org_name}]` : ""}`);
+}
+
+export async function draft(opts) {
+  let r;
+  try { r = await http.get("team-updates", { draft: 1, limit: opts?.limit ?? 60, since: opts?.since }); }
+  catch (e) { console.error(`Draft failed: ${e.message}`); process.exit(1); }
+  if (!r.count) { console.log("Nothing to draft — every changelog row has been emailed. Use --since <iso> to re-cover a period."); return; }
+  await fs.mkdir(DIR, { recursive: true });
+  const out = path.resolve(process.cwd(), opts?.out || path.join(DIR, `${sastStamp()}.json`));
+  const doc = {
+    _help: [
+      "This is a default issue composed from the uncovered changelog rows. Enrich it, then `flowiq updates preview` / `send`.",
+      "headlines[]: type, major, title, what[] (paragraphs), team[] (bullets: how WE use it / what to tell clients), image{url,alt,caption} (host with `flowiq updates asset`), terminal{command,output}, link{label,url}.",
+      "also[]: short rows (title, note, type). tools[]: CLI / MCP sections, same shape as headlines.",
+      "Inline markup in any text: **bold**, `code`, [label](https://…). No emoji, no em dashes.",
+    ],
+    issue: r.issue,
+  };
+  await fs.writeFile(out, JSON.stringify(doc, null, 2) + "\n");
+  console.log(`Drafted ${r.count} row(s) → ${path.relative(process.cwd(), out)}`);
+  console.log(`  headlines ${r.issue.headlines?.length ?? 0} · also ${r.issue.also?.length ?? 0} · cli/mcp ${r.issue.tools?.length ?? 0}`);
+  console.log(`  next: enrich it, then \`flowiq updates preview ${path.relative(process.cwd(), out)} --open\``);
+}
+
+export async function asset(file, opts) {
+  const p = path.resolve(process.cwd(), file);
+  let buf;
+  try { buf = await fs.readFile(p); }
+  catch { console.error(`Error: cannot read ${p}`); process.exit(1); }
+  const ext = path.extname(p).toLowerCase();
+  const type = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif" }[ext];
+  if (!type) { console.error(`Error: ${ext || "(no extension)"} is not an image type the email can use (png, jpg, webp, gif)`); process.exit(1); }
+  let r;
+  try { r = await http.post("team-updates", { action: "asset", name: opts?.name || path.basename(p), content_type: type, data_base64: buf.toString("base64") }); }
+  catch (e) { console.error(`Upload failed: ${e.message}`); process.exit(1); }
+  console.log(r.url);
+}
+
+export async function preview(file, opts) {
+  const { issue, file: p } = await readIssue(file);
+  let r;
+  try { r = await http.post("team-updates", { action: "preview", issue, to_name: opts?.as || "Matt" }); }
+  catch (e) { console.error(`Preview failed: ${e.message}`); process.exit(1); }
+  const out = p.replace(/\.json$/i, "") + ".html";
+  await fs.writeFile(out, r.html);
+  console.log(`Subject: ${r.subject}`);
+  console.log(`Rendered → ${path.relative(process.cwd(), out)} (${(r.html.length / 1024).toFixed(1)} KB)`);
+  if (opts?.open) spawn(process.platform === "darwin" ? "open" : "xdg-open", [out], { stdio: "ignore", detached: true }).unref();
+}
+
+export async function send(file, opts) {
+  const { issue } = await readIssue(file);
+  const to = (opts?.to || "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  const test = !!opts?.test;
+  if (test && !to.length) {
+    let me;
+    try { me = await http.get("whoami"); }
+    catch (e) { console.error(`whoami failed: ${e.message}`); process.exit(1); }
+    const email = me?.user_email || me?.email || me?.userEmail;
+    if (!email) { console.error("Could not resolve your email for the test send; pass --to."); process.exit(1); }
+    to.push(email);
+  }
+  if (!test && !opts?.yes) {
+    console.error("Refusing: this sends to the whole Flowapt team and marks the changelog rows as covered. Re-run with --yes, or use --test first.");
+    process.exit(1);
+  }
+  let r;
+  try { r = await http.post("team-updates", { action: "send", issue, to: to.length ? to : undefined, test }); }
+  catch (e) { console.error(`Send failed: ${e.message}`); process.exit(1); }
+  const ok = (r.recipients ?? []).filter((x) => x.status === "sent");
+  const bad = (r.recipients ?? []).filter((x) => x.status !== "sent");
+  console.log(`${test ? "Test sent" : "Sent"}: "${issue.subject}"`);
+  for (const x of ok) console.log(`  ✓ ${x.to}`);
+  for (const x of bad) console.log(`  ✗ ${x.to}  ${x.error ?? x.status}`);
+  if (!test) console.log(r.covers_until ? `  covered up to ${fmtWhen(r.covers_until)} SAST · record ${r.id}` : `  NOT marked as covered (every send failed)`);
+  if (bad.length) process.exitCode = 1;
+}

package/src/index.js

@@ -21,6 +21,7 @@ import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
 import * as orgFlagsCmd from "./commands/org-flags.js";
 import * as insightsCmd from "./commands/insights.js";
+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";
@@ -410,7 +411,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)")
@@ -864,6 +865,39 @@ export function run(argv) {
     .option("--out <file>", "write the JSON to a file instead of stdout")
     .action((orgId, path, opts) => storeApiCmd.wooGet(orgId, path, opts));
 
+  // updates — the "what changed in FlowIQ" email to the Flowapt team
+  const updates = program.command("updates").description("Team update email: what changed in FlowIQ, sent to every super admin (status / draft / preview / send)");
+  updates.command("status")
+    .description("uncovered changelog rows, recent sends and who receives the email")
+    .option("--json", "machine-readable output")
+    .action((opts) => teamUpdatesCmd.status(opts));
+  updates.command("uncovered")
+    .description("list the changelog rows no team update has covered yet")
+    .option("--limit <n>", "rows to list (default 60)")
+    .option("--json", "machine-readable output")
+    .action((opts) => teamUpdatesCmd.uncovered(opts));
+  updates.command("draft")
+    .description("write ./.flowiq/updates/<date>.json: a default issue composed from the uncovered rows, ready to enrich")
+    .option("--since <iso>", "compose from rows created after this time instead of the last covered point")
+    .option("--limit <n>", "rows to include (default 60)")
+    .option("--out <file>", "write the issue here instead of ./.flowiq/updates/<date>.json")
+    .action((opts) => teamUpdatesCmd.draft(opts));
+  updates.command("asset <file>")
+    .description("host an image (png/jpg/webp/gif, max 6 MB) for the email and print its public URL")
+    .option("--name <name>", "file name to store under (default: the file's own name)")
+    .action((file, opts) => teamUpdatesCmd.asset(file, opts));
+  updates.command("preview <file>")
+    .description("render the issue JSON to <file>.html exactly as it will be emailed")
+    .option("--as <first-name>", "greet this name in the preview (default Matt)")
+    .option("--open", "open the rendered HTML in the browser")
+    .action((file, opts) => teamUpdatesCmd.preview(file, opts));
+  updates.command("send <file>")
+    .description("email the issue: --test sends one copy to you (or --to) and marks nothing; without --test it goes to every super admin and needs --yes")
+    .option("--test", "send a single test copy only (to you unless --to is given); nothing is marked as covered")
+    .option("--to <emails>", "comma-separated recipients instead of the team list")
+    .option("--yes", "confirm the real send to the whole team")
+    .action((file, opts) => teamUpdatesCmd.send(file, opts));
+
   // doctor (version + auth + server contract in one read-only command)
   program.command("doctor")
     .description("Check this install: version vs npm, auth, and whether the server still supports it. Exits 1 if something needs fixing")