superx-cli 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.2 (2026-09-16)
+
+- Lead search offer: `signals:search --offer "<one sentence on what you sell>"` (3-300 chars) tells the search what is being sold, and it plans up to 10 buyer-side query angles from that (workflows, pain, competitors, brand, adjacent) instead of running your keywords verbatim. `--keywords` are now 2-5 short seed angles of how the BUYER talks (a symptom, a tool they already pay for, their jargon), not the product's name and no search operators. Adding `--offer` is the single biggest lever on lead quality; `SKILL.md` carries the updated recipe
+
 ## 0.5.1 (2026-09-14)
 
 - Lead search recency: `signals:search --max-age-days <n>` only counts posts from the last N days (1-90, default 30), so every lead comes from something written recently rather than a lifetime match. Older matches are skipped and counted in `freshness.stale_skipped`, each lead's `provenance.posted_at` / `provenance.post_age_days` says when the matched post was written, and leads come back freshest first within each score. Use `--max-age-days 7` to catch a pain point while it is fresh; an empty result with `stale_skipped` above 0 means people do post about this, just not lately. `SKILL.md` and `PLAYBOOKS.md` (lead hunt recipe) carry the flag

package/SKILL.md

@@ -369,7 +369,8 @@ superx signals:feedback 4821 --clear
 ```bash
 # Find people on X right now (saves NOTHING: no agent, no stored leads)
 superx signals:search \
-  --keywords "losing customers to churn, cancellations killing my MRR" \
+  --offer "ChurnRadar, retention analytics that flags accounts about to cancel" \
+  --keywords "cancelled today, mrr dropped, renewal call, churn rate" \
   --icp "B2B SaaS founders worried about retention" \
   --precision discovery --max 10 --max-age-days 7
 
@@ -387,6 +388,7 @@ superx datasets:rows <dataset-id> --limit 50        # read every drafted message
 
 - **Nothing in this chain sends a DM.** `datasets:outreach-drafts` writes message TEXT onto the dataset's `message` column and stops there. A person reviews and sends them from the SuperX app. Never tell the user their messages have gone out, and never imply the CLI can send them.
 - `signals:suggest-keywords --icp "..."` and `signals:expand-icp (--text | --url)` stage what a new agent needs before you create one: keyword ideas, and the rubric the scorer reads the ICP as. Both are FREE and create nothing. Pass a suggestion to `signals:create-agent --keyword`; the rubric has nowhere to be saved (agents are created with `--icp`), so use it to sharpen that text. `--url` reads a website and also returns an `icp_description` to pass straight to `--icp`; it costs one of the account's 20 page reads a day, shared with the app, and takes up to a minute.
+- `signals:search --offer` is the single biggest lever on result quality: one sentence on what is being sold. `--keywords` are seed ANGLES for the plan, not the query, so write 2-5 short phrases of how the BUYER talks (workflows, tools they already pay for, jargon, a symptom), never the product's own name. The search plans up to 10 queries from those and runs them all: `data.queries_used` says how many angles it covered, `data.query_plan` lists each query with its angle and what it found, and `data.partial` is true when a time budget cut it short.
 - `signals:search` needs a key with the **write** scope (every non-GET API route does), even though it CREATES NOTHING. The leads exist only in that response, so save what you need. For an audience that keeps filling up on its own, use `signals:create-agent` instead. It takes up to a minute, and each lead comes from ONE matched post: `posts_count` is lifetime volume, not proof of current activity. That post is always recent: `--max-age-days` sets the window (1-90, default 30), older matches are skipped and counted in `freshness.stale_skipped`, and each lead's `provenance.posted_at` / `provenance.post_age_days` says when it was written. Use `--max-age-days 7` for a pain point worth catching while it is fresh; leads come back freshest first within each score, so keep that order. An empty result with a `stale_skipped` above 0 means people DO post about this, just not lately: broaden the keywords, or raise the window only if the user wants people active over a longer stretch.
 - `datasets:research` needs exactly one of `--handles` (max 25), `--list`, `--agent` or `--dataset`, and `--max` is 1-25 (default 10). Every hook in a brief QUOTES one of the person's real posts; proposed quotes that failed the verbatim check are dropped server-side, so a brief with no hooks is honest, not broken. More than 5 profiles run in the background (`202 collecting`) - pass `--wait` or poll `datasets:get`.
 - `datasets:outreach-drafts` needs a `--format` from the USER: their template or an example message. Never invent one. `[name]`, `[first]` and `[handle]` are kept intact for per-recipient fill-in at send time. A brief with no usable hook gets an honest generic message counted in `generic`, and a draft that names a DIFFERENT recipient is discarded and counted in `contaminated` (run it again to retry those rows). Re-running overwrites every draft.

package/dist/index.js

@@ -1207,6 +1207,7 @@ async function signalsSearch(argv) {
     keywords: argv.keywords,
     icp_description: argv.icp
   };
+  if (argv.offer) body.offer = argv.offer;
   if (argv.precision) body.precision = argv.precision;
   if (argv.max !== void 0) body.max_leads = argv.max;
   if (argv["max-age-days"] !== void 0) {
@@ -2837,13 +2838,16 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
   "signals:search",
   "Search X now for people matching an audience description (saves nothing)",
   (y) => accountOption(y).option("keywords", {
-    describe: "Plain-language phrases these people would post, comma-separated for alternatives. No search operators",
+    describe: "2-5 seed angles of how the BUYER talks, 2-3 words each, comma-separated: workflows, tools they already pay for, jargon, a symptom. Not the product's name, no search operators",
     type: "string",
     demandOption: true
   }).option("icp", {
     describe: "Who counts as a good lead, in 1-2 sentences: role, domain, and the intent that qualifies them",
     type: "string",
     demandOption: true
+  }).option("offer", {
+    describe: "What you are selling, one sentence (3-300 chars). The search plans its queries from this",
+    type: "string"
   }).option("precision", {
     describe: "high = only confident matches; discovery (default) = broader adjacent matches",
     type: "string",
@@ -2852,7 +2856,7 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
     describe: "Only posts from the last N days count (1-90, default 30). Use 7 to catch a fresh pain point",
     type: "number"
   }).example(
-    "$0 signals:search --keywords 'losing customers to churn' --icp 'B2B SaaS founders worried about retention'",
+    "$0 signals:search --offer 'ChurnRadar, retention analytics for B2B SaaS' --keywords 'cancelled today, mrr dropped, renewal call' --icp 'B2B SaaS founders worried about retention'",
     "Find people posting about churn right now"
   ).epilogue(
     "This CREATES NOTHING: no signal agent, no saved leads. Use signals:create-agent for an audience that keeps filling up. Reading X live costs AI credits (at least 1) plus one of the plan's daily lead searches, and draws on a platform-wide fair-use ceiling shared by every account. Takes up to a minute."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superx-cli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "SuperX CLI - command line interface to the SuperX API for Twitter/X growth: read posts and analytics, find engaged contacts, and schedule posts and threads",
   "main": "dist/index.js",
   "bin": {