@flowapt/flowiq-cli 0.6.3 → 0.6.6

package/README.md

@@ -187,8 +187,8 @@ 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`. 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`).
+- 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.
+- **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`.
 - **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.
 
@@ -485,6 +485,14 @@ flowiq seg untag <org_id> repeat-60d --commit --confirm   # ROLLBACK (its own ta
   shuffle reproducible, `--ordered` keeps server order. `--from-attribute
   allow_broadcast_true --split 3` is the "whole broadcast list → 3 balanced
   tagged cohorts" one-liner — no id file, no database access.
+- **`--start-index N` continues an existing batch series** (v0.6.4, 3 Sep 2026).
+  Batch tags are always numbered from `01`, so a campaign already holding
+  `f500-batch-01…12` could not get its 13th batch from the CLI — the plan would
+  have produced `f500-batch-01` again and, because apply is append-only, quietly
+  MERGED a new cohort into the oldest one. `--start-index 13` names the batch
+  `f500-batch-13`. `plan` now also **refuses outright** when any batch tag it
+  would create already holds contacts, printing the correct `--start-index` to
+  use; `--allow-existing-tag` overrides when the merge is deliberate.
 - Apply is **append-only** — it never touches a contact's other tags, names,
   or anything else, and never double-adds.
 - **Large cohorts are chunked server-side** (fixed 3 Aug 2026): the tagging RPC
@@ -943,6 +951,37 @@ flowiq hours summary                          # every org with logged work this
 - Corrections (delete/edit) live in the Changelog → Client hours page, not the
   CLI. Every `log` is audited.
 
+### Client deck — `flowiq report deck status|build|narrate|generate|inputs|approve|unapprove|send|print|pull` (v0.6.5)
+
+The monthly 10-slide client deck (`/reporting/deck` in the app), driven from the
+terminal. Everything runs server-side through the `flowiq-reporting-deck` edge
+function: the metrics are built from the FROZEN month snapshot, the copy is
+written by the model under the report rules and a numeric guard (every figure
+in the copy must exist in the data), approval needs the required inputs, and
+`send` renders the approved slides with headless Chrome and emails the PDF
+from flowiq@flowapt.com.
+
+```bash
+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 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
+flowiq report deck send <org_id> 2026-08 --test-to me@flowapt.com   # one test copy, status untouched
+flowiq report deck send <org_id> 2026-08 --client          # approved deck → configured client recipients
+flowiq report deck print <org_id> 2026-08                  # 15-minute print URL (what Chrome renders)
+flowiq report deck pull <org_id> 2026-08                   # → ./.flowiq/reports/<slug>-2026-08.json
+```
+
+- Months freeze on the 1st (cron 82); a month with no snapshot cannot be built.
+  Comparisons need the prior month's deck, which `build` creates on the fly.
+- `inputs.json` shape: `{ "changes": { "<update_id>": { "hidden": false, "tag": "client_raised|flowapt_shipped", "title": "…", "description": "…" } }, "changes_reviewed": true, "action_points": { "<title>": "done|in_progress|waiting_on_you|ongoing|dropped" }, "waiting_on_you": [{ "title": "…", "unlocks": "…" }], "recipients_confirmed": true }`.
+  Free text (milestone, the four plan fields) is edited in the app; it is stored as overrides that survive `narrate`.
+- `send --client` needs an approved deck AND `report.email.recipients` in the org's reporting config (Control center → Report delivery); it marks the deck `sent`. `--test-to` never changes status. Fees on the slides are the org's actual Meta billing when the token can read it, otherwise the rate-card estimate, and the footnote says which.
+- Non-store orgs need `config.deck.outcome` (`source: handover | ticket_status | tag | keyword`, labels) — the revenue slides become outcome slides. Every verb except `status` and `pull` is audited.
+
 ### WhatsApp templates — `flowiq templates pull|list|create|status` (alias `tpl`)
 
 Read an org's live templates straight from Meta (read-only), and submit new
@@ -1188,6 +1227,8 @@ 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> --disable-base-tool get_product_info
+flowiq agent config <organization_id> --enable-base-tool get_product_info
 ```
 
 Settable: `settings.use_settings_prompt`, `settings.model`,
@@ -1201,6 +1242,10 @@ the tool-flag columns (`woo_order_build`, `woo_tip_field`, `woo_order_note_field
 (`settings.test_contact_number` / `settings.test_contact_name`). Anything else is
 rejected; every change is reported before → after.
 
+`--disable-base-tool` / `--enable-base-tool` can be repeated. They manage only the
+allowlisted discovery/commerce built-ins; opt-out, human handover and channel-send
+tools cannot be disabled.
+
 **`--tool product_lookup=true` (added 11 Aug 2026).** Turns on the `product_lookup`
 tool: a typo-tolerant **pg_trgm fuzzy match on `product_title`** (plus badge/tag
 search), as opposed to `get_product_info`, which is **semantic**. This matters far
@@ -1339,3 +1384,8 @@ interactive terminal. Silence it with `FLOWIQ_NO_UPDATE_CHECK=1`.
 
 UNLICENSED. Internal staff tool — install requires a valid `fiq_staff_…`
 key issued by a FlowIQ super-admin.
+
+ChatCart rollout: Pick n Pay uses retailer `pnp` and the private connection link.
+Enable its gateway before adding it to the agent tools. Cart retries use
+`{{operation_idempotency_key}}`; configure `timeout_ms` up to 30000 and
+`max_response_bytes` up to 1048576 for bounded batch results.

package/TEAM-GUIDE.md

@@ -98,6 +98,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` |
+| 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) |
 | Talk to the live agent safely (no real WhatsApp ever sent) | `flowiq test send <org_id> "hi, do you sell X?"` |
@@ -114,6 +115,7 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Split your whole broadcast list into N even cohorts (e.g. 3 for A/B/C or waves) | `flowiq seg plan <org_id> --tag-prefix bcast --from-attribute allow_broadcast_true --split 3` → `flowiq seg apply <org_id> bcast --commit` (makes `bcast-batch-01/02/03`, ~even, shuffled) |
 | Combine existing tags → a batched send list (include some tags, drop others, split into batches of N) | `flowiq seg plan <org_id> --tag-prefix clearance-bc --from-tag "loyalty-list" --exclude "recent-campaign" --batch-size 1000` → `flowiq seg apply <org_id> clearance-bc --commit` (makes `clearance-bc-batch-01/02/…`) |
 | Split a big id-list cohort into send-safe batch tags | `flowiq seg plan <org_id> --tag-prefix … --ids-file …` → `flowiq seg apply … --commit` |
+| 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` |
@@ -141,6 +143,10 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | 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` |
+| 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 |
+| Approve a client deck / send it to the client | `flowiq report deck approve <org_id> 2026-08` then `… send … --client` (or let the 09:00 SAST schedule send it on the 5th) |
 | Re-read this guide / the full command reference | `flowiq guide` / `flowiq guide --reference` |
 
 The flow is the same everywhere: **pull → edit the JSON → push**. Slugs are the
@@ -174,12 +180,15 @@ 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
+validates names, URLs, methods and parameter shapes. Unknown keys and unresolved
+`{{placeholders}}` block the write; an
+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
-injected server-side and mutations use `{{whatsapp_message_id}}` for idempotency.
+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.
 
 ### Example: tag a segment of contacts (Advanced Tagging)
 
@@ -320,3 +329,8 @@ Three things worth knowing:
 | "Organization has no active_whatsapp_agent" | Target the agent directly: `--agent <id>` (ids from `flowiq agent list <org_id>`) |
 | Login browser page says the code expired | Codes live 10 minutes — just re-run `flowiq auth login` |
 | Pushed the wrong thing | Everything is pull→push, so re-pull an older copy if you have one, or check with Matt — server logs record every push with who/what/when |
+
+ChatCart rollout: Pick n Pay uses retailer `pnp` and the private connection link.
+Enable its gateway before adding it to the agent tools. Cart retries use
+`{{operation_idempotency_key}}`; configure `timeout_ms` up to 30000 and
+`max_response_bytes` up to 1048576 for bounded batch results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.6.3",
+  "version": "0.6.6",
   "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/agent-config.js

@@ -23,6 +23,12 @@ export function collectTool(val, acc) {
   return acc;
 }
 
+export function collectToolName(val, acc) {
+  acc = acc || [];
+  acc.push(val);
+  return acc;
+}
+
 function printSnapshot(title, snap) {
   console.log(`  ${title}:`);
   for (const [k, v] of Object.entries(snap)) {
@@ -47,6 +53,12 @@ export async function config(orgId, opts = {}) {
   if (Object.keys(settings).length) body.settings = settings;
   if (opts.rename !== undefined) body.name = opts.rename;
   if (opts.discount !== undefined) body.discount_enabled = parseBool(opts.discount, "--discount");
+  if (opts.disableBaseTool?.length || opts.enableBaseTool?.length) {
+    body.base_tool_changes = {
+      disable: opts.disableBaseTool || [],
+      enable: opts.enableBaseTool || [],
+    };
+  }
 
   if (opts.tool && opts.tool.length) {
     const flags = {};
@@ -63,7 +75,7 @@ export async function config(orgId, opts = {}) {
   }
 
   const hasWrite =
-    body.settings || body.name !== undefined || body.tool_flags || body.discount_enabled !== undefined;
+    body.settings || body.name !== undefined || body.tool_flags || body.base_tool_changes || body.discount_enabled !== undefined;
 
   // No write flags → just show current config.
   if (!hasWrite) {
@@ -76,7 +88,7 @@ export async function config(orgId, opts = {}) {
     }
     console.log(`${resp.organization_name} → agent ${resp.agent_id}${resp.is_active === false ? " [NON-active]" : ""}`);
     printSnapshot("current", resp.current);
-    console.log("\n(pass --use-settings-prompt / --model / --reasoning-effort / --rename / --tool / --discount / --test-contact-number / --test-contact-name to change)");
+    console.log("\n(pass --use-settings-prompt / --model / --reasoning-effort / --rename / --tool / --disable-base-tool / --enable-base-tool / --discount / --test-contact-number / --test-contact-name to change)");
     return;
   }
 

package/src/commands/report.js

@@ -0,0 +1,163 @@
+// `flowiq report deck <verb> <org_id> <YYYY-MM>` — the monthly client deck.
+//   status   what exists for the month + workflow status + what blocks approval
+//   build    rebuild the deck metrics from the frozen month (--refresh)
+//   narrate  rewrite the copy (always forces a fresh write)
+//   generate build (if missing or --refresh) + write the copy
+//   approve / unapprove
+//   send     --test-to me@x → one test copy, status untouched; without it the
+//            deck must be approved and goes to the org's configured recipients
+//   inputs   push a JSON file of inputs (the §3.2 form) — see README
+//   print    mint a 15-minute print URL (the page headless Chrome renders)
+//   pull     write ./.flowiq/reports/<slug>-<month>.json (doc + deck + copy + inputs)
+// All the work happens server-side (/cli/report → the flowiq-reporting-deck
+// edge fn); every mutating verb is audited.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const REPORT_DIR = path.resolve(process.cwd(), ".flowiq", "reports");
+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 slugify(name, fallback) {
+  const s = String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return s || fallback;
+}
+
+function requireArgs(orgId, month) {
+  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);
+  }
+  if (!MONTH_RE.test(month || "")) {
+    console.error(`Error: month must be YYYY-MM (got "${month}").`);
+    process.exit(1);
+  }
+}
+
+function printStatus(r) {
+  const s = r.status || (r.deck_available ? "draft" : "no deck");
+  console.log(`${r.organization?.name ?? r.organization?.id} — ${r.month}`);
+  console.log(`  snapshot: ${r.snapshot ? (r.frozen ? "frozen" : "not frozen") : "MISSING (months freeze on the 1st)"}`);
+  console.log(`  metrics:  ${r.deck_available ? `built ${r.deck_computed_at}` : "not built"}${r.deck_available && !r.prior_available ? "  (no prior month deck, comparisons limited)" : ""}`);
+  console.log(`  copy:     ${r.narrative_available ? `written ${r.narrative_generated_at}` : "not written"}`);
+  console.log(`  status:   ${s}${r.approved_at ? ` (approved ${r.approved_at}${r.approved_by ? ` by ${r.approved_by}` : ""})` : ""}${r.sent_at ? ` · sent ${r.sent_at}` : ""}`);
+  if (Array.isArray(r.missing) && r.missing.length && s !== "sent") console.log(`  needed:   ${r.missing.join(" · ")}`);
+  console.log(`  client recipients: ${Array.isArray(r.recipients) && r.recipients.length ? r.recipients.join(", ") : "none configured (Control center → Report delivery)"}`);
+  console.log(`  from flowiq@flowapt.com · reply-to ${r.reply_to ?? "matt@flowapt.com"} · signed ${r.account_owner ?? "Matt Cronson"} · schedule ${r.deck_enabled ? "ON" : "off"}`);
+}
+
+export async function status(orgId, month, opts) {
+  requireArgs(orgId, month);
+  let r;
+  try { r = await http.get("report", { organization_id: orgId, month }); }
+  catch (e) { console.error(`Status failed: ${e.message}`); process.exit(1); }
+  if (opts?.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  printStatus(r);
+}
+
+async function post(action, orgId, month, extra, label) {
+  let r;
+  try { r = await http.post("report", { organization_id: orgId, month, action, ...extra }); }
+  catch (e) { console.error(`${label} failed: ${e.message}`); process.exit(1); }
+  return r;
+}
+
+export async function build(orgId, month, opts) {
+  requireArgs(orgId, month);
+  const r = await post("build", orgId, month, { refresh: !!opts.refresh }, "Build");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(r.built ? `Built the ${month} deck metrics for ${r.organization.name} (${r.broadcasts} broadcast${r.broadcasts === 1 ? "" : "s"} read${r.timings ? `, ${Object.values(r.timings).reduce((a, b) => a + b, 0)} ms` : ""})` : `Metrics already built for ${month}; pass --refresh to rebuild.`);
+}
+
+export async function narrate(orgId, month, opts) {
+  requireArgs(orgId, month);
+  const r = await post("narrate", orgId, month, {}, "Narrate");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  reportCopy(r, month);
+}
+
+export async function generate(orgId, month, opts) {
+  requireArgs(orgId, month);
+  const r = await post("generate", orgId, month, { refresh: !!opts.refresh, force: !!opts.force }, "Generate");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`${r.organization.name} — ${month}: metrics ${r.built ? "built" : "kept"}, copy ${r.generated ? `written by ${r.model}` : "kept"}`);
+  reportCopy(r, month);
+  if (r.status) console.log(`  status: ${r.status}${r.missing?.length ? ` · needed: ${r.missing.join(" · ")}` : ""}`);
+}
+
+function reportCopy(r, month) {
+  if (r.guard && r.guard.passed === false) {
+    const n = Object.keys(r.guard.offenders || {}).length;
+    console.log(`  ⚠ numeric guard: ${n} field${n === 1 ? "" : "s"} carry figures that are not in the data — flagged on the slides: ${Object.keys(r.guard.offenders).join(", ")}`);
+  } else if (r.guard) console.log("  numeric guard: passed (every figure in the copy exists in the data)");
+  if (Array.isArray(r.length_issues) && r.length_issues.length) console.log(`  trimmed to limit: ${r.length_issues.map((i) => `${i.path} (${i.length}→${i.limit})`).join(", ")}`);
+}
+
+export async function approve(orgId, month, opts) {
+  requireArgs(orgId, month);
+  const r = await post("approve", orgId, month, {}, "Approve");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`Approved the ${month} deck for ${r.organization.name}. It goes to the client recipients at 09:00 SAST on the 5th (or the next morning if the 5th has passed).`);
+}
+
+export async function unapprove(orgId, month, opts) {
+  requireArgs(orgId, month);
+  const r = await post("unapprove", orgId, month, {}, "Unapprove");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`Unapproved. Status is now ${r.status}${r.missing?.length ? ` · needed: ${r.missing.join(" · ")}` : ""}.`);
+}
+
+export async function send(orgId, month, opts) {
+  requireArgs(orgId, month);
+  if (!opts.testTo && !opts.client) {
+    console.error("Error: pass --test-to <email> for a test copy, or --client to send to the org's configured recipients (needs an approved deck).");
+    process.exit(1);
+  }
+  if (opts.testTo && opts.client) {
+    console.error("Error: --test-to and --client are alternatives.");
+    process.exit(1);
+  }
+  const r = await post("send", orgId, month, opts.testTo ? { test_to: opts.testTo } : {}, "Send");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  const ok = (r.results || []).filter((x) => x.status === "sent").map((x) => x.to);
+  const failed = (r.results || []).filter((x) => x.status !== "sent");
+  console.log(`${r.test ? "Test copy" : "Deck"} ${ok.length ? `sent to ${ok.join(", ")}` : "not sent"} — ${r.filename} (${Math.round((r.pdf_bytes || 0) / 1024)} KB, rendered in ${((r.pdf_ms || 0) / 1000).toFixed(1)} s)${r.test ? " · status unchanged" : " · status: sent"}`);
+  for (const f of failed) console.log(`  ✗ ${f.to}: ${f.error}`);
+  if (failed.length) process.exit(1);
+}
+
+export async function inputs(orgId, month, opts) {
+  requireArgs(orgId, month);
+  if (!opts.file) { console.error("Error: --file <inputs.json> is required."); process.exit(1); }
+  let parsed;
+  try { parsed = JSON.parse(await fs.readFile(path.resolve(process.cwd(), opts.file), "utf8")); }
+  catch (e) { console.error(`Error: could not read ${opts.file}: ${e.message}`); process.exit(1); }
+  const r = await post("save_inputs", orgId, month, { inputs: parsed }, "Save inputs");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(`Inputs saved. Status: ${r.status}${r.missing?.length ? ` · needed: ${r.missing.join(" · ")}` : " · ready to approve"}`);
+}
+
+export async function print(orgId, month, opts) {
+  requireArgs(orgId, month);
+  const r = await post("print_url", orgId, month, {}, "Print URL");
+  if (opts.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(r.url);
+  console.error(`(valid ${Math.round((r.expires_in || 900) / 60)} min; this is the page headless Chrome prints, one 1600×900 page per slide)`);
+}
+
+export async function pull(orgId, month, opts) {
+  requireArgs(orgId, month);
+  let r;
+  try { r = await http.get("report", { organization_id: orgId, month, pull: 1 }); }
+  catch (e) { console.error(`Pull failed: ${e.message}`); process.exit(1); }
+  const slug = slugify(r.organization?.name, orgId.slice(0, 8));
+  const file = path.resolve(opts.out || path.join(REPORT_DIR, `${slug}-${month}.json`));
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(r, null, 2));
+  const d = r.doc || {};
+  console.log(`Wrote ${path.relative(process.cwd(), file)}`);
+  console.log(`  ${r.organization?.name} — ${month} · status ${r.workflow?.status ?? "draft"} · deck ${d.deck ? "built" : "not built"} · copy ${r.narrative?.fields ? `written by ${r.narrative.model}` : "not written"}`);
+  if (d.revenue?.influenced) console.log(`  influenced ${d.revenue.influenced.revenue} · conversations ${d.conversations?.conversations} · sends ${d.deck?.broadcasts?.totals?.sends ?? "—"}`);
+}

package/src/commands/segments.js

@@ -122,6 +122,13 @@ export async function plan(orgId, opts = {}) {
   }
   const splitMode = opts.split !== undefined;
   const batchSize = Number(opts.batchSize ?? 75);
+  // --start-index continues an EXISTING batch series (f500-batch-13 after 12
+  // manual batches) instead of always restarting at 01 and colliding with it.
+  const startIndex = Number(opts.startIndex ?? 1);
+  if (!Number.isInteger(startIndex) || startIndex < 1 || startIndex > 999) {
+    console.error("Error: --start-index must be an integer 1..999.");
+    process.exit(1);
+  }
   if (!splitMode) {
     if (!Number.isInteger(batchSize) || batchSize < 1) { console.error("Error: --batch-size must be ≥ 1."); process.exit(1); }
     if (batchSize > 500) console.log(`⚠ batch size ${batchSize} is large — Meta tier risk; the runbook default is 75.`);
@@ -252,18 +259,35 @@ export async function plan(orgId, opts = {}) {
     let idx = 0;
     for (let g = 0; g < splitN; g++) {
       const size = base + (g < rem ? 1 : 0);
-      const nn = String(g + 1).padStart(2, "0");
+      const nn = String(startIndex + g).padStart(2, "0");
       batches.push({ tag: `${prefix}-batch-${nn}`, count: size, contact_ids: ids.slice(idx, idx + size) });
       idx += size;
     }
     if (batches[0].count > 500) console.log(`⚠ each cohort is ~${batches[0].count} contacts — a single-cohort send is large (Meta tier risk); pace the sends.`);
   } else {
     for (let i = 0; i < resp.safe_ids.length; i += batchSize) {
-      const nn = String(batches.length + 1).padStart(2, "0");
+      const nn = String(startIndex + batches.length).padStart(2, "0");
       batches.push({ tag: `${prefix}-batch-${nn}`, count: Math.min(batchSize, resp.safe_ids.length - i), contact_ids: resp.safe_ids.slice(i, i + batchSize) });
     }
   }
 
+  // A batch tag that ALREADY holds contacts means this plan would merge a new
+  // cohort into a past one (append-only apply = silent corruption of that
+  // batch's record). Refuse unless the caller says it is deliberate.
+  try {
+    const existing = await http.post("segments", { mode: "list", organization_id: orgId, prefix });
+    const held = new Map((existing?.tags || []).map((t) => [String(t.tag), Number(t.count) || 0]));
+    const clashes = batches.map((b) => b.tag).filter((t) => (held.get(t) || 0) > 0);
+    if (clashes.length && !opts.allowExistingTag) {
+      console.error(`Error: ${clashes.length} batch tag(s) already hold contacts on this org: ${clashes.slice(0, 5).join(", ")}${clashes.length > 5 ? ` …+${clashes.length - 5}` : ""}.`);
+      console.error("  apply is append-only, so this plan would MERGE a new cohort into an existing batch.");
+      console.error(`  Use --start-index ${Math.max(...[...held.keys()].map((t) => Number(String(t).split("-batch-").pop())).filter(Number.isFinite), 0) + 1} to continue the series, or --allow-existing-tag if the merge is deliberate.`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.log(`⚠ could not check existing batch tags (${e.message}) — verify with \`seg list --prefix ${prefix}\` before apply.`);
+  }
+
   const slug = slugify(opts.segment || prefix, prefix);
   const planDoc = {
     schema_version: 1,
@@ -326,7 +350,10 @@ export async function apply(orgId, identifier, opts = {}) {
   // V-11: warn when the batch tags already carry members (tag reuse merges counts).
   try {
     const before = await http.post("segments", { mode: "list", organization_id: orgId, prefix: planDoc.tag_prefix });
-    const existing = (before.tags || []).filter((t) => Number(t.count) > 0);
+    // Only THIS plan's batch tags matter — filtering on the prefix alone warned
+    // about every past batch of the campaign and prompted on a clean plan.
+    const planTags = new Set(planDoc.batches.map((b) => String(b.tag)));
+    const existing = (before.tags || []).filter((t) => Number(t.count) > 0 && planTags.has(String(t.tag)));
     if (existing.length) {
       console.log(`⚠ ${existing.length} of these tags already have members (counts will MERGE):`);
       for (const t of existing.slice(0, 5)) console.log(`    ${t.tag}: ${t.count}`);

package/src/index.js

@@ -16,6 +16,7 @@ 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 reportCmd from "./commands/report.js";
 import * as templatesCmd from "./commands/templates.js";
 import * as orgCmd from "./commands/org.js";
 import * as agentConfigCmd from "./commands/agent-config.js";
@@ -215,6 +216,56 @@ export function run(argv) {
     .option("--json", "raw JSON output")
     .action((opts) => hoursCmd.summary(opts));
 
+  // report deck — the monthly client deck (build / copy / approve / send)
+  const report = program.command("report").description("Client reporting: the monthly 10-slide client deck");
+  const deck = report.command("deck").description("The monthly client deck for one org and month (/reporting/deck)");
+  deck.command("status <organization_id> <month>")
+    .description("What exists for the month, the workflow status and what still blocks approval")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.status(orgId, month, opts));
+  deck.command("build <organization_id> <month>")
+    .description("Build the deck metrics from the frozen month (leaderboard, timing, popup, carts, records, changes)")
+    .option("--refresh", "rebuild even if the metrics already exist")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.build(orgId, month, opts));
+  deck.command("narrate <organization_id> <month>")
+    .description("Rewrite the ten slides' copy (LLM, under the report rules + numeric guard); hand edits are kept")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.narrate(orgId, month, opts));
+  deck.command("generate <organization_id> <month>")
+    .description("Build the metrics (if missing, or --refresh) and write the copy")
+    .option("--refresh", "rebuild the metrics first")
+    .option("--force", "rewrite the copy even if it exists")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.generate(orgId, month, opts));
+  deck.command("inputs <organization_id> <month>")
+    .description("Save the super-admin inputs from a JSON file (changes reviewed, action points, waiting-on-you, recipients confirmed)")
+    .option("--file <path>", "inputs JSON file")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.inputs(orgId, month, opts));
+  deck.command("approve <organization_id> <month>")
+    .description("Approve the deck (refused until every required input is present)")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.approve(orgId, month, opts));
+  deck.command("unapprove <organization_id> <month>")
+    .description("Take an approved deck back to needs input / ready")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.unapprove(orgId, month, opts));
+  deck.command("send <organization_id> <month>")
+    .description("Email the PDF from flowiq@flowapt.com: --test-to for one test copy (status untouched), --client for the configured recipients (needs approval)")
+    .option("--test-to <email>", "send a test copy to this address only")
+    .option("--client", "send to the org's configured client recipients")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.send(orgId, month, opts));
+  deck.command("print <organization_id> <month>")
+    .description("Mint a 15-minute print URL (the page headless Chrome renders to PDF)")
+    .option("--json", "raw JSON output")
+    .action((orgId, month, opts) => reportCmd.print(orgId, month, opts));
+  deck.command("pull <organization_id> <month>")
+    .description("Write the month's doc + deck metrics + copy + inputs to ./.flowiq/reports/<slug>-<month>.json")
+    .option("--out <path>", "write to this file instead")
+    .action((orgId, month, opts) => reportCmd.pull(orgId, month, opts));
+
   // templates (read WhatsApp templates from Meta; create via /cli/meta-templates)
   const templates = program.command("templates")
     .alias("tpl")
@@ -277,6 +328,8 @@ export function run(argv) {
     .option("--discount [bool]", "agent.discount.enabled (true if bare)")
     .option("--test-contact-number <number>", "settings.test_contact_number — the contact `flowiq test` uses (use a FAKE number; \"\" clears it → synthetic fallback)")
     .option("--test-contact-name <name>", "settings.test_contact_name — display name for the test contact (\"\" clears it)")
+    .option("--disable-base-tool <name>", "hide a disableable built-in tool from this agent (repeatable)", agentConfigCmd.collectToolName, [])
+    .option("--enable-base-tool <name>", "restore a previously disabled built-in tool (repeatable)", agentConfigCmd.collectToolName, [])
     .action((orgId, opts) => agentConfigCmd.config(orgId, opts));
 
   // agent-updates (pending client change-requests + chat context; pull + resolve)
@@ -544,6 +597,8 @@ export function run(argv) {
     .option("--split <n>", "split the safe cohort into exactly N even cohorts (alternative to --batch-size; shuffles by default for balanced groups)")
     .option("--seed <n>", "with --split: reproducible shuffle seed (omit = random each run)")
     .option("--ordered", "with --split: keep server order instead of shuffling (deterministic, but skews groups by contact age)")
+    .option("--start-index <n>", "number the first batch tag from N instead of 01 — continues an existing series (e.g. --start-index 13 → <prefix>-batch-13)", "1")
+    .option("--allow-existing-tag", "allow a batch tag that already holds contacts (apply is append-only, so this MERGES cohorts)")
     .option("--segment <name>", "plan file slug (default: the tag prefix)")
     .option("--include-unsafe", "do NOT exclude non-broadcast-safe contacts (rare; default excludes)")
     .action((orgId, opts) => segmentsCmd.plan(orgId, opts));