@flowapt/flowiq-cli 0.9.7 → 0.9.9

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:
@@ -1387,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)
@@ -1540,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"`
@@ -1712,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`,
@@ -1720,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
@@ -1748,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
@@ -1798,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
@@ -1881,7 +1962,7 @@ 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 12 --to done --fixed-in 0.9.8 --note "agent config --tool-instruction name=@file.txt"   # maintainers
 flowiq gaps status 14 --to duplicate --of 12                                                            # hits move to #12
 ```
 
@@ -1905,6 +1986,7 @@ flowiq gaps status 14 --to duplicate --of 12
   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.
@@ -1953,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

@@ -81,14 +81,14 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 
 | 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") |
@@ -104,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. |
@@ -120,16 +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 "agent config cannot set tool_instructions" --command "agent config" --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>` |
-| 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 |
+| **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 --fixed-in 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`.
@@ -165,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` |
@@ -192,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 |
@@ -214,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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "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);
+});

package/src/commands/agent-config.js

@@ -1,8 +1,11 @@
 // `flowiq agent config <organization_id> [flags]` — the prompt-builder skill's
 // Step 5 as a staff-key call. Writes an allowlisted set of agent fields
-// (use_settings_prompt, model, tool flags, discount.enabled, rename) via
-// /cli/agent-config. With no write flags, prints the current config.
+// (use_settings_prompt, model, tool flags, discount.enabled, rename, tool
+// instructions, link shortening, email identity / request recipients, send
+// success rules, after-escalation text, knowledge search, human_notify /
+// order_notify) via /cli/agent-config. With no write flags, prints the current config.
 
+import { readFileSync } from "node:fs";
 import { http } from "../http.js";
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -29,10 +32,77 @@ export function collectToolName(val, acc) {
   return acc;
 }
 
-function printSnapshot(title, snap) {
+// "@path" reads the file; anything else is the literal text.
+export function readValue(v, label) {
+  if (typeof v !== "string" || !v.startsWith("@")) return v;
+  try {
+    return readFileSync(v.slice(1), "utf8").replace(/\r?\n$/, "");
+  } catch (e) {
+    console.error(`Error: ${label} could not read ${v.slice(1)}: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// "key=value" → [key, value]; the value may itself contain "=".
+export function splitPair(pair, label) {
+  const eq = pair.indexOf("=");
+  if (eq < 1) {
+    console.error(`Error: ${label} expects key=value (got "${pair}").`);
+    process.exit(1);
+  }
+  return [pair.slice(0, eq).trim(), pair.slice(eq + 1)];
+}
+
+export function parseShorten(v, label) {
+  const s = String(v).trim().toLowerCase();
+  if (["on", "true", "yes", "1"].includes(s)) return true;
+  if (["off", "false", "no", "0"].includes(s)) return false;
+  if (s === "default") return null;
+  console.error(`Error: ${label} must be on, off or default (got "${v}").`);
+  process.exit(1);
+}
+
+// --knowledge enabled=true,match_count=8,min_similarity=0.3 ("default" clears a key)
+export function parseKnowledge(v) {
+  const out = {};
+  for (const part of String(v).split(",").map((p) => p.trim()).filter(Boolean)) {
+    const [k, raw] = splitPair(part, "--knowledge");
+    const val = raw.trim();
+    if (val === "default" || val === "") out[k] = null;
+    else if (k === "enabled") out[k] = parseBool(val, "--knowledge enabled");
+    else if (!Number.isNaN(Number(val))) out[k] = Number(val);
+    else out[k] = val; // the server names the bad value
+  }
+  return out;
+}
+
+export function parseJsonObject(v, label) {
+  const text = readValue(v, label);
+  let obj;
+  try {
+    obj = JSON.parse(text);
+  } catch (e) {
+    console.error(`Error: ${label} must be a JSON object or @file.json (${e.message}).`);
+    process.exit(1);
+  }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    console.error(`Error: ${label} must be a JSON object (keys are merged; null deletes a key).`);
+    process.exit(1);
+  }
+  return obj;
+}
+
+function short(v, full) {
+  if (v === null || v === undefined) return "(unset)";
+  const s = String(v).replace(/\s+/g, " ");
+  if (full) return String(v);
+  return s.length <= 140 ? s : `${s.slice(0, 137)}… (${String(v).length} chars; --full shows all)`;
+}
+
+function printSnapshot(title, snap, full = false) {
   console.log(`  ${title}:`);
   for (const [k, v] of Object.entries(snap)) {
-    console.log(`    ${k.padEnd(30)} ${v === null ? "(unset)" : v}`);
+    console.log(`    ${k.padEnd(38)} ${short(v, full)}`);
   }
 }
 
@@ -60,6 +130,47 @@ export async function config(orgId, opts = {}) {
     };
   }
 
+  if (opts.toolInstruction?.length) {
+    body.tool_instructions = {};
+    for (const pair of opts.toolInstruction) {
+      const [tool, text] = splitPair(pair, "--tool-instruction");
+      body.tool_instructions[tool] = readValue(text, `--tool-instruction ${tool}`);
+    }
+  }
+  if (opts.shortenLinks?.length) {
+    body.url_shortening = {};
+    for (const pair of opts.shortenLinks) {
+      const [ch, v] = splitPair(pair, "--shorten-links");
+      body.url_shortening[ch] = parseShorten(v, `--shorten-links ${ch}`);
+    }
+  }
+  const identity = {};
+  if (opts.emailFromName !== undefined) identity.from_name = opts.emailFromName;
+  if (opts.emailSignatureName !== undefined) identity.signature_name = opts.emailSignatureName;
+  if (opts.emailSignatureTitle !== undefined) identity.signature_title = opts.emailSignatureTitle;
+  if (Object.keys(identity).length) body.email_identity = identity;
+  const emailRequest = {};
+  if (opts.emailRequestTo !== undefined) {
+    emailRequest.to = String(opts.emailRequestTo).split(/[,;\s]+/).map((e) => e.trim()).filter(Boolean);
+  }
+  if (opts.emailRequestSubjectPrefix !== undefined) emailRequest.subject_prefix = opts.emailRequestSubjectPrefix;
+  if (Object.keys(emailRequest).length) body.email_request = emailRequest;
+  if (opts.sendSuccessRule?.length || opts.sendSuccess !== undefined) {
+    body.send_success = {};
+    if (opts.sendSuccess !== undefined) body.send_success.enabled = parseBool(opts.sendSuccess, "--send-success");
+    if (opts.sendSuccessRule?.length) {
+      body.send_success.rules = {};
+      for (const pair of opts.sendSuccessRule) {
+        const [when, text] = splitPair(pair, "--send-success-rule");
+        body.send_success.rules[when] = readValue(text, `--send-success-rule ${when}`);
+      }
+    }
+  }
+  if (opts.afterEscalation !== undefined) body.after_escalation = readValue(opts.afterEscalation, "--after-escalation");
+  if (opts.knowledge !== undefined) body.knowledge = parseKnowledge(opts.knowledge);
+  if (opts.humanNotify !== undefined) body.human_notify = parseJsonObject(opts.humanNotify, "--human-notify");
+  if (opts.orderNotify !== undefined) body.order_notify = parseJsonObject(opts.orderNotify, "--order-notify");
+
   if (opts.tool && opts.tool.length) {
     const flags = {};
     for (const pair of opts.tool) {
@@ -74,8 +185,12 @@ export async function config(orgId, opts = {}) {
     body.tool_flags = flags;
   }
 
-  const hasWrite =
-    body.settings || body.name !== undefined || body.tool_flags || body.base_tool_changes || body.discount_enabled !== undefined;
+  const WRITE_KEYS = [
+    "settings", "name", "tool_flags", "base_tool_changes", "discount_enabled", "tool_instructions",
+    "url_shortening", "email_identity", "email_request", "send_success", "after_escalation",
+    "knowledge", "human_notify", "order_notify",
+  ];
+  const hasWrite = WRITE_KEYS.some((k) => body[k] !== undefined);
 
   // No write flags → just show current config.
   if (!hasWrite) {
@@ -86,9 +201,26 @@ export async function config(orgId, opts = {}) {
       console.error(`Lookup failed: ${e.message}`);
       process.exit(1);
     }
+    if (opts.json) {
+      console.log(JSON.stringify(resp, null, 2));
+      return;
+    }
     console.log(`${resp.organization_name} → agent ${resp.agent_id}${resp.is_active === false ? " [NON-active]" : ""}`);
-    printSnapshot("current", resp.current);
-    console.log("\n(pass --use-settings-prompt / --model / --reasoning-effort / --rename / --tool / --disable-base-tool / --enable-base-tool / --discount / --test-contact-number / --test-contact-name to change)");
+    printSnapshot("current", resp.current, opts.full);
+    console.log(`
+Settable (flowiq agent config --help for the value formats):
+  --use-settings-prompt  --model  --reasoning-effort  --rename  --discount
+  --tool <flag=bool>  --disable-base-tool / --enable-base-tool <name>
+  --test-contact-number / --test-contact-name
+  --tool-instruction <tool=text|@file>       settings.tool_instructions ("" removes)
+  --shorten-links <channel=on|off|default>   disable_url_shortening
+  --email-from-name / --email-signature-name / --email-signature-title
+  --email-request-to <a,b> / --email-request-subject-prefix
+  --send-success-rule <when=text|@file>  --send-success <bool>
+  --after-escalation <text|@file>            human_notify.success_instructions
+  --knowledge enabled=…,match_count=…,min_similarity=…
+  --human-notify / --order-notify <json|@file.json>  (merged; null deletes a key)
+Not settable here yet: additional_config (use \`flowiq knowledge\`), additional_tools (\`flowiq ct\`).`);
     return;
   }
 
@@ -106,7 +238,7 @@ export async function config(orgId, opts = {}) {
   for (const k of resp.changed) {
     const b = resp.before?.[k];
     const a = resp.after?.[k];
-    console.log(`    ${k.padEnd(30)} ${b === null || b === undefined ? "(unset)" : b} → ${a === null || a === undefined ? "(unset)" : a}`);
+    console.log(`    ${k.padEnd(38)} ${short(b, opts.full)} → ${short(a, opts.full)}`);
   }
   for (const w of resp.warnings || []) console.log(`  ⚠ ${w}`);
 }