@flowapt/flowiq-cli 0.8.1 → 0.9.2

package/README.md

@@ -189,7 +189,8 @@ flowiq ct list
 - **Destructive pushes are blocked by default**: a push that removes a tool, disables one, or sends an empty `tools[]` (wiping everything) writes nothing and shows you exactly what it would strip — re-run with `--confirm` if intentional. Additive/no-op pushes are unaffected.
 - Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates or built-in collisions), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, scalar headers, object-typed `parameters`/`injected_parameters`, valid auth/channels, timeout and response caps. Recursive schemas support strict nested objects, typed arrays, enums and numeric/string/item limits. Unknown tool/schema keys are rejected before anything writes.
 - **`display_name` (optional, 10 Sep 2026):** the label the TEAM sees on the inbox tool-activity card (e.g. `Checked loyalty points`) — plain string, ≤80 chars, never sent to the AI. Leave it out and the card derives a label from the tool name.
-- **Warnings (non-blocking):** an object with properties but no required fields. Unknown `{{placeholder}}` values are hard errors; injected parameters may additionally reference a declared top-level model parameter. Known runtime values include `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `whatsapp_message_id`, `text`, `unique_message_id`, `unix_timestamp`, `operation_idempotency_key`, `supabase_anon_key`, and `openai_api_key`.
+- **Warnings (non-blocking):** an object with properties but no required fields. Unknown `{{placeholder}}` values are hard errors; injected parameters may additionally reference a declared top-level model parameter. Known runtime values include `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `whatsapp_message_id`, `text`, `unique_message_id`, `unix_timestamp`, `operation_idempotency_key`, `supabase_anon_key`, `flowmod_relay_secret`, `flowiq_queue_key`, and `openai_api_key`.
+- **Queue credential:** `{{flowiq_queue_key}}` is super-admin-only and resolves to the service key only as the bearer token of a call to FlowIQ's own `add-to-api-queue` (`https://zvhwjpeeapujvuudfdps.supabase.co/functions/v1/add-to-api-queue`). The queue refuses the public anon key since 22 Sep 2026, so a tool that schedules a send (FlowMod Org's `schedule_reminder` / `schedule_a_task`) uses this. Validation and runtime both reject it anywhere else: another endpoint, another auth type, a body, a header.
 - **Retailer gateway credential:** `{{retailer_tools_internal_key}}` is super-admin-only and resolves only as the `x-api-key` value for `https://express.chatcart.io/retailer-tools/*` (or loopback in local tests). Validation and runtime both reject putting it in a body or sending it to any other host.
 - `--agent` + filenames behave like `prompts`/`knowledge`; the file carries `agent_id`, so `push` targets the agent it was pulled from.
 
@@ -234,7 +235,14 @@ flowiq bc send <org_id> --tag <batch-tag> --template <name> --body param1="…"
 flowiq bc send … --at "2026-08-05 09:00" --needs-approval --commit  # park it for approval
 
 flowiq bc scheduled list <org_id>                   # open rows (pending + awaiting-approval)
-flowiq bc scheduled list <org_id> --all             # incl. fired / cancelled
+flowiq bc scheduled list <org_id> --all             # incl. fired / cancelled — an empty OPEN list now names what --all would show
+flowiq bc scheduled list <org_id> --status completed
+
+# SAVED SEND DRAFTS (v0.9.1) — the send dialog's stored configurations. A draft
+# is NOT scheduled and never fires on its own; before this it was invisible
+# outside the dashboard.
+flowiq bc drafts <org_id>                           # newest first
+flowiq bc drafts show <org_id> <draft_id>           # the whole stored config
 flowiq bc scheduled approve <org_id> <queue_id>     # 'request' → 'pending' (--at re-times it)
 flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
 
@@ -930,6 +938,7 @@ ids and prefixes — never a key.
 | `agent-config` | config | before + after snapshot + the changed keys |
 | `agents` / `org` / `meta-templates` | create | the created record / submitted request |
 | `messaging-webhooks` / `webhooks` | push, reconnect | full before + after |
+| `popups` | create / push / duplicate / delete / upload | **full before + after document** (popup + webhooks) |
 | `pinboard` | push | full prior row + the new one |
 | `agent-updates` | resolve | prior status + the client-facing note |
 | `broadcast` | **send (committed)**, retry | the exact payload sent + the resulting broadcastId |
@@ -1024,6 +1033,85 @@ Push refuses an `auth_type` whose credentials are incomplete (e.g. `bearer`
 with no `auth_config.token`), because that would make every delivery fail
 closed — FlowIQ never falls back to an unauthenticated send.
 
+### Popups — `flowiq popups schema|list|pull|push|create|duplicate|activate|deactivate|live|delete|upload` (alias `pp`) (v0.9.0)
+
+Every popup in FlowIQ — the ones built in the dashboard designer and the
+ones built here — is written through ONE endpoint, the popup service's
+`/api/popup-settings`. That endpoint owns the validator, the write rules
+and the schema; this CLI holds **no popup logic**. So a popup feature that
+ships in the popup service works from the terminal the same day, with no
+CLI release, and `flowiq popups schema` always prints what a popup may
+contain **today**.
+
+```bash
+flowiq popups schema                              # what a document may contain (content, rules, design, webhooks); --json for enums + limits
+flowiq popups list <org_id>                       # every popup: id, active/live, views, signups, what a signup triggers
+flowiq popups pull <org_id> [popup_id]            # → ./.flowiq/popups/<org-slug>/<name>-<id8>.json (popup + webhooks + etag); no id = all
+flowiq popups push <file> [--dry-run]             # apply the document; refused (409) if someone edited it since the pull (--force overrides)
+flowiq popups create <org_id> <file> [--dry-run]  # create from a document (a pulled file from ANY org works — ids are stripped); created INACTIVE
+flowiq popups duplicate <org_id> <popup_id> [--name …] [--from-org <id>] [--no-webhooks]
+flowiq popups activate|deactivate <org_id> <popup_id>
+flowiq popups live <org_id> <popup_id> [--off]    # which ACTIVE popup the store embed shows (one per org; prints what it demoted)
+flowiq popups delete <org_id> <popup_id> [--confirm]
+flowiq popups upload <org_id> <popup_id> <file> --slot main | --font "Gilmer" [--weight 500] [--italic]
+```
+
+**The document.** One JSON file per popup:
+
+```json
+{
+  "organization_id": "…",
+  "etag": "6939ff535be8f3f6",
+  "popup": { "id": "…", "name": "…", "slug": "spin", "is_active": true,
+             "content_settings": { "welcome": {…}, "success": {…}, "wheel": {…} },
+             "style_settings":   { "design": {…} },
+             "rules_settings":   { "when_to_show": {…}, "whom_to_show": {…}, … },
+             "stats": { "sales_stats": false } },
+  "webhooks": [ { "id": "…", "name": "Discount", "url": "…/functions/v1/send-discount-code-popup",
+                  "discount_config": { "enabled": true, "template_name": "welcome_v1", … } } ]
+}
+```
+
+- **A popup with no webhook sends NOTHING on signup.** The WhatsApp welcome +
+  discount code is the `send-discount-code-popup` row; Klaviyo / Omnisend /
+  Marsello / Passes / Flows are their own rows. `flowiq popups schema` lists
+  every FlowIQ function with its URL and config keys. **One row per function
+  per popup** — every row fires on every signup, so two rows = two messages;
+  the server refuses a push that would create the duplicate.
+- **`push` is id-keyed for webhooks** and **MERGES integration configs**
+  (`discount_config` / `pass_config` / `flows_config`) over what the row
+  holds — a file that knows three keys can never wipe a fourth (`null`
+  deletes a key on purpose). A webhook without an `id` but with a URL one
+  existing row already has UPDATES that row. Webhooks missing from the file
+  are left alone unless `--replace-webhooks --confirm-delete-webhooks`.
+- **`push` never changes which popup is live** (`currently_active_on_store`
+  and `image_history` are not sent from the file). Use `popups live`.
+- **Validation is the server's** (the editor gets the same answers): answer
+  keys (`choice_fields`, `questions`, deck cards, wheel segment ids) must
+  match `[a-zA-Z0-9_-]{1,64}` or the submissions API drops them; an enabled
+  wheel needs 2–12 wedges with at least one weight; an enabled teaser needs
+  text; `size.width` is kept equal to `size.maxWidth`. Errors block, warnings
+  ride back and are printed (`⚠`). Unknown keys are **stored with a
+  warning**, never dropped — popups evolve faster than any allowlist.
+- **`create` and `duplicate` land INACTIVE** with no slug and zero stats;
+  `activate` when checked. `duplicate` copies the webhooks too (`--from-org`
+  copies a popup from another org, webhooks excluded — templates, lists and
+  pass designs belong to the source client).
+- **Kill switch = `deactivate`** (`is_active=false`: store embed, pinned id
+  and the `popup.flowapt.com/p/…` link all 404). `live --off` only unselects
+  it — a store embed that pins its id still serves it while active.
+- **`delete` removes the signups, webhooks and delivery history with it**;
+  a live popup or one with signups needs `--confirm`.
+- **`upload`** puts an image in the private `popups_images` bucket (1-year
+  signed URL) or a font in the PUBLIC `popup_fonts` bucket, and prints the
+  URL to paste into the design.
+- **Concurrency:** the file's `etag` is sent as `if_match`; if the popup was
+  edited in the dashboard since the pull, push is refused with 409 — pull,
+  re-apply, push. `--force` overwrites. Every push refreshes the file (new
+  etag), and a rename moves it to its new file name.
+- **Audit:** create / push / duplicate / delete / upload are audited with the
+  full before + after document (`flowiq audit <org> --endpoint popups`).
+
 ### FlowMod prompts — `flowiq flowmod pull|push <slug>` (alias `fm`)
 
 Round-trips a FlowMod org's **master-group** prompts + config. FlowMod groups
@@ -1049,29 +1137,32 @@ the prompt rows directly).
 Common uses: edit a master-group's moderator prompt, or flip its reasoning
 effort via `config.reasoningEffort` (`none` / `low` / `medium` / `high`).
 
-### Group chats — `flowiq groups list|pull <name-or-jid>` (alias `grp`)
+### Group chats — ⛔ DEPRECATED (`flowiq groups`, alias `grp`)
 
-Read-only pull of **WhatsApp group** chat history (e.g. the `… x Flowapt`
-client comms groups) straight out of the FlowMod **Evolution** Postgres. This
-is the analogue of `messages pull`, but for a group instead of a contact, so
-you can pull a window and summarise it.
+**Evolution is retired (22 Sep 2026). Read a WhatsApp group chat with the
+WhatsApp MCP, not this command.** The flowapt Evolution instance logged out of
+WhatsApp on 29 Aug 2026 (`Instance.connectionStatus` = `close`, reason 401) and
+has stored nothing since, so this command answered from a frozen archive while
+looking current — on 22 Sep it reported the Johnson Fitness group's last
+message as 17 Aug while the group had traffic that morning.
 
-> ⚠️ Unlike every other command, this talks to a database **directly** (the
-> Evolution DB is not Supabase and not the `fiq_staff_…` API). To keep this
-> published package secret-free, the connection string comes from your shell
-> environment — set `FLOWMOD_EVO_DB_URL` (or the five `FLOWMOD_DB_*` vars the
-> `flowmod-copilot` edge fn uses) before running. No auth token is needed.
+```
+mcp__whatsapp-flowapt__list_chats    { query: "<group name>" }      → the JID
+mcp__whatsapp-flowapt__list_messages { chat_jid: "…@g.us", limit: 50 }
+mcp__whatsapp-flowmod__*             if the group is not on the flowapt line
+```
+
+Both verbs now **refuse unless `--archive` is passed**, because a stale read
+that looks complete is worse than an error. `--archive` prints the frozen data
+with a banner, and `groups list` shows the instance's connection state so the
+cut-off is visible:
 
 ```bash
 export FLOWMOD_EVO_DB_URL='postgres://user:pass@app.flowmod.ai:5555/flowiq-db'
 
-flowiq groups list                               # default instance: flowapt
-flowiq groups list --instance FlowMod            # the other connected instance
-
-flowiq groups pull "Phytoceutics x Flowapt" --last 7d
-flowiq groups pull "Zorora x Flowapt" --since 2026-06-24 --until "2026-06-25 12:00"
-flowiq grp pull 120363408455897717@g.us --last 48h   # or pass the group JID
-# writes ./.flowiq/groups/<instance>-<group-slug>.json + prints a timeline
+flowiq groups list --archive                     # frozen: 38 groups, all ending 28 Aug 2026
+flowiq groups pull "Zorora x Flowapt" --archive --since 2026-06-24 --until 2026-06-25
+# still writes ./.flowiq/groups/<instance>-<group-slug>.json
 ```
 
 - Group is matched by JID, exact name, or a unique case-insensitive substring
@@ -1099,23 +1190,30 @@ Editable fields: `name`, `description`, `status` (open / in_progress / done),
 null), `organizations[]`, `media[]`, `messages[]`, `created_by`. Array columns
 are full-replace within the row.
 
-### Client hours — `flowiq hours log|list|summary` (v0.5.0)
+### Client hours — `flowiq hours log|list|summary|package` (v0.5.0; packages v0.9.2)
 
-The client-hours ledger. Every org's package includes **10 hours of Flowapt
-work per calendar month**; every piece of client work gets logged against it —
-manually here, or automatically by Claude sessions. **The CLI is the only
-way to log hours:** the FlowIQ MCP's `log_client_hours` tool was removed on
-29 Aug 2026, because the MCP advertises every tool to every connection and a
-staff-only write does not belong on a client-facing surface. The MCP keeps
-`get_client_hours` (read). Clients see their own usage on the Client Console;
-the cross-org view lives in the super-admin Changelog dialog → Client hours.
+The client-hours ledger. Every piece of client work gets logged against the
+org's **monthly hours package** — manually here, or automatically by Claude
+sessions. **The CLI is the only way to log hours:** the FlowIQ MCP's
+`log_client_hours` tool was removed on 29 Aug 2026, because the MCP advertises
+every tool to every connection and a staff-only write does not belong on a
+client-facing surface. The MCP keeps `get_client_hours` (read, staff
+connections only). The Client Console card and the super-admin Changelog
+dialog → Client hours read the same figures.
 
 ```bash
 flowiq hours log <org_id> --hours 1.5 --desc "Rebuilt the abandoned-cart copy"   # fractions fine
 flowiq hours log <org_id> --minutes 45 --desc "Fixed template header" --date 2026-08-18
 flowiq hours list <org_id>                    # this month's entries + package standing
 flowiq hours list <org_id> --month 2026-07    # a past month
-flowiq hours summary                          # every org with logged work this month
+flowiq hours summary                          # every org with logged work or a package
+
+flowiq hours package show [<org_id>]          # every package, or the one an org is on
+flowiq hours package set <org_id> --hours 5 --notes "Order Form 12 Aug 2026"
+flowiq hours package set <pt> <es> <it> --hours 10 --name Barkyn   # ONE package SHARED by three orgs
+flowiq hours package set <org_id> --hours 0   # a plan with no hours included
+flowiq hours package clear <org_id>           # back to "no package on file"
+# add --dry-run to set / clear to see the change first
 ```
 
 - `log` takes exactly ONE of `--minutes <n>` (whole minutes) or `--hours <h>`
@@ -1124,10 +1222,25 @@ flowiq hours summary                          # every org with logged work this
 - `--by` overrides who did the work (default: your staff login email);
   `--date YYYY-MM-DD` backdates an entry (it counts toward THAT month);
   `--session` tags the session/task name.
-- `list` / `summary` default to the current month and print each org's usage
-  against the 10h package, flagging any org that has gone over.
-- Corrections (delete/edit) live in the Changelog → Client hours page, not the
-  CLI. Every `log` is audited.
+- **Packages (v0.9.2).** Each org has its own package, shares one with sibling
+  orgs, or has none on file. There is no default: an org with no package reads
+  "no package on file", never an implied 10h. A **shared** package is measured
+  on the time of ALL its orgs together (Barkyn Portugal + Spain + Italy draw on
+  one 10h), and every org on it shows the shared total. `0` hours is a real
+  plan (self-service, nothing included).
+- `package set` puts EXACTLY the orgs you name on one package. If they already
+  form exactly one package it is updated in place; otherwise they leave their
+  old packages (a package left empty is removed) and get a new one. The output
+  warns when orgs are left behind on the old package. `--name` defaults to the
+  org's name (or the names joined); `--notes` records where the figure comes
+  from.
+- **Only matt@flowapt.com and gidon@flowapt.com can set or clear a package**
+  (enforced on the server; other super admins get a 403, logged as a blocked
+  attempt). `package show` tells you whether you can.
+- `list` / `summary` default to the current month and flag any org, or shared
+  package, that has gone over.
+- Corrections (delete/edit) to entries live in the Changelog → Client hours
+  page, not the CLI. Every `log`, `package set` and `package clear` is audited.
 
 ### Client deck — `flowiq report deck status|build|narrate|generate|inputs|approve|unapprove|send|print|pull` (v0.6.5)
 
@@ -1145,7 +1258,7 @@ from flowiq@flowapt.com.
 flowiq report deck status <org_id> 2026-08                 # what exists, workflow status, what blocks approval
 flowiq report deck generate <org_id> 2026-08               # build the metrics (if missing) + write the copy
 flowiq report deck generate <org_id> 2026-08 --refresh --force   # rebuild everything
-flowiq report deck build <org_id> 2026-08 --refresh        # metrics only
+flowiq report deck build <org_id> 2026-08 --refresh        # metrics only; status then says "Copy is older than the numbers" until you narrate
 flowiq report deck narrate <org_id> 2026-08                # copy only (hand edits are kept)
 flowiq report deck inputs <org_id> 2026-08 --file inputs.json   # the super-admin input form
 flowiq report deck approve <org_id> 2026-08                # refused until every required input is present
@@ -1593,13 +1706,14 @@ flowiq agent config <organization_id> --use-settings-prompt --model gpt-5.6-luna
   --rename Zara --tool woo_order_build=true --tool view_cart_tool=true --discount true
 flowiq agent config <organization_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"
 flowiq agent config <organization_id> --model gpt-5.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
 ```
 
 Settable: `settings.use_settings_prompt`, `settings.model`,
-`settings.reasoning_effort` (`--reasoning-effort low|medium|high`, `""` clears it —
-pairs with reasoning models like `gpt-5.6-luna`), agent `--rename`,
+`settings.reasoning_effort` (`--reasoning-effort low|medium|high|xhigh|max`, `""` clears it —
+pairs with reasoning models like `gpt-5.6-luna`; `max` is Claude only), agent `--rename`,
 the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field`,
 `view_cart_tool`, `restock_tool`, `block_tool_status`, `postal_code_tool_status`,
 `shopify_products_web_chat`, `ticket_tool_status`, `product_lookup`,
@@ -1687,6 +1801,8 @@ and Flowapt reviews), from the terminal.
 flowiq plans list                                        # open plans across every ACTIVE client
 flowiq plans list --status pending_review                # waiting for Flowapt review
 flowiq plans list <organization_id> --status all --since 2026-09-01
+flowiq plans list --created-since 2026-09-22              # what clients submitted TODAY (v0.9.1)
+flowiq plans list --touched-since 2026-09-20              # anything edited or reviewed since
 flowiq plans show <plan_id>                              # copy, second message, buttons, creative, audience, notes
 flowiq plans show <plan_id> --json --out plan.json
 flowiq plans status <plan_id> --to approved              # dry run
@@ -1699,6 +1815,9 @@ flowiq plans status <plan_id> --to sent --commit
   `--status all` / a status / a comma list to widen or narrow, `--since` to
   filter by send date, `--include-inactive` for inactive orgs. The header
   shows the totals for every status, and each row prints the full plan id.
+  **`--created-since` / `--touched-since` (v0.9.1)** filter the ROW's own
+  timestamps instead of the send date (SAST day start) — "what did a client
+  submit today", "what has moved since Friday", which `--since` cannot answer.
 - **`show`** prints the plan the way the dialog does: message copy, the
   second message sent when a button is tapped, buttons with their URLs, the
   creative (file name + link), audience, template link, the response to the
@@ -1760,7 +1879,7 @@ version you have installed.
 | `FLOWIQ_API_URL` | `https://api.flowiq.live` | Override the API host (local dev, staging). |
 | `FLOWIQ_TOKEN` | (saved in `~/.config/flowiq/auth.json`) | Override the auth token, useful for CI. |
 | `FLOWIQ_NO_UPDATE_CHECK` | (unset) | Set to `1` to silence the "you're behind" update hint (also honours `NO_UPDATE_NOTIFIER=1` and any `CI` env). |
-| `FLOWMOD_EVO_DB_URL` | (none) | Full `postgres://` URL for `groups` (Evolution DB). Required for `groups`. |
+| `FLOWMOD_EVO_DB_URL` | (none) | Full `postgres://` URL for the DEPRECATED `groups --archive` (Evolution DB, frozen since 29 Aug 2026). Not needed for anything else. |
 | `FLOWMOD_DB_HOST/PORT/USER/PASS/NAME` | (none) | Alternative to `FLOWMOD_EVO_DB_URL` — assembled into a connection string. |
 
 ## Upgrading

package/TEAM-GUIDE.md

@@ -86,9 +86,17 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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") |
+| **See a client's popups** and what each one sends on signup | `flowiq popups list <org_id>` — "sends to: NOTHING" means a signup goes nowhere; add a `send-discount-code-popup` webhook |
+| **Change a popup's copy, wheel, rules or webhooks** | `flowiq popups pull <org_id> <popup_id>` → edit the JSON → `flowiq popups push <file> --dry-run` → `… push <file>`. Same rules as the dashboard (it is the same endpoint); if someone edited it in between you get a 409 — pull again |
+| **What can a popup contain right now?** (wheel, deck, intro page, scratch card, questions…) | `flowiq popups schema` — served by the popup service, so it is never stale |
+| **Build a client's popup from a proven one** | `flowiq popups duplicate <client_org> <popup_id> --from-org <source_org> --name "Client — welcome"`, then `pull` → edit → `push`, add its webhooks, `activate`, `live` |
+| Copy a popup inside the same client (webhooks included) | `flowiq popups duplicate <org_id> <popup_id>` — lands inactive with zero stats |
+| Switch a popup on / off / choose which one the store shows | `flowiq popups activate\|deactivate <org_id> <popup_id>` · `flowiq popups live <org_id> <popup_id>` (prints which popup it demoted) |
+| Put a picture or the client's own font on a popup | `flowiq popups upload <org_id> <popup_id> ./hero.jpg --slot main` · `… ./Gilmer-Medium.otf --font Gilmer --weight 500` — paste the printed URL into the design, then push |
 | **Find an org's ID** (needed by nearly every command) | `flowiq org list` — or `flowiq org list african` to filter |
 | See broadcast plans waiting for Flowapt review, across every client | `flowiq plans list --status pending_review`, then `flowiq plans show <plan_id>` for the copy, second message, buttons, creative and audience |
 | 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 |
 | Has this order shipped? What's the tracking? | `flowiq shopify order <org_id> '#14728'` — status, courier, tracking number + link |
@@ -102,6 +110,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | See an org's agents / create one | `flowiq agent list <org_id>` / `flowiq agent create <org_id> --name "…"` — a new agent arrives ready to work (gpt-5.6-luna, high reasoning, prompt switched ON); no follow-up `agent config` needed |
 | Change agent model / tool flags | `flowiq agent config <org_id> --model … --tool view_cart_tool=true` |
 | Set the house model + reasoning tier | `flowiq agent config <org_id> --model gpt-5.6-luna --reasoning-effort high` |
+| Run the agent on Claude (org needs a Claude key in Settings → Integrations) | `flowiq agent config <org_id> --model claude-sonnet-5 --reasoning-effort medium` |
 | 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) |
@@ -163,7 +172,10 @@ several.
 | Send the NEXT batch of a campaign that already has batches 01-12 | `flowiq seg plan <org_id> --tag-prefix f500 --ids-file next100.txt --batch-size 100 --start-index 13` → `flowiq seg apply <org_id> f500 --commit` (makes `f500-batch-13`; without `--start-index` the plan is REFUSED, because it would re-use `f500-batch-01` and merge the two cohorts) |
 | Split a whole tagged audience into batches of N (e.g. 90k → 7000s) | `flowiq seg plan <org_id> --tag-prefix 3-aug-bc --from-tag "3-aug-bc" --batch-size 7000` → `flowiq seg apply <org_id> 3-aug-bc --commit --yes` (makes `…-batch-01…13`; works at any size — big applies are chunked internally) |
 | Schedule a broadcast for later instead of sending now | `flowiq bc send <org_id> --tag <batch-tag> --template <name> --at "2026-08-05 09:00" --commit` (time is SAST; fires on its own; audience resolved at send time). **Works with --csv too (v0.6.1):** rows import+tag immediately, the send queues server-side, and it shows on the dashboard's Scheduled sends page. Nothing depends on your laptop being on at send time. |
-| See / approve / cancel what's scheduled | `flowiq bc scheduled list <org_id>` → `flowiq bc scheduled approve <org_id> <queue_id>` or `flowiq bc scheduled cancel <org_id> <queue_id> --confirm` |
+| See / approve / cancel what's scheduled | `flowiq bc scheduled list <org_id>` → `flowiq bc scheduled approve <org_id> <queue_id>` or `flowiq bc scheduled cancel <org_id> <queue_id> --confirm`. The plain list shows only what is still OPEN; it now tells you how many fired / cancelled rows it is hiding, and `--all` shows them with who scheduled each one and how big the audience was |
+| "Did a broadcast go out, and who scheduled it?" | `flowiq bc scheduled list <org_id> --all` — every queued send ever, with `via flowiq-cli (name@flowapt.com)`, the audience at schedule time, when it fired and its broadcastId |
+| Find a broadcast someone half-built and saved but never sent | `flowiq bc drafts <org_id>` → `flowiq bc drafts show <org_id> <draft_id>` (v0.9.1). These are the send dialog's SAVED DRAFTS — a draft is not scheduled and will never fire on its own |
+| Read a client's WhatsApp GROUP chat | **Not the CLI.** `flowiq groups` is deprecated — Evolution was retired on 29 Aug 2026 and its copy is frozen. Ask Claude to read it with the WhatsApp MCP (`whatsapp-flowapt`, then `whatsapp-flowmod`) |
 | Send to one batch tag | `flowiq bc send <org_id> --tag <batch-tag> --template … --body param1="Hi {{first_name}}" --commit` (per-contact tokens: the 6 contact fields + `{{attributes.<key>}}`). Sending a **different template to the SAME tag**? Add a distinct `--campaign <name>` — otherwise the CLI aborts (a campaign belongs to one template; reusing it would send the first template's image + skip everyone it already reached). |
 | Send a broadcast whose template has an IMAGE/VIDEO/DOCUMENT header | Same as above — the media is automatic (the template's own stored header). Override with `--header-media <public-url>` if needed. The CLI verifies the resolved media's actual type against the header format — `header video (video ✓ video/mp4)` means verified; a mismatch (e.g. a video template whose stored default is secretly a png — templates made before 3 Aug 2026 can carry this) ABORTS and tells you to pass `--header-media` with the real file. |
 | Send a **CAROUSEL** template (v0.4.9) | Tag mode only: `flowiq bc send <org_id> --tag <batch-tag> --template <carousel_name> --body param1="Hi {{first_name}}" --commit`. Card images are automatic (each card's stored template image, type-verified per card); override with repeatable `--card-media <url>` (one per card, in order). If the cards carry `{{n}}` body variables or URL-button variables, the CLI tells you exactly what to put in a `--cards-file <path>` JSON (one entry per card: `header_media` / `body_params` / `button_payloads` / `url_vars`). Always sends via the python engine (any size); no CSV mode for carousels. |
@@ -201,8 +213,9 @@ several.
 | Store insights daily without emailing anyone (build history first) | `flowiq insights enable <org_id> --daily --store-only` |
 | Send one insights report right now | `flowiq insights run <org_id> --period weekly --recipient you@flowapt.com` (dry run) → add `--commit` |
 | Work a Pin Board task | `flowiq pin list-remote open` → `pull` → edit → `push` |
-| Log hours you worked for a client (every package = 10h Flowapt work/month) | `flowiq hours log <org_id> --hours 1.5 --desc "what you did"` — plain language, the client sees it on their Client Console |
-| Check a client's package hours / the month across all clients | `flowiq hours list <org_id>` / `flowiq hours summary` |
+| Log hours you worked for a client (against the client's own monthly package) | `flowiq hours log <org_id> --hours 1.5 --desc "what you did"` — plain language, the client sees it on their Client Console |
+| Check a client's package hours / the month across all clients | `flowiq hours list <org_id>` / `flowiq hours summary` (a shared package, like Barkyn's three stores, shows the total across all of them) |
+| See what hours package a client is on | `flowiq hours package show <org_id>` (no org = every package). Setting one is Matt or Gidon only: `flowiq hours package set <org_id> --hours 5` |
 | 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 |
@@ -245,7 +258,9 @@ validates names, URLs, methods and parameter shapes. Unknown keys and unresolved
 object with no required fields remains a warning because it can be intentional.
 Nested object/array schemas are strict and supported. For ChatCart retailer tools, use
 `{{retailer_tools_internal_key}}` only as the `x-api-key` auth value on the
-trusted `express.chatcart.io/retailer-tools/*` gateway; org/contact identity is
+trusted `express.chatcart.io/retailer-tools/*` gateway. A tool that schedules a
+send through `add-to-api-queue` authenticates with `{{flowiq_queue_key}}` as its
+bearer token (the queue refuses the public anon key); it works nowhere else; org/contact identity is
 injected server-side and mutations use `{{operation_idempotency_key}}` for stable,
 operation-scoped idempotency. Batch independent product requests in one
 `search_retailer_products.queries` array (1–12) instead of repeated search calls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.8.1",
+  "version": "0.9.2",
   "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/commands/broadcast.js

@@ -1791,7 +1791,21 @@ export async function scheduledList(orgId, opts = {}) {
     });
   } catch (e) { console.error(`Scheduled list failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
   if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
-  if (!resp.scheduled?.length) { console.log(`No ${opts.all ? "" : "open "}scheduled broadcasts on ${resp.organization_name}.`); return; }
+  // An empty list must say what it is HIDING. "No open scheduled broadcasts"
+  // read as "this org has never scheduled anything" on an org with four fired
+  // rows (Johnson Fitness, 22 Sep 2026) and sent that session to raw SQL.
+  const counts = resp.status_counts ?? {};
+  const shownFilter = opts.all ? "all" : (opts.status || "open");
+  const hidden = Object.entries(counts)
+    .filter(([st]) => shownFilter === "all" ? false : (shownFilter === "open" ? !["pending", "request"].includes(st) : st !== shownFilter))
+    .map(([st, n]) => `${n} ${st}`);
+  if (!resp.scheduled?.length) {
+    console.log(`No ${opts.all ? "" : `${shownFilter} `}scheduled broadcasts on ${resp.organization_name}.`);
+    if (hidden.length) {
+      console.log(`  ${hidden.join(" · ")} row(s) exist on this org — see them with: flowiq bc scheduled list ${orgId} --all`);
+    }
+    return;
+  }
   console.log(`Scheduled broadcasts on ${resp.organization_name}:`);
   for (const s of resp.scheduled) {
     const flag = s.stalled ? " ⚠ AWAITING APPROVAL — will NOT fire" : "";
@@ -1806,6 +1820,62 @@ export async function scheduledList(orgId, opts = {}) {
   }
   console.log("");
   console.log(`  ${resp.count} row(s). Approve: flowiq bc scheduled approve <org> <id> · Cancel: … cancel <org> <id>`);
+  if (hidden.length) console.log(`  not shown: ${hidden.join(" · ")} (add --all)`);
+}
+
+/** List the org's SAVED SEND DRAFTS (broadcast_send_drafts). Read-only. */
+export async function draftsList(orgId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("broadcast", { action: "drafts-list", organization_id: orgId, limit: opts.limit });
+  } catch (e) { console.error(`Drafts list failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  if (!resp.drafts?.length) { console.log(`No saved send drafts on ${resp.organization_name}.`); return; }
+  console.log(`Saved send drafts on ${resp.organization_name} (newest first):`);
+  for (const d of resp.drafts) {
+    console.log("");
+    console.log(`  ${d.id}`);
+    console.log(`    ${d.name || "(unnamed)"} · template ${d.template_name ?? "?"}${d.mode ? ` · ${d.mode}` : ""}${d.engine ? ` · ${d.engine}` : ""}`);
+    const aud = [];
+    if (d.tags?.length) aud.push(`tags ${d.tags.join(", ")}`);
+    if (d.segment) aud.push(`segment ${d.segment}`);
+    if (d.recipient_count != null) aud.push(`${d.recipient_count} recipient(s)`);
+    if (!aud.length) aud.push("no audience chosen yet");
+    if (aud.length) console.log(`    ${aud.join(" · ")}`);
+    if (d.scheduled_for) console.log(`    scheduled for ${fmtSast(d.scheduled_for)} SAST`);
+    console.log(`    saved ${fmtSast(d.updated_at)} SAST${d.created_by_name ? ` by ${d.created_by_name}` : ""}`);
+  }
+  console.log("");
+  console.log(`  ${resp.count} draft(s). Full config: flowiq bc drafts show ${orgId} <draft_id>`);
+  console.log("  A draft is NOT scheduled and will never fire on its own — it is a saved form in the send dialog.");
+}
+
+/** One saved send draft in full. Read-only. */
+export async function draftsShow(orgId, draftId, opts = {}) {
+  if (!UUID_RE.test(orgId)) { console.error(`Error: "${orgId}" is not a valid organization UUID.`); process.exit(1); }
+  if (!UUID_RE.test(draftId || "")) { console.error(`Error: "${draftId}" is not a valid draft id (get it from: flowiq bc drafts <org>).`); process.exit(1); }
+  let resp;
+  try {
+    resp = await http.post("broadcast", { action: "drafts-show", organization_id: orgId, draft_id: draftId });
+  } catch (e) { console.error(`Draft show failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (opts.json) { console.log(JSON.stringify(resp, null, 2)); return; }
+  const d = resp.draft;
+  console.log(`${d.name || "(unnamed)"} — ${resp.organization_name}`);
+  console.log(`  id:        ${d.id}`);
+  console.log(`  template:  ${d.template_name ?? "?"}`);
+  if (d.mode) console.log(`  mode:      ${d.mode}`);
+  if (d.tags?.length) console.log(`  tags:      ${d.tags.join(", ")}`);
+  if (d.segment) console.log(`  segment:   ${d.segment}`);
+  if (d.recipient_count != null) console.log(`  audience:  ${d.recipient_count} recipient(s)`);
+  if (d.engine) console.log(`  engine:    ${d.engine}`);
+  if (d.carousel_cards) console.log(`  carousel:  ${d.carousel_cards} card override(s)`);
+  if (d.scheduled_for) console.log(`  scheduled: ${fmtSast(d.scheduled_for)} SAST (in the draft only — nothing is queued)`);
+  if (d.header_media) console.log(`  header:    ${d.header_media}`);
+  console.log(`  saved:     ${fmtSast(d.updated_at)} SAST${d.created_by_name ? ` by ${d.created_by_name}` : ""} · created ${fmtSast(d.created_at)} SAST`);
+  console.log("");
+  console.log("Stored config:");
+  console.log(JSON.stringify(d.config ?? {}, null, 2).split("\n").map((l) => `  ${l}`).join("\n"));
 }
 
 /** Approve (request → pending) or cancel a scheduled broadcast. */

package/src/commands/groups.js

@@ -11,6 +11,16 @@
 //   FLOWMOD_DB_HOST / FLOWMOD_DB_PORT / FLOWMOD_DB_USER / FLOWMOD_DB_PASS / FLOWMOD_DB_NAME
 //
 // Read-only: there is no `push` — group history is a system of record.
+//
+// ⛔ DEPRECATED (Matt, 22 Sep 2026): Evolution is fully deprecated. The flowapt
+// instance logged out of WhatsApp on 29 Aug 2026 (`Instance.connectionStatus`
+// 'close', reason 401) and has stored NOTHING since, so this command answers
+// from a frozen archive while looking current — on 22 Sep it reported the
+// Johnson Fitness group's last message as 17 Aug when the group had traffic
+// that morning. READ A GROUP CHAT WITH THE WHATSAPP MCP:
+//   mcp__whatsapp-flowapt__list_chats / list_messages  (then whatsapp-flowmod)
+// Both verbs now REFUSE unless --archive is passed, because a stale read that
+// looks complete is worse than an error.
 
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -64,6 +74,32 @@ async function connect() {
   return client;
 }
 
+// ---------- deprecation guard ----------
+// Evolution is deprecated; the store is frozen. Refuse rather than answer with
+// a stale window that reads as complete.
+const ARCHIVE_FROZEN_NOTE =
+  "Evolution stopped syncing on 29 Aug 2026 (the flowapt instance was logged out), so anything after that date is MISSING here.";
+
+function refuseUnlessArchive(opts, what) {
+  if (opts.archive) {
+    console.error("⚠ ARCHIVE READ — Evolution is deprecated and this data is FROZEN.");
+    console.error(`  ${ARCHIVE_FROZEN_NOTE}`);
+    console.error("  Anything recent must come from the WhatsApp MCP (whatsapp-flowapt, then whatsapp-flowmod).");
+    console.error("");
+    return;
+  }
+  console.error(`⛔ \`flowiq groups ${what}\` is DEPRECATED — Evolution is no longer in use.`);
+  console.error(`   ${ARCHIVE_FROZEN_NOTE}`);
+  console.error("");
+  console.error("   Read a group chat with the WhatsApp MCP instead:");
+  console.error("     mcp__whatsapp-flowapt__list_chats   { query: \"<group name>\" }");
+  console.error("     mcp__whatsapp-flowapt__list_messages { chat_jid: \"…@g.us\", limit: 50 }");
+  console.error("     …and mcp__whatsapp-flowmod__* if the group is not on the flowapt line.");
+  console.error("");
+  console.error("   To read the frozen pre-29-Aug archive anyway, pass --archive.");
+  process.exit(1);
+}
+
 // ---------- helpers ----------
 function slugify(name, fallback) {
   const s = String(name || "")
@@ -132,7 +168,10 @@ function extractText(m) {
 }
 
 async function resolveInstanceId(client, instanceName) {
-  const r = await client.query('SELECT id, "profileName" FROM "Instance" WHERE name = $1', [instanceName]);
+  const r = await client.query(
+    'SELECT id, "profileName", "connectionStatus", "updatedAt" FROM "Instance" WHERE name = $1',
+    [instanceName]
+  );
   if (!r.rows.length) {
     const all = await client.query('SELECT name FROM "Instance" ORDER BY name');
     console.error(
@@ -145,6 +184,7 @@ async function resolveInstanceId(client, instanceName) {
 
 // ---------- groups list ----------
 export async function list(opts = {}) {
+  refuseUnlessArchive(opts, "list");
   const instanceName = opts.instance || DEFAULT_INSTANCE;
   const client = await connect();
   try {
@@ -161,7 +201,12 @@ export async function list(opts = {}) {
         ORDER BY last_ts DESC NULLS LAST`,
       [inst.id]
     );
-    console.log(`Instance "${instanceName}" (${inst.profileName ?? "?"}) — ${r.rows.length} group chats\n`);
+    // The instance's own state explains every stale row below it.
+    const connLabel = inst.connectionStatus === "open" ? "connected" : `${inst.connectionStatus} (not syncing)`;
+    console.log(
+      `Instance "${instanceName}" (${inst.profileName ?? "?"}) — ${r.rows.length} group chats · ${connLabel}` +
+        (inst.updatedAt ? ` since ${new Date(inst.updatedAt).toISOString().slice(0, 10)}` : "") + "\n"
+    );
     const rows = r.rows.map((x) => ({
       group: x.name || "(no name)",
       msgs: Number(x.msgs || 0),
@@ -181,6 +226,7 @@ export async function list(opts = {}) {
 
 // ---------- groups pull ----------
 export async function pull(nameOrJid, opts = {}) {
+  refuseUnlessArchive(opts, "pull");
   const instanceName = opts.instance || DEFAULT_INSTANCE;
   const limit = Math.max(1, Math.min(Number(opts.limit) || DEFAULT_LIMIT, 5000));