@flowapt/flowiq-cli 0.11.0 → 0.12.0

package/README.md

@@ -261,6 +261,16 @@ flowiq bc route <org_id> <broadcastId> --team "Spa" --commit             # set i
 flowiq bc route <org_id> <broadcastId> --clear --commit                  # switch it off
 ```
 
+**Coexistence numbers are sent at a steady pace (2 Oct 2026).** On an org whose number
+is shared with the WhatsApp Business app (`feature_flags.coexistence.enabled`), every
+send engine (python, `/api/broadcast`, `/api/send-template`) sends one message every
+200 ms (5 a second) instead of in bursts, and the `bc send` dry run says so with the
+time it will take: `🐢 Coexistence number: sent one at a time at 5 a second, about 5 min
+for 1500 contact(s)`. On every org, a send Meta refuses with **130429** (its send-speed
+limit) is retried after 2 / 5 / 10 s before it is recorded as failed; Meta never sent it,
+so a retry cannot double-message anyone. `flowiq org whatsapp` notes a coexistence
+number (Meta's own `throughput` still reads STANDARD on them). Server-side, no new flags.
+
 - **Scheduling (v0.4.4 tag / v0.6.1 CSV)** — `--at "YYYY-MM-DD HH:MM"` queues the
   send instead of firing it. It writes the same `api_request_queue` row the
   dashboard writes, replayed by the `process-api-queue` cron (every 3 min, so it
@@ -2255,6 +2265,44 @@ flowiq messages delete <contact_id> [--before 30d] [--sender-type tool-call] --c
   On with `vert.active` not false = live for every customer, which needs
   `--yes`; the command prints which of the three it would produce.
 
+### Batch G (0.12.0): the 1 October filings
+
+Eighteen requests filed by the team on 1 Oct 2026, each reproduced against the
+code before the fix.
+
+```bash
+flowiq contacts show <contact_id>                        # no --org needed any more: the org is resolved from the id
+flowiq contacts lint <org>                               # now also flags a 27 + 11 digit number (SA is 27 + 9) and suggests the real one
+flowiq contacts ai off <org> --tag <tag> [--commit]      # AI off/on for every contact on a tag (or --contact / --ids-file), agent-off rows written
+flowiq contacts add <org> --whatsapp-id 27637186304 --name Lau --no-broadcast --commit
+flowiq members invite <org> someone@client.co.za --role viewer   # an invitation they accept at sign-up (no account needed)
+flowiq messages search <org> "being updated at the same time" --tool-calls   # inside tool-call request / response
+flowiq messages failures <org>                           # rows with only an error_message no longer roll up as "?"
+flowiq messages purge <org> --subject-regex '^Automatic reply' --sender-type user-email --confirm   # org-wide delete by pattern
+flowiq org automations <org> --set payment_received --template payment_received_v3 --body param1=full_name,param2=order_number --buttons param1=short_code --commit
+flowiq org whatsapp <org> | --all                        # LIMIT = the business portfolio's messaging limit (Meta's new field); code verification EXPIRED is info, not a problem
+flowiq org health <org>                                  # flags an active agent with no human_notify (a handover alerts nobody)
+flowiq agent config <org>                                # human_notify / order_notify / tool_instructions print "(unset)" instead of vanishing
+flowiq tag field <org> --field whatsapp_id --any 2779…,2782…   # a digit-only list is matched whole (exact) automatically; 0.7 s instead of a timeout
+flowiq test seed <org> --from <contact_id> --until "2026-10-01 09:08" --commit   # copy a real chat onto a test contact; test unseed removes it
+flowiq plans create <org> --topic "Heritage Day" --type utility --date 2026-10-09 --time 10:00 --line-1 … --line-2 … --follow-up … --landing https://… --commit
+flowiq woo get <org> products --all --fields id,name,permalink,status   # past the 3.5 MB cap; the truncation message now says how to trim and resume
+```
+
+- **`contacts ai off`** writes `bot_status` and the same `agent-off` row the
+  inbox toggle writes, so the chat shows who switched it. It warns about the
+  reactivation cron: an AI-off contact is turned back on once their last
+  customer message is 12 h old and the agent-off row is older than 24 h
+  (unless `bot_reactivation.enabled` is false on the org).
+- **`messages purge`** matches an email subject regex (`more_data.subject`),
+  a text substring, sender types and a time window; 5,000 rows a run; the dry
+  run lists subjects and contacts; `--confirm` asks you to type the org id.
+- **`plans create`** files the same row the MCP's `submit_plan` writes and
+  alerts the team the same way; staff are exempt from the client lead time
+  (a sub-24 h send is noted, not refused).
+- Not a CLI fix: #186 (Shopify store analytics need the `read_reports` scope
+  on the FlowIQ app).
+
 ### Guide — `flowiq guide`
 
 Read the bundled docs in the terminal — no digging through node_modules.

package/TEAM-GUIDE.md

@@ -143,7 +143,8 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Did the agent say something wrong to anyone today? | `flowiq messages search <org_id> "the words" --since 24h` |
 | Why did messages not arrive / what failed to send? | `flowiq messages failures <org_id> --since 7d` (Meta error codes by reason, media and contact, plus sends Meta accepted and never confirmed) |
 | How many messages did an org send last month, free-form vs template? | `flowiq messages stats <org_id> --since 6m` |
-| Is a client's WhatsApp number healthy / connected / rate-limited? | `flowiq org whatsapp <org_id>` (straight from Meta); every org: `flowiq org whatsapp --all` |
+| Is a client's WhatsApp number healthy / connected / rate-limited? | `flowiq org whatsapp <org_id>` (straight from Meta); every org: `flowiq org whatsapp --all`. A number shared with the WhatsApp Business app says "coexistence number … paced to 5 a second". |
+| Why did a broadcast lose sends to error 130429? | The number is on **coexistence** (shared with the WhatsApp Business app) and was sent to in bursts. Since 2 Oct 2026 every engine sends those numbers one at a time (5 a second, the `bc send` dry run shows how long it takes) and retries a 130429 after a pause. Resend the old failures with `flowiq bc retry <org_id> <broadcastId>`. |
 | Which channels are connected (Messenger, Instagram, email…)? | `flowiq org channels <org_id>`; every org: `flowiq org channels --all` |
 | Is this client's agent ready to switch on? | `flowiq org health <org_id>` (master switch, keys probed incl. the spare key, prompt, catalogue, webhooks, order sync, traffic; ⚠ lines are warnings, ✗ lines block) |
 | What automated messages / flows / rules does an org have armed? | `flowiq org automations <org_id>` · `flowiq flows list <org_id>` (+ `flows status` for failures) · `flowiq rules list <org_id>` (+ `rules results <rule_id>`) · `flowiq org abandoned <org_id>` |
@@ -161,6 +162,14 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Tag a list of contact ids, or see who carries a tag | `flowiq tag ids <org_id> --ids-file ids.txt --tag vip --commit` · `flowiq tag holders <org_id> vip --csv` |
 | Why did the agent answer that? | `flowiq test send <org_id> "<the question>" --tools` shows each tool's arguments and result |
 | Was that message the agent, a broadcast or an automation? | `flowiq messages pull <contact_id>` ends with a "sent by" line per source |
+| Stop the agent answering everyone who got a broadcast (a whole tag) | `flowiq contacts ai off <org_id> --tag <tag>` (dry run) → `--commit`; back on with `ai on`. Read the reactivation warning it prints |
+| Add a tester or a team member as a contact | `flowiq contacts add <org_id> --whatsapp-id 27637186304 --name Lau --no-broadcast --commit` |
+| Invite a client user who has no FlowIQ account | `flowiq members invite <org_id> <email> --role member` (they accept it when they sign up; FlowIQ sends no email, so tell them) |
+| Remove imported junk emails (auto-replies) across the whole inbox | `flowiq messages purge <org_id> --subject-regex '^Automatic reply' --sender-type user-email` (dry run) → `--confirm` |
+| Point an order message at a new template version, or fix its params | `flowiq org automations <org_id> --set <type> --template <name> --body param1=full_name,param2=order_number --buttons param1=short_code --commit` |
+| Reproduce what the agent or the Coworker said to a real customer | `flowiq test seed <org_id> --from <contact_id> --until "YYYY-MM-DD HH:MM" --commit`, open the seeded contact in the inbox, then `flowiq test unseed <org_id> <id> --confirm` |
+| File a broadcast plan for a client from the terminal | `flowiq plans create <org_id> --topic … --type utility\|marketing --date YYYY-MM-DD …` (dry run) → `--commit` |
+| What did a tool actually return? | `flowiq messages search <org_id> "<text>" --tool-calls` |
 > **Publishing the CLI (maintainers only):** publish from a clean clone, never
 > from your working tree — `npm publish` packs whatever is on disk. A
 > `prepublishOnly` check now stops you if `cli/` differs from `origin/main`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "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/batch-g.test.mjs

@@ -0,0 +1,35 @@
+// node --test src/batch-g.test.mjs — pure helpers behind the 0.12.0 verbs.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { withFields } from "./commands/store-api.js";
+import { parseButton } from "./commands/plans.js";
+process.env.VITE_SUPABASE_URL ||= "https://example.supabase.co";
+process.env.SUPABASE_SERVICE_ROLE ||= "test-key";
+const { lintNumber } = await import("../../api/cli/contacts.js");
+
+test("lintNumber flags a wrong national length and suggests the last-n twin", () => {
+  assert.deepEqual(lintNumber("2729829037707"), { problem: "27 + 11 digits (a +27 number is 27 + 9)", suggested: "27829037707" });
+  assert.deepEqual(lintNumber("2782903770"), { problem: "27 + 8 digits (a +27 number is 27 + 9)", suggested: null });
+  assert.equal(lintNumber("27829037707"), null);
+  assert.equal(lintNumber("351912345678"), null);
+  assert.equal(lintNumber("447700900123"), null);
+  // variable-length countries stay untouched
+  assert.equal(lintNumber("4915112345678"), null);
+  assert.equal(lintNumber("12125551234"), null);
+  // the older rules still win first
+  assert.match(lintNumber("270821234567").problem, /trunk 0/);
+  assert.match(lintNumber("2727821234567").problem, /doubled/);
+});
+
+test("withFields adds the platform's field-trim parameter and leaves other query keys", () => {
+  assert.deepEqual(withFields({ status: "any" }, "id, name ,permalink", "_fields"), { status: "any", _fields: "id,name,permalink" });
+  assert.deepEqual(withFields({ status: "any" }, undefined, "fields"), { status: "any" });
+  assert.deepEqual(withFields(undefined, "id", "fields"), { fields: "id" });
+});
+
+test("parseButton reads the four button shapes", () => {
+  assert.deepEqual(parseButton("quick_reply:VIEW MORE"), { type: "quick_reply", text: "VIEW MORE" });
+  assert.deepEqual(parseButton("url:CLICK HERE=https://x.co/a=b"), { type: "url", text: "CLICK HERE", url: "https://x.co/a=b" });
+  assert.deepEqual(parseButton("phone:Call us=+27 60 975 1832"), { type: "phone", text: "Call us", phone_number: "+27 60 975 1832" });
+  assert.deepEqual(parseButton("copy_code:SAVE10"), { type: "copy_code", code: "SAVE10" });
+});

package/src/commands/agent-test.js

@@ -165,6 +165,35 @@ export async function qa(orgId, opts = {}) {
   await runPack(orgId, pack, opts);
 }
 
+// `flowiq test seed <org> --from <contact_id> [--until "2026-10-01 09:08"] [--name X] [--rows 60] [--with-tools] [--ai-on] [--commit]`
+export async function seed(orgId, opts = {}) {
+  requireOrg(orgId);
+  if (!UUID_RE.test(opts.from || "")) { console.error("Error: --from <contact_id> is required (the real chat to copy)."); process.exit(1); }
+  let until = opts.until;
+  if (until && /^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}(:\d{2})?)?$/.test(until)) until = until.replace(" ", "T") + (until.length === 10 ? "T23:59:59" : "") + "+02:00";
+  let r;
+  try { r = await http.post("agent-test", { action: "seed", organization_id: orgId, agent_id: opts.agent, from_contact_id: opts.from, until, name: opts.name, rows: opts.rows, with_tools: !!opts.withTools, ai_on: !!opts.aiOn, copy_attributes: !!opts.copyAttributes, dry_run: !opts.commit }); }
+  catch (e) { console.error(`Seed failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`${r.organization_name}: copy ${r.rows} row(s) from ${r.from.name ?? r.from.whatsapp_id} (${r.from.id})${r.until ? ` up to ${r.until}` : ""}${r.first ? `, ${r.first.slice(0, 16)} → ${r.last.slice(0, 16)}` : ""}`);
+  console.log(`  by sender: ${Object.entries(r.by_sender).map(([k, v]) => `${k} ${v}`).join(" · ") || "none"}`);
+  console.log(`  new contact: ${r.new_contact.whatsapp_id} "${r.new_contact.full_name}" · AI ${r.new_contact.bot_status ? "on" : "OFF"} · no broadcasts · tags ${r.new_contact.tags.join(", ")}`);
+  if (r.dry_run) { console.log("\nDRY RUN — add --commit to create the seeded contact."); return; }
+  console.log(`\n✓ seeded ${r.contact_id} (${r.copied} rows). Open it in the inbox or: flowiq test send ${orgId} "<question>" is NOT routed to it (the agent's test contact is separate); the Coworker reads it from the inbox. Remove: flowiq test unseed ${orgId} ${r.contact_id} --confirm`);
+}
+
+// `flowiq test unseed <org> <contact_id> --confirm`
+export async function unseed(orgId, contactId, opts = {}) {
+  requireOrg(orgId);
+  if (!UUID_RE.test(contactId || "")) { console.error("Error: pass the seeded contact id."); process.exit(1); }
+  let r;
+  try { r = await http.post("agent-test", { action: "unseed", organization_id: orgId, agent_id: opts.agent, contact_id: contactId, confirm: !!opts.confirm }); }
+  catch (e) { console.error(`Unseed failed: ${e.message}`); if (e.body?.error && !e.message.includes(e.body.error)) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  if (r.dry_run) { console.log(`Would delete ${r.whatsapp_id} "${r.name}" and its ${r.messages} message(s)${r.seeded_from ? ` (seeded from ${r.seeded_from})` : ""}. Add --confirm.`); return; }
+  console.log(`✓ deleted the seeded contact and ${r.messages} message(s).`);
+}
+
 export async function clear(orgId, opts = {}) {
   requireOrg(orgId);
   let resp;

package/src/commands/broadcast.js

@@ -1129,6 +1129,7 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   try {
     const dry = await http.post("broadcast", reqBody(true));
     pyTotal = dry.total_contacts_found ?? null;
+    printPacing(dry.pacing, pyTotal);
   } catch (e) {
     console.error(`Python dry-run failed after tagging: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`);
     console.error(`Nothing sent. The ${workSet.length} contact(s) ARE tagged "${tag}" — re-run to retry the fan-off.`);
@@ -1391,6 +1392,14 @@ function reportRoutingResult(orgId, rr, broadcastId) {
   }
 }
 
+// Coexistence numbers (shared with the WhatsApp Business app) are sent one at a time
+// at a fixed pace by python (flowiq gaps #196); the server says so on the dry run.
+export function printPacing(pacing, total) {
+  if (!pacing?.coexistence) return;
+  const time = pacing.estimated_minutes != null ? `, about ${pacing.estimated_minutes} min for ${total} contact(s)` : "";
+  console.log(`🐢 Coexistence number: sent one at a time at ${pacing.per_second} a second${time}. Meta's 130429 throttles are retried, not dropped.`);
+}
+
 async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, buttonParams = null, commitStage, cardOverrides = null, cardLines = [], replyRouting = null }) {
   const buttons = buttonParams && Object.keys(buttonParams).length ? buttonParams : (buttonLiteral ? { param1: buttonLiteral } : null);
   const reqBody = (dryRun) => ({
@@ -1412,6 +1421,7 @@ async function runPythonTagSend(orgId, { opts, tag, templateName, template, head
   console.log("");
   console.log(`Engine: PYTHON (yapi.store/meta-broadcast) — fire-and-forget, python-tracked.`);
   console.log(`Tag "${tag}": ${total} eligible contact(s) (allow_broadcast + not blocked, resolved server-side).`);
+  printPacing(dry.pacing, total);
   const sampleNum = dry.sample_contacts?.[0]?.whatsapp_id || dry.sample_contacts?.[0]?.phone_number || "<first eligible>";
   renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral, buttonParams: buttons }, headerMedia);
   printCarouselPlan(cardOverrides, cardLines);

package/src/commands/contacts.js

@@ -47,8 +47,49 @@ export async function find(orgId, opts = {}) {
 
 export async function show(contactId, opts = {}) {
   if (!UUID_RE.test(contactId || "")) { console.error(`Error: "${contactId}" is not a valid contact UUID.`); process.exit(1); }
-  if (!UUID_RE.test(opts.org || "")) { console.error("Error: --org <organization_id> is required (a contact id alone is not scoped)."); process.exit(1); }
-  return find(opts.org, { id: contactId, json: opts.json });
+  if (opts.org && !UUID_RE.test(opts.org)) { console.error(`Error: "${opts.org}" is not a valid organization UUID.`); process.exit(1); }
+  if (opts.org) return find(opts.org, { id: contactId, json: opts.json });
+  // No --org: the server resolves the contact's own org (one indexed read).
+  let resp;
+  try { resp = await http.get("contacts", { find: "1", contact_id: contactId }); } catch (e) { fail("Lookup failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.contacts.length) { console.log(`No contact ${contactId}.`); return; }
+  console.log(`${resp.organization_name} (${resp.organization_id}):\n`);
+  for (const c of resp.contacts) { printContact(c); console.log(""); }
+}
+
+// `flowiq contacts ai off|on <org> --tag <tag> | --contact <id> | --ids-file f [--reason] [--commit]`
+export async function ai(state, orgId, opts = {}) {
+  requireOrg(orgId);
+  const s = String(state || "").toLowerCase();
+  if (!["on", "off"].includes(s)) { console.error('Error: flowiq contacts ai off|on <org> --tag <tag> (or --contact / --ids-file)'); process.exit(1); }
+  if (!opts.tag && !opts.contact?.length && !opts.idsFile) { console.error("Error: pass --tag <tag>, --contact <id> (repeatable) or --ids-file <file>."); process.exit(1); }
+  if (opts.tag && (opts.contact?.length || opts.idsFile)) { console.error("Error: --tag or an id list, not both."); process.exit(1); }
+  const ids = opts.tag ? undefined : await readIds(opts);
+  let resp;
+  try { resp = await http.post("contacts", { action: "ai", organization_id: orgId, enabled: s === "on", tag: opts.tag, contact_ids: ids, reason: opts.reason, dry_run: !opts.commit }); }
+  catch (e) { fail("AI switch failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: ${resp.matched} contact(s)${resp.tag ? ` on tag ${resp.tag}` : ""} · ${resp.to_change} to switch ${s.toUpperCase()} · ${resp.already} already ${s}${resp.not_found ? ` · ${resp.not_found} not in this org` : ""}`);
+  for (const c of resp.sample) console.log(`  ${pad(c.whatsapp_id ?? "—", 16)} ${c.name ?? ""}  ${c.id}`);
+  if (resp.to_change > resp.sample.length) console.log(`  … ${resp.to_change - resp.sample.length} more`);
+  if (resp.caveat) console.log(`\n⚠ ${resp.caveat}`);
+  if (resp.dry_run) { console.log(`\nDRY RUN — nothing changed. Add --commit to set bot_status=${s === "on"} and write the agent-${s === "on" ? "on" : "off"} row on each chat.`); return; }
+  console.log(`\n✓ AI ${s.toUpperCase()} for ${resp.changed} contact(s).${resp.tag ? ` Undo: flowiq contacts ai ${s === "on" ? "off" : "on"} ${orgId} --tag ${resp.tag} --commit` : ""}`);
+}
+
+// `flowiq contacts add <org> --whatsapp-id <n> [--name] [--email] [--no-broadcast] [--tag a,b] [--ai-off] [--commit]`
+export async function add(orgId, opts = {}) {
+  requireOrg(orgId);
+  if (!opts.whatsappId) { console.error("Error: --whatsapp-id <digits> is required (country code first, e.g. 27637186304)."); process.exit(1); }
+  let resp;
+  try { resp = await http.post("contacts", { action: "add", organization_id: orgId, whatsapp_id: opts.whatsappId, full_name: opts.name, email: opts.email, allow_broadcast: opts.broadcast !== false, tags: opts.tag ? String(opts.tag).split(",").map((t) => t.trim()).filter(Boolean) : [], bot_status: opts.aiOff ? false : true, dry_run: !opts.commit }); }
+  catch (e) { fail("Add failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const r = resp.would_insert ?? resp.inserted;
+  console.log(`${resp.organization_name}: ${r.whatsapp_id} ${r.full_name ?? "(no name)"}${r.email ? ` · ${r.email}` : ""} · broadcasts ${r.allow_broadcast ? "yes" : "NO"} · AI ${r.bot_status ? "on" : "off"}${r.tags?.length ? ` · tags ${r.tags.join(", ")}` : ""}`);
+  if (resp.dry_run) { console.log("DRY RUN — add --commit to create the contact."); return; }
+  console.log(`✓ created ${resp.contact_id}. Show: flowiq contacts show ${resp.contact_id}`);
 }
 
 export async function census(orgId, opts = {}) {

package/src/commands/members.js

@@ -37,6 +37,19 @@ export async function add(orgId, emailOrId, opts = {}) {
   console.log(`✓ ${resp.email} is now a ${resp.role}${resp.reactivated ? " again" : ""}. Undo: flowiq members remove ${orgId} ${resp.email} --confirm`);
 }
 
+// `flowiq members invite <org> <email> [--role member]` — the app's door for
+// someone with no account: an invitations row they are shown at sign-up.
+export async function invite(orgId, email, opts = {}) {
+  requireOrg(orgId);
+  if (!email) { console.error("Error: flowiq members invite <org> <email> [--role member]"); process.exit(1); }
+  let resp;
+  try { resp = await http.post("members", { action: "invite", organization_id: orgId, email, role: opts.role || "member", dry_run: !!opts.dryRun }); } catch (e) { fail("Invite failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (resp.dry_run) { console.log(`Would invite ${resp.would_insert.email} to ${resp.organization_name} as ${resp.would_insert.role}.`); return; }
+  if (resp.unchanged) { console.log(resp.note); return; }
+  console.log(`✓ invited ${resp.email} as ${resp.role} (invitation ${resp.invitation_id}).\n  ${resp.note}.`);
+}
+
 export async function role(orgId, emailOrId, newRole, opts = {}) {
   requireOrg(orgId);
   if (!emailOrId || !newRole) { console.error("Error: flowiq members role <org> <email> admin|member|viewer"); process.exit(1); }

package/src/commands/messages.js

@@ -94,6 +94,33 @@ export function sentBy(m) {
   return "agent";
 }
 
+// `flowiq messages purge <org> --subject-regex <re> | --text <s> | --sender-type a,b [--since] [--before] --confirm`
+// Org-wide delete by pattern (the 71 Lego auto-replies across 69 contacts).
+export async function purge(orgId, opts = {}) {
+  requireOrg(orgId);
+  const senderTypes = opts.senderType ? String(opts.senderType).split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+  if (!opts.subjectRegex && !opts.text && !senderTypes) { console.error("Error: give at least one of --subject-regex, --text, --sender-type."); process.exit(1); }
+  const body = { action: "delete", organization_id: orgId, subject_regex: opts.subjectRegex, text: opts.text, sender_types: senderTypes, since: opts.since, before: opts.before };
+  let preview;
+  try { preview = await http.post("messages", { ...body, dry_run: true }); } catch (e) { fail("Purge failed", e); }
+  if (opts.json && !opts.confirm) { console.log(JSON.stringify(preview, null, 2)); return; }
+  console.log(`${preview.organization_name}: ${preview.count} message(s) across ${preview.contacts} contact(s) match${preview.capped ? " (capped at 5,000 a run; re-run for the rest)" : ""}`);
+  for (const [k, v] of Object.entries(preview.by_sender).sort()) console.log(`    ${pad(k, 18)} ${v}`);
+  if (preview.top_subjects.length) { console.log("  subjects:"); for (const s of preview.top_subjects) console.log(`    ${String(s.n).padStart(5)} × ${s.subject}`); }
+  if (preview.oldest) console.log(`  from ${fmtSast(preview.oldest)} to ${fmtSast(preview.newest)} SAST`);
+  for (const c of preview.sample_contacts.slice(0, 8)) console.log(`    ${String(c.n).padStart(5)} × ${c.contact?.full_name ?? ""} ${c.contact?.whatsapp_id ?? ""} (${c.contact_id})`);
+  if (!preview.count) return;
+  if (!opts.confirm) { console.log(`\nDRY RUN — nothing deleted. Add --confirm to delete (you will be asked to type the organization id).`); return; }
+  const readline = await import("node:readline");
+  const typed = await new Promise((resolve) => { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); rl.question(`This cannot be undone. Type the organization id (${orgId}) to delete ${preview.count} message(s): `, (a) => { rl.close(); resolve(a.trim()); }); });
+  if (typed !== orgId) { console.log("Mismatch — aborted, nothing deleted."); process.exit(0); }
+  let resp;
+  try { resp = await http.post("messages", { ...body, dry_run: false, confirm: true }); } catch (e) { fail("Purge failed", e); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`✓ deleted ${resp.deleted} message(s) across ${resp.contacts} contact(s). The audit row keeps ids, types and times (flowiq audit --endpoint messages).`);
+  if (resp.error) console.error(`  ⚠ ${resp.error}`);
+}
+
 // `flowiq messages delete <contact_id> [--before 30d] [--sender-type a,b] --confirm`
 export async function remove(contactId, opts = {}) {
   if (!UUID_RE.test(contactId)) { console.error(`Error: "${contactId}" is not a valid contact UUID.`); process.exit(1); }
@@ -137,12 +164,12 @@ export async function search(orgId, textParts, opts = {}) {
   const text = (Array.isArray(textParts) ? textParts.join(" ") : String(textParts ?? "")).trim();
   if (text.length < 2) { console.error("Error: give at least 2 characters to search for."); process.exit(1); }
   let resp;
-  try { resp = await http.get("messages", { organization_id: orgId, search: text, since: opts.since, until: opts.until, sender_type: opts.senderType, include_templates: opts.includeTemplates ? "1" : undefined, limit: opts.limit }); }
+  try { resp = await http.get("messages", { organization_id: orgId, search: text, since: opts.since, until: opts.until, sender_type: opts.senderType, include_templates: opts.includeTemplates ? "1" : undefined, tool_calls: opts.toolCalls ? "1" : undefined, limit: opts.limit }); }
   catch (e) { fail("Search failed", e); }
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
-  console.log(`${resp.organization_name}: ${resp.count} message(s) containing "${text}" since ${fmtSast(resp.since)} SAST${resp.capped ? ` (capped at ${resp.limit}; narrow with --since / --sender-type)` : ""}${opts.includeTemplates ? "" : " (template sends excluded; --include-templates)"}`);
+  console.log(`${resp.organization_name}: ${resp.count} ${opts.toolCalls ? "tool call(s) whose request or response contains" : "message(s) containing"} "${text}" since ${fmtSast(resp.since)} SAST${resp.capped ? ` (capped at ${resp.limit}; narrow with --since / --sender-type)` : ""}${opts.includeTemplates || opts.toolCalls ? "" : " (template sends excluded; --include-templates)"}`);
   for (const r of resp.rows) {
-    console.log(`  ${pad(fmtSast(r.created_at), 17)} ${pad(r.sender_type, 16)} ${pad((r.contact?.full_name || r.contact?.whatsapp_id || r.contact_id || "").slice(0, 22), 22)} ${snippetAround(r.message, text)}`);
+    console.log(`  ${pad(fmtSast(r.created_at), 17)} ${pad(opts.toolCalls ? (r.tool_name ?? "tool") : r.sender_type, 16)} ${pad((r.contact?.full_name || r.contact?.whatsapp_id || r.contact_id || "").slice(0, 22), 22)} ${opts.toolCalls ? String(r.message).replace(/\s+/g, " ").slice(0, 160) : snippetAround(r.message, text)}`);
   }
   if (resp.rows.length) console.log(`\n  contact ids: flowiq messages search … --json | jq '.rows[].contact_id'  ·  full chat: flowiq messages pull <contact_id>`);
 }

package/src/commands/org.js

@@ -197,8 +197,9 @@ export async function whatsapp(orgId, opts = {}) {
     console.log(`${resp.checked} Meta number(s) checked at Meta, ${resp.unhealthy} with a problem (${resp.skipped_not_meta_or_unconnected} org(s) skipped: not Meta or not connected)`);
     const pad = (s, n) => String(s ?? "").padEnd(n);
     console.log("");
-    console.log(`  ${pad("ORG", 30)} ${pad("NUMBER", 18)} ${pad("STATUS", 12)} ${pad("QUALITY", 9)} ${pad("TIER", 12)} PROBLEMS`);
-    for (const o of [...resp.orgs].sort((a, b) => Number(a.healthy) - Number(b.healthy))) console.log(`  ${pad(o.name.slice(0, 30), 30)} ${pad(o.phone_number, 18)} ${pad(o.status ?? "?", 12)} ${pad(o.quality ?? "?", 9)} ${pad(o.tier ?? "?", 12)} ${(o.problems || []).join("; ")}`);
+    console.log(`  ${pad("ORG", 30)} ${pad("NUMBER", 18)} ${pad("STATUS", 12)} ${pad("QUALITY", 9)} ${pad("LIMIT", 14)} PROBLEMS`);
+    for (const o of [...resp.orgs].sort((a, b) => Number(a.healthy) - Number(b.healthy))) console.log(`  ${pad(o.name.slice(0, 30), 30)} ${pad(o.phone_number, 18)} ${pad(o.status ?? "?", 12)} ${pad(o.quality ?? "?", 9)} ${pad(o.tier ?? "—", 14)} ${(o.problems || []).join("; ")}${o.notes?.length ? `${o.problems?.length ? " · " : ""}info: ${o.notes.join("; ")}` : ""}`);
+    console.log(`\n  LIMIT = the business portfolio's messaging limit (Meta sets it per portfolio now; the per-number tier field is deprecated). "—" = Meta returned neither field for this number.`);
     return;
   }
   const resp = await view(orgId, "whatsapp");
@@ -209,11 +210,11 @@ export async function whatsapp(orgId, opts = {}) {
   const p = w.phone || {};
   console.log(`  number:      ${p.display_phone_number ?? "?"} · "${p.verified_name ?? "?"}" · phone ${w.phone_id} · WABA ${w.waba_id ?? "?"}`);
   console.log(`  status:      ${p.status ?? "?"} · platform ${p.platform_type ?? "?"} · account mode ${p.account_mode ?? "?"}`);
-  console.log(`  quality:     ${p.quality_rating ?? "?"} · limit tier ${p.messaging_limit_tier ?? "?"}${p.throughput?.level ? ` · throughput ${p.throughput.level}` : ""}`);
+  console.log(`  quality:     ${p.quality_rating ?? "?"} · messaging limit ${w.messaging_limit ?? "not returned"}${w.messaging_limit_source ? ` (${w.messaging_limit_source})` : ""}${p.throughput?.level ? ` · throughput ${p.throughput.level}` : ""}`);
   console.log(`  name:        ${p.name_status ?? "?"}${p.new_name_status && p.new_name_status !== "NONE" ? ` · pending "${p.new_display_name}" (${p.new_name_status})` : ""} · OBA ${yn(p.is_official_business_account)} · code verification ${p.code_verification_status ?? "?"}`);
   console.log(`  webhooks:    ${Array.isArray(w.subscribed_apps) ? (w.subscribed_apps.length ? w.subscribed_apps.join(", ") : "NO app subscribed") : w.subscribed_apps ?? "?"}`);
   if (w.waba && !w.waba.error) console.log(`  waba:        ${w.waba.name ?? ""} · review ${w.waba.account_review_status ?? "?"} · ${w.waba.ownership_type ?? ""}`);
-  console.log(`  ${w.healthy ? "✓ healthy" : `✗ ${w.problems.join("; ")}`}`);
+  console.log(`  ${w.healthy ? "✓ healthy" : `✗ ${w.problems.join("; ")}`}${w.notes?.length ? `  (info: ${w.notes.join("; ")})` : ""}`);
 }
 
 export async function health(orgId, opts = {}) {
@@ -236,6 +237,22 @@ export async function health(orgId, opts = {}) {
 
 export async function automations(orgId, opts = {}) {
   requireOrg(orgId);
+  // --set <type> --template <name> / --body k=v,… / --buttons k=v,…: repoint
+  // one type at a new template version or fix its param mapping.
+  if (opts.set) {
+    const parseMap = (v, flag) => { if (v === undefined) return undefined; if (v === "none" || v === "null") return null; const out = {}; for (const pair of String(v).split(",").map((s) => s.trim()).filter(Boolean)) { const i = pair.indexOf("="); if (i < 1) { console.error(`Error: ${flag} takes param1=full_name,param2=order_number (got "${pair}")`); process.exit(1); } out[pair.slice(0, i).trim()] = pair.slice(i + 1).trim(); } return out; };
+    const body = { action: "automations_set", organization_id: orgId, type: opts.set, template_name: opts.template, body_parameters: parseMap(opts.body, "--body"), button_parameters: parseMap(opts.buttons, "--buttons"), dry_run: !opts.commit };
+    if (body.template_name === undefined && body.body_parameters === undefined && body.button_parameters === undefined) { console.error("Error: with --set <type> pass --template <name>, --body k=v,… and/or --buttons k=v,… (\"none\" clears a mapping)."); process.exit(1); }
+    let resp;
+    try { resp = await http.post("org", body); } catch (e) { fail("Set failed", e); }
+    if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+    if (resp.unchanged) { console.log(`${opts.set}: nothing to change (template ${resp.current?.template_name ?? "none"}, mapping ${JSON.stringify(resp.current?.meta_parameter_mapping ?? null)}).`); return; }
+    console.log(`${resp.organization_name} · ${resp.type}:`);
+    for (const c of resp.changes) console.log(`  ${c}`);
+    if (resp.warning) console.log(`  ⚠ ${resp.warning}`);
+    console.log(resp.dry_run ? "\nDRY RUN — add --commit to write." : "\n✓ written (the next order event sends with these values).");
+    return;
+  }
   if (opts.enable || opts.disable) {
     const type = opts.enable || opts.disable;
     let resp;
@@ -257,6 +274,7 @@ export async function automations(orgId, opts = {}) {
     if (t.warning) console.log(`      ⚠ ${t.warning}`);
   }
   console.log(`\nflowiq org automations ${orgId} --enable <type> | --disable <type> [--commit]  (the whole feature: --enable/--disable with no type)`);
+  console.log(`flowiq org automations ${orgId} --set <type> --template <name> --body param1=full_name,param2=order_number --buttons param1=short_code [--commit]`);
 }
 
 export async function abandoned(orgId, opts = {}) {

package/src/commands/plans.js

@@ -230,6 +230,56 @@ export async function show(planId, opts = {}) {
   console.log(`\nChange status: flowiq plans status ${p.id} --to <status> [--comment "..."] [--commit]`);
 }
 
+// `flowiq plans create <org> --topic … --type utility|marketing --date YYYY-MM-DD [--time HH:MM] …`
+// Files a plan on the client's Planning board (the MCP submit_plan row). Staff
+// are exempt from the client lead time. Dry run unless --commit.
+export function parseButton(spec) {
+  // type:text[=value]  e.g. quick_reply:VIEW MORE · url:CLICK HERE=https://x · phone:Call us=+27… · copy_code:SAVE10
+  const m = /^(quick_reply|url|phone|copy_code):(.*)$/.exec(String(spec).trim());
+  if (!m) { console.error(`Error: --button must be type:text[=value] (got "${spec}"); types quick_reply | url | phone | copy_code`); process.exit(1); }
+  const [, type, rest] = m;
+  if (type === "copy_code") return { type, code: rest.trim() };
+  const eq = rest.indexOf("=");
+  const text = (eq >= 0 ? rest.slice(0, eq) : rest).trim();
+  const value = eq >= 0 ? rest.slice(eq + 1).trim() : "";
+  if (type === "url") return { type, text, url: value };
+  if (type === "phone") return { type, text, phone_number: value };
+  return { type, text };
+}
+
+export async function create(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId || "")) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  const buttons = (opts.button || []).map(parseButton);
+  for (const f of opts.reply || []) {
+    const i = f.indexOf("=");
+    if (i < 1) { console.error(`Error: --reply must be <button text>=<follow-up message> (got "${f}")`); process.exit(1); }
+    const b = buttons.find((x) => x.type === "quick_reply" && x.text.toLowerCase() === f.slice(0, i).trim().toLowerCase());
+    if (!b) { console.error(`Error: --reply names "${f.slice(0, i).trim()}" but no quick_reply button has that text`); process.exit(1); }
+    b.follow_up = f.slice(i + 1).trim();
+  }
+  const body = {
+    action: "create", organization_id: orgId, topic: opts.topic, type: opts.type, scheduled_date: opts.date, scheduled_time: opts.time,
+    product_focus: opts.product, audience: opts.audience, line_1: opts.line1, line_2: opts.line2, follow_up_message: opts.followUp, landing_page_url: opts.landing,
+    message: opts.message, buttons: buttons.length ? buttons : undefined, graphic_brief: opts.graphic, media_url: opts.media, save_as_draft: !!opts.draft, dry_run: !opts.commit,
+  };
+  let resp;
+  try { resp = await http.post("plans", body); }
+  catch (e) {
+    console.error(`Create failed: ${e.message}`);
+    for (const p of e.body?.problems || []) console.error(`  - ${p}`);
+    process.exit(1);
+  }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  console.log(`${resp.organization_name}: "${resp.topic}" (${resp.type}) · ${resp.send} · audience: ${resp.audience} · files as ${resp.files_as}`);
+  console.log(`  copy:    ${String(resp.copy).replace(/\n/g, "\n           ")}`);
+  if (resp.buttons?.length) console.log(`  buttons: ${resp.buttons.map((b) => `${b.type}:${b.text ?? b.code}${b.url ? `=${b.url}` : ""}`).join(" · ")}`);
+  if (resp.follow_ups && Object.keys(resp.follow_ups).length) console.log(`  follow-ups: ${JSON.stringify(resp.follow_ups)}`);
+  console.log(`  graphic: ${resp.graphic}`);
+  for (const n of resp.notes || []) console.log(`  ⚠ ${n}`);
+  if (resp.dry_run) { console.log("\nDRY RUN — nothing filed. Add --commit to file it on the Planning board."); return; }
+  console.log(`\n✓ filed plan ${resp.plan_id} (${resp.status}). ${resp.alert?.note ?? ""}\n  flowiq plans show ${resp.plan_id}`);
+}
+
 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\`).`);

package/src/commands/store-api.js

@@ -107,7 +107,7 @@ function banner(resp) {
 
   if (resp.truncated) {
     console.error(`⚠ TRUNCATED — ${resp.truncated_reason}. Not all records were returned.`);
-    console.error("  Narrow the query, or raise --max-pages and page through with the store's own cursor.");
+    console.error("  Narrow the query, trim records with --fields id,name,…, or raise --max-pages and page through with the store's own cursor.");
   }
   // Shopify's *Count fields return {count, precision}. `AT_LEAST` means the
   // number is a CAP (10,000), not an answer — and it is quiet enough to be read
@@ -213,6 +213,14 @@ async function send(payload, opts, sentQuery) {
 // shopify
 // ---------------------------------------------------------------------------
 
+// --fields id,name,… = the platform's own field-trim parameter (Shopify REST
+// `fields`, Woo `_fields`): the way past the 3.5 MB response cap on a fat
+// record type (Revive's 894 products stopped at 200 without it, 30 Sep 2026).
+export function withFields(query, fields, key) {
+  if (!fields) return query;
+  return { ...(query || {}), [key]: String(fields).split(",").map((s) => s.trim()).filter(Boolean).join(",") };
+}
+
 export async function shopifyGet(orgId, path, opts = {}) {
   requireOrg(orgId);
   await send({
@@ -220,7 +228,7 @@ export async function shopifyGet(orgId, path, opts = {}) {
     organization_id: orgId,
     mode: "rest",
     path,
-    query: opts.q || {},
+    query: withFields(opts.q, opts.fields, "fields"),
     all: !!opts.all,
     max_pages: opts.maxPages ? Number(opts.maxPages) : undefined,
     api_version: opts.apiVersion,
@@ -446,7 +454,7 @@ export async function wooGet(orgId, path, opts = {}) {
     mode: "rest",
     path,
     namespace: opts.namespace,
-    query: opts.q || {},
+    query: withFields(opts.q, opts.fields, "_fields"),
     all: !!opts.all,
     max_pages: opts.maxPages ? Number(opts.maxPages) : undefined,
   }, opts);

package/src/commands/tag.js

@@ -96,12 +96,23 @@ export async function field(orgId, opts = {}) {
   const keywords = splitList(opts.any || opts.all);
   if (!keywords) { console.error("Error: pass --any \"a,b\" (OR) or --all \"a,b\" (AND)."); process.exit(1); }
   if (opts.exact && opts.all) { console.error("Error: --exact matches whole values, so it is an OR over --any (drop --all)."); process.exit(1); }
+  // A list of phone numbers against whatsapp_id / phone_number is a whole-value
+  // match by nature. The substring RPC runs one ILIKE per keyword over every
+  // contact and timed out at 77 numbers on a 95k-contact org (Kiah, 30 Sep
+  // 2026: 8.2 s measured); the exact path is an indexed IN and is what
+  // everyone meant anyway, so it is chosen for a digit-only list.
+  let exact = !!opts.exact;
+  const field = opts.field || "order_history";
+  if (!exact && !opts.all && ["whatsapp_id", "phone_number"].includes(field) && keywords.every((k) => /^\d{8,15}$/.test(k))) {
+    exact = true;
+    console.error(`(whole-number match: ${keywords.length} number(s) against ${field}; the substring search would scan every contact. Pass --any with a partial number for a substring match.)`);
+  }
   const payload = {
-    mode: "field", organization_id: orgId, field_name: opts.field || "order_history",
-    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive, exact: !!opts.exact,
+    mode: "field", organization_id: orgId, field_name: field,
+    keywords, logic: opts.all ? "AND" : "OR", case_sensitive: !!opts.caseSensitive, exact,
   };
   await confirmLargeWrite(orgId, payload, opts, "Field search");
-  await runMatch(opts.exact ? "Exact field match" : "Field search", payload, opts);
+  await runMatch(exact ? "Exact field match" : "Field search", payload, opts);
 }
 
 async function readIds(csv, file) {

package/src/index.js

@@ -148,9 +148,20 @@ export function run(argv) {
     .option("--until <when>", "upper bound")
     .option("--sender-type <list>", "comma list, e.g. bot-whatsapp or user-whatsapp,user-web (default: conversation rows only)")
     .option("--include-templates", "also match template / broadcast payloads")
+    .option("--tool-calls", "search inside tool-call rows' request / response instead of message text (what a tool was asked and answered)")
     .option("--limit <n>", "max rows (default 200, max 1000)")
     .option("--json", "raw JSON (rows carry contact_id)")
     .action((orgId, text, opts) => messagesCmd.search(orgId, text, opts));
+  msgs.command("purge <organization_id>")
+    .description("DELETE messages org-wide by pattern: email subject regex, text, sender types, time window (5,000 a run). Dry run by default; --confirm asks you to type the org id")
+    .option("--subject-regex <re>", "case-insensitive regex on the email subject (more_data.subject), e.g. '^Automatic reply'")
+    .option("--text <substr>", "message text contains this")
+    .option("--sender-type <list>", "comma list, e.g. user-email")
+    .option("--since <when>", "only rows newer than this (30d | YYYY-MM-DD)")
+    .option("--before <when>", "only rows older than this")
+    .option("--confirm", "actually delete (typed confirmation follows)")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => messagesCmd.purge(orgId, opts));
   msgs.command("failures <organization_id>")
     .description("What failed to send and why (Meta error codes by reason / media / contact), plus sends Meta accepted and never confirmed")
     .option("--since <when>", "7d (default) | 24h | 30d | YYYY-MM-DD")
@@ -484,9 +495,13 @@ export function run(argv) {
     .option("--json", "raw JSON")
     .action((orgId, opts) => orgCmd.health(orgId, opts));
   org.command("automations <organization_id>")
-    .description("Automated order messages (automated_messages_config): each type, its template and whether that template is approved")
+    .description("Automated order messages (automated_messages_config): each type, its template and whether that template is approved; --set changes a type's template or mapping")
     .option("--enable [type]", "switch a type on (or the whole feature with no type); dry run unless --commit")
     .option("--disable [type]", "switch a type off (or the whole feature)")
+    .option("--set <type>", "change this type: with --template / --body / --buttons")
+    .option("--template <name>", "with --set: the template name to send (must exist in FlowIQ's templates; approval is checked and warned)")
+    .option("--body <map>", "with --set: body param mapping, param1=full_name,param2=order_number (\"none\" clears)")
+    .option("--buttons <map>", "with --set: button param mapping, param1=short_code (\"none\" clears)")
     .option("--commit", "write the change")
     .option("--json", "raw JSON")
     .action((orgId, opts) => orgCmd.automations(orgId, opts));
@@ -694,6 +709,27 @@ export function run(argv) {
     .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("create <organization_id>")
+    .description("File a plan on the client's Planning board (the MCP submit_plan row; staff are exempt from the client lead time). Dry run unless --commit")
+    .requiredOption("--topic <text>", "campaign name (under 120 chars)")
+    .requiredOption("--type <t>", "utility | marketing")
+    .requiredOption("--date <YYYY-MM-DD>", "send date (SAST)")
+    .option("--time <HH:MM>", "send time SAST (omit = any time that day)")
+    .option("--product <text>", "product or collection it is about")
+    .option("--audience <text>", "who it goes to, in words (omit = the whole opted-in list)")
+    .option("--line-1 <text>", "utility: first sentence after \"Hi [Name],\"")
+    .option("--line-2 <text>", "utility: second paragraph")
+    .option("--follow-up <text>", "utility: the message VIEW MORE sends")
+    .option("--landing <url>", "utility: the https:// page CLICK HERE opens")
+    .option("--message <text>", "marketing: the full first message (≤ 1,024 chars)")
+    .option("--button <spec>", "marketing button, repeatable: quick_reply:TEXT | url:TEXT=https://… | phone:TEXT=+27… | copy_code:CODE", (v, acc) => (acc || []).concat([v]), [])
+    .option("--reply <text=follow-up>", "marketing: the message a quick_reply button sends (repeatable)", (v, acc) => (acc || []).concat([v]), [])
+    .option("--graphic <brief>", "have Flowapt design the image: describe it")
+    .option("--media <url>", "use your own public https:// image or video instead")
+    .option("--draft", "save as a draft (nobody alerted) instead of filing for review")
+    .option("--commit", "file it")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => plansCmd.create(orgId, 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")
@@ -710,9 +746,29 @@ export function run(argv) {
     .option("--limit <n>", "max matches (default 20, max 100)").option("--json", "raw JSON")
     .action((orgId, opts) => contactsCmd.find(orgId, opts));
   contacts.command("show <contact_id>")
-    .description("One contact's record + inbox state (needs --org)")
-    .requiredOption("--org <organization_id>", "the contact's org").option("--json", "raw JSON")
+    .description("One contact's record + inbox state (the org is resolved from the id; --org to pin it)")
+    .option("--org <organization_id>", "the contact's org (optional since 0.12.0)").option("--json", "raw JSON")
     .action((contactId, opts) => contactsCmd.show(contactId, opts));
+  contacts.command("add <organization_id>")
+    .description("Create one contact by hand (a tester, a team member for a test send). Dry run unless --commit")
+    .requiredOption("--whatsapp-id <digits>", "the number with country code, e.g. 27637186304")
+    .option("--name <name>", "full_name")
+    .option("--email <email>", "email")
+    .option("--no-broadcast", "allow_broadcast false (default: true, like the inbox)")
+    .option("--ai-off", "bot_status false (default: on)")
+    .option("--tag <csv>", "tags to start with")
+    .option("--commit", "create it")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => contactsCmd.add(orgId, opts));
+  contacts.command("ai <on|off> <organization_id>")
+    .description("Switch the AI agent on or off for every contact on a tag (or an id list), writing the agent-on/off row each chat shows. Dry run unless --commit")
+    .option("--tag <tag>", "every contact carrying this tag")
+    .option("--contact <id>", "contact UUID (repeatable)", (v, acc) => (acc || []).concat([v]), [])
+    .option("--ids-file <path>", "file of contact UUIDs")
+    .option("--reason <text>", "noted on the agent-on/off row and the audit")
+    .option("--commit", "write bot_status + the marker rows")
+    .option("--json", "raw JSON")
+    .action((state, orgId, opts) => contactsCmd.ai(state, orgId, opts));
   contacts.command("census <organization_id>")
     .description("Archived chats that still carry unread messages or where the customer wrote last")
     .option("--json", "raw JSON")
@@ -908,6 +964,24 @@ export function run(argv) {
     .option("--timeout <ms>", "per-turn HTTP timeout")
     .option("--json", "print raw JSON results")
     .action((orgId, opts) => testCmd.qa(orgId, opts));
+  test.command("seed <organization_id>")
+    .description("Copy a real chat onto a NEW test contact (test_seed_*, tag test-contact, no broadcasts, AI off) to reproduce an agent or Coworker answer. Dry run unless --commit")
+    .requiredOption("--from <contact_id>", "the real contact whose thread is copied")
+    .option("--until <time>", "copy rows up to this SAST time, e.g. \"2026-10-01 09:08\" or an ISO time")
+    .option("--rows <n>", "newest rows to copy (default 60, max 500)")
+    .option("--name <name>", "the seeded contact's display name (default: \"<name> (seeded test)\")")
+    .option("--with-tools", "also copy tool-call rows")
+    .option("--copy-attributes", "copy the contact's attributes (dog name, weight, …)")
+    .option("--ai-on", "leave the agent ON for the seeded contact (default off)")
+    .option("--agent <id>", "scope to a specific agent (audit only)")
+    .option("--commit", "create it")
+    .option("--json", "raw JSON")
+    .action((orgId, opts) => testCmd.seed(orgId, opts));
+  test.command("unseed <organization_id> <contact_id>")
+    .description("DELETE a seeded test contact (test_seed_* only) and its copied rows")
+    .option("--confirm", "actually delete")
+    .option("--json", "raw JSON")
+    .action((orgId, contactId, opts) => testCmd.unseed(orgId, contactId, opts));
   test.command("clear <organization_id>")
     .description("Clear the test conversation (hide history via memory_cutoff)")
     .option("--agent <id>", "target a specific agent's test contact")
@@ -1267,6 +1341,12 @@ export function run(argv) {
     .description("Members with role, name, email, last sign-in; pending invitations")
     .option("--json", "raw JSON")
     .action((orgId, opts) => membersCmd.list(orgId, opts));
+  members.command("invite <organization_id> <email>")
+    .description("Invite someone who has NO account yet (an invitations row they accept at sign-up; FlowIQ sends no email)")
+    .option("--role <role>", "admin | member | viewer", "member")
+    .option("--dry-run", "show what would be written")
+    .option("--json", "raw JSON")
+    .action((orgId, email, opts) => membersCmd.invite(orgId, email, opts));
   members.command("add <organization_id> <email>")
     .description("Add an EXISTING account to the org (someone with no account must be invited from the app)")
     .option("--role <role>", "admin | member | viewer", "member")
@@ -1363,6 +1443,7 @@ export function run(argv) {
   shopify.command("get <organization_id> <path>")
     .description('GET any Shopify Admin REST endpoint, e.g. `get <org> orders.json --q status=any` (".json" optional)')
     .option("--q <k=v>", "query parameter (repeatable), e.g. --q status=any --q limit=250", storeApiCmd.collectQuery, {})
+    .option("--fields <csv>", "return only these fields per record (Shopify REST `fields`); the way past the 3.5 MB cap on big lists")
     .option("--all", "follow Link rel=next and return every page (bounded by --max-pages and a size/time cap)")
     .option("--max-pages <n>", "page limit when using --all (default 10, cap 50)")
     .option("--api-version <ver>", "Shopify Admin API version (default 2024-01)")
@@ -1398,6 +1479,7 @@ export function run(argv) {
   woo.command("get <organization_id> <path>")
     .description("GET any WooCommerce REST endpoint, e.g. `get <org> orders --q status=completed`")
     .option("--q <k=v>", "query parameter (repeatable), e.g. --q status=completed --q per_page=100", storeApiCmd.collectQuery, {})
+    .option("--fields <csv>", "return only these fields per record (Woo `_fields`), e.g. id,name,permalink,status; the way past the 3.5 MB cap on a big catalogue")
     .option("--namespace <ns>", "REST namespace (default wc/v3; also wc-analytics, wp/v2)")
     .option("--all", "page through every result (bounded by --max-pages and a size/time cap)")
     .option("--max-pages <n>", "page limit when using --all (default 10, cap 50)")