@flowapt/flowiq-cli 0.4.8 → 0.6.0

package/README.md

@@ -187,8 +187,9 @@ flowiq ct list
 
 - **Always `--dry-run` first** on a production agent — it prints added/removed/changed tool names before you commit.
 - **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), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, object-typed `parameters`/`headers`/`injected_parameters`, valid `auth_type`/`channels`. Bad payloads are rejected before anything writes.
-- **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime — known: `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `supabase_anon_key`, `openai_api_key`, …).
+- Server-side validation is strict: tool `name` (`^[a-zA-Z0-9_-]{1,64}$`, no duplicates), non-empty `description`, `http(s)` `endpoint`, method `GET/POST/PUT/PATCH/DELETE`, object-typed `parameters`/`headers`/`injected_parameters`, valid `auth_type`/`channels`. Recursive JSON schemas are supported, including arrays of objects and integer/min/max constraints. Bad payloads are rejected before anything writes.
+- **Warnings (non-blocking):** unknown keys (likely typos the runtime would silently ignore) and unknown `{{placeholders}}` (they will NOT be substituted at runtime; known values include `organization_id`, `contact_id`, `agent_id`, `contact_whatsapp_id`, `contact_full_name`, `whatsapp_message_id`, `supabase_anon_key`, `openai_api_key`).
+- **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.
 
 ### Broadcast — `flowiq broadcast map|preview|send|resume|list-remote|status|retry|list` (alias `bc`)
@@ -198,6 +199,16 @@ template's variables **per row** from the CSV's own columns. The
 highest-stakes command in the CLI — built as a map → preview → commit
 pipeline with several layers of deliberate friction.
 
+**v0.6.0 — the CSV send is a server-side fan-out.** A commit imports every
+sendable row as a contact carrying the campaign tag `bc-<campaign>` plus that
+row's values as campaign-scoped attributes (`bc_<campaign>_param1…` /
+`_button`), then fires **ONE** python `/meta-broadcast` call whose params are
+`{{attributes.bc_<campaign>_paramN}}` tokens — python resolves them **per
+contact** (body AND URL-button) and paces the send server-side. The CLI
+returns in seconds; closing the laptop no longer matters. A 1,846-row CSV
+that took ~77 min on the old per-row loop is now python-paced like any big
+tag send.
+
 ```bash
 # 1) Build the column→param mapping interactively (saved per campaign, no send)
 flowiq bc map <org_id> --template rewards_referral_v1 --csv ./people.csv --campaign july-referrals
@@ -205,11 +216,15 @@ flowiq bc map <org_id> --template rewards_referral_v1 --csv ./people.csv --campa
 # 2) Dry-run: validation + exact rendered messages for sample rows (default)
 flowiq bc send <org_id> --template rewards_referral_v1 --csv ./people.csv --campaign july-referrals
 
-# 3) Commit: upsert contacts, then send per row @ ≤8/s
+# 3) Commit: import+tag the rows, fire ONE python broadcast (returns a broadcastId)
 flowiq bc send <org_id> --template … --csv … --campaign july-referrals --commit
 #   → prompts: type the campaign name to confirm
+#   → then audit with: flowiq bc status <org_id> <broadcastId> [--failures]
+
+# 4) Re-fire ONLY the failed recipients (python campaigns have no per-row resume):
+flowiq bc retry <org_id> <broadcastId> --commit
 
-# 4) Interrupted? Continue only unsent rows:
+# (pre-v0.6.0 campaigns with a per-row status log still finish on the old loop:)
 flowiq bc resume <org_id> --campaign july-referrals --commit [--retry-failed]
 
 # SCHEDULE a tag send for later instead of sending now (--at is SAST):
@@ -306,10 +321,31 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   DRY-RUN by default (shows the failed count + reason breakdown); `--commit` fires.
   Note: permanent failures (e.g. `131026` undeliverable, opt-outs) just fail again —
   retry earns its keep on transient (throttle/throughput) failures. Capped at 500.
+- **CSV fan-out semantics (v0.6.0)** — the things the engine change makes true:
+  - **Per-row values persist on the contact** as `bc_<campaign>_paramN` /
+    `_button` attributes (and the `bc-<campaign>` tag) — deliberate: they're the
+    audit trail of exactly what each person was sent. Re-running a campaign
+    overwrites them with the current CSV's values. Names are safe: a blank/missing
+    CSV name can never null a real contact's name (the upsert RPC preserves it).
+  - **One campaign = one audience.** A campaign that already fanned out refuses
+    a re-run (`--resend` overrides, and resends to EVERY tagged contact — for
+    failures use `bc retry`, which re-fires only the failed ones). Smoke-test
+    with `--limit` under a THROWAWAY `--campaign`: a limited fan-off still
+    records the campaign as fired, and the full run would need `--resend`.
+  - **The audience is the TAG, not the file.** If an earlier run of the same
+    campaign tagged rows since removed from the CSV, python still resolves them —
+    the CLI cross-checks python's count against the CSV after tagging and makes
+    you type `YES` when the tag carries MORE people than the file.
+  - No per-row write-ahead log or `resume` on fresh sends — the campaign log
+    records ONE `handoff` line (broadcastId); delivery/failure detail lives in
+    `bc status <org> <broadcastId> [--failures]` and `bc retry`.
+  - `--rate` / `--skip-upsert` only apply to pre-v0.6.0 `resume`; fresh sends
+    ignore them (python paces itself; the upsert IS the mechanism).
 - **Engine auto-routing (v0.3.6):** any `send --tag` of **more than 10** eligible
   recipients **always uses the python engine** (a `>2000` tag routes there too).
-  Only a ≤10 send stays on the resumable per-row Node engine. `--python` forces
-  python at any size. (CSV per-row sends stay on Node — python takes uniform params.)
+  Only a ≤10 tag send stays on the per-row Node engine. `--python` forces
+  python at any size. **CSV sends are ALWAYS python from v0.6.0** (per-row values
+  ride as contact attributes — see above).
 - **`--python` engine (v0.3.4, `send --tag` only)**: hand the whole send to the
   **python `/meta-broadcast` endpoint** — the *same* sender the dashboard's "Python
   endpoint" toggle uses — via a staff-gated proxy (the master key stays server-side
@@ -319,8 +355,29 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   python for the eligible count + a sample. Trade-off vs the default per-row engine:
   no CLI write-ahead-log / `resume` (python owns the broadcast record), and archived
   contacts aren't separately filtered. Media headers work on both engines.
-- **v1 scope**: Meta orgs, POSITIONAL templates, text / no header / media header.
-  NAMED and carousel templates and WATI orgs are refused with a clear message.
+- **Scope**: Meta orgs, POSITIONAL templates, text / no header / media header,
+  and **carousel templates (tag mode only, v0.4.9)**. NAMED templates and WATI
+  orgs are refused with a clear message; carousels in CSV mode are refused with
+  a pointer to tag mode.
+- **Carousel templates (v0.4.9, `send --tag` only, always the python engine):**
+  the CLI introspects every card (header format, body variables, buttons) and
+  builds the per-card send payload python's `/meta-broadcast` expects. Card
+  media defaults to each card's **stored template image** (written by
+  `create-meta-template` at creation), overridable with repeatable
+  `--card-media <url>` (one per card, in card order); every resolved URL is
+  content-type probed against that card's own IMAGE/VIDEO format (mismatch
+  aborts, per card). Cards whose body carries `{{n}}` variables, or whose URL
+  buttons carry a variable, **require `--cards-file <path>`** — a JSON array
+  with one entry per card:
+  `[{"header_media":"<url>","body_params":{"param1":"…"},"button_payloads":{"btn0":"…"},"url_vars":{"btn1":"<value>"}}, …]`
+  (all keys optional per card; quick-reply payloads default to the button text;
+  `{{first_name}}`-style tokens inside card values are resolved per contact).
+  Carousel sends route to the **python engine at any size** — the per-row Node
+  engine cannot send carousels — so there is no CLI write-ahead log / `resume`
+  for them; audit via `bc status <broadcastId>`. `--at` scheduling works: the
+  card payload is frozen into the queued request. `bc retry` on a carousel
+  broadcast re-resolves card media from the template's stored defaults and does
+  NOT replay per-card body/url values — retry only carousels that need none.
 - **Validation before anything sends**: APPROVED-only, every slot mapped,
   contiguous params (the Meta `#132000` guard — a stray key is structurally
   impossible), phone validity, illegal characters (Meta `#100`; `reject` by
@@ -328,17 +385,19 @@ flowiq bc scheduled cancel  <org_id> <queue_id> --confirm
   blocked contacts are skipped, always.
 - **Dry-run is the default**; `--commit` + typing the campaign name is the
   only way to send (`--yes` for CI skips the typing, never the dry-run).
-- **Write-ahead status log** (`.flowiq/campaigns/<campaign>.status.jsonl`):
-  every row logs `sending` *before* the POST and `sent`/`failed` after. A
-  crash mid-row leaves an *ambiguous* row that is **never auto-resent** —
-  it's surfaced for manual review. `resume` sends only never-attempted rows
-  (`--retry-failed` adds confirmed failures).
-- **Error handling**: `#132000` aborts the run (config bug — every row would
-  fail); rate errors back off exponentially and halve the send rate; a Meta
-  daily-cap soft-stops cleanly with a resume hint.
-- Contacts are **pre-upserted** (`/cli/contacts-upsert`, ≤4000/batch, retries
-  then aborts) so the send payload never needs a `name` key — the classic
-  `#132000` footgun.
+- **Campaign status log** (`.flowiq/campaigns/<campaign>.status.jsonl`): a
+  fresh (v0.6.0) send records a `meta` header + ONE `handoff` line carrying the
+  `broadcastId` — the re-run guard and your local pointer to `bc status`.
+  Pre-v0.6.0 campaigns keep their per-row `sending`/`sent`/`failed` lines and
+  finish on `resume` (ambiguous mid-crash rows are still never auto-resent;
+  `--retry-failed` adds confirmed failures).
+- **Error handling**: all pre-send validation is unchanged and client-side;
+  per-recipient send errors are python-side — audit them with
+  `bc status <org> <broadcastId> --failures`, re-fire with `bc retry`.
+- Contacts are **imported/updated** via `/cli/contacts-upsert` (≤4000/batch,
+  retries then aborts) carrying the campaign tag + attributes; the python
+  params are pure `{{attributes.*}}` tokens, so the payload never needs a
+  `name` key — the classic `#132000` footgun stays structurally impossible.
 
 **Tag mode** — send to everyone carrying a tag (e.g. a `segments` batch tag)
 instead of a CSV. Same guards, same status log, same resume:
@@ -623,6 +682,16 @@ flowiq m pull <contact_id> --count 25
 
 `--count` defaults to 25, max 200.
 
+**When you ask for more than exists, you get the WHOLE history (16 Aug 2026).**
+If the contact has fewer `user-*` messages than `--count`, there is nothing
+older to withhold, so the pull returns every row from the first message onward
+and reports `reached_start: true` (`user msgs: 1/25 requested — that is ALL of
+them; this pull is the entire history`). Before this, the anchor sat on the
+oldest inbound message and silently dropped everything before it — so on a
+contact whose conversation OPENS with an outbound (a delivery notification, a
+broadcast), the message that STARTED the conversation was missing while the
+pull still printed success.
+
 ### Audit log — `flowiq audit [org] | audit show <id>` (v0.3.8)
 
 **Who changed what, when — with the full before/after content.** Every
@@ -727,6 +796,40 @@ Validation: `platform` ∈ `{whatsapp, web}`, `type` from the per-platform
 allowed enum, valid http(s) URL, no duplicate (platform, type, url)
 tuples.
 
+**Auth fields (19 Aug 2026).** Each row also carries `auth_type`
+(`none` | `bearer` | `basic` | `api_key` | `oauth2_client_credentials`),
+`auth_config`, `headers` and `secret` — how FlowIQ authenticates when it POSTs
+the event, plus an optional HMAC signing key. Pull returns all four; push
+writes all four.
+
+**Because push is FULL-REPLACE, a body that omits these fields STRIPS the
+credentials off every webhook.** Always pull-edit-push the same file; never
+hand-write a push body. The dry-run diff includes an auth fingerprint, so
+changing only a credential correctly shows as `to insert 1 / to delete 1`
+rather than "unchanged".
+
+```jsonc
+{
+  "url": "https://middleware.example.com/notification/log",
+  "type": "sent_message",
+  "platform": "whatsapp",
+  "auth_type": "oauth2_client_credentials",
+  "auth_config": {
+    "token_url": "https://middleware.example.com/oauth2/token",
+    "client_id": "acme_flowapt",
+    "client_secret": "…",
+    "scope": "notify:write",        // optional
+    "client_auth": "basic"          // optional: "basic" (default) | "body"
+  },
+  "headers": { "X-Tenant": "acme" },  // optional static headers
+  "secret": "…"                       // optional → X-Flowiq-Signature: sha256=<hmac>
+}
+```
+
+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.
+
 ### FlowMod prompts — `flowiq flowmod pull|push <slug>` (alias `fm`)
 
 Round-trips a FlowMod org's **master-group** prompts + config. FlowMod groups
@@ -802,6 +905,33 @@ 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)
+
+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 via the FlowIQ MCP's
+`log_client_hours` tool. Clients see their own usage on the Client Console;
+the cross-org view lives in the super-admin Changelog dialog → Client hours.
+
+```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
+```
+
+- `log` takes exactly ONE of `--minutes <n>` (whole minutes) or `--hours <h>`
+  (fractions fine — `--hours 1.5` = 90 min). `--desc` is required and should be
+  plain language the client could read (it shows on their Client Console).
+- `--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.
+
 ### WhatsApp templates — `flowiq templates pull|list|create|status` (alias `tpl`)
 
 Read an org's live templates straight from Meta (read-only), and submit new

package/TEAM-GUIDE.md

@@ -60,7 +60,11 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
    would change before anything writes.
 3. **Pushes are full-replace.** What's in your file becomes the whole surface
    (all prompt sections, all tools, all webhooks). Deleting an entry from the
-   file deletes it from the platform.
+   file deletes it from the platform. This is also why you must never
+   hand-write a push body: messaging webhooks carry their own credentials
+   (`auth_type` / `auth_config` / `headers` / `secret`), and a body that leaves
+   those fields out strips the auth off every webhook for that org. Pull, edit
+   that same file, push it.
 4. **`--agent <id>` targets a specific agent**; without it you get the org's
    *active* agent. Files remember which agent they came from, so a push always
    goes back to the agent you pulled — never "whatever is active now".
@@ -101,7 +105,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Short links for every URL in a message | `flowiq links shorten <org_id> --file ./message.txt --campaign X --content X --commit` |
 | Check which links a campaign has, and their clicks | `flowiq links list <org_id> --campaign 13Aug_Seeds` |
 | A link already looks short (`linklnk.io/abc123`) — can I re-tag it? | No: paste the DESTINATION url instead. Re-shortening keeps the old campaign tag and splits the click count, so the CLI refuses it |
-| Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit` |
+| Send a template broadcast to a CSV of people | `flowiq bc map <org_id> --template … --csv …` → `flowiq bc send … ` (dry-run) → `… --commit`. **v0.6.0: the commit imports every row as a contact (tag `bc-<campaign>` + the row's values as attributes) and fires ONE python broadcast** — it returns in seconds with a `broadcastId`; python sends in the background. Check delivery with `bc status`, re-fire failures with `bc retry`. A campaign that already fired refuses a re-run (`--resend` deliberately resends to everyone tagged). |
 | Tag every repeat buyer (e.g. 2+ orders in the last 60 days) | `flowiq seg plan <org_id> --tag-prefix repeat-60d --min-orders 2 --window 60d` → `flowiq seg apply <org_id> repeat-60d` (dry run) → `… --commit` |
 | Tag everyone who bought a product (accurate, windowable) | `flowiq seg plan <org_id> --tag-prefix whey --bought "Whey" --window 90d` → `flowiq seg apply … --commit` |
 | Advanced Tagging in the terminal (one named tag on a matched set) | `flowiq tag field\|cohort\|segment\|attributes\|messages <org_id> …` (dry-run) → add `--tag <name> --commit` |
@@ -114,6 +118,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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` |
 | 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. |
 | 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`) |
@@ -123,16 +128,18 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | **See who changed what, and when** | `flowiq audit <org_id>` — add `--endpoint prompts`, `--user <name>`, `--since 2026-07-01` to narrow |
 | 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 |
+| Read a contact's chat | `flowiq m pull <contact_id>` then open the JSON. Ask for more than exists (`--count 100`) and you get the entire history — it says "that is ALL of them" when there is nothing older |
 | Export an org's full chat history | `flowiq export chats <org_id>` |
 | Check / create WhatsApp templates | `flowiq tpl pull <org_id>` / `flowiq tpl create <org_id> --request-file req.json` |
 | Manage Shopify/Woo platform webhooks | `flowiq wh pull <org_id>` → edit → `flowiq wh push <slug>` |
-| Manage outbound messaging webhooks | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
+| Manage outbound messaging webhooks (incl. their auth) | `flowiq mw pull <org_id>` → `flowiq mw push <slug> --dry-run` → push |
 | Create a brand-new client org | `flowiq org create --name "Client Name"` → then `agent create` on the printed id |
 | See a client's pending change requests | `flowiq au pull <org_id>` |
 | Close a client's change request (after verifying the fix!) | `flowiq au resolve <update_id> --note "what changed"` — the client reads the note |
 | Check an org's platform + active agent | `flowiq org info <org_id>` |
 | 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` |
 | Re-read this guide / the full command reference | `flowiq guide` / `flowiq guide --reference` |
 
 The flow is the same everywhere: **pull → edit the JSON → push**. Slugs are the
@@ -168,6 +175,10 @@ flowiq ct push <slug>
 Custom tools define real HTTP calls the agent can execute, so the server
 validates hard (names, URLs, methods, parameter shapes) and warns about typo'd
 keys or `{{placeholders}}` it doesn't recognise. Take the warnings seriously.
+Nested object/array schemas are 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
+injected server-side and mutations use `{{whatsapp_message_id}}` for idempotency.
 
 ### Example: tag a segment of contacts (Advanced Tagging)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.4.8",
+  "version": "0.6.0",
   "description": "Command-line tool for FlowIQ staff: round-trip agent prompts, questionnaires, fine-tuning, pin-board tasks, webhooks, templates, agent-updates, chat exports, and live agent testing without ever touching service-role credentials.",
   "type": "module",
   "bin": {

package/src/commands/broadcast.js

@@ -6,17 +6,23 @@
 //   send    <org>  --template T --csv F [--commit]       full pipeline; DRY-RUN by default
 //   resume  <org>  --campaign C [--commit]               continue from the status log
 //
-// Pipeline: introspect template (live Meta + DB labels, via /cli/broadcast) →
-// parse CSV → build/load column→param MAPPING (each row fills the template
-// with its OWN values) → validate (V-1..V-13) → broadcast-safety classify
-// (opted-out/archived/blocked are skipped) → preview → [--commit] upsert
-// contacts (/cli/contacts-upsert, ≤4000/batch, 3× retry then ABORT) → send
-// per row via /api/send-template (org-UUID branch, NO auth header), paced
-// ≤10 msg/s, with a WRITE-AHEAD per-row status log:
-//   {status:"sending"} appended BEFORE the POST, the terminal sent/failed
-//   line after — so a crash mid-row leaves an ambiguous row that is NEVER
-//   auto-resent (surfaced for manual review). Resume dedups on
-//   normalized-number-within-campaign, never on CSV fingerprint.
+// Pipeline (v0.6.0 — python server-side fan-out): introspect template (live
+// Meta + DB labels, via /cli/broadcast) → parse CSV → build/load column→param
+// MAPPING (each row fills the template with its OWN values) → validate
+// (V-1..V-13) → broadcast-safety classify (opted-out/archived/blocked are
+// skipped) → preview → [--commit] upsert contacts (/cli/contacts-upsert,
+// ≤4000/batch, 3× retry then ABORT) carrying the campaign TAG bc-<campaign>
+// plus each row's values as campaign-scoped ATTRIBUTES
+// (bc_<campaign>_paramN / _button) → ONE python /meta-broadcast call with
+// {{attributes.bc_<campaign>_paramN}} tokens, which python resolves PER
+// CONTACT (broadcast.py substitute_contact_fields — body AND URL-button
+// params). The send is fire-and-forget: python owns pacing + the broadcast
+// record; audit via `bc status <org> <broadcastId>` / `bc retry`.
+//
+// The OLD per-row Node loop (write-ahead status log, `resume`) survives ONLY
+// to finish campaigns started before v0.6.0 — a fresh CSV send never uses it.
+// A python campaign records ONE {type:"handoff"} line instead; re-running it
+// needs --resend (the tag fan-out cannot skip already-reached rows).
 //
 // #132000 structural guard: the payload builder whitelists /^param\d+$/ keys
 // only — a stray "name" key (which would add a body param on a POSITIONAL
@@ -308,16 +314,18 @@ async function saveCampaign(cfg) {
 async function loadStatusLog(campaign) {
   const map = new Map();
   let header = null;
+  let handoff = null; // last {type:"handoff"} line — a completed python fan-off
   try {
     const text = await fs.readFile(logPath(campaign), "utf8");
     for (const line of text.split("\n")) {
       if (!line.trim()) continue;
       let obj; try { obj = JSON.parse(line); } catch { continue; }
       if (obj.type === "meta") { header = obj; continue; }
+      if (obj.type === "handoff") { handoff = obj; continue; }
       if (obj.type === "row" && obj.number) map.set(obj.number, obj);
     }
   } catch { /* no log yet */ }
-  return { header, map };
+  return { header, map, handoff };
 }
 
 async function appendLog(campaign, obj) {
@@ -380,11 +388,121 @@ function headerMismatchMessage(template, headerMedia, contentType, { explicit })
     : `${base} — the template's stored default header media is broken (created before the 3 Aug 2026 create-meta-template mime fix?); pass --header-media <url> with the real ${template.header_type}`;
 }
 
+// ---------------------------------------------------------------------------
+// carousel card resolution (18 Aug 2026 — tag mode, python engine only)
+// ---------------------------------------------------------------------------
+// Builds the card_overrides[] payload python's /meta-broadcast expects: one
+// entry per card, in card order. Media precedence per card: --cards-file entry
+// header_media → --card-media (positional) → the template's stored default
+// (template_data.carousel.cards[i].header_url, surfaced by introspect). Every
+// resolved URL is content-type probed against that CARD's own header format —
+// a carousel can mix IMAGE and VIDEO cards, so this is per-card, not global.
+// Cards with {{n}} body variables or URL-button variables REQUIRE a
+// --cards-file entry (python emits '' for a missing url var → Meta rejects the
+// whole message, so we refuse client-side). Exported for the test harness.
+
+export async function resolveCarouselCards(template, { cardMediaFlags = [], cardsFileEntries = null } = {}, probe = probeContentType) {
+  const cards = template.carousel_cards || [];
+  const aborts = [], warnings = [], lines = [];
+  const overrides = [];
+  if (!cards.length) {
+    aborts.push("carousel template, but the server returned no card details — api.flowiq.live needs the carousel-aware deploy (api/cli/_introspect.js); until then use the dashboard");
+    return { aborts, warnings, overrides: null, lines };
+  }
+  if (cardMediaFlags.length && cardMediaFlags.length !== cards.length) {
+    aborts.push(`--card-media given ${cardMediaFlags.length} time(s) but the template has ${cards.length} cards — pass one per card, in card order`);
+  }
+  if (cardsFileEntries !== null && (!Array.isArray(cardsFileEntries) || cardsFileEntries.length !== cards.length)) {
+    aborts.push(`--cards-file must be a JSON array with exactly ${cards.length} entries (one per card, in card order)`);
+  }
+  if (aborts.length) return { aborts, warnings, overrides: null, lines };
+
+  for (let i = 0; i < cards.length; i++) {
+    const card = cards[i];
+    const fileEntry = (cardsFileEntries?.[i] && typeof cardsFileEntries[i] === "object") ? cardsFileEntries[i] : {};
+    const media = fileEntry.header_media || cardMediaFlags[i] || card.header_media_default || null;
+    if (!media) {
+      aborts.push(`card ${i + 1}: no media resolved — the template stores no default for this card; pass --card-media <url> (one per card, in order) or a --cards-file entry with header_media`);
+      continue;
+    }
+    const contentType = await probe(media);
+    let mediaLabel;
+    if (!contentType) {
+      warnings.push(`card ${i + 1}: media unverified — ${media} did not answer a type probe`);
+      mediaLabel = `${card.header_format} · unverified`;
+    } else if (contentType.split("/")[0] !== card.header_format) {
+      aborts.push(`card ${i + 1}: the template card header is ${card.header_format.toUpperCase()} but the resolved media (${media}) serves ${contentType} — point it at a real ${card.header_format}`);
+      continue;
+    } else {
+      mediaLabel = `${card.header_format} ✓ ${contentType}`;
+    }
+
+    // Per-card body variables must be supplied — python sends only what we pass.
+    let bodyParams = null;
+    if (card.body_positions.length) {
+      bodyParams = fileEntry.body_params && typeof fileEntry.body_params === "object" ? fileEntry.body_params : null;
+      const badKeys = bodyParams ? Object.keys(bodyParams).filter((k) => !/^param\d+$/.test(k)) : [];
+      if (badKeys.length) { aborts.push(`card ${i + 1}: body_params keys must be param1..N (got ${badKeys.join(", ")})`); continue; }
+      const missing = card.body_positions.filter((p) => !bodyParams?.[`param${p}`]);
+      if (missing.length) {
+        aborts.push(`card ${i + 1}: its body carries variable(s) ${missing.map((p) => `{{${p}}}`).join(", ")} — supply them via --cards-file (entry ${i}: {"body_params":{${card.body_positions.map((p) => `"param${p}":"…"`).join(",")}}}). {{first_name}}-style tokens inside the values are resolved per contact.`);
+        continue;
+      }
+    }
+
+    // URL buttons WITH a variable need a send-side value; static URL / QUICK_REPLY do not
+    // (quick-reply payloads default to the button text server-side).
+    const urlVarButtons = (card.buttons || []).filter((b) => b.type === "URL" && b.has_url_var);
+    let urlVars = null;
+    if (urlVarButtons.length) {
+      urlVars = fileEntry.url_vars && typeof fileEntry.url_vars === "object" ? fileEntry.url_vars : null;
+      const missing = urlVarButtons.filter((b) => {
+        const v = urlVars?.[`btn${b.index}`] ?? urlVars?.[String(b.index)];
+        return v === undefined || v === null || String(v) === "";
+      });
+      if (missing.length) {
+        aborts.push(`card ${i + 1}: button(s) ${missing.map((b) => `"${b.text ?? "URL"}"`).join(", ")} carry a URL variable — supply via --cards-file (entry ${i}: {"url_vars":{${missing.map((b) => `"btn${b.index}":"<value>"`).join(",")}}})`);
+        continue;
+      }
+    }
+    const buttonPayloads = fileEntry.button_payloads && typeof fileEntry.button_payloads === "object" ? fileEntry.button_payloads : null;
+
+    overrides.push({
+      file_url: media,
+      ...(bodyParams ? { body_parameters: bodyParams } : {}),
+      ...(buttonPayloads ? { button_payloads: buttonPayloads } : {}),
+      ...(urlVars ? { url_vars: urlVars } : {}),
+    });
+
+    // Preview lines for the dry-run.
+    let bodyPreview = card.body_text || "";
+    for (const [k, v] of Object.entries(bodyParams || {})) bodyPreview = bodyPreview.replaceAll(`{{${k.replace("param", "")}}}`, String(v));
+    const btnBits = (card.buttons || []).map((b) => {
+      if (b.type === "URL" && b.has_url_var) {
+        const v = urlVars?.[`btn${b.index}`] ?? urlVars?.[String(b.index)] ?? "";
+        return `[${b.text ?? "URL"} → ${String(b.url || "").replace(/\{\{[^}]+\}\}/, String(v))}]`;
+      }
+      if (b.type === "URL") return `[${b.text ?? "URL"} → ${b.url}]`;
+      return `[${b.text ?? b.type}]`;
+    }).join(" ");
+    lines.push(`    Card ${i + 1} (${mediaLabel}): ${media}`);
+    if (bodyPreview) lines.push(`      ${bodyPreview.replace(/\n/g, " ")}`);
+    if (btnBits) lines.push(`      ${btnBits}`);
+  }
+  return { aborts, warnings, overrides: aborts.length ? null : overrides, lines };
+}
+
+function printCarouselPlan(cardOverrides, cardLines) {
+  if (!cardOverrides?.length) return;
+  console.log(`  Carousel (${cardOverrides.length} cards — media re-uploaded to Meta once per broadcast):`);
+  for (const l of cardLines) console.log(l);
+}
+
 function validateRows(template, mapping, headers, rows, illegalChars, headerMedia) {
   const aborts = [];
   if (template.status !== "APPROVED") aborts.push(`V-1: template status is ${template.status} — only APPROVED templates send`);
   if (template.parameter_format !== "POSITIONAL") aborts.push("V-2: NAMED templates are not supported in v1");
-  if (template.is_carousel) aborts.push("V-3: carousel templates are not supported in v1");
+  if (template.is_carousel) aborts.push("V-3: carousel templates are TAG-MODE only — use: flowiq bc send <org> --tag <tag> --template <name> (the python engine sends carousels; per-row CSV carousel sends are not supported)");
   // Media headers (image/video/document) ARE supported — they just need an image
   // URL, exactly like the dashboard. Resolved as --header-media / saved mapping /
   // the template's stored default_url. Only block if a media header has none.
@@ -492,11 +610,54 @@ function renderPreview(template, sample, headerMedia) {
   }
 }
 
-async function upsertContacts(orgId, rows, batchCap) {
+// ---------------------------------------------------------------------------
+// CSV → python fan-out builders (v0.6.0). Exported for the test harness.
+// ---------------------------------------------------------------------------
+
+/** The campaign's contact tag — what python resolves the audience from. */
+export const csvCampaignTag = (campaign) => `bc-${campaign}`;
+
+/** Campaign-scoped attribute key for one template slot ("param1".."paramN" | "button"). */
+export const csvAttrKey = (campaign, slot) => `bc_${campaign}_${slot}`;
+
+/** workSet rows → /cli/contacts-upsert contact rows: tag + per-row values as
+ *  attributes. full_name only when the CSV actually carries a non-empty name
+ *  (the RPC COALESCEs, so an omitted name can never null a real one). */
+export function buildCsvContactRows(workSet, campaign) {
+  const tag = csvCampaignTag(campaign);
+  return workSet.map((r) => {
+    const attributes = {};
+    for (const [k, v] of Object.entries(r.values)) {
+      // Same structural guard as the old per-row payload builder (V-12).
+      if (!/^param\d+$/.test(k)) throw new Error(`internal: stray value key "${k}" — refusing (V-12)`);
+      attributes[csvAttrKey(campaign, k)] = v;
+    }
+    if (r.buttonValue != null) attributes[csvAttrKey(campaign, "button")] = r.buttonValue;
+    return {
+      whatsapp_id: r.number,
+      ...(typeof r.contactName === "string" && r.contactName.trim() ? { full_name: r.contactName.trim() } : {}),
+      tags: [tag],
+      attributes,
+    };
+  });
+}
+
+/** The ONE shared param set handed to python — every value is an
+ *  {{attributes.bc_<campaign>_slot}} token python resolves per contact. */
+export function buildCsvTokenParams(template, campaign) {
+  const body = {};
+  for (const pos of template.body_positions) {
+    body[`param${pos}`] = `{{attributes.${csvAttrKey(campaign, `param${pos}`)}}}`;
+  }
+  const button = template.url_button?.present ? `{{attributes.${csvAttrKey(campaign, "button")}}}` : null;
+  return { body, button };
+}
+
+async function upsertContacts(orgId, contactRows, batchCap) {
   let created = 0, updated = 0, skippedN = 0, dropped = 0;
-  const uniq = rows;
+  const uniq = contactRows;
   for (let i = 0; i < uniq.length; i += batchCap) {
-    const chunk = uniq.slice(i, i + batchCap).map((r) => ({ whatsapp_id: r.number, full_name: r.contactName }));
+    const chunk = uniq.slice(i, i + batchCap);
     let resp = null, lastErr = null;
     for (let attempt = 1; attempt <= 3; attempt++) {
       try { resp = await http.post("contacts-upsert", { organization_id: orgId, contacts: chunk }); break; }
@@ -639,9 +800,16 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   let sendable = await applySafetyExclusions(orgId, valid, skipped);
   if (opts.limit) sendable = sendable.slice(0, Number(opts.limit));
 
-  // resume folding
-  const { header: logHeader, map: statusMap } = await loadStatusLog(campaign);
+  // resume folding (pre-v0.6.0 per-row campaigns only — python campaigns have no per-row log)
+  const { header: logHeader, map: statusMap, handoff } = await loadStatusLog(campaign);
   if (isResume) {
+    if (handoff) {
+      console.error(`Campaign "${campaign}" already fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
+      console.error("There is no per-row resume on the python engine — python owns the send. Audit / re-fire failures with:");
+      console.error(`  flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
+      console.error(`  flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
+      process.exit(1);
+    }
     if (!logHeader) { console.error(`No status log for campaign "${campaign}" — nothing to resume.`); process.exit(1); }
     if (logHeader.csv_fingerprint && logHeader.csv_fingerprint !== csv.header_fingerprint) {
       console.error("CSV headers changed since this campaign started — start a NEW campaign instead of resuming.");
@@ -668,37 +836,142 @@ async function runPipeline(orgId, opts, { commitStage, isResume }) {
   console.log(`Summary: ${sendable.length} sendable · skipped ${skipped.length} (${Object.entries(skippedByReason).map(([k, v]) => `${k}: ${v}`).join(", ") || "none"})`);
   if (statusMap.size) console.log(`Status log: ${[...statusMap.values()].filter((s) => s.status === "sent").length} already sent · work set ${workSet.length}`);
   if (ambiguous.length) console.log(`⚠ ${ambiguous.length} number(s) have an AMBIGUOUS in-flight status (crash mid-send?) — never auto-resent: ${ambiguous.slice(0, 5).join(", ")}${ambiguous.length > 5 ? "…" : ""}. Check the chat, then edit the status log if they must be retried.`);
-  console.log(`Upsert plan: ${workSet.length} contacts in ${Math.ceil(workSet.length / CONTACT_BATCH_CAP)} batch(es)`);
-  const rate = Math.min(Number(opts.rate ?? 8) || 8, HARD_RATE_CAP);
-  console.log(`Send plan:   ${workSet.length} messages @ ≤${rate}/s ≈ ${Math.ceil(workSet.length / rate)}s`);
+  // ── OLD-STYLE RESUME (pre-v0.6.0 per-row campaign): finish it on the Node loop ──
+  if (isResume) {
+    const rate = Math.min(Number(opts.rate ?? 8) || 8, HARD_RATE_CAP);
+    console.log(`Send plan:   ${workSet.length} messages @ ≤${rate}/s (per-row Node loop — pre-v0.6.0 campaign)`);
+    if (!commitStage) {
+      console.log("");
+      console.log("DRY RUN — nothing was sent, no contacts written. Add --commit to send.");
+      return;
+    }
+    if (!workSet.length) { console.log("Nothing to send — all rows are already sent/skipped."); return; }
+    if (!opts.yes) {
+      console.log("");
+      const answer = await ask(`Type the campaign name ("${campaign}") to send ${workSet.length} message(s): `);
+      if (answer !== campaign) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+    }
+    await executeSendLoop({
+      orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
+      skippedCount: skipped.length,
+      writeMetaHeader: !logHeader,
+      metaExtras: { csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length },
+    });
+    return;
+  }
+
+  // ── FRESH SEND: python server-side fan-out (v0.6.0) ────────────────────────
+  // Per-row values ride as campaign-scoped contact attributes; ONE python
+  // /meta-broadcast call resolves {{attributes.bc_<campaign>_paramN}} per
+  // contact and paces the send server-side. No laptop in the loop.
+  const tag = csvCampaignTag(campaign);
+  const tokens = buildCsvTokenParams(template, campaign);
+  const batchCap = Math.min(Number(opts.upsertBatch ?? CONTACT_BATCH_CAP) || CONTACT_BATCH_CAP, CONTACT_BATCH_CAP);
+  if (opts.skipUpsert) console.log("⚠ --skip-upsert is ignored on the python CSV path — the upsert IS how per-row values reach python.");
+  console.log(`Engine:      PYTHON server-side fan-out (yapi.store/meta-broadcast) — fire-and-forget, python-paced`);
+  console.log(`Tag:         "${tag}"  ·  per-row values → attributes bc_${campaign}_param1..${template.body_var_count}${tokens.button ? " + _button" : ""}`);
+  console.log(`Plan:        upsert+tag ${workSet.length} contact(s) in ${Math.ceil(Math.max(1, workSet.length) / batchCap)} batch(es) → one python broadcast`);
+
+  // A prior fan-off means the tag already reached its audience — re-running
+  // resends to EVERY tagged contact (python cannot skip per row).
+  if (handoff && !opts.resend) {
+    console.log("");
+    console.log(`⚠ Campaign "${campaign}" ALREADY fanned out via python on ${handoff.at}${handoff.broadcast_id ? ` (broadcastId ${handoff.broadcast_id})` : ""}.`);
+    if (!commitStage) {
+      console.log("  A --commit re-run would resend to EVERY tagged contact (no per-row skip). Audit with bc status; re-fire failures with bc retry; pass --resend to deliberately resend to all.");
+    } else {
+      console.error("  Refusing to resend to the whole tag. Audit / re-fire failures with:");
+      console.error(`    flowiq bc status ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} [--failures]`);
+      console.error(`    flowiq bc retry  ${orgId} ${handoff.broadcast_id || "<broadcast_id>"} --commit`);
+      console.error("  To deliberately resend to EVERYONE tagged, pass --resend.");
+      process.exit(1);
+    }
+  }
+  // A pre-v0.6.0 per-row log means part of the audience was already reached
+  // row-by-row — the tag fan-out cannot skip them, so this campaign must be
+  // finished on the old engine (bc resume) or restarted under a fresh slug.
+  if (statusMap.size > 0) {
+    const sentAlready = [...statusMap.values()].filter((s) => s.status === "sent").length;
+    if (!commitStage) {
+      console.log("");
+      console.log(`⚠ This campaign has a pre-v0.6.0 per-row status log (${sentAlready} already sent). A --commit here would be refused — finish it with \`flowiq bc resume\`, or start a fresh --campaign.`);
+    } else {
+      console.error("");
+      console.error(`Refusing: campaign "${campaign}" has a pre-v0.6.0 per-row status log (${sentAlready} row(s) already sent).`);
+      console.error("The python fan-out sends to the WHOLE tag and cannot skip already-sent rows. Either:");
+      console.error(`  flowiq bc resume ${orgId} --campaign ${campaign} --commit     # finish on the old per-row engine`);
+      console.error("  …or re-run under a NEW --campaign slug (fresh tag, everyone in the CSV gets it).");
+      process.exit(1);
+    }
+  }
 
   if (!commitStage) {
     console.log("");
-    console.log("DRY RUN — nothing was sent, no contacts written. Add --commit to send.");
+    console.log("DRY RUN — nothing was sent, no contacts written or tagged. Add --commit to send.");
     return;
   }
-  if (!workSet.length) { console.log("Nothing to send — all rows are already sent/skipped."); return; }
+  if (!workSet.length) { console.log("Nothing to send — all rows were skipped."); return; }
 
-  // 8. gate
+  // 8. gate (BEFORE any write — the upsert itself tags real contacts)
   if (!opts.yes) {
     console.log("");
-    const answer = await ask(`Type the campaign name ("${campaign}") to send ${workSet.length} message(s): `);
-    if (answer !== campaign) { console.log("Mismatch — aborted, nothing sent."); process.exit(0); }
+    const answer = await ask(`Type the campaign name ("${campaign}") to tag ${workSet.length} contact(s) and fire ONE python broadcast: `);
+    if (answer !== campaign) { console.log("Mismatch — aborted, nothing written, nothing sent."); process.exit(0); }
   }
 
-  // 9. upsert
-  if (!opts.skipUpsert && !(isResume && logHeader)) {
-    try { await upsertContacts(orgId, workSet, Math.min(Number(opts.upsertBatch ?? CONTACT_BATCH_CAP) || CONTACT_BATCH_CAP, CONTACT_BATCH_CAP)); }
-    catch (e) { console.error(e.message); process.exit(1); }
+  // 9. upsert: tag + per-row attributes (the fan-out's data plane)
+  try { await upsertContacts(orgId, buildCsvContactRows(workSet, campaign), batchCap); }
+  catch (e) { console.error(e.message); process.exit(1); }
+
+  // 10. python dry-run cross-check: what does the tag ACTUALLY resolve to?
+  const reqBody = (dryRun) => ({
+    action: "send-python", organization_id: orgId, tag, template_name: templateName,
+    body_parameters: tokens.body,
+    ...(tokens.button ? { button_parameters: { param1: tokens.button } } : {}),
+    ...(headerMedia ? { header_media: headerMedia } : {}),
+    dry_run: dryRun,
+  });
+  let pyTotal = null;
+  try {
+    const dry = await http.post("broadcast", reqBody(true));
+    pyTotal = dry.total_contacts_found ?? null;
+  } catch (e) {
+    console.error(`Python dry-run failed after tagging: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`);
+    console.error(`Nothing sent. The ${workSet.length} contact(s) ARE tagged "${tag}" — re-run to retry the fan-off.`);
+    process.exit(1);
+  }
+  if (pyTotal != null && pyTotal !== workSet.length) {
+    if (pyTotal > workSet.length) {
+      console.log(`⚠ Tag "${tag}" resolves to ${pyTotal} contact(s) — ${pyTotal - workSet.length} MORE than this CSV (tagged by an earlier run of this campaign?). They will ALSO receive the send.`);
+      if (!opts.yes) {
+        const extra = await ask(`Type YES to send to all ${pyTotal}: `);
+        if (extra !== "YES") { console.log(`Aborted — nothing sent. The tag still carries ${pyTotal} contact(s); use a fresh --campaign for a clean audience.`); process.exit(0); }
+      }
+    } else {
+      console.log(`Note: python resolves ${pyTotal} of ${workSet.length} tagged (the rest are opted-out/blocked server-side).`);
+    }
   }
 
-  // 10-11. send loop + report (shared with the --tag pipeline)
-  await executeSendLoop({
-    orgId, campaign, templateName, workSet, statusMap, rate, headerMedia,
-    skippedCount: skipped.length,
-    writeMetaHeader: !logHeader,
-    metaExtras: { csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length },
+  // 11. fire — ONE call; python paces + tracks the rest
+  let out;
+  try { out = await http.post("broadcast", reqBody(false)); }
+  catch (e) { console.error(`Python broadcast failed: ${e.message}${e.body?.error ? ` — ${e.body.error}` : ""}`); process.exit(1); }
+  if (!logHeader) {
+    await appendLog(campaign, {
+      type: "meta", campaign, organization_id: orgId, template_name: templateName, engine: "python",
+      csv_fingerprint: csv.header_fingerprint, total_rows: csv.rows.length, valid_rows: sendable.length,
+      started_at: new Date().toISOString(),
+    });
+  }
+  await appendLog(campaign, {
+    type: "handoff", engine: "python", tag, broadcast_id: out.broadcastId ?? out.broadcast_id ?? null,
+    tagged: workSet.length, python_total: pyTotal, at: new Date().toISOString(),
   });
+  console.log("");
+  console.log(`✅ ${out.message || "Broadcast started"}${out.broadcastId ? `  ·  broadcastId ${out.broadcastId}` : ""}`);
+  console.log(`   Python is sending in the background to tag "${tag}" (${pyTotal ?? workSet.length} contact(s)) and tracking it under that broadcast id.`);
+  console.log(`   Delivery:  flowiq bc status ${orgId} ${out.broadcastId || "<broadcast_id>"} [--failures]`);
+  console.log(`   Failures:  flowiq bc retry  ${orgId} ${out.broadcastId || "<broadcast_id>"} --commit`);
 }
 
 /** The paced, write-ahead-logged per-row send loop + final report. */
@@ -793,12 +1066,13 @@ export function collectKV(pair, mapAcc) {
  *  (allow_broadcast=true, not blocked) and sends in the background, returning a
  *  broadcastId. No CLI write-ahead log / resume for this engine (python owns the
  *  broadcast record). Dry-run (no --commit) asks python for the eligible count. */
-async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage }) {
+async function runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [] }) {
   const reqBody = (dryRun) => ({
     action: "send-python", organization_id: orgId, tag, template_name: templateName,
     body_parameters: bodyLiterals,
     ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
     ...(headerMedia ? { header_media: headerMedia } : {}),
+    ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
     dry_run: dryRun,
   });
 
@@ -813,6 +1087,7 @@ async function runPythonTagSend(orgId, { opts, tag, templateName, template, head
   console.log(`Tag "${tag}": ${total} eligible contact(s) (allow_broadcast + not blocked, resolved server-side).`);
   const sampleNum = dry.sample_contacts?.[0]?.whatsapp_id || dry.sample_contacts?.[0]?.phone_number || "<first eligible>";
   renderPreview(template, { rownum: 1, number: sampleNum, values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  printCarouselPlan(cardOverrides, cardLines);
   if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
     console.log("  ({{first_name}}-style tokens are resolved PER CONTACT by python)");
   }
@@ -867,12 +1142,28 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
     ? (opts.headerMedia || cfg?.header_media || template.header_media_default || null)
     : null;
   const headerCheck = await verifyHeaderMedia(template, headerMedia);
-  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerCheck.label}${template.url_button?.present ? ", dynamic URL button" : ""}`);
+  console.log(`Template ${template.name} [${template.status}] — ${template.parameter_format}, ${template.body_var_count} body var(s), header ${template.header_type}${headerCheck.label}${template.url_button?.present ? ", dynamic URL button" : ""}${template.is_carousel ? `, CAROUSEL (${template.carousel_cards?.length ?? "?"} cards)` : ""}`);
   const aborts = [];
   if (headerCheck.status === "mismatch") aborts.push(headerMismatchMessage(template, headerMedia, headerCheck.contentType, { explicit: !!opts.headerMedia }));
   if (template.status !== "APPROVED") aborts.push(`template status is ${template.status} — only APPROVED templates send`);
   if (template.parameter_format !== "POSITIONAL") aborts.push("NAMED templates are not supported in v1");
-  if (template.is_carousel) aborts.push("carousel templates are not supported in v1");
+  // Carousel templates (18 Aug 2026): supported in tag mode via the python
+  // engine. Resolve + verify every card BEFORE any other gate so a dry run
+  // reports the full card plan (or every card problem at once).
+  let carouselPlan = null;
+  if (template.is_carousel) {
+    let cardsFileEntries = null;
+    let cardsFileBroken = false;
+    if (opts.cardsFile) {
+      try { cardsFileEntries = JSON.parse(await fs.readFile(opts.cardsFile, "utf8")); }
+      catch (e) { aborts.push(`--cards-file ${opts.cardsFile}: ${e.message}`); cardsFileBroken = true; }
+    }
+    if (!cardsFileBroken) {
+      carouselPlan = await resolveCarouselCards(template, { cardMediaFlags: opts.cardMedia || [], cardsFileEntries });
+      for (const w of carouselPlan.warnings) console.log(`⚠ ${w}`);
+      aborts.push(...carouselPlan.aborts);
+    }
+  }
   // Media headers supported — need an image (--header-media / saved / default_url).
   if (isMediaHeader && !headerMedia) aborts.push(`template has a ${template.header_type} header but no image resolved — pass --header-media <url> (the template has no stored default header image)`);
   const keys = Object.keys(bodyLiterals);
@@ -885,14 +1176,22 @@ async function runTagPipeline(orgId, opts, { commitStage }) {
   // gated by exactly the same checks as an immediate one (APPROVED, positional,
   // param arithmetic, header-media type). Instead of sending we queue the send
   // for later; python resolves the tag at FIRE time, so the audience is fresh.
-  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+  const cardOverrides = carouselPlan?.overrides ?? null;
+  const cardLines = carouselPlan?.lines ?? [];
+
+  if (opts.at) return scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines });
 
   // ENGINE ROUTING (policy): any send of MORE THAN 10 recipients ALWAYS uses the
   // python /meta-broadcast engine (the proven bulk sender). --python forces it at
   // any size; only a ≤10 send stays on the resumable per-row Node engine.
+  // Carousels are python at ANY size — the per-row Node engine
+  // (/api/send-template) has no carousel support.
   const PYTHON_MIN = 10;
-  if (opts.python) {
-    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage });
+  if (template.is_carousel && !opts.python) {
+    console.log("Carousel template → PYTHON engine at any size (the per-row Node engine cannot send carousels).");
+  }
+  if (opts.python || template.is_carousel) {
+    return runPythonTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides, cardLines });
   }
 
   // resolve the tag server-side (broadcast-safe recipients only). A >2000 tag
@@ -985,6 +1284,10 @@ export async function map(orgId, opts = {}) {
   let intro;
   try { intro = await introspect(orgId, opts.template); }
   catch (e) { console.error(`Template introspection failed: ${e.message}`); if (e.body?.error) console.error(`  ${e.body.error}`); process.exit(1); }
+  if (intro.template.is_carousel) {
+    console.error("Carousel templates are TAG-MODE only (no CSV mapping) — use: flowiq bc send <org> --tag <tag> --template <name>.");
+    process.exit(1);
+  }
   let csv;
   try { csv = await loadCsv(opts.csv); }
   catch (e) { console.error(`CSV error: ${e.message}`); process.exit(1); }
@@ -1050,7 +1353,7 @@ const fmtSast = (iso) =>
   new Date(iso).toLocaleString("en-ZA", { timeZone: "Africa/Johannesburg", dateStyle: "medium", timeStyle: "short" });
 
 /** Queue a tag broadcast to fire later (server writes the api_request_queue row). */
-async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage }) {
+async function scheduleTagSend(orgId, { opts, tag, templateName, template, headerMedia, bodyLiterals, buttonLiteral, commitStage, cardOverrides = null, cardLines = [] }) {
   const when = parseSastAt(opts.at);
   if (when.error) { console.error(`Error: --at ${when.error}`); process.exit(1); }
   if (new Date(when.iso).getTime() <= Date.now()) {
@@ -1061,13 +1364,14 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
 
   console.log("");
   renderPreview(template, { rownum: 1, number: "(resolved at send time)", values: bodyLiterals, buttonValue: buttonLiteral }, headerMedia);
+  printCarouselPlan(cardOverrides, cardLines);
   if (Object.values(bodyLiterals).some((v) => /\{\{(first_name|full_name|email|phone_number|whatsapp_id)\}\}/.test(String(v)))) {
     console.log("  ({{first_name}}-style tokens are resolved PER CONTACT at send time)");
   }
   console.log("");
   console.log(`Schedule:    ${fmtSast(when.iso)} SAST${when.explicitOffset ? "" : "  (--at read as SAST)"}`);
   console.log(`Audience:    tag "${tag}" — resolved when it FIRES, not now (so late joiners are included)`);
-  console.log(`Engine:      python /meta-broadcast`);
+  console.log(`Engine:      python /meta-broadcast${cardOverrides ? ` · carousel, ${cardOverrides.length} cards (frozen into the queued request)` : ""}`);
   console.log(needsApproval
     ? `Approval:    REQUIRED — parks as 'request'; run "flowiq bc scheduled approve" before it can fire`
     : `Approval:    none — fires automatically at the scheduled time`);
@@ -1090,6 +1394,7 @@ async function scheduleTagSend(orgId, { opts, tag, templateName, template, heade
       body_parameters: bodyLiterals,
       ...(buttonLiteral ? { button_parameters: { param1: buttonLiteral } } : {}),
       ...(headerMedia ? { header_media: headerMedia } : {}),
+      ...(cardOverrides ? { card_overrides: cardOverrides } : {}),
     });
   } catch (e) {
     console.error(`Schedule failed: ${e.message}`);

package/src/commands/hours.js

@@ -0,0 +1,150 @@
+// `flowiq hours log <org> --minutes N|--hours H --desc "…"` / `list <org>` /
+// `summary`. The client-hours ledger: every org's package includes 10 hours of
+// Flowapt work per calendar month, and every piece of client work gets logged
+// against it (manually here, or automatically by Claude via the FlowIQ MCP).
+// All writes happen server-side (/cli/hours) with the staff token.
+
+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;
+const MONTH_RE = /^\d{4}-(0[1-9]|1[0-2])$/;
+
+function fmtHours(minutes) {
+  const h = minutes / 60;
+  return `${Number.isInteger(h) ? h : h.toFixed(1)}h`;
+}
+
+function requireOrg(orgId) {
+  if (!UUID_RE.test(orgId || "")) {
+    console.error(`Error: "${orgId}" is not a valid organization UUID (find it with \`flowiq org list <search>\`).`);
+    process.exit(1);
+  }
+}
+
+function requireMonth(month) {
+  if (month && !MONTH_RE.test(month)) {
+    console.error(`Error: --month must be YYYY-MM (got "${month}").`);
+    process.exit(1);
+  }
+}
+
+/** --minutes and --hours are alternatives; exactly one must yield an integer minute count. */
+function resolveMinutes(opts) {
+  const hasMinutes = opts.minutes !== undefined;
+  const hasHours = opts.hours !== undefined;
+  if (hasMinutes === hasHours) {
+    console.error("Error: pass exactly one of --minutes <n> or --hours <h> (e.g. --hours 1.5).");
+    process.exit(1);
+  }
+  let minutes;
+  if (hasMinutes) {
+    minutes = Number(opts.minutes);
+    if (!Number.isInteger(minutes)) {
+      console.error(`Error: --minutes must be a whole number (got "${opts.minutes}"). Use --hours for fractions.`);
+      process.exit(1);
+    }
+  } else {
+    const h = Number(opts.hours);
+    if (!Number.isFinite(h)) {
+      console.error(`Error: --hours must be a number (got "${opts.hours}").`);
+      process.exit(1);
+    }
+    minutes = Math.round(h * 60);
+  }
+  if (minutes < 1 || minutes > 6000) {
+    console.error(`Error: the entry must be between 1 minute and 100 hours (got ${minutes} min).`);
+    process.exit(1);
+  }
+  return minutes;
+}
+
+export async function log(orgId, opts) {
+  requireOrg(orgId);
+  const minutes = resolveMinutes(opts);
+  const description = (opts.desc || "").trim();
+  if (!description) {
+    console.error('Error: --desc "what was done" is required.');
+    process.exit(1);
+  }
+  if (opts.date && !/^\d{4}-\d{2}-\d{2}$/.test(opts.date)) {
+    console.error(`Error: --date must be YYYY-MM-DD (got "${opts.date}").`);
+    process.exit(1);
+  }
+
+  let resp;
+  try {
+    resp = await http.post("hours", {
+      organization_id: orgId,
+      description,
+      minutes,
+      performed_by: opts.by || undefined,
+      session: opts.session || undefined,
+      // A bare date logs at noon UTC so it can never slip into a neighbouring
+      // day (or month) in any sane timezone rendering.
+      performed_at: opts.date ? `${opts.date}T12:00:00Z` : undefined,
+    });
+  } catch (e) {
+    console.error(`Log failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  const used = resp.month_total_minutes;
+  const allowance = resp.allowance_hours * 60;
+  console.log(`Logged ${fmtHours(minutes)} for ${resp.organization.name}`);
+  console.log(`  entry:  ${resp.id}`);
+  console.log(`  month:  ${resp.month} — ${fmtHours(used)} of ${resp.allowance_hours}h package used${used > allowance ? `  ⚠ ${fmtHours(used - allowance)} OVER` : ` (${fmtHours(allowance - used)} left)`}`);
+}
+
+export async function list(orgId, opts) {
+  requireOrg(orgId);
+  requireMonth(opts.month);
+  let resp;
+  try {
+    resp = await http.get("hours", { organization_id: orgId, month: opts.month });
+  } catch (e) {
+    console.error(`List failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const over = resp.remaining_minutes < 0;
+  console.log(`${resp.organization.name} — ${resp.month}`);
+  console.log(`  package: ${resp.allowance_hours}h/month · used ${fmtHours(resp.total_minutes)} · ${over ? `⚠ ${fmtHours(-resp.remaining_minutes)} OVER` : `${fmtHours(resp.remaining_minutes)} left`}`);
+  if (!resp.entries.length) {
+    console.log("  (no entries this month)");
+    return;
+  }
+  console.log("");
+  for (const e of resp.entries) {
+    const when = String(e.performed_at).slice(0, 10);
+    const src = e.source === "manual" ? "ui" : e.source;
+    console.log(`  ${when}  ${fmtHours(e.minutes).padStart(6)}  [${src}]  ${e.performed_by} — ${e.description}`);
+  }
+}
+
+export async function summary(opts) {
+  requireMonth(opts.month);
+  let resp;
+  try {
+    resp = await http.get("hours", { summary: "1", month: opts.month });
+  } catch (e) {
+    console.error(`Summary failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  if (!resp.organizations.length) {
+    console.log(`(no hours logged for any org in ${resp.month})`);
+    return;
+  }
+  const allowance = resp.allowance_hours * 60;
+  console.log(`Client hours — ${resp.month} (package: ${resp.allowance_hours}h/month per org)\n`);
+  for (const o of resp.organizations) {
+    const flag = o.total_minutes > allowance ? `  ⚠ ${fmtHours(o.total_minutes - allowance)} OVER` : "";
+    console.log(`  ${fmtHours(o.total_minutes).padStart(6)}  (${String(o.entries).padStart(2)} entr${o.entries === 1 ? "y" : "ies"})  ${o.name || o.id}${flag}`);
+  }
+}

package/src/commands/messages.js

@@ -56,8 +56,11 @@ export async function pull(contactId, opts = {}) {
   if (resp.organization_name) {
     console.log(`  organization:   ${resp.organization_name} (${resp.organization_id})`);
   }
-  console.log(`  user msgs:      ${resp.user_messages_found}/${resp.user_messages_requested} requested`);
-  console.log(`  anchor:         ${resp.anchor_created_at}`);
+  console.log(
+    `  user msgs:      ${resp.user_messages_found}/${resp.user_messages_requested} requested` +
+    (resp.reached_start ? ` — that is ALL of them; this pull is the entire history` : '')
+  );
+  console.log(`  anchor:         ${resp.anchor_created_at}${resp.reached_start ? ' (start of history)' : ''}`);
   console.log(`  total rows:     ${resp.total_rows}`);
   console.log(`  by sender:`);
   for (const [k, v] of Object.entries(resp.sender_breakdown).sort()) {

package/src/commands/messaging-webhooks.js

@@ -97,8 +97,15 @@ export async function push(identifier, opts = {}) {
   try {
     resp = await http.post("messaging-webhooks", {
       organization_id: data.organization_id,
+      // auth_type / auth_config / headers / secret ride along deliberately:
+      // push is FULL-REPLACE (delete-all then insert), so dropping them here
+      // would silently strip every webhook's credentials on the next push.
       messaging_webhooks: data.messaging_webhooks.map((w) => ({
         url: w.url, type: w.type, platform: w.platform,
+        auth_type: w.auth_type ?? "none",
+        auth_config: w.auth_config ?? null,
+        headers: w.headers ?? null,
+        secret: w.secret ?? null,
       })),
       dry_run: !!opts.dryRun,
     });

package/src/index.js

@@ -15,6 +15,7 @@ import * as webhooksCmd from "./commands/webhooks.js";
 import * as flowmodCmd from "./commands/flowmod.js";
 import * as groupsCmd from "./commands/groups.js";
 import * as pinboardCmd from "./commands/pinboard.js";
+import * as hoursCmd from "./commands/hours.js";
 import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
@@ -191,6 +192,29 @@ export function run(argv) {
     .description("List every task in the DB (optionally filter: open | in_progress | done) to find an id")
     .action((status) => pinboardCmd.listRemote(status));
 
+  // hours (client-hours ledger — every org's package = 10h Flowapt work/month)
+  const hours = program.command("hours")
+    .description("Client-hours ledger: log + report Flowapt work against each org's 10h/month package");
+  hours.command("log <organization_id>")
+    .description("Log work done for a client org (exactly one of --minutes / --hours)")
+    .option("--minutes <n>", "duration in whole minutes")
+    .option("--hours <h>", "duration in hours (fractions fine, e.g. 1.5)")
+    .option("--desc <text>", "what was done, in plain language the client could read")
+    .option("--by <name>", "who did the work (default: your staff login email)")
+    .option("--session <name>", "session/task name the work happened in")
+    .option("--date <YYYY-MM-DD>", "when the work was done (default: now)")
+    .action((orgId, opts) => hoursCmd.log(orgId, opts));
+  hours.command("list <organization_id>")
+    .description("One org's entries + package standing for a month (default: current)")
+    .option("--month <YYYY-MM>", "which month to report")
+    .option("--json", "raw JSON output")
+    .action((orgId, opts) => hoursCmd.list(orgId, opts));
+  hours.command("summary")
+    .description("Cross-org month totals — every org with logged work, vs the 10h package")
+    .option("--month <YYYY-MM>", "which month to report")
+    .option("--json", "raw JSON output")
+    .action((opts) => hoursCmd.summary(opts));
+
   // templates (read WhatsApp templates from Meta; create via /cli/meta-templates)
   const templates = program.command("templates")
     .alias("tpl")
@@ -432,6 +456,8 @@ export function run(argv) {
     .option("--button <k=v>", "with --tag: dynamic URL button param, e.g. --button param1=<short-code>", broadcastCmd.collectKV, {})
     .option("--campaign <name>", "campaign id / config file slug (default: CSV filename / tag)")
     .option("--header-media <url>", "header image/video/doc URL for a media-header template (default: the template's own stored image)")
+    .option("--card-media <url>", "with --tag, carousel templates: card image/video URL in card order (repeatable — one per card; default: each card's stored template image)", (v, acc) => (acc || []).concat([v]), [])
+    .option("--cards-file <path>", "with --tag, carousel templates: JSON file of per-card overrides [{header_media?, body_params?, button_payloads?, url_vars?}] — required when cards carry {{n}} body variables or URL-button variables")
     .option("--python", "with --tag: force the python /meta-broadcast engine (same as the dashboard's Python toggle). NOTE: any tag send >10 recipients ALWAYS uses python automatically")
     .option("--at <when>", "with --tag: SCHEDULE instead of sending now — \"YYYY-MM-DD HH:MM\" in SAST (e.g. --at \"2026-08-05 09:00\"). Fires automatically; audience is resolved at send time")
     .option("--needs-approval", "with --at: park it awaiting approval (flowiq bc scheduled approve) instead of firing automatically")
@@ -439,11 +465,12 @@ export function run(argv) {
     .option("--yes", "skip the type-the-campaign-name confirm gate (CI)")
     .option("--force-remap", "ignore the saved mapping and rebuild interactively")
     .option("--illegal-chars <mode>", "reject | strip — newlines/tabs/4+ spaces in values (Meta #100)", "reject")
-    .option("--rate <n>", "max messages per second (hard cap 10)", "8")
+    .option("--rate <n>", "max messages per second — ONLY the pre-v0.6.0 per-row resume path; python paces fresh sends itself", "8")
     .option("--upsert-batch <n>", "contacts per upsert call (max 4000)", "4000")
-    .option("--skip-upsert", "assume contacts already exist; skip the upsert stage")
-    .option("--limit <n>", "only process the first N valid rows (smoke test)")
-    .option("--resume", "continue from the existing status log instead of starting fresh")
+    .option("--skip-upsert", "pre-v0.6.0 resume only — ignored on fresh CSV sends (the upsert IS how per-row values reach python)")
+    .option("--limit <n>", "only process the first N valid rows (smoke-test under a THROWAWAY --campaign — a limited python fan-off still records the campaign as fired)")
+    .option("--resend", "re-fire a CSV campaign that already fanned out via python — resends to EVERY tagged contact, incl. those already reached (bc retry re-fires failures only)")
+    .option("--resume", "continue a pre-v0.6.0 per-row campaign from its status log (python campaigns have no per-row resume — use bc status / bc retry)")
     .option("--retry-failed", "with --resume: also re-attempt rows previously marked failed")
     .action((orgId, opts) => broadcastCmd.send(orgId, opts));
   broadcast.command("resume <organization_id>")