@flowapt/flowiq-cli 0.9.6 → 0.9.8

package/README.md

@@ -77,9 +77,13 @@ Round-trips an org's active WhatsApp agent's system prompt
 flowiq prompts pull <organization_id>
 # edit ./.flowiq/prompts/<slug>.json — modify section titles/content
 flowiq prompts push <slug>
+flowiq prompts pull <organization_id> --out /tmp/check.json   # a scratch copy; the working file is untouched (0.9.8)
 ```
 
 Notes:
+- **A new section needs no id (0.9.8).** Add `{ "title": …, "content": … }` and push:
+  the CLI writes a fresh uuid into the local file first, says which sections got
+  one, then pushes, so the next pull keeps the same id.
 - `system_prompt` is regenerated server-side from `prompt_sections` on
   push using the `## SECTION: <title>` format.
 - Sections support optional `hidden: boolean` + `channels: string[]` (`web`, `whatsapp`, `messenger`, `instagram`, `email`; empty = every channel)
@@ -348,12 +352,17 @@ flowiq bc route <org_id> <broadcastId> --clear --commit                  # switc
   the **full broadcastId** per row + template, status, recipient count and SAST
   created time — the discovery step `status` / `retry` need (previously the id
   existed only in the send output or the DB). `--limit <n>` (default 25, max 200),
-  `--template <substr>` (case-insensitive contains), `--since <date>`, `--json`.
-  Read-only. NOTE: plain `bc list` (no org) still lists your **local campaign
+  `--template <substr>` (case-insensitive contains), `--since <date>`,
+  `--min-recipients <n>` (0.9.8: `2` hides one-recipient traffic like popup welcomes
+  and cart reminders, which otherwise fill the cap and hide campaign sends), `--json`.
+  When more rows match than are shown it prints `N of M shown` and says so. Read-only. NOTE: plain `bc list` (no org) still lists your **local campaign
   files** — the remote verb is named after `pinboard list-remote`.
 - **`status <org> <broadcastId>` (v0.3.5)**: live delivery **funnel** for a
   broadcast by its id — `accepted` → `delivered` → `read`, plus `pending` and
-  `failed`, with percentages, from `helpdesk_messages`. Built for the `--python`
+  `failed`, with percentages, from `helpdesk_messages`. Since 0.9.8 it also prints
+  what the send said (`sent with:` header / body / button slot values) and, for a
+  button short code, the link's destination with its UTM tags and click count
+  (`payload` in `--json`). Built for the `--python`
   fire-and-forget engine (which returns a `broadcastId` but has no CLI status
   log), but works for any broadcast id (dashboard sends included).
   **`--failures` (v0.3.7)** additionally lists each failed recipient + the Meta
@@ -654,6 +663,14 @@ flowiq doctor --json   # same, machine-readable; exits 1 when something needs fi
   ✓ server     contract 0.6.8 or newer · build 1f0fd48c
 ```
 
+**A Vercel security checkpoint is named as one (0.9.8).** When Vercel's bot
+protection challenges this network, every command (and `doctor`) now says so:
+"Vercel is challenging this network… not your key". Wait a few minutes or switch
+network; do not re-login and do not narrow the request. Only a JSON 401/403 from
+the API means the key itself was refused. A timeout on a WRITE now says the server
+may have finished it (check before retrying); `templates create` names the exact
+`templates status --live` command to check with.
+
 **Three ways this install tells you it is stale**, so nobody — person or AI
 assistant — has to remember to check:
 
@@ -745,6 +762,12 @@ Spring Promotion is **`9Sep_SpringPromotion`**.
 
 - The resolved tag is **printed before anything is minted**, and `shorten` is
   dry-run by default, so you always see it first.
+- **A running campaign never forks (0.9.8).** Before minting, the org's tags from
+  the last 120 days are checked: when one normalises to the same tag but is
+  spelled differently (`5Sept_BraaiDayOffer` running, you asked for
+  `5Sep_BraaiDayOffer`), the dry run prints `⚠ CAMPAIGN FORK` and `--commit` is
+  refused. Reuse the running tag with `--campaign 5Sept_BraaiDayOffer --raw-campaign`,
+  or pass `--new-campaign` when it really is a separate campaign.
 - `--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
@@ -797,6 +820,17 @@ flowiq kw push <slug>                    # id-keyed upsert (never touches keywor
 flowiq kw push <slug> --prune            # ALSO deletes DB keywords missing from the file (dry-run first!)
 ```
 
+- **Runtime order and collisions (0.9.8).** `kw pull` lists ACTIVE rows in the
+  order the runtime tries them (by `type`, first match answers), then the inactive
+  ones, and prints `⚠ TRIGGER COLLISION` when two active rows match the same
+  message: which row wins, and whether `allowed_tags` lets the other one answer
+  some contacts. `kw push` warns the same way (a dry run predicts the order).
+- **Schedule labels.** The keyword-scheduler cron switches `active` on at
+  `start_date` and off at `end_date` (every 30 min); the runtime reads `active`
+  only. So `kw pull` shows `starts … SAST` on a scheduled inactive row, and a loud
+  `⚠ LIVE BEFORE ITS START` on an active row whose start is still ahead (it is
+  answering now), or `⚠ PAST ITS END` on one not yet switched off.
+
 - **Identity = the `id`s.** Keep an id to update that row; drop the id to
   create a new one; remove an *action* from a kept keyword to delete it.
   A file id that doesn't exist for the org aborts (stale file → re-pull).
@@ -915,7 +949,11 @@ flowiq audit show <audit_id> --out entry.json       # dump the whole entry
 ```
 
 Filters: `--endpoint --action --status --agent --target --user --since --until
---limit` (default 50, max 200) `--json`.
+--before --limit` (default 50, max 200) `--json`. `--since` / `--until` take a date
+(SAST day start), an ISO time, or a window like `2d` / `12h` / `2w` (0.9.8). A
+`--limit` above 200 is clamped (it used to fall back to 50 silently); when more
+entries match than are shown, the header reads `200 of 1,044 matching entries`
+and the footer prints the `--before <created_at>` that pages further back.
 
 **What gets logged.** Every command that CHANGES something writes a row —
 including two that were missed until 4 Aug 2026 and are now covered:
@@ -1273,10 +1311,13 @@ flowiq report deck pull <org_id> 2026-08                   # → ./.flowiq/repor
   predates the current build logic, unless it is approved, sent or held).
 - Send fees are estimated at the category each template had on its send day. A send whose category
   cannot be known shows no fee and is left out of the broadcast return (`totals.unpriced_sends`).
-- `inputs.json` shape: `{ "changes": { "<update_id>": { "hidden": false, "tag": "client_raised|flowapt_shipped", "title": "…", "description": "…" } }, "changes_reviewed": true, "action_points": { "<title>": "done|in_progress|waiting_on_you|ongoing|dropped" }, "waiting_on_you": [{ "title": "…", "unlocks": "…" }], "recipients_confirmed": true }`.
+- `inputs.json` shape: `{ "changes": { "<update_id>": { "hidden": false, "tag": "client_raised|flowapt_shipped", "title": "…", "description": "…" } }, "changes_reviewed": true, "action_points": { "<title>": "done|in_progress|waiting_on_you|ongoing|dropped" }, "waiting_on_you": [{ "title": "…", "unlocks": "…" }], "recipients_confirmed": true, "hidden": { "tile:tail": true, "pill:new_contacts": true } }`.
+  `hidden` (29 Sep 2026) takes any tile, pill, card or block off the slides and the PDF for that month only: the keys are what the deck page's rail lists (`tile:…`, `pill:<metric>`, `card:…`, `block:…`, `box:…`, `strip:…`); a metric's pill hides everywhere that metric shows. The copy is not rewritten when something is hidden.
   Free text (milestone, the four plan fields) is edited in the app; it is stored as overrides that survive `narrate`.
 - `send --client` needs an approved deck AND `report.email.recipients` in the org's reporting config (Control center → Report delivery); it marks the deck `sent`. `--test-to` never changes status. Fees on the slides are the org's actual Meta billing when the token can read it, otherwise the rate-card estimate, and the footnote says which.
 - Non-store orgs need `config.deck.outcome` (`source: handover | ticket_status | tag | keyword`, labels) — the revenue slides become outcome slides. Every verb except `status` and `pull` is audited.
+- A month with a Customer Insights report gets the "What your customers asked" slide after slide 7 (29 Sep 2026): `build` takes the one `org_insights` export-insights row whose window covers the most of the month (top questions, trending topics, complaints or product mentions, sentiment, each as "N customers"), stores it under `deck.insights`, and the copy carries `insights_title` + `insights_read`. `status --json` shows the window under `insights` (null = no report, no slide). The timing slide's next-step card is now written by the narrator (`next_step_title` / `next_step_body`) against next month's South African retail calendar (public holidays, Mother's / Father's Day, Black Friday, payday, month-end) and edited in place like every other block.
+- Cart funnel and buckets (29 Sep 2026): "messaged" counts reminders WhatsApp reports delivered (the old send-request count rides along as `messaged_requested`); a Woo cart reminder now matches its order, so Woo recoveries are no longer zero; our own cart link is a recovery, another tool's abandoned-cart email is not; on Woo an agent-built order is a conversation, not a campaign; chat-to-order counts buyers who chatted, any bucket. `status` refuses approval when the agent replied to nobody in the month (no live channel).
 - Store orgs get slide 8, "Store health": cart abandonment (online checkouts started, bought, abandoned), first-time vs returning buyers and opt-in growth, each with a twelve-month strip and measured on the online store checkout only (till and other channels are named in the footer). `status --json` carries the headline figures under `store`; `config.deck.channel_labels {"<source_name>": "Label"}` renames a sales channel on the slide.
 
 ### Insights — `flowiq insights status|enable|disable|run` (v0.7.0)
@@ -1384,7 +1425,8 @@ create call, including the ones that failed and why.
 
 ```bash
 flowiq templates pull <organization_id>   # → ./.flowiq/templates/<slug>.json (Meta-side truth)
-flowiq templates status <organization_id> --name booking   # poll approval
+flowiq templates status <organization_id> --name booking   # FlowIQ's record (webhook-kept status)
+flowiq templates status <organization_id> --live --name booking --watch   # straight from Meta, re-checked every 15 s until decided (0.9.8)
 flowiq templates show <organization_id> heritage_day_v2    # render ONE row, drafts included
 flowiq templates create <organization_id> --request-file req.json
 flowiq templates attempts <organization_id> --failed       # why a submit was refused (v0.8.1)
@@ -1537,6 +1579,14 @@ Looking up stock for "1 litre Oil Pourer" — the calls being made:
 `stock` prints **"not tracked"** where Shopify returns `available: null` — that
 means no inventory record exists at that location, which is not the same as zero.
 
+**No exact title? It asks Shopify's product search (0.9.8).** The first call is an
+exact `products.json?title=`; when that finds nothing, the recipe runs Shopify's
+own product search over the WHOLE catalogue (it used to scan only the first 250
+products and then say "Nothing matched" on a 3,594-product store). Titles holding
+every word you typed are kept; if none do, Shopify's closest matches are shown and
+labelled as such. Search syntax passes through: `"sku:5702018068984"`,
+`"handle:up-scaled-darth-vader"`. Per-location levels cover the first 50 variants.
+
 #### Counting things — read `precision` before you trust a number
 
 Shopify's `*Count` fields return `{count, precision}`. **`precision: "AT_LEAST"`
@@ -1709,6 +1759,18 @@ flowiq agent config <organization_id> --model gpt-6-luna --reasoning-effort high
 flowiq agent config <organization_id> --model claude-sonnet-5 --reasoning-effort medium   # Claude (needs the org's Claude key; warns if missing)
 flowiq agent config <organization_id> --disable-base-tool get_product_info
 flowiq agent config <organization_id> --enable-base-tool get_product_info
+# 0.9.8: the fields that used to need SQL
+flowiq agent config <org> --tool-instruction send_whatsapp_message=@rules.txt   # appended to that tool's description ("tool=" removes)
+flowiq agent config <org> --shorten-links web=on --shorten-links whatsapp=default
+flowiq agent config <org> --email-from-name "Litehouse Support" --email-signature-name "Laia (AI)" --email-signature-title "Customer care"
+flowiq agent config <org> --email-request-to a@shop.co.za,b@shop.co.za --tool email_request_tool=true
+flowiq agent config <org> --send-success-rule "image=Stay silent after your last image." --send-success-rule "document="
+flowiq agent config <org> --after-escalation "Tell the customer the team replies here; never repeat what you already sent."
+flowiq agent config <org> --knowledge enabled=true,match_count=8,min_similarity=0.3
+flowiq agent config <org> --human-notify @human-notify.json      # merged into human_notify; null deletes a key
+flowiq agent config <org> --order-notify '{"enabled":false}'
+flowiq agent config <org> --tool silent_option=true
+flowiq agent config <org> --full        # show mode without truncating long values (also --json)
 ```
 
 Settable: `settings.use_settings_prompt`, `settings.model`,
@@ -1717,10 +1779,26 @@ pairs with reasoning models like `gpt-5.6-luna`; `max` is GPT-6 and Claude only)
 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`, `email_request_tool`),
+`collapse_product_variants`, `email_request_tool`, `silent_option`),
 `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.
+(`settings.test_contact_number` / `settings.test_contact_name`). Since 0.9.8 also:
+
+| Flag | Stored in | Runtime reader |
+|---|---|---|
+| `--tool-instruction <tool>=<text\|@file>` (repeatable; `tool=` removes) | `settings.tool_instructions` | appended to that tool's description (`tool-instructions.ts`); a name with no such tool is skipped and logged |
+| `--shorten-links <channel>=on\|off\|default` (repeatable) | `disable_url_shortening` | channels whatsapp / web / messenger / instagram / tiktok / email / call; `default` = on for WhatsApp only |
+| `--email-from-name` / `--email-signature-name` / `--email-signature-title` (`""` clears) | `settings.email_*` | the From name and signature on the agent's email replies |
+| `--email-request-to a,b` (`""` clears) / `--email-request-subject-prefix` | `settings.email_request` | `email_request_to_team`; warns while `email_request_tool` is off |
+| `--send-success-rule <when>=<text\|@file>` (repeatable; `when=` removes) / `--send-success <bool>` | `send_message_success_instructions` | one rule per `when` (media / image / video / document / audio / text / always), appended to the send tool's "sent" reply |
+| `--after-escalation <text\|@file>` (`""` clears) | `human_notify.success_instructions` | the NEXT STEP appended to the handover tool's reply |
+| `--knowledge enabled=…,match_count=…,min_similarity=…` (`default` clears a key) | `knowledge_config` | `search_knowledge` (match_count 1-20, min_similarity 0-1) |
+| `--human-notify` / `--order-notify <json\|@file.json>` | `human_notify` / `order_notify` | top-level merge, `null` deletes a key; unknown keys and wrong types are refused |
+
+Show mode (no write flags) prints every one of these, collapses long values to one
+line (`--full` prints them whole, `--json` gives the raw response) and lists what
+is settable. Anything else is rejected; every change is reported before → after.
+Not settable here: `additional_config` (use `flowiq knowledge`) and
+`additional_tools` (use `flowiq ct`).
 
 `--disable-base-tool` / `--enable-base-tool` can be repeated. They manage only the
 allowlisted discovery/commerce built-ins; opt-out, human handover and channel-send
@@ -1745,7 +1823,7 @@ addresses in `agents.settings.email_request.to`, from flowiq@flowapt.com with Re
 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.
+Library (Agents → Tool Library → Email Request to Team) or with `--email-request-to` (0.9.8).
 
 **`--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
@@ -1795,8 +1873,14 @@ flowiq au pull <organization_id> --before 20 --after 10 --no-files
 
 flowiq au resolve <update_id> --note "We updated the agent so it no longer …"
 flowiq au resolve <update_id> --status declined --internal "duplicate of …"
+flowiq au resolve <update_id> --status in_progress --note "Fixed; waiting to see it on a real order"   # 0.9.8
 ```
 
+- **`--status in_progress`** puts a ticket in progress without closing it: no
+  resolution stamp (an old one is cleared, as the app's reopen does), the note is
+  optional and an earlier client note is kept when you pass none. Use it when the
+  fix shipped but cannot be proven yet.
+
 - **`--note` is what the client reads** (rendered as `FlowIQ: <note>` in their
   console) and is **required** when resolving; `--internal` is staff-only.
 - The typical flow is `prompts push → flowiq test → au resolve` — resolve is
@@ -1859,6 +1943,54 @@ flowiq plans status <plan_id> --to sent --commit
 - Editing a plan's copy, buttons or links is not in the CLI yet; do that in
   the app.
 
+### CLI gaps + requests — `flowiq gaps report|list|show|hit|note|status` (alias `requests`) (v0.9.7)
+
+Found something the CLI cannot do, does wrong, or should do? File it here, from
+the terminal, the moment you hit it. This is the shared list of what the CLI
+is missing: anyone with a staff key can add to it, and so can a Claude session
+driving the CLI for you (it is marked `claude` automatically).
+
+```bash
+flowiq gaps report "agent config cannot set tool_instructions" --command "agent config" \
+  --error "error: unknown option '--tool-instruction'" --workaround "SQL on agents.settings" \
+  --detail "Needed to add a per-tool instruction for Clara's get_product_info" --org <uuid>
+flowiq gaps report "links shorten should take a readable --slug" --kind idea --command "links shorten"
+flowiq gaps report "…" --dry-run          # only check whether it is already on the list
+flowiq gaps list                          # open requests, most-hit first
+flowiq gaps list --command "bc" --status all --search slug
+flowiq gaps list --mine
+flowiq gaps show 12                       # detail, verbatim error, every hit / note / status change
+flowiq gaps hit 12 --note "same on Barkyn IT while copying the escalation config"
+flowiq gaps note 12 "also needs --agent"
+flowiq gaps status 12 --to done --version 0.9.8 --note "agent config --tool-instruction name=@file.txt"   # maintainers
+flowiq gaps status 14 --to duplicate --of 12                                                            # hits move to #12
+```
+
+- **`report`** takes a one-line title plus whatever context you have:
+  `--command` (the command it concerns, or the one you expected to exist),
+  `--kind gap|bug|idea` (default gap), `--error` (paste it verbatim),
+  `--workaround` (what you did instead), `--detail` / `--detail-file`, `--org`,
+  `--priority low|normal|high` (high = it blocked the job).
+- **Duplicates are caught before they are filed.** A report that closely
+  matches an OPEN request is refused and names it; add yourself to that one
+  with `hit` instead, or pass `--new` if yours is genuinely different.
+  `--dry-run` shows the similar requests and files nothing.
+- **`hit`** is "this bit me too": it adds your case and counts it. `list` is
+  ordered by hits, so the requests that cost the team most get built first.
+  `note` adds context without counting.
+- **`status`** (open / planned / in_progress / done / declined / duplicate) is
+  for the CLI maintainers (Matt and Gidon). You can withdraw your OWN request
+  with `--to declined` or `--to duplicate --of <n>`. `done` and `declined` need
+  `--note`: closing a request **emails everyone who reported or hit it** (from
+  FlowIQ (CLI), reply-to the person who closed it), with the version to update
+  to. `--no-notify` closes quietly.
+- **A command or flag that does not exist** now ends its error with the exact
+  `flowiq gaps report …` line to file it, `--command` and `--error` filled in.
+- **In the app:** the Changelog dialog has a **CLI requests** tab (super admins) showing the same list, filterable by status and kind, with each request's detail and history. It is read only; reporting and closing stay in the CLI.
+- Every report / hit / note / status change is audited
+  (`flowiq audit --endpoint gaps`). A report or hit from anyone but Matt also
+  emails him through the standing CLI-write alert.
+
 ### Chat export — `flowiq export chats <organization_id> [--out <path>]`
 
 Full chat history → TXT, byte-identical to the in-app "Export Settings TXT"
@@ -1903,6 +2035,16 @@ messages (`memory_cutoff`) AND sets aside the agent's remembered tool results
 (`more_data.tool_usage_history`, which the agent reads as TOOL USAGE HISTORY) under
 `more_data.tool_usage_history_cleared`, so a cleared test really starts fresh. Since 0.9.6;
 before that earlier tool results and escalation reasons leaked into "cleared" tests.
+`test clear` prints the PREVIOUS `memory_cutoff` so a clear can be undone (0.9.8).
+
+**Real-customer guard (0.9.8).** The configured test contact can be a real person
+(a client's reviewer, a dormant customer). When it had real (non-web) inbound in
+the last 6 h, `send`, `scenario`, `qa` and `clear` are refused with the latest
+message time; `--force` overrides. A test contact that has ever messaged on a real
+channel gets a warning on every run. Point the agent at a fake number with
+`flowiq agent config <org> --test-contact-number 27000000001`. A test contact the
+CLI creates is born with `allow_broadcast=false` and the `test-contact` tag, so it
+never lands on a broadcast list (stress contacts too).
 
 ### Guide — `flowiq guide`
 

package/TEAM-GUIDE.md

@@ -70,19 +70,25 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
    goes back to the agent you pulled — never "whatever is active now".
 5. Run the CLI from the repo root when you can — `./.flowiq/` is gitignored
    there.
+6. **Hit a wall? File it.** Whenever the CLI cannot do something and you (or
+   your Claude session) fell back to the dashboard, SQL or a script, file it:
+   `flowiq gaps report "<what you needed>" --command "<topic>" --error "<the
+   exact error>"`. Already on the list? `flowiq gaps hit <number> --note "…"`
+   instead. The most-hit requests get built first, and you are emailed when
+   yours ships. Tell your Claude session to do this too.
 
 ## Everyday tasks
 
 | I want to… | Run |
 |---|---|
-| Edit a client agent's system prompt | `flowiq prompts pull <org_id>` → edit the JSON → `flowiq prompts push <slug>` |
+| Edit a client agent's system prompt | `flowiq prompts pull <org_id>` → edit the JSON → `flowiq prompts push <slug>` (a new section needs no id; the push adds one) |
 | Edit the questionnaire answers | `flowiq q pull <org_id>` → edit → `flowiq q push <slug>` |
 | Edit fine-tuning instructions / Q&A | `flowiq ft pull <org_id>` → edit → `flowiq ft push <slug>` |
 | Edit the text knowledge sources (get_more_answers playbooks) | `flowiq kn pull <org_id>` → edit `sources[]` → `flowiq kn push <slug>` |
 | Edit the custom tools (API-call tools) | `flowiq ct pull <org_id>` → edit `tools[]` → `flowiq ct push <slug> --dry-run` → `flowiq ct push <slug>` |
 | Turn one custom tool on/off | `flowiq ct enable\|disable <org_id> <tool_name>` |
 | Give a custom tool a friendly name on the inbox tool-activity card | add `"display_name": "Checked loyalty points"` to that tool in `tools[]` → `flowiq ct push` (≤80 chars, never shown to the AI; empty = derived from the tool name) |
-| Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>` |
+| Edit keyword auto-replies (incl. competition entry keywords, add/remove-tag, set-agent and delay actions) | `flowiq kw pull <org_id>` → edit → `flowiq kw push <slug> --dry-run` → `flowiq kw push <slug>`. `kw pull` flags two active keywords answering the same word (and which one wins) and a keyword that is live before its start date |
 | Send a **different auto-reply depending on the contact** (e.g. "we already have your email" vs "send us your email") | add `"when": {"field":"email","op":"is_not_empty"}` to one action and `is_empty` to the other — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | Make a follow-up button **close the customer's ticket** ("Query solved") or **re-alert the team** ("I still need help") | keyword action `{"type":"update_ticket_status","status":"resolved"}` / `{"type":"renotify_ticket"}` — see *Keywords* in `flowiq guide --reference`. CLI-only, no dashboard field yet |
 | Make a keyword/button **hand the chat to a team or person** (assign in the inbox + email/WhatsApp them) | keyword action `{"type":"assign_chat","team_id":"…","assignee_user_id":"…","notify_member":true}` — see *Keywords* in `flowiq guide --reference`. Also in the dashboard (action type "Assign Chat") |
@@ -98,7 +104,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | See one client's broadcast plans | `flowiq plans list <org_id>` (open plans) or `flowiq plans list <org_id> --status all --since 2026-09-01` |
 | "What did clients submit today?" | `flowiq plans list --created-since 2026-09-22` (v0.9.1) — `--since` filters the SEND date, `--created-since` / `--touched-since` filter when the plan itself was created or last changed |
 | Mark a broadcast plan approved, scheduled or sent | `flowiq plans status <plan_id> --to sent` (a dry run), then add `--commit`. Rejecting needs `--comment "..."`, which the client reads |
-| What's the stock on a product, per branch? | `flowiq shopify stock <org_id> "olive oil"` — shows each location by NAME, and says "not tracked" rather than a confusing 0 |
+| What's the stock on a product, per branch? | `flowiq shopify stock <org_id> "olive oil"` — shows each location by NAME, and says "not tracked" rather than a confusing 0. Part of the title is enough (it searches the whole catalogue); `"sku:…"` works too |
 | Has this order shipped? What's the tracking? | `flowiq shopify order <org_id> '#14728'` — status, courier, tracking number + link |
 | **Size a customer cohort** | Use `customers(first:250, query:…)` and paginate — **NOT `customersCount(query:…)`, which Shopify ignores the filter on** and answers 10,000 every time. Any count showing `precision: AT_LEAST` is a cap, not a total; the CLI warns you. |
 | A big `--all` failed with a timeout | It's transient, not a limit — retry, or narrow it with `--max-pages` / a smaller `--q limit`. The message now says so. |
@@ -114,13 +120,22 @@ 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) |
+| Client wants leads/requests emailed to their team instead of a human escalation | `flowiq agent config <org_id> --tool email_request_tool=true --email-request-to a@shop.co.za,b@shop.co.za` |
+| Add extra rules to one tool (appended to its description) | `flowiq agent config <org_id> --tool-instruction send_whatsapp_message=@rules.txt` (`tool=` removes it) |
+| Turn link shortening on/off per channel | `flowiq agent config <org_id> --shorten-links web=on` (`off`, or `default` = on for WhatsApp only) |
+| Set the agent's email From name / signature | `flowiq agent config <org_id> --email-from-name "Shop Support" --email-signature-name "Laia (AI)" --email-signature-title "Customer care"` |
+| Tell the agent what to do right after it sends an image / after a handover | `flowiq agent config <org_id> --send-success-rule "image=…"` / `--after-escalation "…"` |
+| Knowledge search settings, human_notify / order_notify keys | `flowiq agent config <org_id> --knowledge enabled=true,match_count=8` · `--human-notify @file.json` · `--order-notify '{"enabled":false}'` (merged; `null` deletes a key) |
+| See EVERYTHING an agent is configured with | `flowiq agent config <org_id>` (`--full` for long values, `--json` raw) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
-| Start a test chat from scratch (agent forgets the earlier test messages AND its earlier tool results) | `flowiq test clear <org_id>` (or `flowiq test send <org_id> "…" --clear`) |
+| Start a test chat from scratch (agent forgets the earlier test messages AND its earlier tool results) | `flowiq test clear <org_id>` (or `flowiq test send <org_id> "…" --clear`). It prints the previous `memory_cutoff`, and refuses when the test contact is a real customer who wrote in the last 6 h (`--force` overrides; better: use a fake test number) |
 | **Tell the team what shipped** (the FlowIQ team update email) | `flowiq updates draft` → enrich the JSON (screenshots via `flowiq updates asset`, a *For the team* note per headline) → `flowiq updates preview <file> --open` → `flowiq updates send <file> --test` → `flowiq updates send <file> --yes` |
 | Can I use `flowiq updates`? | Yes: `status`, `uncovered`, `draft`, `preview` and `send --test` (a copy to yourself) work for everyone. Only the real `send --yes` to the whole team is Matt's; anyone else gets a 403 there |
 | Which changelog rows has nobody emailed the team about yet? | `flowiq updates status` / `flowiq updates uncovered` — anything left 20h+ goes out automatically at 08:30 SAST as a plain digest |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
+| **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 "…"` |
+| 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 --version 0.9.8 --note "what shipped"` — emails everyone who reported or hit it |
 > **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`.
@@ -156,7 +171,7 @@ 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 |
+| **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. If the campaign already runs under another spelling (`5Sept_…` vs `5Sep_…`) it refuses and tells you to reuse the running tag (`--raw-campaign`) or confirm with `--new-campaign` |
 | 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` |
@@ -183,19 +198,21 @@ several.
 | Send a broadcast whose link button should open a page on the store, tracked | Paste the real link: `flowiq bc send <org_id> --tag <batch-tag> --template <name> --button param1="https://shop.co.za/collections/spring?ref=ig"` (dry run shows `→ linklnk.io/<code>`, the campaign tag and anything replaced) → `… --commit` mints the code and sends. `--link-campaign "Spring Promotion"` names the tag (default: the template name); `--keep-link` sends your link untouched with no FlowIQ tags (clicks counted, the sale will not show as WhatsApp) |
 | Send a template with TWO link buttons (e.g. one per product) and track clicks per batch | Mint two short links per batch with the same campaign and a different `--content` (e.g. `--content CycleHarmony_b01` and `--content NeuroShyft_b01`), then `flowiq bc send <org_id> --tag <batch-tag> --template <name> --button param1=<first-code> --button param2=<second-code>`. `param1` is the first link button on the template, `param2` the second. The dry run prints both final URLs and stops if either is missing. Tag mode only (v0.7.5). |
 | Send via the SAME engine as the dashboard's "Python" toggle | add `--python` to a `bc send --tag …` (fire-and-forget; python resolves the tag + sends + tracks; no CLI resume for this engine). **Any tag send over 10 recipients uses python automatically.** |
-| Find a broadcast's id (don't have the `broadcastId`?) | `flowiq bc list-remote <org_id>` — the org's broadcasts newest-first with full ids (`--template <substr>` / `--since <date>` / `--limit <n>` to narrow) |
-| Check how a broadcast is landing (accepted → delivered → read, plus failed/pending) | `flowiq bc status <org_id> <broadcastId>` (from the send output, or `bc list-remote`) |
+| Find a broadcast's id (don't have the `broadcastId`?) | `flowiq bc list-remote <org_id>` — the org's broadcasts newest-first with full ids (`--template <substr>` / `--since <date>` / `--limit <n>` to narrow; `--min-recipients 2` hides welcomes and cart reminders) |
+| Check how a broadcast is landing (accepted → delivered → read, plus failed/pending) and what it said | `flowiq bc status <org_id> <broadcastId>` — also prints the slot values, the button code and the link's destination (UTM tag) |
 | See WHO failed on a broadcast + why (Meta error) | `flowiq bc status <org_id> <broadcastId> --failures` |
 | Re-send a broadcast to only the ones that failed | `flowiq bc retry <org_id> <broadcastId>` (dry-run) → `… --commit` |
 | Make EVERY reply to a broadcast land with a team or a person (client asks "all replies to the Spa team") | Add `--route-team "Spa"` (and/or `--route-member kim@client.com`) to the `bc send`. The first reply from each recipient within 72 hours (`--route-window 48h` to change) assigns the chat and notifies them, typed replies and button taps alike. The AI agent and keywords still answer as normal, so nothing is muted. The dry run shows `Replies → team Spa …`; a wrong team name stops the run and lists the org's teams. Works with `--csv` and `--at` too. |
 | Add, check or remove that routing on a broadcast that already went out | `flowiq bc route <org_id> <broadcastId>` shows it and how many chats it has routed · `… --team "Spa" --commit` sets it · `… --clear --commit` removes it. Only replies from now on are affected. |
 | **Get an OLD version of a prompt back** | `flowiq prompts history <org_id>` (pick the version) → `flowiq prompts restore <org_id> <audit_id>` (dry-run) → `… --commit` |
-| **See who changed what, and when** | `flowiq audit <org_id>` — add `--endpoint prompts`, `--user <name>`, `--since 2026-07-01` to narrow |
+| **See who changed what, and when** | `flowiq audit <org_id>` — add `--endpoint prompts`, `--user <name>`, `--since 2d` (or a date) to narrow; `N of M` in the header means there is more (`--before` pages back) |
 | See exactly what a change looked like (before → after) | `flowiq audit show <audit_id> --content` (or `--out entry.json`) |
 | Know what the log does and doesn't keep | Anything that CHANGES something is logged — including `flowiq test` (it creates the test contact and clears conversations) and `flowiq auth refresh`. Reads and dry-runs are not. The log never stores the content itself: chats, store data and agent replies are recorded as "who read what", never copied. |
 | 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>`. If it stops mid-way it says which page failed and nothing is written, so just re-run it (a 502/503/504 page retries on its own) |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
+| Is my new template approved yet? | `flowiq tpl status <org_id> --live --name <name> --watch` — straight from Meta every 15 s until decided, with the rejection reason. If a create timed out, run this before retrying (it may already exist) |
+| A command says "Vercel is challenging this network" | Not your key: wait a few minutes or switch network (hotspot). Don't log in again |
 | **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 |
 | **A template would not submit and you want to know why** | `flowiq tpl attempts <org_id> --failed` — the submission ledger. Every create call since 21 Sep 2026, from the dashboard or the CLI, with the reason a refused one was refused (e.g. `HEADER format is DOCUMENT but the media at file_url is video/mp4`). A failed submit writes no template row and never reaches Meta, so this is the ONLY place it shows |
@@ -205,6 +222,7 @@ several.
 | See EVERY client's open change requests at once | `flowiq au all` (grouped by org; `--since 14d`, `--priority urgent,high`, `--search <text>`, `--status all`, `--summary`, `--json`) |
 | See one client's pending change requests, with the chat around each | `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 |
+| Fix shipped but not provable yet | `flowiq au resolve <update_id> --status in_progress --note "…"` (stays open, no resolution stamp) |
 | 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` |
@@ -221,6 +239,7 @@ several.
 | Generate a client's monthly deck (metrics + copy) after the month has frozen | `flowiq report deck generate <org_id> 2026-08` — then review it at /reporting/deck |
 | See whether a client deck can be approved, and what is still missing | `flowiq report deck status <org_id> 2026-08` |
 | Send yourself a test copy of a client deck (PDF from flowiq@flowapt.com) | `flowiq report deck send <org_id> 2026-08 --test-to you@flowapt.com` — status untouched |
+| Take a tile, pill or card off a client deck (and its PDF) for one month | On `/reporting/deck` open **Inputs** (the rail beside the slides) → Show or hide; or `flowiq report deck inputs <org_id> 2026-08 --file inputs.json` with `{ "hidden": { "tile:tail": true } }` |
 | Approve a client deck / send it to the client | `flowiq report deck approve <org_id> 2026-08` then `… send … --client` (or let the 09:00 SAST schedule send it on the 5th) |
 | Re-read this guide / the full command reference | `flowiq guide` / `flowiq guide --reference` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "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/agent-config.test.mjs

@@ -0,0 +1,39 @@
+// node --test src/agent-config.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { splitPair, parseShorten, parseKnowledge, parseJsonObject, readValue } from "./commands/agent-config.js";
+
+test("splitPair keeps '=' inside the value", () => {
+  assert.deepEqual(splitPair("send_whatsapp_message=use a=b style", "x"), ["send_whatsapp_message", "use a=b style"]);
+  assert.deepEqual(splitPair("document=", "x"), ["document", ""]);
+});
+
+test("parseShorten maps on/off/default", () => {
+  assert.equal(parseShorten("on", "x"), true);
+  assert.equal(parseShorten("OFF", "x"), false);
+  assert.equal(parseShorten("default", "x"), null);
+});
+
+test("parseKnowledge types each pair and clears on default", () => {
+  assert.deepEqual(parseKnowledge("enabled=true, match_count=8,min_similarity=0.35"), { enabled: true, match_count: 8, min_similarity: 0.35 });
+  assert.deepEqual(parseKnowledge("min_similarity=default"), { min_similarity: null });
+});
+
+test("readValue reads @file and drops one trailing newline", () => {
+  const dir = mkdtempSync(join(tmpdir(), "flowiq-ac-"));
+  const f = join(dir, "t.txt");
+  writeFileSync(f, "line one\nline two\n");
+  assert.equal(readValue(`@${f}`, "x"), "line one\nline two");
+  assert.equal(readValue("plain text", "x"), "plain text");
+});
+
+test("parseJsonObject accepts inline JSON and @file", () => {
+  assert.deepEqual(parseJsonObject('{"enabled":false,"template_name":null}', "x"), { enabled: false, template_name: null });
+  const dir = mkdtempSync(join(tmpdir(), "flowiq-ac-"));
+  const f = join(dir, "hn.json");
+  writeFileSync(f, '{"whatsapp_ids":["27000000000"]}');
+  assert.deepEqual(parseJsonObject(`@${f}`, "x"), { whatsapp_ids: ["27000000000"] });
+});

package/src/batch-a.test.mjs

@@ -0,0 +1,36 @@
+// node --test src/batch-a.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mintSectionIds } from "./commands/prompts.js";
+import { scheduleLabel } from "./commands/keywords.js";
+import { describeError, isVercelChallenge } from "./http.js";
+
+test("mintSectionIds gives only id-less sections a uuid and names them", () => {
+  const secs = [{ id: "keep-me", title: "A", content: "" }, { title: "New one", content: "" }, { id: "  ", title: "Blank", content: "" }];
+  const touched = mintSectionIds(secs);
+  assert.deepEqual(touched, ["New one", "Blank"]);
+  assert.equal(secs[0].id, "keep-me");
+  assert.match(secs[1].id, /^[0-9a-f-]{36}$/);
+  assert.notEqual(secs[1].id, secs[2].id);
+});
+
+test("scheduleLabel flags an active row before its start and past its end", () => {
+  const now = Date.parse("2026-09-30T20:00:00Z");
+  assert.match(scheduleLabel({ active: true, start_date: "2026-09-30T22:00:00Z" }, now), /LIVE BEFORE ITS START/);
+  assert.match(scheduleLabel({ active: false, start_date: "2026-09-30T22:00:00Z" }, now), /starts 2026-10-01 00:00 SAST/);
+  assert.match(scheduleLabel({ active: true, end_date: "2026-09-29T10:00:00Z" }, now), /PAST ITS END/);
+  assert.equal(scheduleLabel({ active: true }, now), "");
+});
+
+test("describeError: HTML 'timeout' text is not a timeout; a POST timeout says check first", () => {
+  assert.doesNotMatch(describeError({ _raw: "<html>setTimeout(…) timed out</html>" }, "GET", "hours", 403, { json: false }), /TIMEOUT/);
+  assert.match(describeError({ error: "x" }, "POST", "meta-templates", 504), /may still have finished the write/);
+  assert.match(describeError({ error: "x" }, "GET", "store-api", 504), /--max-pages/);
+});
+
+test("isVercelChallenge reads the header or the checkpoint page", () => {
+  const h = (v) => ({ get: (k) => (k === "x-vercel-mitigated" ? v : null) });
+  assert.equal(isVercelChallenge(403, h("challenge"), ""), true);
+  assert.equal(isVercelChallenge(403, h(null), "<title>Vercel Security Checkpoint</title>"), true);
+  assert.equal(isVercelChallenge(403, h(null), '{"error":"Forbidden"}'), false);
+});