@flowapt/flowiq-cli 0.9.6 → 0.9.7

package/README.md

@@ -1273,10 +1273,13 @@ flowiq report deck pull <org_id> 2026-08                   # → ./.flowiq/repor
   predates the current build logic, unless it is approved, sent or held).
 - Send fees are estimated at the category each template had on its send day. A send whose category
   cannot be known shows no fee and is left out of the broadcast return (`totals.unpriced_sends`).
-- `inputs.json` shape: `{ "changes": { "<update_id>": { "hidden": false, "tag": "client_raised|flowapt_shipped", "title": "…", "description": "…" } }, "changes_reviewed": true, "action_points": { "<title>": "done|in_progress|waiting_on_you|ongoing|dropped" }, "waiting_on_you": [{ "title": "…", "unlocks": "…" }], "recipients_confirmed": true }`.
+- `inputs.json` shape: `{ "changes": { "<update_id>": { "hidden": false, "tag": "client_raised|flowapt_shipped", "title": "…", "description": "…" } }, "changes_reviewed": true, "action_points": { "<title>": "done|in_progress|waiting_on_you|ongoing|dropped" }, "waiting_on_you": [{ "title": "…", "unlocks": "…" }], "recipients_confirmed": true, "hidden": { "tile:tail": true, "pill:new_contacts": true } }`.
+  `hidden` (29 Sep 2026) takes any tile, pill, card or block off the slides and the PDF for that month only: the keys are what the deck page's rail lists (`tile:…`, `pill:<metric>`, `card:…`, `block:…`, `box:…`, `strip:…`); a metric's pill hides everywhere that metric shows. The copy is not rewritten when something is hidden.
   Free text (milestone, the four plan fields) is edited in the app; it is stored as overrides that survive `narrate`.
 - `send --client` needs an approved deck AND `report.email.recipients` in the org's reporting config (Control center → Report delivery); it marks the deck `sent`. `--test-to` never changes status. Fees on the slides are the org's actual Meta billing when the token can read it, otherwise the rate-card estimate, and the footnote says which.
 - Non-store orgs need `config.deck.outcome` (`source: handover | ticket_status | tag | keyword`, labels) — the revenue slides become outcome slides. Every verb except `status` and `pull` is audited.
+- A month with a Customer Insights report gets the "What your customers asked" slide after slide 7 (29 Sep 2026): `build` takes the one `org_insights` export-insights row whose window covers the most of the month (top questions, trending topics, complaints or product mentions, sentiment, each as "N customers"), stores it under `deck.insights`, and the copy carries `insights_title` + `insights_read`. `status --json` shows the window under `insights` (null = no report, no slide). The timing slide's next-step card is now written by the narrator (`next_step_title` / `next_step_body`) against next month's South African retail calendar (public holidays, Mother's / Father's Day, Black Friday, payday, month-end) and edited in place like every other block.
+- Cart funnel and buckets (29 Sep 2026): "messaged" counts reminders WhatsApp reports delivered (the old send-request count rides along as `messaged_requested`); a Woo cart reminder now matches its order, so Woo recoveries are no longer zero; our own cart link is a recovery, another tool's abandoned-cart email is not; on Woo an agent-built order is a conversation, not a campaign; chat-to-order counts buyers who chatted, any bucket. `status` refuses approval when the agent replied to nobody in the month (no live channel).
 - Store orgs get slide 8, "Store health": cart abandonment (online checkouts started, bought, abandoned), first-time vs returning buyers and opt-in growth, each with a twelve-month strip and measured on the online store checkout only (till and other channels are named in the footer). `status --json` carries the headline figures under `store`; `config.deck.channel_labels {"<source_name>": "Label"}` renames a sales channel on the slide.
 
 ### Insights — `flowiq insights status|enable|disable|run` (v0.7.0)
@@ -1859,6 +1862,53 @@ flowiq plans status <plan_id> --to sent --commit
 - Editing a plan's copy, buttons or links is not in the CLI yet; do that in
   the app.
 
+### CLI gaps + requests — `flowiq gaps report|list|show|hit|note|status` (alias `requests`) (v0.9.7)
+
+Found something the CLI cannot do, does wrong, or should do? File it here, from
+the terminal, the moment you hit it. This is the shared list of what the CLI
+is missing: anyone with a staff key can add to it, and so can a Claude session
+driving the CLI for you (it is marked `claude` automatically).
+
+```bash
+flowiq gaps report "agent config cannot set tool_instructions" --command "agent config" \
+  --error "error: unknown option '--tool-instruction'" --workaround "SQL on agents.settings" \
+  --detail "Needed to add a per-tool instruction for Clara's get_product_info" --org <uuid>
+flowiq gaps report "links shorten should take a readable --slug" --kind idea --command "links shorten"
+flowiq gaps report "…" --dry-run          # only check whether it is already on the list
+flowiq gaps list                          # open requests, most-hit first
+flowiq gaps list --command "bc" --status all --search slug
+flowiq gaps list --mine
+flowiq gaps show 12                       # detail, verbatim error, every hit / note / status change
+flowiq gaps hit 12 --note "same on Barkyn IT while copying the escalation config"
+flowiq gaps note 12 "also needs --agent"
+flowiq gaps status 12 --to done --version 0.9.8 --note "agent config --tool-instruction name=@file.txt"   # maintainers
+flowiq gaps status 14 --to duplicate --of 12                                                            # hits move to #12
+```
+
+- **`report`** takes a one-line title plus whatever context you have:
+  `--command` (the command it concerns, or the one you expected to exist),
+  `--kind gap|bug|idea` (default gap), `--error` (paste it verbatim),
+  `--workaround` (what you did instead), `--detail` / `--detail-file`, `--org`,
+  `--priority low|normal|high` (high = it blocked the job).
+- **Duplicates are caught before they are filed.** A report that closely
+  matches an OPEN request is refused and names it; add yourself to that one
+  with `hit` instead, or pass `--new` if yours is genuinely different.
+  `--dry-run` shows the similar requests and files nothing.
+- **`hit`** is "this bit me too": it adds your case and counts it. `list` is
+  ordered by hits, so the requests that cost the team most get built first.
+  `note` adds context without counting.
+- **`status`** (open / planned / in_progress / done / declined / duplicate) is
+  for the CLI maintainers (Matt and Gidon). You can withdraw your OWN request
+  with `--to declined` or `--to duplicate --of <n>`. `done` and `declined` need
+  `--note`: closing a request **emails everyone who reported or hit it** (from
+  FlowIQ (CLI), reply-to the person who closed it), with the version to update
+  to. `--no-notify` closes quietly.
+- **A command or flag that does not exist** now ends its error with the exact
+  `flowiq gaps report …` line to file it, `--command` and `--error` filled in.
+- Every report / hit / note / status change is audited
+  (`flowiq audit --endpoint gaps`). A report or hit from anyone but Matt also
+  emails him through the standing CLI-write alert.
+
 ### Chat export — `flowiq export chats <organization_id> [--out <path>]`
 
 Full chat history → TXT, byte-identical to the in-app "Export Settings TXT"

package/TEAM-GUIDE.md

@@ -70,6 +70,12 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
    goes back to the agent you pulled — never "whatever is active now".
 5. Run the CLI from the repo root when you can — `./.flowiq/` is gitignored
    there.
+6. **Hit a wall? File it.** Whenever the CLI cannot do something and you (or
+   your Claude session) fell back to the dashboard, SQL or a script, file it:
+   `flowiq gaps report "<what you needed>" --command "<topic>" --error "<the
+   exact error>"`. Already on the list? `flowiq gaps hit <number> --note "…"`
+   instead. The most-hit requests get built first, and you are emailed when
+   yours ships. Tell your Claude session to do this too.
 
 ## Everyday tasks
 
@@ -121,6 +127,9 @@ When you see it, run `npm i -g @flowapt/flowiq-cli` — a stale version also mea
 | Can I use `flowiq updates`? | Yes: `status`, `uncovered`, `draft`, `preview` and `send --test` (a copy to yourself) work for everyone. Only the real `send --yes` to the whole team is Matt's; anyone else gets a 403 there |
 | Which changelog rows has nobody emailed the team about yet? | `flowiq updates status` / `flowiq updates uncovered` — anything left 20h+ goes out automatically at 08:30 SAST as a plain digest |
 | Set which contact `flowiq test` uses (use a FAKE number!) | `flowiq agent config <org_id> --test-contact-number 27000000001 --test-contact-name "QA Bot"` |
+| **The CLI can't do something I need** (or does it wrong, or should do more) | `flowiq gaps report "agent config cannot set tool_instructions" --command "agent config" --error "<exact error>" --workaround "<what you did instead>"`. If it is already on the list you are told its number: `flowiq gaps hit <number> --note "…"` |
+| See what the team has asked the CLI to do | `flowiq gaps list` (open, most-hit first) · `flowiq gaps list --mine` · `flowiq gaps show <number>` |
+| Close a request (Matt / Gidon) | `flowiq gaps status <number> --to done --version 0.9.8 --note "what shipped"` — emails everyone who reported or hit it |
 > **Publishing the CLI (maintainers only):** publish from a clean clone, never
 > from your working tree — `npm publish` packs whatever is on disk. A
 > `prepublishOnly` check now stops you if `cli/` differs from `origin/main`.
@@ -221,6 +230,7 @@ several.
 | Generate a client's monthly deck (metrics + copy) after the month has frozen | `flowiq report deck generate <org_id> 2026-08` — then review it at /reporting/deck |
 | See whether a client deck can be approved, and what is still missing | `flowiq report deck status <org_id> 2026-08` |
 | Send yourself a test copy of a client deck (PDF from flowiq@flowapt.com) | `flowiq report deck send <org_id> 2026-08 --test-to you@flowapt.com` — status untouched |
+| Take a tile, pill or card off a client deck (and its PDF) for one month | On `/reporting/deck` open **Inputs** (the rail beside the slides) → Show or hide; or `flowiq report deck inputs <org_id> 2026-08 --file inputs.json` with `{ "hidden": { "tile:tail": true } }` |
 | Approve a client deck / send it to the client | `flowiq report deck approve <org_id> 2026-08` then `… send … --client` (or let the 09:00 SAST schedule send it on the 5th) |
 | Re-read this guide / the full command reference | `flowiq guide` / `flowiq guide --reference` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "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/gaps.js

@@ -0,0 +1,346 @@
+// `flowiq gaps report|list|show|hit|note|status` — CLI gap reports and feature
+// requests (alias `flowiq requests`), via /cli/gaps.
+//   report  file one: something the CLI cannot do, does wrong, or should do
+//   list    open requests, most-hit first (every status with --status all)
+//   show    one request in full, with every hit, note and status change
+//   hit     "this bit me too": +1 with what you were doing (the ranking signal)
+//   note    add context without counting a hit
+//   status  planned / in_progress / done / declined / duplicate (maintainers;
+//           closing emails everyone who reported or hit it)
+// Anyone with a staff key can report, hit and note — including a Claude
+// session driving the CLI, which is marked `claude` automatically.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { http } from "../http.js";
+
+const KINDS = ["gap", "idea", "bug"];
+const STATUSES = ["open", "planned", "in_progress", "done", "declined", "duplicate"];
+const STATUS_ORDER = ["in_progress", "planned", "open", "done", "declined", "duplicate"];
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** Who is typing: a Claude session, a script/pipe, or a person at a terminal. */
+export function filedVia(env = process.env, stdin = process.stdin, stdout = process.stdout) {
+  if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) return "claude";
+  if (!stdin?.isTTY || !stdout?.isTTY) return "script";
+  return "human";
+}
+
+/** "42", "#42" or a UUID; anything else is refused before a request is made. */
+export function normaliseRef(ref) {
+  const raw = String(ref ?? "").trim().replace(/^#/, "");
+  if (/^\d{1,12}$/.test(raw)) return raw;
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw)) return raw;
+  return null;
+}
+
+function sastParts(ts) {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Africa/Johannesburg",
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false,
+  }).formatToParts(new Date(ts));
+  return Object.fromEntries(parts.map((p) => [p.type, p.value]));
+}
+
+function fmtTs(ts) {
+  if (!ts) return "-";
+  const p = sastParts(ts);
+  const hour = p.hour === "24" ? "00" : p.hour;
+  return `${Number(p.day)} ${MONTHS[Number(p.month) - 1]} ${p.year} ${hour}:${p.minute}`;
+}
+
+export function ago(ts, now = Date.now()) {
+  if (!ts) return "-";
+  const mins = Math.max(0, Math.round((now - new Date(ts).getTime()) / 60000));
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.round(mins / 60);
+  if (hrs < 48) return `${hrs}h ago`;
+  return `${Math.round(hrs / 24)}d ago`;
+}
+
+function who(email) {
+  if (!email) return "?";
+  return String(email).split("@")[0];
+}
+
+function indent(text, pad = "    ") {
+  return String(text ?? "").trim().split("\n").map((l) => `${pad}${l}`).join("\n");
+}
+
+function fail(prefix, e) {
+  console.error(`${prefix}: ${e.message}`);
+  if (e.body?.error && !String(e.message).includes(e.body.error)) console.error(`  ${e.body.error}`);
+  process.exit(1);
+}
+
+function requireRef(ref) {
+  const r = normaliseRef(ref);
+  if (!r) {
+    console.error(`Error: "${ref}" is not a request number (e.g. 42 or #42). Find it with \`flowiq gaps list\`.`);
+    process.exit(1);
+  }
+  return r;
+}
+
+function printSimilar(similar, heading) {
+  if (!similar?.length) return;
+  console.log(heading);
+  for (const s of similar) {
+    const shipped = s.status === "done" && s.resolved_version ? ` in ${s.resolved_version}` : "";
+    console.log(`  #${s.number}  ${s.title}  [${s.status}${shipped} · ${s.hit_count} hit(s) · match ${s.score}]`);
+  }
+}
+
+// ── report ──────────────────────────────────────────────────────────────────
+export async function report(titleWords, opts = {}) {
+  const title = (Array.isArray(titleWords) ? titleWords.join(" ") : String(titleWords || "")).trim();
+  if (title.length < 3) {
+    console.error('Error: give a one-line title, e.g. flowiq gaps report "agent config cannot set tool_instructions" --command "agent config"');
+    process.exit(1);
+  }
+  const kind = String(opts.kind || "gap").toLowerCase();
+  if (!KINDS.includes(kind)) {
+    console.error(`Error: --kind must be ${KINDS.join(" | ")} (gap = the CLI cannot do it, bug = it does it wrong, idea = it should).`);
+    process.exit(1);
+  }
+  let detail = opts.detail ?? null;
+  if (opts.detailFile) {
+    try {
+      detail = await fs.readFile(path.resolve(process.cwd(), opts.detailFile), "utf8");
+    } catch (e) {
+      console.error(`Error: cannot read --detail-file ${opts.detailFile}: ${e.message}`);
+      process.exit(1);
+    }
+  }
+
+  let resp;
+  try {
+    resp = await http.post("gaps", {
+      action: "report",
+      title,
+      kind,
+      command: opts.command ?? null,
+      detail,
+      error_text: opts.error ?? null,
+      workaround: opts.workaround ?? null,
+      priority: opts.priority ?? "normal",
+      organization_id: opts.org ?? null,
+      filed_via: filedVia(),
+      force_new: Boolean(opts.new),
+      dry_run: Boolean(opts.dryRun),
+    });
+  } catch (e) {
+    if (e.status === 409) {
+      console.error(e.body?.error || e.message);
+      printSimilar(e.body?.similar, "\nAlready on the list:");
+      process.exit(1);
+    }
+    fail("Report failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  if (resp.dry_run) {
+    console.log(`DRY RUN · nothing filed · "${title}"`);
+    if (!resp.similar?.length) console.log("  No similar requests on the list. File it by re-running without --dry-run.");
+    printSimilar(resp.similar, "Similar requests:");
+    if (resp.would_block) console.log("\nA real report would be held as a duplicate: hit the matching one, or pass --new if it is different.");
+    return;
+  }
+  const r = resp.request;
+  console.log(`Filed #${r.number} (${r.kind}${r.command ? ` · flowiq ${r.command}` : ""}): ${r.title}`);
+  console.log(`  by ${r.reporter_email ?? "?"} via ${r.filed_via}${r.organization_name ? ` · org ${r.organization_name}` : ""}`);
+  printSimilar(resp.similar, "\nPossibly related:");
+  console.log(`\nTrack it: flowiq gaps show ${r.number}   ·   hit it again next time: flowiq gaps hit ${r.number} --note "…"`);
+}
+
+// ── list ────────────────────────────────────────────────────────────────────
+export async function list(opts = {}) {
+  const query = {};
+  if (opts.status) query.status = opts.status;
+  if (opts.command) query.command = opts.command;
+  if (opts.kind) query.kind = opts.kind;
+  if (opts.mine) query.mine = "1";
+  if (opts.search) query.search = opts.search;
+  if (opts.sort) query.sort = opts.sort;
+  if (opts.limit != null) query.limit = String(opts.limit);
+
+  let resp;
+  try {
+    resp = await http.get("gaps", query);
+  } catch (e) {
+    fail("List failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+
+  const totals = STATUS_ORDER.filter((s) => resp.counts?.[s]).map((s) => `${s} ${resp.counts[s]}`).join(" · ");
+  console.log(`CLI requests · status ${resp.status_filter} · ${resp.total} shown · every status: ${totals || "none yet"}`);
+  const rows = resp.requests || [];
+  if (!rows.length) {
+    console.log("  (nothing matches)");
+    console.log('\nFile one: flowiq gaps report "<what the CLI cannot do>" --command "<topic>"');
+    return;
+  }
+  for (const r of rows) {
+    const cmd = r.command ? `[${r.command}] ` : "";
+    const shipped = r.status === "done" && r.resolved_version ? ` ${r.resolved_version}` : "";
+    console.log(`\n#${r.number}  ${r.kind.padEnd(4)} ×${r.hit_count}  ${cmd}${r.title}`);
+    const bits = [
+      `${r.status}${shipped}`,
+      r.priority !== "normal" ? `${r.priority} priority` : null,
+      `by ${who(r.reporter_email)}${r.filed_via === "claude" ? " (Claude)" : ""} ${ago(r.created_at)}`,
+      r.hit_count > 1 ? `last hit ${ago(r.last_hit_at)}` : null,
+      r.organization_name ? `org ${r.organization_name}` : null,
+    ].filter(Boolean);
+    console.log(`    ${bits.join(" · ")}`);
+  }
+  if (resp.truncated) console.log(`\n⚠ the limit (${resp.limit}) was reached: pass --limit, or narrow with --status / --command / --search.`);
+  console.log("\nOne in full: flowiq gaps show <number>   ·   same problem? flowiq gaps hit <number> --note \"…\"");
+}
+
+// ── show ────────────────────────────────────────────────────────────────────
+export async function show(ref, opts = {}) {
+  const r0 = requireRef(ref);
+  let resp;
+  try {
+    resp = await http.get("gaps", { ref: r0 });
+  } catch (e) {
+    fail("Show failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const r = resp.request;
+  console.log(`#${r.number}  ${r.title}`);
+  console.log(`  kind:      ${r.kind}${r.command ? ` · flowiq ${r.command}` : ""} · priority ${r.priority}`);
+  console.log(`  status:    ${r.status}${r.resolved_version ? ` (${r.resolved_version})` : ""}${resp.duplicate_of ? ` of #${resp.duplicate_of.number} "${resp.duplicate_of.title}"` : ""}`);
+  console.log(`  hits:      ${r.hit_count} · last ${fmtTs(r.last_hit_at)} SAST`);
+  console.log(`  filed:     ${fmtTs(r.created_at)} SAST by ${r.reporter_email ?? "?"} via ${r.filed_via ?? "?"}${r.cli_version ? ` (CLI ${r.cli_version})` : ""}`);
+  if (r.organization_name) console.log(`  org:       ${r.organization_name}`);
+  if (r.resolved_at) console.log(`  closed:    ${fmtTs(r.resolved_at)} SAST by ${r.resolved_by_email ?? "?"}`);
+  console.log(`  id:        ${r.id}`);
+  if (r.detail) console.log(`\nDetail\n${indent(r.detail, "  ")}`);
+  if (r.error_text) console.log(`\nError (verbatim)\n${indent(r.error_text, "  ")}`);
+  if (r.workaround) console.log(`\nWorkaround used\n${indent(r.workaround, "  ")}`);
+  if (r.resolution_note) console.log(`\nResolution\n${indent(r.resolution_note, "  ")}`);
+
+  const events = resp.events || [];
+  if (events.length) {
+    console.log(`\nHistory (${events.length})`);
+    for (const e of events) {
+      const head = e.kind === "status"
+        ? `status ${e.from_status} → ${e.to_status}`
+        : e.kind === "hit" ? "hit again" : "note";
+      const org = e.organization_name ? ` · ${e.organization_name}` : "";
+      console.log(`  ${fmtTs(e.created_at)}  ${who(e.user_email)}${e.filed_via === "claude" ? " (Claude)" : ""}: ${head}${org}`);
+      if (e.body) console.log(indent(e.body, "      "));
+      if (e.error_text) console.log(indent(`error: ${e.error_text}`, "      "));
+    }
+  }
+  console.log(`\nSame problem? flowiq gaps hit ${r.number} --note "what you were doing"`);
+  console.log(`Maintainers (${(resp.editors || []).join(", ")}): flowiq gaps status ${r.number} --to done --version <x.y.z> --note "…"`);
+}
+
+// ── hit ─────────────────────────────────────────────────────────────────────
+export async function hit(ref, opts = {}) {
+  const r0 = requireRef(ref);
+  let resp;
+  try {
+    resp = await http.post("gaps", {
+      action: "hit",
+      ref: r0,
+      note: opts.note ?? null,
+      error_text: opts.error ?? null,
+      organization_id: opts.org ?? null,
+      filed_via: filedVia(),
+    });
+  } catch (e) {
+    fail("Hit failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const r = resp.request;
+  console.log(`+1 on #${r.number} (${resp.hit_count} hits): ${r.title}`);
+  if (r.status === "done") {
+    console.log(`  ⚠ this is marked DONE${r.resolved_version ? ` in ${r.resolved_version}` : ""}. Update first (npm i -g @flowapt/flowiq-cli@latest); if it still fails, say so with: flowiq gaps note ${r.number} "still fails on <version>: …"`);
+  } else if (r.status !== "open") {
+    console.log(`  status: ${r.status}`);
+  }
+}
+
+// ── note ────────────────────────────────────────────────────────────────────
+export async function note(ref, textWords, opts = {}) {
+  const r0 = requireRef(ref);
+  const text = (Array.isArray(textWords) ? textWords.join(" ") : String(textWords || "")).trim();
+  if (!text) {
+    console.error("Error: give the note text, e.g. flowiq gaps note 42 \"also happens with --agent\"");
+    process.exit(1);
+  }
+  let resp;
+  try {
+    resp = await http.post("gaps", { action: "note", ref: r0, body: text });
+  } catch (e) {
+    fail("Note failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  console.log(`Noted on #${resp.request.number}: ${resp.request.title}`);
+}
+
+// ── status ──────────────────────────────────────────────────────────────────
+export async function status(ref, opts = {}) {
+  const r0 = requireRef(ref);
+  const to = String(opts.to || "").toLowerCase();
+  if (!STATUSES.includes(to)) {
+    console.error(`Error: --to must be one of ${STATUSES.join(" | ")} (got "${opts.to ?? ""}").`);
+    process.exit(1);
+  }
+  if (["done", "declined"].includes(to) && !(opts.note && opts.note.trim())) {
+    console.error(`Error: --note is required for ${to}. The people who asked get it by email: what shipped, or why not.`);
+    process.exit(1);
+  }
+  let dupRef = null;
+  if (to === "duplicate") {
+    dupRef = normaliseRef(opts.of);
+    if (!dupRef) {
+      console.error("Error: --to duplicate needs --of <number>: the request this one duplicates.");
+      process.exit(1);
+    }
+  }
+  let resp;
+  try {
+    resp = await http.post("gaps", {
+      action: "status",
+      ref: r0,
+      status: to,
+      note: opts.note ?? null,
+      version: opts.version ?? null,
+      duplicate_of: dupRef,
+      notify: opts.notify !== false,
+    });
+  } catch (e) {
+    fail("Status change failed", e);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(resp, null, 2));
+    return;
+  }
+  const r = resp.request;
+  console.log(`#${r.number} ${resp.previous_status} → ${r.status}${r.resolved_version ? ` (${r.resolved_version})` : ""}: ${r.title}`);
+  if (resp.duplicate_of) console.log(`  merged into #${resp.duplicate_of.number} "${resp.duplicate_of.title}" (hits carried over)`);
+  const n = resp.notified || {};
+  if (n.skipped) return;
+  if (n.sent?.length) console.log(`  emailed: ${n.sent.join(", ")}`);
+  else console.log("  nobody else to email (you were the only reporter)");
+  for (const f of n.failed || []) console.log(`  ⚠ email to ${f.to} failed: ${f.error}`);
+}

package/src/gaps.test.mjs

@@ -0,0 +1,48 @@
+// node --test src/gaps.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { filedVia, normaliseRef, ago } from "./commands/gaps.js";
+import { gapHint } from "./index.js";
+
+test("filedVia: a Claude Code session is marked claude, even on a TTY", () => {
+  const tty = { isTTY: true };
+  assert.equal(filedVia({ CLAUDECODE: "1" }, tty, tty), "claude");
+  assert.equal(filedVia({ CLAUDE_CODE_ENTRYPOINT: "cli" }, tty, tty), "claude");
+});
+
+test("filedVia: a person at a terminal vs a pipe or script", () => {
+  assert.equal(filedVia({}, { isTTY: true }, { isTTY: true }), "human");
+  assert.equal(filedVia({}, { isTTY: undefined }, { isTTY: true }), "script");
+  assert.equal(filedVia({}, { isTTY: true }, { isTTY: false }), "script");
+});
+
+test("normaliseRef: number, #number and uuid pass; anything else is refused", () => {
+  assert.equal(normaliseRef("42"), "42");
+  assert.equal(normaliseRef("#42"), "42");
+  assert.equal(normaliseRef(" 7 "), "7");
+  assert.equal(normaliseRef("0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b"), "0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b");
+  assert.equal(normaliseRef("abc"), null);
+  assert.equal(normaliseRef("42a"), null);
+  assert.equal(normaliseRef(""), null);
+  assert.equal(normaliseRef(undefined), null);
+});
+
+test("ago: minutes, hours, days", () => {
+  const now = Date.parse("2026-09-30T12:00:00Z");
+  assert.equal(ago("2026-09-30T11:55:00Z", now), "5m ago");
+  assert.equal(ago("2026-09-30T09:00:00Z", now), "3h ago");
+  assert.equal(ago("2026-09-26T12:00:00Z", now), "4d ago");
+  assert.equal(ago(null, now), "-");
+});
+
+test("gapHint: only for a missing command / flag, with the topic filled in", () => {
+  const argv = ["node", "flowiq", "agent", "config", "0689d0be-ba76-43d9-a0d5-f4d59c1db537", "--tool-instructions", "x"];
+  const hint = gapHint("error: unknown option '--tool-instructions'\n", argv);
+  assert.match(hint, /flowiq gaps report/);
+  assert.match(hint, /--command "agent config"/);
+  assert.match(hint, /--error "unknown option '--tool-instructions'"/);
+  assert.equal(gapHint("error: missing required argument 'organization_id'\n", argv), "");
+  assert.match(gapHint("error: unknown command 'widgets'\n", ["node", "flowiq", "widgets", "list"]), /--command "widgets list"/);
+  // an id in second place is not part of the topic
+  assert.match(gapHint("error: too many arguments\n", ["node", "flowiq", "messages", "0689d0be-ba76-43d9-a0d5-f4d59c1db537"]), /--command "messages"/);
+});

package/src/index.js

@@ -27,6 +27,7 @@ import * as agentConfigCmd from "./commands/agent-config.js";
 import * as agentsCmd from "./commands/agents.js";
 import * as agentUpdatesCmd from "./commands/agent-updates.js";
 import * as plansCmd from "./commands/plans.js";
+import * as gapsCmd from "./commands/gaps.js";
 import * as exportCmd from "./commands/export.js";
 import * as testCmd from "./commands/agent-test.js";
 import * as knowledgeCmd from "./commands/knowledge.js";
@@ -48,6 +49,19 @@ import * as doctorCmd from "./commands/doctor.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
 
+/** The one-line "file it" hint appended to a missing-command / missing-flag error. */
+export function gapHint(errorText, argv = []) {
+  if (!/unknown option|unknown command|too many arguments/i.test(String(errorText))) return "";
+  const args = argv.slice(2).filter((a) => !a.startsWith("-"));
+  // "agent config", "bc send", "org flags": a verb-shaped second word belongs to the topic.
+  const topic = (args[1] && /^[a-z][a-z-]*$/.test(args[1]) ? args.slice(0, 2) : args.slice(0, 1)).join(" ") || "<topic>";
+  const firstLine = String(errorText).split("\n")[0].replace(/^error:\s*/i, "").replace(/"/g, "'").trim();
+  return (
+    `  → If the CLI should be able to do this, file it so it gets built:\n` +
+    `    flowiq gaps report "<what you needed>" --command "${topic}" --error "${firstLine}"\n`
+  );
+}
+
 export function run(argv) {
   // Non-blocking "you're behind" hint (stderr; cached; detached refresh).
   maybeNotifyUpdate(pkg.version);
@@ -56,7 +70,12 @@ export function run(argv) {
   program
     .name("flowiq")
     .description("FlowIQ staff CLI — round-trip agent prompts, webhooks, and more, without service-role credentials.")
-    .version(pkg.version);
+    .version(pkg.version)
+    // Set before any subcommand exists so every subcommand inherits it. When a
+    // command or flag does not exist, that is usually a gap: say how to file it,
+    // so a teammate (or their Claude session) records it instead of quietly
+    // falling back to SQL.
+    .configureOutput({ outputError: (str, write) => write(str + gapHint(str, argv)) });
 
   // auth
   const auth = program.command("auth").description("Manage CLI authentication");
@@ -579,6 +598,60 @@ export function run(argv) {
     .option("--commit", "apply the change (default is a dry run)")
     .action((planId, opts) => plansCmd.status(planId, opts));
 
+  // gaps (CLI gap reports + feature requests, filed by anyone incl. a Claude session)
+  const gaps = program.command("gaps")
+    .alias("requests")
+    .description("Found something the CLI can't do (or does wrong)? `report` it; `list` what is asked for; `hit` one that bit you too");
+  gaps.command("report <title...>")
+    .description("File a gap / bug / idea (one-line title). Refused with the matching number if it is already on the list")
+    .option("--command <topic>", "the flowiq command it concerns, e.g. \"agent config\" or \"bc send\" (none yet? name the one you expected)")
+    .option("--kind <kind>", "gap (default: the CLI cannot do it) | bug (it does it wrong) | idea (it should)")
+    .option("--detail <text>", "what you were trying to do and what should happen")
+    .option("--detail-file <path>", "read --detail from a file")
+    .option("--error <text>", "the exact error the CLI printed, verbatim")
+    .option("--workaround <text>", "what you did instead (SQL, the dashboard, a script…)")
+    .option("--org <uuid>", "the org you were working on, for context")
+    .option("--priority <p>", "low | normal (default) | high — high = it blocked the job")
+    .option("--new", "file it even though a similar open request exists")
+    .option("--dry-run", "only show similar requests; file nothing")
+    .option("--json", "print the raw response")
+    .action((titleWords, opts) => gapsCmd.report(titleWords, opts));
+  gaps.command("list")
+    .description("Requests, most-hit first (default: open = open, planned, in_progress)")
+    .option("--status <list>", "open (default) | all | open | planned | in_progress | done | declined | duplicate (comma-separated allowed)")
+    .option("--command <topic>", "only requests about this command (contains)")
+    .option("--kind <kind>", "gap | bug | idea")
+    .option("--search <text>", "title / detail / error contains this text")
+    .option("--mine", "only requests you filed")
+    .option("--sort <how>", "hits (default) | new | old | touched")
+    .option("--limit <n>", "max rows (default 100, max 500)")
+    .option("--json", "print the raw response")
+    .action((opts) => gapsCmd.list(opts));
+  gaps.command("show <number>")
+    .description("One request in full: detail, verbatim error, every hit, note and status change")
+    .option("--json", "print the raw response")
+    .action((ref, opts) => gapsCmd.show(ref, opts));
+  gaps.command("hit <number>")
+    .description("It bit you too: +1 with what you were doing (the most-hit requests get built first)")
+    .option("--note <text>", "what you were doing when you hit it")
+    .option("--error <text>", "the exact error, if it differs")
+    .option("--org <uuid>", "the org you were working on")
+    .option("--json", "print the raw response")
+    .action((ref, opts) => gapsCmd.hit(ref, opts));
+  gaps.command("note <number> <text...>")
+    .description("Add context to a request without counting a hit")
+    .option("--json", "print the raw response")
+    .action((ref, textWords, opts) => gapsCmd.note(ref, textWords, opts));
+  gaps.command("status <number>")
+    .description("Maintainers: planned | in_progress | done | declined | duplicate. Closing emails everyone who reported or hit it")
+    .requiredOption("--to <status>", "open | planned | in_progress | done | declined | duplicate")
+    .option("--note <text>", "what shipped / why not (required for done + declined; the people who asked read it)")
+    .option("--version <x.y.z>", "the CLI version the fix shipped in (done)")
+    .option("--of <number>", "with --to duplicate: the request this one duplicates (hits move across)")
+    .option("--no-notify", "close without emailing the people who asked")
+    .option("--json", "print the raw response")
+    .action((ref, opts) => gapsCmd.status(ref, opts));
+
   // audit (who did what, when — with the full before/after content)
   const audit = program.command("audit")
     .description("Staff-CLI audit trail: who changed what, when — with full before/after content")