superx-cli 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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
+
 ## 0.5.0 (2026-09-13)
 
 - Workers: `workers:list` shows the account's Workers (the agents inside SuperX that write posts for one account on a schedule) with their schedules and next run times, and `workers:suggestions` lists what they wrote, newest first (`--status to_review|drafted|scheduled|dismissed|all`, default `to_review`; `--worker <id>`, `--limit` up to 100, `--page`). `workers:draft <id>` saves one suggestion to Drafts as written, `workers:schedule <id> --at <UTC ISO-8601>` queues it as written (no Default Post Settings inherited: add auto retweet, plug, delete or DM afterwards with `scheduled:update`), and `workers:dismiss <id>` clears it out of To review. Workers are created, edited and run in the app; there is no create or run command. A suggestion can only be saved once (second save = 400, another account's Worker = 404). Costs no AI credits. `PLAYBOOKS.md` gains recipe 29, Worker output review

package/PLAYBOOKS.md

@@ -351,10 +351,10 @@ A live search of X right now for people matching the audience described, scored,
 
 ```bash
 superx signals:suggest-keywords --icp "<who you want to reach>"
-superx signals:search --keywords "<phrase>,<phrase>" --icp "<who you want to reach>" --max 30
+superx signals:search --keywords "<phrase>,<phrase>" --icp "<who you want to reach>" --max 30 --max-age-days 7
 ```
 
-The search creates no agent and stores no leads, so keep what the person needs from that one response.
+The search creates no agent and stores no leads, so keep what the person needs from that one response. `--max-age-days` is the recency window (1-90, default 30): 7 for a pain point worth catching while it is fresh.
 
 MCP: `suggest_keywords` -> `search_leads`
 

package/SKILL.md

@@ -371,7 +371,7 @@ superx signals:feedback 4821 --clear
 superx signals:search \
   --keywords "losing customers to churn, cancellations killing my MRR" \
   --icp "B2B SaaS founders worried about retention" \
-  --precision discovery --max 10
+  --precision discovery --max 10 --max-age-days 7
 
 # Turn people into outreach briefs saved as a dataset (exactly one source)
 superx datasets:research --handles levelsio,naval --focus "audience-growth tooling" --wait
@@ -387,7 +387,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` 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.
+- `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.
 - Costs: `signals:search` is measured, at least 1 credit for a search that reaches X; `datasets:research` is a flat **1 credit per profile actually researched** (the rest are returned); `datasets:outreach-drafts` is measured and usually 1-3 credits. Research settles when the run finishes, so after a `--wait` read `superx status` for the pool rather than the response.

package/dist/index.js

@@ -1209,6 +1209,9 @@ async function signalsSearch(argv) {
   };
   if (argv.precision) body.precision = argv.precision;
   if (argv.max !== void 0) body.max_leads = argv.max;
+  if (argv["max-age-days"] !== void 0) {
+    body.max_post_age_days = argv["max-age-days"];
+  }
   if (argv.account) body.account_id = argv.account;
   const api = new SuperXAPI(getConfig());
   printJson(await api.searchLeads(body));
@@ -2845,7 +2848,10 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
     describe: "high = only confident matches; discovery (default) = broader adjacent matches",
     type: "string",
     choices: ["high", "discovery"]
-  }).option("max", { describe: "Leads to return at most (1-30, default 10)", type: "number" }).example(
+  }).option("max", { describe: "Leads to return at most (1-30, default 10)", type: "number" }).option("max-age-days", {
+    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'",
     "Find people posting about churn right now"
   ).epilogue(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superx-cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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": {