@flowapt/flowiq-cli 0.6.7 → 0.7.0

package/README.md

@@ -555,6 +555,70 @@ flowiq tag remove <org_id> vip,old-promo --confirm  # remove tag(s) from ALL con
   matches — re-run until `matched 0`. Idempotent and safe to re-run.
 - **Undo** any tag with `flowiq tag remove <org> <tag> --confirm`.
 
+### Staying current — `flowiq doctor` (v0.6.9)
+
+```bash
+flowiq doctor          # version vs npm, auth, and whether the server still supports this install
+flowiq doctor --json   # same, machine-readable; exits 1 when something needs fixing
+```
+
+```
+  ✓ version    0.6.9 (latest)
+  ✓ api        https://api.flowiq.live
+  ✓ auth       you@flowapt.com · super admin
+  ✓ server     contract 0.6.8 or newer · build 1f0fd48c
+```
+
+**Three ways this install tells you it is stale**, so nobody — person or AI
+assistant — has to remember to check:
+
+1. **npm nudge.** Any command prints, on stderr, when a newer version is
+   published:
+   `⬆ FLOWIQ CLI OUT OF DATE — installed X, latest Y / Run this before continuing: npm i -g @flowapt/flowiq-cli@latest`.
+   The registry is polled at most once a day by a detached child, so the hint
+   costs nothing on the hot path and appears on the next run after a release.
+2. **Server contract.** Every `api/cli/*` response carries
+   `X-Flowiq-Min-Version` — the oldest client the deployed server still
+   supports — and the CLI warns once per process when this install is below it.
+   This is the half npm cannot tell you: the registry knows what is *published*,
+   not whether the **server** still speaks your dialect. It is instant and
+   offline-safe, riding on a request you were making anyway.
+3. **`flowiq doctor`**, when you want to ask deliberately.
+
+⚠️ Until 9 Sep 2026 the npm nudge was also gated on `process.stderr.isTTY`, so
+it was invisible to exactly the audience that most needs it — an assistant
+running `flowiq` through a tool call gets a pipe, not a TTY. Teammates' AI
+sessions could run a months-old CLI forever without ever being told. Writing to
+stderr was already the whole safety property; the TTY gate bought nothing.
+
+**Bumping `MIN_CLI_VERSION`** (`api/cli/_auth.js`): only when a server change
+would MISBEHAVE on an older client — a removed or renamed response field, a
+changed request shape, a validation rule an old client cannot satisfy. Never for
+additive work; a new endpoint or an opt-in query param leaves old clients
+correct, and crying wolf trains people to ignore the warning.
+
+### Publishing (maintainers) — publish from a CLEAN checkout
+
+`npm publish` packs the **working tree**, not your branch. This repo's local
+tree is routinely dozens of commits behind `origin/main` with other sessions'
+work in it, so `cd cli && npm publish` from it ships a stale CLI under a version
+number you can never reuse. That has happened twice — **0.6.5** (8 Sep 2026) and
+**0.6.7** (9 Sep 2026) both shipped a local tree while the real work sat on
+`origin/main`.
+
+A `prepublishOnly` hook now refuses when `cli/` differs from `origin/main`:
+
+```bash
+# the safe recipe
+git clone https://github.com/MattFlowapt/flow-v1.git /tmp/pub
+cd /tmp/pub/cli && npm publish
+
+# or bring the local tree level first
+git checkout origin/main -- cli/ && cd cli && npm publish
+```
+
+`FLOWIQ_ALLOW_DIRTY_PUBLISH=1` overrides it, for a genuine emergency only.
+
 ### Links — `flowiq links shorten|list` (v0.4.8)
 
 Short links with campaign UTM tags — the terminal half of the in-app **URL
@@ -564,16 +628,53 @@ minted here is identical to one minted in the dialog.
 ```bash
 # Dry run FIRST — shows the exact destination each short link will carry
 flowiq links shorten <org> --url "https://shop.co.za/product/x" \
-  --campaign 13Aug_Seeds --content 13Aug_Seeds
+  --campaign "Spring Promotion"          # → utm_campaign=9Sep_SpringPromotion
 
 flowiq links shorten <org> --url "https://shop.co.za/product/x" \
   --url "https://shop.co.za/product/y" \
-  --campaign 13Aug_Seeds --content 13Aug_Seeds --domain linklnk.io --commit
+  --campaign "Spring Promotion" --content ViewMore --domain linklnk.io --commit
 
-flowiq links shorten <org> --file ./slide2.txt --campaign 13Aug_Seeds_VM --content 13Aug_Seeds_VM --commit
-flowiq links list <org> --campaign 13Aug_Seeds
+# a send going out later — give the send date, not today's
+flowiq links shorten <org> --file ./slide2.txt \
+  --campaign "Heritage Day" --date 2026-09-24 --commit
+
+flowiq links list <org> --campaign 9Sep_SpringPromotion
 ```
 
+#### Campaign naming — `Date_Campaign` (you do not have to type it) (v0.6.7)
+
+The house convention is **`Date_Campaign`**: the date the broadcast **goes out**
+(`9Sep` — no leading zero, three letters, `Sep` never `Sept`), an underscore,
+then the campaign title in PascalCase. A broadcast going out today for the
+Spring Promotion is **`9Sep_SpringPromotion`**.
+
+`--campaign` is normalised to it, so pass the campaign in plain words:
+
+| you type | you get |
+|---|---|
+| `--campaign "Spring Promotion"` | `9Sep_SpringPromotion` (today's date prefixed) |
+| `--campaign spring-promotion` | `9Sep_SpringPromotion` |
+| `--campaign 10JunFathersDay` | `10Jun_FathersDay` (underscore inserted) |
+| `--campaign 5Sept_BraaiDayOffer` | `5Sep_BraaiDayOffer` (`Sept` → `Sep`) |
+| `--campaign "Heritage Day" --date 24/9/2026` | `24Sep_HeritageDay` |
+
+- The resolved tag is **printed before anything is minted**, and `shorten` is
+  dry-run by default, so you always see it first.
+- `--date` takes `9Sep`, `2026-09-24` or `24/9/2026` — use it whenever the send
+  is not today.
+- `--content` is the **per-link** tag (which button, which product), so it gets
+  no date: `--content ViewMore`. Omit it and it defaults to the campaign.
+- `--raw-campaign` uses your string exactly as typed, for the rare tag that is
+  deliberately outside the convention.
+- **Not applied** to the agent's own auto-shortened links (minted server-side as
+  `ai_<org>` — a different namespace) or to `flowiq bc --campaign`, which names
+  the local `.flowiq/campaigns/<x>.json` file and the `bc-<x>` contact tag
+  rather than a UTM.
+
+Why it exists: of 1,042 distinct date-prefixed campaign tags minted in the 12
+months to 9 Sep 2026, only **27 (2.6%)** matched the convention — 924 fused the
+date onto the title (`10JunFathersDay`) and 5 wrote `Sept`.
+
 - **`utm_source=whatsapp` and `utm_medium=whatsapp_paid` are FIXED** (the dialog
   sets them too) — a link built any other way stops matching the attribution
   queries. You supply `--campaign` and `--content`, and they must be **supplied
@@ -982,17 +1083,92 @@ flowiq report deck pull <org_id> 2026-08                   # → ./.flowiq/repor
 - `send --client` needs an approved deck AND `report.email.recipients` in the org's reporting config (Control center → Report delivery); it marks the deck `sent`. `--test-to` never changes status. Fees on the slides are the org's actual Meta billing when the token can read it, otherwise the rate-card estimate, and the footnote says which.
 - Non-store orgs need `config.deck.outcome` (`source: handover | ticket_status | tag | keyword`, labels) — the revenue slides become outcome slides. Every verb except `status` and `pull` is audited.
 
-### WhatsApp templates — `flowiq templates pull|list|create|status` (alias `tpl`)
+### Insights — `flowiq insights status|enable|disable|run` (v0.7.0)
+
+The **Customer Insights Report** (the scheduled AI email: exec summary, top
+questions / complaints / topics, sentiment, product mentions — cron 72, 09:00
+SAST) per org. Reads and writes `feature_flags.export_insights` exactly the
+way the Insights Studio does, and fires a report the way the Profile tab's
+Run Now does.
 
-Read an org's live templates straight from Meta (read-only), and submit new
-ones through the `create-meta-template` edge function.
+```bash
+flowiq insights status                          # every org: STATE · CHATS30D · KEY · LAST REPORT · RCPT · SCHEDULES
+flowiq insights status --off --min-chats 20     # who is missing it and has real chat volume
+flowiq insights status <organization_id>        # one org + its last 10 reports
+
+flowiq insights enable <organization_id> --weekly monday --recipient client@example.com --recipient matt@flowapt.com
+flowiq insights enable <organization_id> --daily --store-only --monthly last            # two schedules; dailies stored, not emailed
+flowiq insights enable <organization_id> --monthly 1 --report advanced                  # advanced engine (PDF + Studio config)
+flowiq insights enable <organization_id> --add-recipient kiah@flowapt.com               # edit recipients, keep the cadence
+flowiq insights enable <organization_id> --weekly friday --dry-run                      # show what would be written
+
+flowiq insights disable <organization_id>       # enabled=false; schedules + recipients kept
+
+flowiq insights run <organization_id> --period weekly --recipient matt@flowapt.com      # DRY RUN: engine, window, recipients, message count
+flowiq insights run <organization_id> --period weekly --recipient matt@flowapt.com --commit
+flowiq insights run <organization_id> --from 2026-09-01 --to 2026-09-07 --store-only --commit
+```
+
+- **`enable` composes the whole config** (`enabled` + `recipient_emails` +
+  `schedules[]`). Cadence flags (`--daily` / `--weekly [day]` / `--monthly [day]`)
+  REPLACE the schedules; none given keeps what exists, or applies the default
+  (weekly Monday, standard, emailed). `--report` and `--store-only` apply to the
+  cadence flags you pass. `--recipient` replaces the list; `--add-recipient` /
+  `--remove-recipient` edit it.
+- **It refuses the three ways an enabled org silently produces nothing**
+  (`--force` overrides): the org has **no OpenAI key** (both engines hard-require
+  `organizations.openai_api_key`); an emailing schedule with **no recipients**
+  (the engines would email a hardcoded fallback address); an **inactive** org.
+- **`status` shows schedules as the scheduler will actually run them.** An
+  enabled org with no schedules stored runs *daily standard* by default — it is
+  marked `(implicit)`; `enable` replaces that with an explicit schedule.
+- **`run` is a dry run by default** (it costs OpenAI tokens and can email a
+  client): it prints the engine, the window, who would get it and how many
+  customer messages are in the window, and refuses an empty window. `--commit`
+  fires it through python-render (fire-and-forget) and prints the job id; the
+  report shows under *Recent reports* in `status <org>` a few minutes later.
+- `--from` / `--to` are SAST calendar days. `--report` defaults to the org's
+  schedule for that period, else standard.
+- `enable` / `disable` / `run` are audited (`flowiq audit --endpoint insights`).
+
+### WhatsApp templates — `flowiq templates pull|list|show|create|status` (alias `tpl`)
+
+Read an org's live templates straight from Meta (read-only), render any single
+row **including an unsubmitted DRAFT**, and submit new ones through the
+`create-meta-template` edge function.
 
 ```bash
 flowiq templates pull <organization_id>   # → ./.flowiq/templates/<slug>.json (Meta-side truth)
-flowiq templates create <organization_id> --request-file req.json
 flowiq templates status <organization_id> --name booking   # poll approval
+flowiq templates show <organization_id> heritage_day_v2    # render ONE row, drafts included
+flowiq templates create <organization_id> --request-file req.json
 ```
 
+**`show` is the only way to read a DRAFT from the terminal (v0.6.7).** A draft
+never reaches Meta, so `templates pull` cannot see it and neither can the
+broadcast introspector — before this, reviewing one meant opening the dialog.
+`show` prints the body with its examples substituted (as the customer will read
+it), then every carousel card: media URL, source filename, whether the Meta
+asset handle is present, card body, and each button's resolved URL. `--raw`
+also prints the escaped body so invisible whitespace is visible; `--json` gives
+the row.
+
+It closes with **Checks** — cheap structural rules that Meta would otherwise
+catch only at review, or not at all until send:
+
+- body variables not sequential from `{{1}}`, or missing an example
+- a card URL button using anything but `{{1}}` (Meta numbers each card's
+  parameters per card, so `{{2}}` on a card breaks that card's link at send)
+- more than one variable in a card URL (Meta supports exactly one)
+- a bold/italic/strikethrough marker sitting against a space, which WhatsApp
+  does not render — the customer sees the literal `_` or `*`
+- carousel outside 2–10 cards, cards that do not share one shape, missing media,
+  body/card text over Meta's 1024 / 160 limits
+
+Checks are structural only. They cannot tell you a card names a product your
+store does not sell — `show` renders the text so you can read it against the
+shop.
+
 `req.json` holds `{ template_request, template_data?, media_header?, cards_media? }`.
 Media headers: pass `media_header.file_url` (a public URL) — the edge function
 uploads it to Meta server-side. Approval is async; re-`pull` for the
@@ -1146,7 +1322,7 @@ Notes:
   org, which endpoint or query, how many records. **The response body is never
   stored**; the log records what was asked, not the customer data that came back.
 
-### Org — `flowiq org create` / `flowiq org info <organization_id>`
+### Org — `flowiq org create` / `flowiq org info <organization_id>` / `flowiq org flags …`
 
 Create a brand-new organization, or look one up (read-only; raw store/Meta
 credentials are stripped server-side).
@@ -1173,6 +1349,46 @@ flowiq prompts pull <new_org_id>   # edit → push
 (No `agent config` step any more — since 29 Aug 2026 a new agent is born on the
 house default: `gpt-5.6-luna`, `reasoning_effort high`, `use_settings_prompt` ON.)
 
+#### Feature flags — `flowiq org flags show|list|set|unset|keys` (v0.7.0)
+
+The Settings → Profile switches (`organizations.feature_flags`) from the
+terminal. `show` reads one org, `list --key` is the cross-org census, `set` /
+`unset` write. Only keys the Profile tab manages can be set (server-side
+allowlist + type check); anything that looks like a credential is redacted on
+read and refused on write.
+
+```bash
+flowiq org flags show <organization_id>                    # every flag, by Settings section
+flowiq org flags list --key export_insights.enabled --off   # which orgs do NOT have it (--on / --present / --absent / --all)
+flowiq org flags list --key mcp_member_access.enabled --on
+
+flowiq org flags set <organization_id> mcp_member_access.enabled true
+flowiq org flags set <organization_id> wait_for_more_messages 5            # integer, 0-60
+flowiq org flags set <organization_id> UTM.excluded_campaign_keywords "test,internal"   # string[] (comma list or JSON)
+flowiq org flags set <organization_id> integrations_visible.instagram true # wildcard keys take one more segment
+flowiq org flags set <organization_id> vert.active true --yes              # dangerous keys need --yes
+flowiq org flags set <organization_id> export_insights @insights.json      # JSON from a file (prefer `flowiq insights enable`)
+
+flowiq org flags unset <organization_id> wait_for_more_messages --yes      # remove the key (= platform default); always --yes
+flowiq org flags keys                                                      # what is settable, with type + danger notes
+flowiq org flags keys --section "members"
+```
+
+- **Values:** `true`/`false`, a whole number, JSON (`'["a","b"]'` / `'{"enabled":true}'`),
+  `@file.json`, or a comma list for list keys. The server validates against the
+  registry — a boolean given `12` is a 400, not a corrupted flag.
+- **Dangerous keys** (the Profile tab's amber-warning switches: `vert.active`,
+  `ip_whitelist`, `follow_up.enabled`, `subscriptions_test_mode`,
+  `api_key_member_access.enabled`, `export_insights`, `wait_for_more_messages`, …)
+  are refused without `--yes`, with the reason printed.
+- **Writes are atomic per path** (the same `_jsonb_deep_set` the Profile tab
+  uses), so `set a.b` never clobbers `a.c` that someone else just changed.
+- **Every set/unset is audited** (`flowiq audit --endpoint org-flags`) and the
+  response prints before → after plus the exact undo command.
+- A key that is on the org but not in the registry is shown by `show` (and
+  `--json`) but cannot be set here — it is DB-only by design; add it to the
+  Profile tab first.
+
 ### Agents — `flowiq agent list|create <org>`
 
 List an org's agents (to discover ids) and create a new one.
@@ -1237,7 +1453,7 @@ pairs with reasoning models like `gpt-5.6-luna`), agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
 `shopify_products_web_chat`, `ticket_tool_status`, `product_lookup`,
-`collapse_product_variants`),
+`collapse_product_variants`, `email_request_tool`),
 `discount.enabled`, and the `flowiq test` contact
 (`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
 rejected; every change is reported before → after.
@@ -1258,6 +1474,15 @@ agent answers product questions with "I can't pull the live menu". Found on Ouma
 Bets Gebak (11 Aug 2026): 25 product rows, 0 embeddings, and an unfunded OpenAI
 account — enabling this flag restored product answers immediately.
 
+**`--tool email_request_tool=true` (added 9 Sep 2026).** Turns on the `email_request_to_team`
+tool: once the agent has a customer's name, email and/or phone, preferred contact
+method and what they need, it emails that (plus the last few messages) to the
+addresses in `agents.settings.email_request.to`, from flowiq@flowapt.com with Reply-To
+set to the customer, and leaves an internal note on the thread. No ticket, no bot-off,
+no staff WhatsApp — built for businesses that want requests in an inbox rather than a
+human escalation (GIB Financial Services). The recipient list is set in the Tool
+Library (Agents → Tool Library → Email Request to Team); the CLI cannot set it yet.
+
 **`--tool collapse_product_variants=true` (added 4 Aug 2026).** Not a tool toggle —
 it changes what `get_product_info` RETURNS. OFF (the default) the result cap counts
 **variant rows**, so on a catalogue with several packaging/size variants per product
@@ -1333,22 +1558,6 @@ flowiq test cleanup <organization_id> --confirm      # delete the stress contact
 `--agent <id>` targets a specific (non-active) agent. `test stress cleanup` is
 destructive and requires `--confirm`.
 
-**Scenario pack shape.** `{scenarios:[{id, title, turns:[{text, expect?, expectNot?}]}]}`.
-`expect` / `expectNot` are case-insensitive substring checks (informational —
-reported and summed, never a hard fail) and accept **either a single string or an
-array of strings**:
-
-```json
-{ "text": "What investment options do I have?",
-  "expect": "depend on your fund rules",
-  "expectNot": ["Destiny offers", "guaranteed return"] }
-```
-
-Before v0.6.7 a bare string was iterated character by character, so
-`"expect": "fund rules"` reported ten single-letter checks that all trivially
-passed — a wrong pass/fail signal that still looked like a real result. Write
-either form now.
-
 ### Guide — `flowiq guide`
 
 Read the bundled docs in the terminal — no digging through node_modules.

package/TEAM-GUIDE.md

@@ -101,11 +101,48 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Remove a conflicting built-in tool from one agent | `flowiq agent config <org_id> --disable-base-tool get_product_info` (repeatable; safety/delivery tools cannot be disabled) |
 | Agent says an in-stock product "isn't showing" | `flowiq agent config <org_id> --tool collapse_product_variants=true` — the search cap counts VARIANT rows until this is on |
 | Agent can't quote ANY price / "I can't pull the live menu" | `flowiq agent config <org_id> --tool product_lookup=true` — name-based fuzzy lookup that works without embeddings or a live OpenAI key (semantic `get_product_info` needs both) |
+| Client wants leads/requests emailed to their team instead of a human escalation | `flowiq agent config <org_id> --tool email_request_tool=true`, then set the recipient list in Agents → Tool Library → Email Request to Team (no CLI path for the addresses yet) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
-| Prove a batch of fixes actually landed, in one run | `flowiq test scenario <org_id> ./pack.json` — pack is `{scenarios:[{id,title,turns:[{text,expect?,expectNot?}]}]}`. `expect`/`expectNot` are case-insensitive substring checks and take **a single string OR an array**. (Before v0.6.7 a bare string was checked letter by letter, so it always "passed" — if you wrote packs on an older version, re-run them.) |
-| **Make short links for a campaign** (with UTM tracking) | `flowiq links shorten <org_id> --url "https://shop.co.za/product/x" --campaign 13Aug_Seeds --content 13Aug_Seeds` (dry run) → `… --commit`. `utm_source`/`utm_medium` are set for you; campaign + content must be given together |
-| Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign X --content X --commit` |
+> **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`.
+
+### Keeping the CLI current
+
+Run **`flowiq doctor`** any time you are unsure — it checks your version against
+npm, your login, and whether the server still supports your install, and tells
+you the exact command to fix anything wrong.
+
+You will usually not need to: the CLI now tells you itself. If a newer version
+is out, or if your install is older than the server supports, every command
+prints a line starting `⬆ FLOWIQ CLI …` with the fix:
+
+```bash
+npm i -g @flowapt/flowiq-cli@latest
+```
+
+That warning is printed for AI assistants too, not just people — so if you work
+with Claude in this repo, it will see it and can update for you.
+
+### Campaign naming — `Date_Campaign`
+
+Every campaign tag is **the date the broadcast goes out, then the campaign
+title**: a Spring Promotion going out on 9 September is `9Sep_SpringPromotion`.
+
+**You do not have to type it that way.** Pass `--campaign "Spring Promotion"`
+and the CLI builds the tag, prints it, and only mints once you add `--commit`.
+Use `--date` when the send is not today (`--date 24/9/2026`), and `--content`
+for a second link in the same send (`--content ViewMore`).
+
+Getting this right is what makes a campaign's clicks and revenue group together
+in reporting — a tag typed a different way each time splits one campaign into
+several.
+
+| **Make short links for a campaign** (with UTM tracking) | `flowiq links shorten <org_id> --url "https://shop.co.za/product/x" --campaign "Spring Promotion"` (dry run) → `… --commit`. **Just type the campaign in plain words** — the CLI names it for you as `9Sep_SpringPromotion` and prints it before minting. `utm_source`/`utm_medium` are set for you |
+| A campaign going out on a later date | Add `--date`: `--campaign "Heritage Day" --date 24/9/2026` → `24Sep_HeritageDay`. Without it you get today's date |
+| A second link in the same send (e.g. a VIEW MORE button) | Same `--campaign`, different `--content`: `--content ViewMore`. Content is the per-link tag and gets no date |
+| Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign "Spring Promotion" --commit` |
 | Check which links a campaign has, and their clicks | `flowiq links list <org_id> --campaign 13Aug_Seeds` |
 | A link already looks short (`linklnk.io/abc123`) — can I re-tag it? | No: paste the DESTINATION url instead. Re-shortening keeps the old campaign tag and splits the click count, so the CLI refuses it |
 | Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit`. **v0.6.0: the commit imports every row as a contact (tag `bc-<campaign>` + the row's values as attributes) and fires ONE python broadcast** — it returns in seconds with a `broadcastId`; python sends in the background. Check delivery with `bc status`, re-fire failures with `bc retry`. A campaign that already fired refuses a re-run (`--resend` deliberately resends to everyone tagged). |
@@ -135,12 +172,22 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON. Ask for more than exists (`--count 100`) and you get the entire history — it says "that is ALL of them" when there is nothing older |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
+| **Read a template you have not submitted yet (a DRAFT)** | `flowiq tpl show <org_id> <template_name>` — the ONLY way to see a draft from the terminal (`pull` reads Meta, and a draft never gets there). Renders the message as the customer will read it, every carousel card, and a **Checks** list of the things Meta would bounce it for |
+| Check a carousel before submitting it | `flowiq tpl show <org_id> <name>` and read **Checks**. It catches a card link using the wrong `{{n}}`, a missing greeting example, a bold/italic marker against a space (WhatsApp shows the literal `_`), wrong card counts and over-length text. It cannot know a card names a product you do not stock — read the card text against the shop yourself |
 | Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
 | Manage outbound messaging webhooks (incl. their auth) | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
 | Create a brand-new client org | `flowiq org create --name "Client Name"` → then `agent create` on the printed id |
 | See a client's pending change requests | `flowiq au pull <org_id>` |
 | Close a client's change request (after verifying the fix!) | `flowiq au resolve <update_id> --note "what changed"` — the client reads the note |
 | Check an org's platform + active agent | `flowiq org info <org_id>` |
+| **See every Settings → Profile switch on an org** | `flowiq org flags show <org_id>` (credentials are never shown) |
+| **Which orgs have a flag on / off** (insights, MCP member access, a debounce…) | `flowiq org flags list --key export_insights.enabled --off` · `--key mcp_member_access.enabled --on` |
+| Flip a Settings → Profile switch from the terminal | `flowiq org flags set <org_id> mcp_member_access.enabled true` — `flowiq org flags keys` lists what you can set; the risky ones ask for `--yes`; the reply prints the undo |
+| Set the agent's message debounce ("customer sends 3 fragments, agent replies 3 times") | `flowiq org flags set <org_id> wait_for_more_messages 5` (seconds, 0-60) |
+| **Who is missing the Customer Insights report?** | `flowiq insights status --off --min-chats 20` — KEY `NO` means the org has no OpenAI key and the report cannot run |
+| Switch the insights report on for a client | `flowiq insights enable <org_id> --weekly monday --recipient client@example.com --recipient you@flowapt.com` — it refuses if there is no OpenAI key or nobody to email |
+| Store insights daily without emailing anyone (build history first) | `flowiq insights enable <org_id> --daily --store-only` |
+| Send one insights report right now | `flowiq insights run <org_id> --period weekly --recipient you@flowapt.com` (dry run) → add `--commit` |
 | Work a Pin Board task | `flowiq pin list-remote open` → `pull` → edit → `push` |
 | Log hours you worked for a client (every package = 10h Flowapt work/month) | `flowiq hours log <org_id> --hours 1.5 --desc "what you did"` — plain language, the client sees it on their Client Console |
 | Check a client's package hours / the month across all clients | `flowiq hours list <org_id>` / `flowiq hours summary` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.6.7",
+  "version": "0.7.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": {
@@ -16,7 +16,9 @@
     "node": ">=18"
   },
   "scripts": {
-    "start": "node bin/flowiq.js"
+    "start": "node bin/flowiq.js",
+    "prepublishOnly": "node scripts/prepublish-check.mjs",
+    "test": "node --test src/*.test.mjs"
   },
   "dependencies": {
     "commander": "^12.1.0",

package/src/campaign-naming.js

@@ -0,0 +1,164 @@
+// Campaign / UTM naming convention — Date_Campaign  (Matt, 9 Sep 2026).
+// ====================================================================
+//   Date     = the physical date the broadcast GOES OUT, as `9Sep` (no
+//              leading zero, three-letter month, "Sep" never "Sept").
+//   Campaign = the broadcast title / campaign, PascalCase, no spaces.
+//   → `9Sep_SpringPromotion`
+//
+// Staff should not have to remember this, so the CLI resolves it for them:
+// `--campaign "Spring Promotion"` on a send going out today becomes
+// `9Sep_SpringPromotion`, and the resolved value is always PRINTED before a
+// --commit so it can be seen and overridden.
+//
+// Measured 9 Sep 2026, why this exists: of 1,042 distinct date-prefixed
+// campaign tags minted in 12 months, only 27 (2.6%) matched the convention —
+// 924 fused the date to the title (`10JunFathersDay`) and 5 wrote `Sept`.
+//
+// SCOPE: this is the UTM campaign tag on a STAFF-minted short link
+// (`flowiq links shorten`). It is deliberately NOT applied to:
+//   • agent auto-shortened links, tagged `ai_<org>` by api/_url-shorten-engine.js
+//     (5,337 `ai_flw`, 3,649 `ai_gf`, … — a different namespace, not a campaign)
+//   • `flowiq bc --campaign`, which names the LOCAL .flowiq/campaigns/<x>.json
+//     file and the `bc-<x>` contact tag, not a UTM.
+// `--raw-campaign` bypasses normalisation entirely when you genuinely need it.
+
+export const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+const MONTH_ALIASES = new Map([
+  ["sept", "Sep"], ["january", "Jan"], ["february", "Feb"], ["march", "Mar"],
+  ["april", "Apr"], ["june", "Jun"], ["july", "Jul"], ["august", "Aug"],
+  ["september", "Sep"], ["october", "Oct"], ["november", "Nov"], ["december", "Dec"],
+]);
+
+/** `9Sep` for the given Date (default: today, local time). */
+export function dateToken(d = new Date()) {
+  return `${d.getDate()}${MONTHS[d.getMonth()]}`;
+}
+
+/**
+ * Accepts `9Sep`, `09Sep`, `9Sept`, `9 September`, `2026-09-09`, `09/09/2026`.
+ * Returns a canonical `9Sep`, or null if it is not a date at all.
+ */
+export function parseDateToken(input) {
+  const raw = String(input ?? "").trim();
+  if (!raw) return null;
+  const iso = raw.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (iso) {
+    const m = Number(iso[2]);
+    if (m < 1 || m > 12) return null;
+    return `${Number(iso[3])}${MONTHS[m - 1]}`;
+  }
+  const slash = raw.match(/^(\d{1,2})[/](\d{1,2})[/](\d{2,4})$/); // D/M/YYYY (SA order)
+  if (slash) {
+    const m = Number(slash[2]);
+    if (m < 1 || m > 12) return null;
+    return `${Number(slash[1])}${MONTHS[m - 1]}`;
+  }
+  const dm = raw.match(/^(\d{1,2})\s*([A-Za-z]+)$/);
+  if (dm) {
+    const day = Number(dm[1]);
+    if (day < 1 || day > 31) return null;
+    const mon = canonicalMonth(dm[2]);
+    return mon ? `${day}${mon}` : null;
+  }
+  return null;
+}
+
+// Longest-first alternation, so `10JunFathersDay` splits as Jun|FathersDay and
+// not as the 9-letter non-month "JunFathers" (which a greedy [A-Za-z]{3,9} does,
+// silently leaving the whole tag title-side and prefixing TODAY's date on top).
+const MONTH_ALT = [...MONTH_ALIASES.keys(), ...MONTHS.map((m) => m.toLowerCase())]
+  .sort((a, b) => b.length - a.length)
+  .join("|");
+const LEAD_RE = new RegExp(`^(\\d{1,2})\\s*(${MONTH_ALT})([_\\-\\s]*)(.*)$`, "i");
+
+function canonicalMonth(word) {
+  const w = String(word || "").toLowerCase();
+  if (MONTH_ALIASES.has(w)) return MONTH_ALIASES.get(w);
+  const hit = MONTHS.find((m) => m.toLowerCase() === w);
+  return hit || null;
+}
+
+/** "Spring Promotion" / "spring-promotion" / "spring_promotion" → "SpringPromotion". */
+export function pascal(input) {
+  return String(input ?? "")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => (/^[A-Z0-9]+$/.test(w) ? w : w[0].toUpperCase() + w.slice(1)))
+    .join("");
+}
+
+export const CAMPAIGN_RE = /^\d{1,2}(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)_[A-Za-z0-9]+$/;
+
+export function isConforming(value) {
+  return CAMPAIGN_RE.test(String(value ?? ""));
+}
+
+/**
+ * Resolve whatever the operator typed into `Date_Campaign`.
+ *
+ * @param {string} input        what they passed to --campaign
+ * @param {object} [opts]
+ * @param {string} [opts.date]  --date override (any parseDateToken form)
+ * @param {Date}   [opts.now]   injectable clock (tests)
+ * @returns {{value:string, changed:boolean, notes:string[], error?:string}}
+ */
+export function resolveCampaign(input, opts = {}) {
+  const notes = [];
+  const original = String(input ?? "").trim();
+  if (!original) return { value: "", changed: false, notes, error: "campaign is empty" };
+
+  let overrideDate = null;
+  if (opts.date) {
+    overrideDate = parseDateToken(opts.date);
+    if (!overrideDate) {
+      return { value: original, changed: false, notes, error: `--date "${opts.date}" is not a date I understand (try 9Sep, 2026-09-09 or 9/9/2026)` };
+    }
+  }
+
+  // Split a leading date off the front, however it was written / fused.
+  let datePart = null;
+  let rest = original;
+  const lead = original.match(LEAD_RE);
+  if (lead) {
+    const mon = canonicalMonth(lead[2]);
+    if (mon) {
+      datePart = `${Number(lead[1])}${mon}`;
+      rest = lead[4];
+      if (lead[2] !== mon) notes.push(`month "${lead[2]}" → "${mon}"`);
+      if (!lead[3].includes("_")) notes.push("inserted the missing underscore after the date");
+    }
+  }
+
+  if (overrideDate) {
+    if (datePart && datePart !== overrideDate) notes.push(`date ${datePart} → ${overrideDate} (--date)`);
+    datePart = overrideDate;
+  }
+  if (!datePart) {
+    datePart = dateToken(opts.now || new Date());
+    notes.push(`prefixed today's send date "${datePart}"`);
+  }
+
+  const titlePart = pascal(rest);
+  if (!titlePart) {
+    return { value: original, changed: false, notes, error: `no campaign title found in "${original}" — expected something like "Spring Promotion"` };
+  }
+  if (titlePart !== rest) notes.push(`title "${rest}" → "${titlePart}"`);
+
+  const value = `${datePart}_${titlePart}`;
+  return { value, changed: value !== original, notes };
+}
+
+/** utm_content is per-LINK (which button / which product), so no date is imposed. */
+export function resolveContent(input) {
+  const original = String(input ?? "").trim();
+  if (!original) return { value: "", changed: false, notes: [] };
+  const value = pascal(original);
+  return {
+    value: value || original,
+    changed: !!value && value !== original,
+    notes: value && value !== original ? [`content "${original}" → "${value}"`] : [],
+  };
+}