@flowapt/flowiq-cli 0.10.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
@@ -2148,7 +2158,7 @@ flowiq rules disable <rule_id>
 ### Org views — `flowiq org channels|whatsapp|health|automations|abandoned` (0.10.0)
 
 ```bash
-flowiq org channels <org>          # WhatsApp (provider, master switch), Messenger, Instagram, TikTok, email, Meta Ads, Zernio
+flowiq org channels <org>          # WhatsApp (provider, master switch), Messenger, Instagram, TikTok, email, Meta Ads (FlowIQ app or Zernio route), Zernio
 flowiq org channels --all          # census across every active org
 flowiq org whatsapp <org>          # the number's health straight from Meta: status, quality, tier, name status, webhook subscription
 flowiq org whatsapp --all          # every Meta org, unhealthy first
@@ -2160,7 +2170,13 @@ flowiq org abandoned <org> --disable 2 --commit
 ```
 
 `health` probes the org's OpenAI key with a one-token embedding, so an
-exhausted or invalid key shows as such rather than "present".
+exhausted or invalid key shows as such rather than "present". It probes the
+spare key (`feature_flags.spare_openai_key`) too: the agent, product search and
+both product syncs fall back to it, so a dead primary with a working spare is a
+`⚠` warning, not a problem (1 Oct 2026). The webhook count covers both hosts our
+Shopify webhooks use (`auth.flowiq.live` and the older `supabase.co`); before
+1 Oct 2026 it counted `supabase.co` only and read 0 on every org registered by
+`flowiq webhooks push`.
 
 ### Messages, org-wide — `flowiq messages search|failures|stats` (0.10.0)
 
@@ -2182,6 +2198,111 @@ flowiq messages stats <org> --since 6m
   (`cli_message_volume_summary`): template = broadcast_id, JSON payload, or no
   customer message in the preceding 24 h.
 
+### Members · users · steers · notes · products (0.11.0)
+
+Batch F of the request list. Three new topics, plus a long tail of verbs on
+existing ones (next section).
+
+```bash
+flowiq members list <org>                              # role · name · email · last sign-in · pending invitations
+flowiq members add <org> <email> --role member         # an EXISTING account (no account → invite from the app)
+flowiq members role <org> <email> admin|member|viewer  # the last admin cannot be demoted
+flowiq members rename <email> "Full Name"              # profiles.full_name, shown in every org
+flowiq members remove <org> <email> --confirm          # owner + last admin refused
+flowiq users lookup <email>                            # sign-in method, confirmation, last sign-in, every org + role
+flowiq steer list <contact_id> · steer add <contact_id> "Offer the 10% code" [--once] · steer clear <contact_id> [--id <id>] --confirm
+flowiq notes list <contact_id> · notes add <contact_id> "Vet to CS: …"
+flowiq products status <org> · products search <org> "whey protein" · products reconcile <org> --confirm
+```
+
+- **`steer`** is the inbox's supervisor instruction: vert injects every
+  unconsumed steer into the agent's history. An ongoing steer applies to EVERY
+  reply until it is deleted, and the inbox has no delete, which is why
+  `steer clear` exists (dry-run; the texts stay in the audit row).
+- **`products search`** calls the agent's own `fuzzy_match_products` RPC with
+  the agent's threshold (0.15), so "what does the agent find for X?" is answered
+  without a test send. `products status` counts rows with no embedding (the
+  agent cannot find those by meaning) and shows the last syncs; `reconcile`
+  queues the org on `products-reconcile-scheduler` (re-sync + re-embed).
+- **`members add` takes an existing account only.** Someone who has never
+  signed up goes through the app's invite flow (an invitation row + email);
+  the CLI says so rather than minting a login.
+
+### The 0.11.0 long tail (verbs added to existing topics)
+
+```bash
+flowiq links shorten <org> --url <u> --slug spring-sale --commit     # readable code; a taken slug falls back and says so
+flowiq links list <org> --code <code> | --to /collections/x | --all  # one code · by destination · every page (500 a call)
+flowiq links repoint <org> <code> --to <url> --commit                # move a live code (clicks + messages keep it)
+flowiq org list --number 27609751832                                 # the org behind a WhatsApp number / phone id / WABA
+flowiq org agent <org> on|off --commit [--yes]                       # the master switch; ON for everyone needs --yes
+flowiq org park <org> [--unpark] --confirm                           # organizations.inactive
+flowiq org flags set <org> product-tag-notes @notes.json             # {tag: sentence}; instagram_comments.* are objects now
+flowiq agent flags [--tool product_lookup] [--model luna]            # every active agent's model + tool gates
+flowiq tag ids <org> --ids-file ids.txt --tag vip --commit           # one tag on an explicit id list
+flowiq tag holders <org> vip [--all] [--csv]                         # who carries a tag
+flowiq tag field <org> --field whatsapp_id --any 27794975464 --exact # whole value, not a substring
+flowiq tag remove <org> vip --contacts a,b --confirm                 # only those contacts lose it
+flowiq prompts push <slug> --dry-run                                 # added / removed / changed sections, nothing written
+flowiq bc scheduled list <org> --detail                              # the queued send's body / button values + header
+flowiq templates show <org> <name>                                   # falls back to Meta when FlowIQ has no row
+flowiq templates attempts <org> --name x                             # + Meta's status / category history ("CATEGORY MOVED")
+flowiq test send <org> "hi" --tools --sender "Sofia"                # tool arguments + results; renames a synthetic test contact
+flowiq messages pull <contact_id>                                    # footer: sent by agent / broadcast / automation: <template>
+flowiq messages delete <contact_id> [--before 30d] [--sender-type tool-call] --confirm
+```
+
+- **`seg apply` sends one request per 4,000 ids** (the server already split its
+  DB calls; one request still timed out on 18k), and a failure names the chunk;
+  re-running is idempotent. **`seg plan --start-index N`** writes
+  `<slug>-from-NN.json` instead of overwriting the earlier plan (the record of
+  who got the earlier batches); an applied plan file is never overwritten.
+- **`bc send` audit rows and the `[CLI]` email now carry the audience** (python
+  reports no count on a real fire; the server counts the tag's broadcast-safe
+  contacts itself).
+- **`org agent`** is `organizations.wati_webhook_status`. Off = no customer gets
+  the AI. On with `vert.active false` + `vert.allowed_whatsapp_ids` = test mode.
+  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,12 +143,33 @@ 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, prompt, catalogue, webhooks, order sync, traffic) |
+| 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>` |
 | See what the team has asked the CLI to do | `flowiq gaps list` (open, most-hit first) · `flowiq gaps list --mine` · `flowiq gaps show <number>` · in the app: Changelog → **CLI requests** |
 | Close a request (Matt / Gidon) | `flowiq gaps status <number> --to done --fixed-in 0.9.8 --note "what shipped"` — emails everyone who reported or hit it |
+| Who is on a client's account, and give someone access | `flowiq members list <org_id>` · `flowiq members add <org_id> <email> --role member` (they must already have an account; otherwise invite from the app) · `flowiq members role <org_id> <email> admin` |
+| "I can't log in" / which orgs is this person on? | `flowiq users lookup <email>`: sign-in method, email confirmed or not, last sign-in, every org and role |
+| Tell the agent how to handle ONE customer, or stop an ongoing steer | `flowiq steer add <contact_id> "Offer the 10% code once"` (`--once` for the next reply only) · `flowiq steer list <contact_id>` · `flowiq steer clear <contact_id> --confirm` |
+| Leave a note for the team on a contact | `flowiq notes add <contact_id> "Vet to CS: …"` |
+| The agent cannot find a product the store has | `flowiq products search <org_id> "<what the customer typed>"` (the agent's own match) · `flowiq products status <org_id>` (rows with no embedding) · `flowiq products reconcile <org_id> --confirm` |
+| Which org owns this WhatsApp number? | `flowiq org list --number 27609751832` |
+| Switch an org's agent off (or on) for every customer | `flowiq org agent <org_id> off --commit` · back on: `flowiq org agent <org_id> on --commit --yes` (test mode first: `org flags set <org> vert.allowed_whatsapp_ids <numbers>` + `vert.active false`) |
+| A short link points at the wrong page | `flowiq links list <org_id> --code <code>` to see it · `flowiq links repoint <org_id> <code> --to <url> --commit` |
+| Check a prompt edit before it goes live | `flowiq prompts push <slug> --dry-run` — added / removed / changed sections against the live agent |
+| 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.10.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-f.test.mjs

@@ -0,0 +1,63 @@
+// node --test src/batch-f.test.mjs — pure helpers behind the 0.11.0 topics.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { diffSections } from "./commands/prompts.js";
+import { sentBy } from "./commands/messages.js";
+process.env.VITE_SUPABASE_URL ||= "https://example.supabase.co";
+process.env.SUPABASE_SERVICE_ROLE ||= "test-key";
+const reg = await import("../../api/_shared/feature-flag-registry.js");
+
+test("diffSections reports added / removed / changed by id and ignores untouched sections", () => {
+  const live = [
+    { id: "a", title: "Main", content: "hello" },
+    { id: "b", title: "Hours", content: "9-5", hidden: false },
+    { id: "c", title: "Old", content: "gone" },
+  ];
+  const local = [
+    { id: "a", title: "Main", content: "hello" },
+    { id: "b", title: "Hours", content: "9-6", hidden: true, channels: ["web"] },
+    { id: "d", title: "New", content: "x".repeat(12) },
+  ];
+  const d = diffSections(live, local);
+  assert.deepEqual(d.added, [{ title: "New", chars: 12 }]);
+  assert.deepEqual(d.removed, [{ title: "Old", chars: 4 }]);
+  assert.equal(d.changed.length, 1);
+  assert.equal(d.changed[0].title, "Hours");
+  assert.match(d.changed[0].what.join("; "), /content 3 → 3 chars; hidden false → true; channels "all" → \["web"\]/);
+  assert.equal(d.unchanged, false);
+  assert.equal(diffSections(live, live).unchanged, true);
+});
+
+test("diffSections notices a pure reorder", () => {
+  const live = [{ id: "a", title: "A", content: "1" }, { id: "b", title: "B", content: "2" }];
+  const d = diffSections(live, [live[1], live[0]]);
+  assert.equal(d.reordered, true);
+  assert.equal(d.unchanged, false);
+});
+
+test("sentBy labels broadcast, automation, rule and agent rows", () => {
+  assert.equal(sentBy({ broadcast_id: "x" }), "broadcast");
+  assert.equal(sentBy({ notification_template: "order_confirm_v1", notification_event: "orders/paid" }), "automation: order_confirm_v1 (orders/paid)");
+  assert.equal(sentBy({ notification_rule_id: "38f20704-aaaa-bbbb-cccc-dddddddddddd" }), "rule 38f20704");
+  assert.equal(sentBy({ sender_type: "bot-whatsapp" }), "agent");
+});
+
+test("product-tag-notes validator takes a {tag: sentence} map and refuses empties", () => {
+  const spec = reg.FLAG_REGISTRY["product-tag-notes"];
+  assert.deepEqual(reg.validateFlagValue(spec, '{"Free2024":" Ships free. "}'), { value: { Free2024: "Ships free." } });
+  assert.match(reg.validateFlagValue(spec, { Free2024: "" }).error, /non-empty sentence/);
+  assert.match(reg.validateFlagValue(spec, {}).error, /empty/);
+  assert.match(reg.validateFlagValue(spec, "true").error, /must be an object/);
+});
+
+test("instagram_comments legs are objects with a bounded message", () => {
+  const leg = reg.FLAG_REGISTRY["instagram_comments.private_reply"];
+  assert.equal(leg.type, "object");
+  assert.match(reg.validateFlagValue(leg, "true").error, /must be an object/);
+  assert.deepEqual(reg.validateFlagValue(leg, { enabled: true, message: " hi " }), { value: { enabled: true, message: "hi" } });
+  assert.match(reg.validateFlagValue(leg, { enabled: true }).error, /message is empty/);
+  assert.match(reg.validateFlagValue(leg, { enabled: true, message: "x".repeat(1001) }).error, /over 1000/);
+  const whole = reg.FLAG_REGISTRY["instagram_comments"];
+  assert.deepEqual(reg.validateFlagValue(whole, { enabled: true, ads_only: false, public_reply: { enabled: false } }), { value: { enabled: true, ads_only: false, public_reply: { enabled: false } } });
+  assert.match(reg.validateFlagValue(whole, { bogus: 1 }).error, /not a known key/);
+});

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

@@ -72,10 +72,22 @@ function checkExpectations(turn, replyText) {
   return results;
 }
 
-function printTurn(sc, t, userText, r, checks) {
+function printTurn(sc, t, userText, r, checks, opts = {}) {
   if (t === 0) console.log(`\n━━ ${sc.tq ? sc.tq + " · " : ""}${sc.title || sc.id} ━━`);
   console.log(`\n  🧑 ${userText}`);
   if (r.tool_calls?.length) console.log(`  ⚙  tools: ${r.tool_calls.join(", ")}`);
+  // --tools: what each tool was asked and what it answered (the tool-call rows
+  // vert writes). Without it a wrong answer could not be traced to the tool
+  // result that produced it.
+  if (opts.tools && r.tool_details?.length) {
+    for (const d of r.tool_details) {
+      console.log(`     ⚙ ${d.tool_name}${d.duration_ms != null ? ` (${d.duration_ms} ms)` : ""}${d.error ? `  ERROR ${d.error}` : ""}`);
+      if (d.request != null) console.log(`       in:  ${String(d.request).split("\n").join("\n            ")}`);
+      if (d.response != null) console.log(`       out: ${String(d.response).split("\n").join("\n            ")}`);
+    }
+  } else if (opts.tools && r.tool_calls?.length) {
+    console.log(`     (tool arguments / results are not stored for this org: switch on feature flag tool_logging, or the API predates 1 Oct 2026)`);
+  }
   if (r.reply) console.log(`  🤖 ${r.reply.split("\n").join("\n     ")}`);
   else console.log(`  ⚠  no reply — status=${r.status}${r.raw?.error ? " (" + r.raw.error + ")" : ""}`);
   for (const c of checks || []) {
@@ -103,7 +115,7 @@ export async function send(orgId, messageParts, opts = {}) {
   printWarnings(r);
   if (opts.clear && r.previous_memory_cutoff !== undefined) console.log(`# cleared first; previous memory_cutoff: ${r.previous_memory_cutoff ?? "(none)"}`);
   console.log(`# org=${r.org?.name} agent=${r.agent?.name}${r.agent?.is_active ? " (active)" : " (override)"} contact=${r.contact?.id}`);
-  printTurn({ title: "send", tq: "" }, 0, message, r, []);
+  printTurn({ title: "send", tq: "" }, 0, message, r, [], { tools: !!opts.tools });
 }
 
 async function runPack(orgId, pack, opts) {
@@ -128,7 +140,7 @@ async function runPack(orgId, pack, opts) {
       }
       const checks = checkExpectations(turn, r.reply);
       scResult.turns.push({ ...r, checks });
-      if (!opts.json) printTurn(sc, t, turn.text, r, checks);
+      if (!opts.json) printTurn(sc, t, turn.text, r, checks, { tools: !!opts.tools });
     }
     results.push(scResult);
   }
@@ -153,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/agents.js

@@ -32,6 +32,37 @@ export async function list(orgId, opts = {}) {
   console.log("\n★ = active agent. Pass any id as --agent <id> to prompts/questionnaires/fine-tuning/agent config.");
 }
 
+// `flowiq agent flags [--tool product_lookup] [--model x] [--all] [--json]` —
+// every active org's active agent: model, reasoning, prompt switch and the
+// tool gates, one row per org. Filters narrow to the orgs that matter.
+export async function flags(opts = {}) {
+  let resp;
+  try { resp = await http.get("agents", { census: "flags", all: opts.all ? "1" : undefined }); }
+  catch (e) { console.error(`Census failed: ${e.message}`); process.exit(1); }
+  let rows = resp.agents || [];
+  if (opts.tool) {
+    const [k, v] = String(opts.tool).split("=");
+    const want = v === undefined ? true : !["false", "0", "off", "no"].includes(v.toLowerCase());
+    rows = rows.filter((r) => !r.missing && (r.tools?.[k] === want || (want === false && r.tools?.[k] === undefined)));
+  }
+  if (opts.model) rows = rows.filter((r) => String(r.model || "").includes(opts.model));
+  if (opts.json) { console.log(JSON.stringify({ ...resp, count: rows.length, agents: rows }, null, 2)); return; }
+  const pad = (s, n) => String(s ?? "").padEnd(n);
+  const short = { product_lookup: "lookup", ticket_tool_status: "tickets", postal_code_tool_status: "postal", restock_tool: "restock", view_cart_tool: "cart", block_tool_status: "block", email_request_tool: "email-req", shopify_products_web_chat: "web-products", woo_order_build: "woo-order", woo_tip_field: "woo-tip", woo_order_note_field: "woo-note", collapse_product_variants: "collapse", silent_option: "silent" };
+  console.log(`${rows.length} active agent(s)${opts.tool ? ` with ${opts.tool}` : ""}${opts.model ? ` on model ~${opts.model}` : ""}`);
+  console.log("");
+  console.log(`  ${pad("ORG", 26)} ${pad("AGENT", 18)} ${pad("MODEL", 20)} ${pad("REASON", 7)} ${pad("PROMPT", 9)} ${pad("SW", 3)} TOOLS ON`);
+  for (const r of rows) {
+    if (r.missing) { console.log(`  ${pad(r.organization_name.slice(0, 26), 26)} ⚠ active_whatsapp_agent ${r.agent_id} does not exist`); continue; }
+    const on = Object.entries(r.tools || {}).filter(([, v]) => v).map(([k]) => short[k] || k);
+    if (r.discount) on.push("discount");
+    if (r.custom_tools) on.push(`${r.custom_tools} custom`);
+    if (r.disabled_base_tools?.length) on.push(`-${r.disabled_base_tools.join(",-")}`);
+    console.log(`  ${pad(r.organization_name.slice(0, 26), 26)} ${pad(String(r.agent_name || "").slice(0, 18), 18)} ${pad(r.model || "house", 20)} ${pad(r.reasoning_effort || "—", 7)} ${pad(`${r.prompt_chars.toLocaleString()}${r.use_settings_prompt ? "" : " OFF"}`, 9)} ${pad(r.master_switch ? "on" : "OFF", 3)} ${on.join(" ") || "—"}`);
+  }
+  console.log(`\n  SW = agent master switch · PROMPT = chars (OFF = use_settings_prompt false) · columns: ${(resp.tool_columns || []).map((k) => `${short[k] || k}=${k}`).join(", ")}`);
+}
+
 export async function create(orgId, opts = {}) {
   if (!UUID_RE.test(orgId)) {
     console.error(`Error: "${orgId}" is not a valid organization UUID.`);

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);
@@ -1815,6 +1825,15 @@ export async function scheduledList(orgId, opts = {}) {
     console.log(`    template ${s.template_name ?? "?"} → tag ${s.tag ?? "?"} · ${s.engine} · via ${s.source}${s.scheduled_by ? ` (${s.scheduled_by})` : ""}`);
     if (s.audience_at_schedule != null) console.log(`    ~${s.audience_at_schedule} recipients at schedule time`);
     if (s.reply_routing) console.log(`    replies → ${describeRouting(s.reply_routing)}`);
+    if (opts.detail) {
+      const bp = s.body_parameters && Object.keys(s.body_parameters).length ? s.body_parameters : null;
+      const bt = s.button_parameters && Object.keys(s.button_parameters).length ? s.button_parameters : null;
+      console.log(`    body:    ${bp ? Object.entries(bp).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join("  ") : "(no body values)"}`);
+      if (bt) console.log(`    buttons: ${Object.entries(bt).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join("  ")}`);
+      if (s.header_media) console.log(`    header:  ${typeof s.header_media === "string" ? s.header_media : JSON.stringify(s.header_media)}`);
+      if (s.card_overrides != null) console.log(`    cards:   ${s.card_overrides} card override(s)`);
+      if (!bp && !bt && !s.header_media && s.engine !== "python") console.log(`    (a node-engine row carries its values inside the request; --json shows them)`);
+    }
     if (s.processed_at) console.log(`    fired ${fmtSast(s.processed_at)} SAST${s.broadcast_id ? ` · broadcastId ${s.broadcast_id}` : ""}`);
     if (s.error_message) console.log(`    error: ${s.error_message}`);
   }

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 = {}) {