@flowapt/flowiq-cli 0.9.9 → 0.11.0

package/README.md

@@ -2046,6 +2046,215 @@ channel gets a warning on every run. Point the agent at a fake number with
 CLI creates is born with `allow_broadcast=false` and the `test-contact` tag, so it
 never lands on a broadcast list (stress contacts too).
 
+### Contacts — `flowiq contacts find|show|census|lint|merge|optout|optin|set|export` (0.10.0)
+
+The contact record from the terminal. `find` searches every contact of the org,
+archived and blocked included (the inbox hides archived chats on every tab but
+Archived), and prints the inbox state with each match.
+
+```bash
+flowiq contacts find <org> --email sofia@            # or --phone 3519 / --name "Sofia" / --id <uuid>
+flowiq contacts show <contact_id> --org <org>
+flowiq contacts census <org>                          # archived chats still carrying unread / customer-last messages
+flowiq contacts lint <org>                            # malformed numbers + the repair + whether a twin contact holds it
+flowiq contacts set <org> <contact_id> --whatsapp-id 27821234567 --commit
+flowiq contacts merge <org> <keep_id> <remove_id> --commit       # the app's merge_contacts_v2
+flowiq contacts optout <org> --contact <id> --reason "asked on 30 Sep" --commit
+flowiq contacts optin  <org> --ids-file ids.txt --commit --confirm
+flowiq contacts export <org> [--subscribers] [--out contacts.csv]
+```
+
+- **`find`** prints id, number, email, other channel identities, state
+  (archived / blocked / AI off / opted out / unread), team, assignee, the
+  latest message and any open ticket. Max 100 matches.
+- **`lint`** flags a doubled country code (`351351…`), a trunk 0 kept after the
+  code (`270…`), non-digits and bad lengths, with the suggested repair. When
+  another contact already holds the repaired number it names the twin and
+  prints the `merge` command instead. Test, stress and web-chat identities
+  are counted and skipped.
+- **`set`** changes one contact's WhatsApp number (and `phone_number` when it
+  was the same). Refused when another contact holds the number: merge instead.
+- **`merge`** is dry-run by default and shows both records with message and
+  order counts; `--commit` runs `merge_contacts_v2` (identities released, every
+  child row repointed, the losing contact deactivated, undo in the inbox).
+- **`optout` / `optin`** write `allow_broadcast` and the same inbox marker row
+  the app writes (`contact-opted-out` / `contact-opted-in`). Already-set
+  contacts are skipped so the count is honest. Opting someone back IN needs
+  `--confirm` on top of `--commit`.
+- **`export`** writes `.flowiq/contacts/<org>.csv` (Excel opens it). `--subscribers`
+  = opted in, not archived, not blocked.
+
+### Widgets — `flowiq widgets list|show|pull|push|embed|activate` (0.10.0)
+
+```bash
+flowiq widgets list <org>
+flowiq widgets pull <widget_id>            # → .flowiq/widgets/<org>-<id8>.json
+flowiq widgets push .flowiq/widgets/lego-ddb5ab43.json            # dry run: every field that would change
+flowiq widgets push … --commit
+flowiq widgets embed <org> [widget_id]     # the <script> snippet a client pastes
+flowiq widgets activate <widget_id>        # the widget an org-only embed resolves to
+```
+
+A push is an **id-keyed patch, never a full replace**: scalar columns are set,
+jsonb bags (`home_copy`, `home_design`, `launcher`, `team_avatars`, …) are
+merged at their top level and a key set to `null` is removed. These render on
+live storefronts, so the dry run prints each change before `--commit`. Avatar
+and icon uploads are not here yet (file upload with circle compositing).
+
+### Tickets — `flowiq tickets list|show|status` (0.10.0)
+
+```bash
+flowiq tickets list <org>                                  # open + in_progress, newest first
+flowiq tickets list <org> --older-than 48h --status open   # stale escalations
+flowiq tickets list <org> --contact <contact_id> --status all
+flowiq tickets show <ticket_id>
+flowiq tickets status <ticket_id> --set resolved --note "…" --commit
+```
+
+`status` writes what the app writes (`resolved_by/at`, `last_updated_*`, reopen
+fields, a `status_history` entry) and, when the org runs
+`reenable_bot_on_ticket_resolve`, switches the contact's AI back on with the
+inbox's three guards (open → closed transition, latest ticket only, bot not
+already on). Dry run by default.
+
+### Flows — `flowiq flows list|show|status|enable|disable` (0.10.0)
+
+```bash
+flowiq flows list <org>                       # trigger, templates, stats, param-key lint per flow
+flowiq flows show <flow_id>                   # full configuration
+flowiq flows status <org> --since 14d [--failed] [--flow <id>]   # execution funnel + verbatim error rollup
+flowiq flows enable <flow_id> --confirm       # arms real sends
+flowiq flows disable <flow_id>
+```
+
+The lint flags a `send_message` step whose `body_parameters` keys are not
+`param1..N` (`b1..b4`, `1,b1`, …): `bc send` refuses those shapes, the flow
+engine hands them to Meta where jsonb key order decides the slots.
+
+### Rules — `flowiq rules list|show|results|enable|disable` (0.10.0)
+
+The Automations rules engine (Shoppers → Rules, `custom_notification_rules`):
+the delayed-send engine behind tag-based, order-stage, webhook and
+Instagram-comment sends.
+
+```bash
+flowiq rules list <org> [--trigger tag_added]
+flowiq rules show <rule_id>
+flowiq rules results <rule_id> --since 30d    # what it queued: status counts, errors, recent sends
+flowiq rules enable <rule_id> --confirm
+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 (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
+flowiq org health <org>            # is the agent ready? master switch, keys (OpenAI probed), agent, catalogue + embeddings, store webhooks + order sync, traffic
+flowiq org automations <org>       # automated order messages, each type checked against the org's templates
+flowiq org automations <org> --enable order_shipped --commit     # or --disable; no type = the whole feature
+flowiq org abandoned <org>         # abandoned-cart recovery per sequence + the last 30 days of sends
+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". 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)
+
+```bash
+flowiq messages search <org> "flash sale" --since 24h [--sender-type bot-whatsapp] [--include-templates]
+flowiq messages failures <org> --since 7d
+flowiq messages stats <org> --since 6m
+```
+
+- **`search`** answers "did the agent say X to anyone today?" without knowing
+  the contact: time · sender · contact · the match in context. Template and
+  broadcast payloads are excluded unless `--include-templates`.
+- **`failures`** rolls up Meta-failed sends by error code, media type and
+  contact, and lists the sends Meta accepted (wamid) but never confirmed.
+  `messages pull` now ends with the same delivery footer.
+- **`stats`** is the monthly volume: inbound, outbound, free-form (sent inside
+  a customer's 24 h window, Meta's in-window charge from 1 Oct 2026) vs
+  template, bot vs human. The classifier lives in ONE RPC
+  (`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.
+
 ### Guide — `flowiq guide`
 
 Read the bundled docs in the terminal — no digging through node_modules.

package/TEAM-GUIDE.md

@@ -134,8 +134,33 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Which changelog rows has nobody emailed the team about yet? | `flowiq updates status` / `flowiq updates uncovered` — anything left 20h+ goes out automatically at 08:30 SAST as a plain digest |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
 | **The CLI can't do something I need** (or does it wrong, or should do more) | `flowiq gaps report "<command> cannot <thing>" --command "<command>" --error "<exact error>" --workaround "<what you did instead>"`. If it is already on the list you are told its number: `flowiq gaps hit <number> --note "…"` |
+| Find a customer the inbox cannot show (archived, blocked, wrong tab) | `flowiq contacts find <org_id> --email <part>` (or `--phone`, `--name`): every match with its state, team, latest message and open ticket |
+| A customer's number is wrong (country code doubled, leading 0 kept) | `flowiq contacts lint <org_id>` finds them with the repair; `flowiq contacts set <org_id> <contact_id> --whatsapp-id <number> --commit` fixes one; if a twin contact holds the number, `flowiq contacts merge <org_id> <keep> <remove> --commit` |
+| Opt a customer out of broadcasts (or back in) | `flowiq contacts optout <org_id> --contact <id> --reason "…" --commit` · back in: `flowiq contacts optin … --commit --confirm` |
+| Export the contact list for a client | `flowiq contacts export <org_id> --subscribers` → a CSV Excel opens |
+| Change a web chat widget's copy / colours, or get the embed code | `flowiq widgets pull <widget_id>` → edit → `flowiq widgets push <file>` (dry run) → `--commit` · `flowiq widgets embed <org_id>` |
+| Which escalations are still open, and close one | `flowiq tickets list <org_id> --older-than 48h` · `flowiq tickets status <ticket_id> --set resolved --note "…" --commit` |
+| 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` |
+| 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>` |
 | 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 |
 > **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.9.9",
+  "version": "0.11.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-cde.test.mjs

@@ -0,0 +1,73 @@
+// node --test src/batch-cde.test.mjs — pure helpers behind the 0.10.0 topics.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { toCsv } from "./commands/contacts.js";
+import { embedSnippet } from "./commands/widgets.js";
+import { snippetAround } from "./commands/messages.js";
+// The server modules build a Supabase client at import time; dummies keep the
+// pure helpers testable without a key on the machine.
+process.env.VITE_SUPABASE_URL ||= "https://example.supabase.co";
+process.env.SUPABASE_SERVICE_ROLE ||= "test-key";
+const { lintNumber } = await import("../../api/cli/contacts.js");
+const { buildUpdate } = await import("../../api/cli/widgets.js");
+const { lintParams, summariseFlow } = await import("../../api/cli/flows.js");
+const { describeSendAt } = await import("../../api/cli/rules.js");
+
+test("lintNumber catches the doubled country code and the kept trunk 0", () => {
+  assert.deepEqual(lintNumber("351351912345678"), { problem: "country code 351 doubled", suggested: "351912345678" });
+  assert.deepEqual(lintNumber("270821234567"), { problem: "trunk 0 kept after +27", suggested: "27821234567" });
+  assert.equal(lintNumber("27821234567"), null);
+  assert.equal(lintNumber("351912345678"), null);
+  assert.equal(lintNumber("447700900123"), null);
+  assert.equal(lintNumber("12125551234"), null);
+  assert.match(lintNumber("+27 82 123 4567").problem, /non-digit/);
+});
+
+test("toCsv quotes commas, quotes and newlines; arrays join with |", () => {
+  const csv = toCsv([{ a: 'He said "hi", ok', b: ["x", "y"], c: null }], ["a", "b", "c"]);
+  assert.equal(csv, 'a,b,c\n"He said ""hi"", ok",x|y,\n');
+});
+
+test("embedSnippet matches the app's snippet shape", () => {
+  const s = embedSnippet("org-1", "w-1");
+  assert.match(s, /widget\/loader\.js/);
+  assert.match(s, /data-organization-id="org-1"/);
+  assert.match(s, /data-widget-id="w-1"/);
+  assert.doesNotMatch(embedSnippet("org-1", null), /data-widget-id/);
+});
+
+test("snippetAround centres the match", () => {
+  const s = snippetAround("a".repeat(200) + " flash sale " + "b".repeat(200), "flash sale", 60);
+  assert.match(s, /^…a+ flash sale b+…$/);
+});
+
+test("buildUpdate patches scalars, merges jsonb bags and removes null keys", () => {
+  const cur = { name: "A", home_copy: { greeting: "Hi", tagline: "x" }, launcher: null };
+  const { update, changes, errors } = buildUpdate(cur, { name: "B", home_copy: { tagline: null, intro: "yo" }, launcher: { size: "lg" }, organization_id: "nope" });
+  assert.deepEqual(errors.map((e) => e.split(" ")[0]), ["organization_id"]);
+  assert.equal(update.name, "B");
+  assert.deepEqual(update.home_copy, { greeting: "Hi", intro: "yo" });
+  assert.deepEqual(update.launcher, { size: "lg" });
+  assert.deepEqual(changes.map((c) => c.field), ["name", "home_copy.tagline", "home_copy.intro", "launcher.size"]);
+  assert.deepEqual(buildUpdate(cur, { name: "A" }).changes, []);
+});
+
+test("lintParams accepts param1..N and flags anything else", () => {
+  assert.equal(lintParams({ param1: "a", param2: "b" }), null);
+  assert.match(lintParams({ b1: "a", b2: "b" }), /jsonb order/);
+  assert.match(lintParams({ param1: "a", param3: "b" }), /skip a slot/);
+  assert.equal(lintParams({}), null);
+});
+
+test("summariseFlow reads the trigger and the template steps", () => {
+  const f = summariseFlow({ id: "f", name: "n", enabled: true, configuration: { trigger: { type: "event", event: "subscription.renewed", source: "stitch" }, steps: [{ type: "action", action_type: "send_message", config: { template_name: "t_v1", body_parameters: { param1: "x" } } }] } });
+  assert.equal(f.trigger.event, "subscription.renewed");
+  assert.equal(f.steps[0].template_name, "t_v1");
+  assert.deepEqual(f.warnings, []);
+});
+
+test("describeSendAt reads delay, time, quiet hours", () => {
+  assert.equal(describeSendAt({ delay_minutes: 720, quiet_hours: { tz: "Europe/Madrid", start_hour: 10, end_hour: 20 } }), "+720min · quiet 10-20 Europe/Madrid");
+  assert.equal(describeSendAt({ delay_days: 3, send_at_time: "10:00", skip_weekends: true }), "+3d · at 10:00 · skip weekends");
+  assert.equal(describeSendAt(null), "immediately");
+});

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/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);
   }

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

@@ -1815,6 +1815,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}`);
   }