@flowapt/flowiq-cli 0.2.7 → 0.2.8

package/TEAM-GUIDE.md

@@ -122,6 +122,43 @@ 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.
 
+### Example: tag a segment of contacts (Advanced Tagging)
+
+`flowiq tag` is the Contacts → **Advanced Tagging** dialog in your terminal.
+It applies **one named tag** to a matched set. It is **always dry-run first** —
+you see the count and a sample, and *nothing writes* until you add `--commit`.
+
+```bash
+# 1. See who matches (nothing is written)
+flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP
+#    → "Custom segment: 4502 contact(s) match." + a 10-row sample
+
+# 2. Happy with the count? Apply the tag:
+flowiq tag segment <org_id> --min-orders 2 --min-spent 1000 --region ZA-GP \
+  --tag gp-repeat-spenders --commit
+#    → "matched 4502 · newly tagged 4502 · already had ... 0"
+
+# 3. Verify, then (if needed) undo:
+flowiq tag list   <org_id> --prefix gp-repeat            # tag → count
+flowiq tag remove <org_id> gp-repeat-spenders --confirm  # removes it from everyone
+```
+
+The five match modes (swap `segment` for any of these):
+
+| Mode | Tags contacts who… |
+|---|---|
+| `field --field order_history --any "Whey,Protein"` | have a keyword in a field (order history, summary, shopify tags, name, email…) |
+| `cohort --type top_spenders --limit 500` | rank in the **top N** by spend / orders / recency (top-N, not a threshold) |
+| `segment --min-orders 2 --min-spent 1000 --region ZA-GP` | match order-count / spend / last-order-date / region filters |
+| `attributes --filter allow_broadcast_true` | match a broadcast-permission state |
+| `messages --min-count 3 --sender user-whatsapp` | have ≥ N messages of a channel type |
+
+Two things to know: for **"who bought product X"** use
+`flowiq seg plan --bought "X" --window 90d` instead of `tag field` — it reads the
+real order line-items (accurate + windowable) rather than the order-history text.
+And a commit over 2000 contacts asks you to type the tag name to confirm
+(add `--yes` to skip). Everything is appends-only and reversible with `tag remove`.
+
 ## Keys, rotation, logging out
 
 - **`flowiq auth refresh`** — rotates this device's key in place (a fresh key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowapt/flowiq-cli",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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": {