superx-cli 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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
+- Drafts: `scheduled:list --status draft` now lists drafts newest first (the API previously returned the oldest drafts) and accepts `--page`
+- Docs and help text only: `posts:draft --voice mine` writes in the voice of the account you pass in `--account` (your main account when omitted, using that account's own posts and style guide), and `posts:draft` returns 403 `writes_main_account_only` on an account shared with you, unlike the other writing helpers
+
 ## 0.4.0 (2026-09-11)
 
 - Playbooks: a new `PLAYBOOKS.md` ships with the package, holding 28 goal-shaped recipes, one per SuperX skill (weekly recap, week of posts, queue reshuffle, reply sprint, lead hunt, audience export, warm outreach and the rest). Each entry gives the CLI chain in order, the equivalent MCP tool chain, and where the chain STOPS: the four that stop short of a send say so in the entry, because no reply is posted and no DM is delivered from here. `SKILL.md` gains a `## Playbooks` index so an agent can pick a recipe by goal before opening the file

package/PLAYBOOKS.md

@@ -1,6 +1,6 @@
 # SuperX Playbooks
 
-Twenty-eight goal-shaped recipes, one per SuperX skill. Each is the same job the
+Twenty-nine goal-shaped recipes, one per SuperX skill. Each is the same job the
 in-app skill of that name does, run from the CLI or from the hosted MCP server.
 Pick by goal, run the chain in order, hand the result to the person.
 
@@ -219,6 +219,25 @@ MCP: `find_inspiration`
 
 Stops at: the posts and the suggested angles in chat. Reads only, no AI credits.
 
+### Worker Output Review
+
+The posts a Worker wrote while the person was away, triaged: save the good ones, queue one, clear the rest.
+
+```bash
+superx workers:list
+superx workers:suggestions --status to_review --limit 20
+superx workers:draft <suggestion-id>
+superx workers:schedule <suggestion-id> --at "<UTC ISO-8601 with Z>"
+superx workers:dismiss <suggestion-id>
+superx scheduled:list --status draft --limit 10
+```
+
+Workers are created, edited and RUN in the SuperX app: this chain only reads what they produced and acts on it. The text is saved exactly as the Worker wrote it, so show each suggestion to the person and let them pick before you save or queue anything. To change the wording, run it through `posts:remix` and save your version with `scheduled:create`, then dismiss the original. A suggestion can only be saved once, so a second draft or schedule call on the same id is a 400.
+
+MCP: `list_workers` -> `list_worker_suggestions` -> `draft_worker_suggestion` / `schedule_worker_suggestion` / `dismiss_worker_suggestion` -> `get_scheduled_posts`
+
+Stops at: the saved drafts and the queued post, for the person to edit. Reads and the three actions cost no AI credits.
+
 ---
 
 ## Queue
@@ -332,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/README.md

@@ -11,7 +11,7 @@ npx skills add superx-so/superx-agent
 Two things ship in this repo:
 
 - `superx-cli`, an npm package installing the `superx` binary (a thin client for `api.superx.so/v1`)
-- An agent skill (`SKILL.md`) plus a growth strategy guide (`PLAYBOOK.md`) and 28 goal-shaped recipes (`PLAYBOOKS.md`) so agents do not just schedule posts, they follow a strategy that works
+- An agent skill (`SKILL.md`) plus a growth strategy guide (`PLAYBOOK.md`) and 29 goal-shaped recipes (`PLAYBOOKS.md`) so agents do not just schedule posts, they follow a strategy that works
 
 ---
 
@@ -344,7 +344,7 @@ superx docs   # Prints the API quickstart as markdown; works without auth
 
 - **Skill included**: `npx skills add superx-so/superx-agent` installs [SKILL.md](./SKILL.md), a complete agent reference with hard rules, workflows, and gotchas.
 - **Strategy included**: [PLAYBOOK.md](./PLAYBOOK.md) distills the SuperX growth methodology (action hierarchy, out-of-network discovery, the 3-3-3 engagement loop, weekly operating system) into directives an agent can execute with this CLI. The skill instructs agents to read it before creating content.
-- **Playbooks included**: [PLAYBOOKS.md](./PLAYBOOKS.md) holds 28 goal-shaped recipes, one per SuperX skill, each with its CLI chain, the matching MCP tool chain, and the point where the agent hands the result back to a person.
+- **Playbooks included**: [PLAYBOOKS.md](./PLAYBOOKS.md) holds 29 goal-shaped recipes, one per SuperX skill, each with its CLI chain, the matching MCP tool chain, and the point where the agent hands the result back to a person.
 - **Clean JSON stdout**: no decoration to strip; every data command is `jq`-safe.
 - **Idempotent writes**: agents can retry `scheduled:create` safely with `--idempotency-key`.
 - **Self-describing**: `superx docs` fetches the current API quickstart at runtime.

package/SKILL.md

@@ -30,9 +30,9 @@ official website: https://superx.so
 
 **Rule 1: Run `superx status` before anything else.** Every other command fails without valid credentials. If the `superx` binary is missing, install it with `npm install -g superx-cli`. If not authenticated, either run `superx login` (interactive) or set `export SUPERX_API_KEY=sxk_...` (CI and non-interactive sessions). Keys are created at https://app.superx.so/account?tab=api.
 
-**Rule 2: Read PLAYBOOK.md before creating any content.** This repo ships a growth strategy guide (`PLAYBOOK.md`, also inside the installed npm package). It tells you WHAT to post, WHEN, and WHY: the action hierarchy, out-of-network discovery, the engagement loop, and the failure modes that kill reach. The CLI gives you data and actions; the playbook gives you judgment. Do not schedule content without it. For a goal-shaped task ("give me my weekly recap", "DM the people who replied to this post"), read `PLAYBOOKS.md` too: it holds the 28 named recipes with their exact command chains, MCP tool names and stopping points.
+**Rule 2: Read PLAYBOOK.md before creating any content.** This repo ships a growth strategy guide (`PLAYBOOK.md`, also inside the installed npm package). It tells you WHAT to post, WHEN, and WHY: the action hierarchy, out-of-network discovery, the engagement loop, and the failure modes that kill reach. The CLI gives you data and actions; the playbook gives you judgment. Do not schedule content without it. For a goal-shaped task ("give me my weekly recap", "DM the people who replied to this post"), read `PLAYBOOKS.md` too: it holds the 29 named recipes with their exact command chains, MCP tool names and stopping points.
 
-**Rule 3: Know the write constraints.** `scheduled:create` without `--at` creates a DRAFT (nothing publishes). With `--at` it schedules for that time. `scheduled:update` changes only the flags you pass, and a new `--at` alone never schedules a draft; add `--status scheduled` to promote. Writes work on your main account or any linked account (pass the same `--account` you used to read it); accounts shared with you by other people are read-only, and tags are workspace-wide. Images attach via `media:upload` then `--media` (JPG/PNG/WEBP up to 5MB, GIF up to 15MB; max 4 images or 1 GIF per post); video is not supported. Timestamps MUST be UTC ISO-8601 with an explicit `Z` or offset; naive timestamps are rejected with 400. `posts:publish` and `articles:publish` post to X IMMEDIATELY and irreversibly; treat them like hitting Publish in public and get human confirmation of the exact text unless the user already gave it. `posts:publish` also requires `--idempotency-key`, which you reuse verbatim on any retry. `posts:draft` writes post text in the user's voice and saves NOTHING: show the drafts, let the user pick and edit one, then pass the final text to `scheduled:create` yourself; it costs AI credits per draft, so ask for the count the user actually wants.
+**Rule 3: Know the write constraints.** `scheduled:create` without `--at` creates a DRAFT (nothing publishes). With `--at` it schedules for that time. `scheduled:update` changes only the flags you pass, and a new `--at` alone never schedules a draft; add `--status scheduled` to promote. Writes work on your main account or any linked account (pass the same `--account` you used to read it); accounts shared with you by other people are read-only, and tags are workspace-wide. Images attach via `media:upload` then `--media` (JPG/PNG/WEBP up to 5MB, GIF up to 15MB; max 4 images or 1 GIF per post); video is not supported. Timestamps MUST be UTC ISO-8601 with an explicit `Z` or offset; naive timestamps are rejected with 400. `posts:publish` and `articles:publish` post to X IMMEDIATELY and irreversibly; treat them like hitting Publish in public and get human confirmation of the exact text unless the user already gave it. `posts:publish` also requires `--idempotency-key`, which you reuse verbatim on any retry. `posts:draft` writes post text in the user's voice and saves NOTHING: show the drafts, let the user pick and edit one, then pass the final text to `scheduled:create` yourself; it costs AI credits per draft, so ask for the count the user actually wants. `--voice mine` is the voice of the `--account` you pass (its own posts and style guide); shared accounts are refused.
 
 ---
 
@@ -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.
@@ -424,6 +424,29 @@ superx tools:predict --a "$(cat v1.txt)" --b "$(cat v2.txt)"
 - `tools:factcheck` reports `result` (true, false or unknown), a one-sentence `comment` and the `sources` it read. It is a model's reading of a couple of search results, NOT a guarantee: show the sources and never present the verdict as settled. `tools:predict` scores are an opinion for comparing two drafts against each other, not a prediction of reach.
 - Costs are measured AI credits: typically 1 each, and 2 for a remix or a reply draft. None of them spends a live X request except `engage:reply-draft --post`.
 
+### Workers (posts written for you on a schedule)
+
+```bash
+superx workers:list                                  # your Workers, schedules, next run times
+superx workers:suggestions --limit 10                # newest posts waiting for review
+superx workers:suggestions --worker 3 --status all   # everything one Worker has written
+superx workers:suggestions --status scheduled        # the ones already queued
+
+# Act on one (suggestion id from workers:suggestions; write scope)
+superx workers:draft 4821                            # save it to Drafts
+superx workers:schedule 4821 --at "2026-09-15T14:00:00Z"
+superx workers:dismiss 4821                          # clear it out of To review
+```
+
+- A Worker is an agent inside SuperX that writes posts for one account on a schedule. Workers are CREATED, EDITED AND RUN IN THE APP: there is no create or run command here, and no API endpoint for either. This chain reads what they wrote and acts on it.
+- `workers:suggestions` defaults to `--status to_review`, the ones waiting on a person. The other values are `drafted`, `scheduled`, `dismissed` and `all`. `--worker <id>` narrows to one Worker, `--limit` (max 100, default 20) and `--page` walk the list, newest first.
+- Each suggestion carries `id`, `worker_id`, `text`, `status`, `generated_at`, the `drafted_at`/`scheduled_at`/`dismissed_at` stamps, `post_id` once it has been saved, and `reference` (the kind of source the Worker wrote from). The Worker's own collection ids stay private.
+- AI OUTPUT NEEDS A HUMAN: show the user the text and let them edit it before it is saved or queued. `workers:draft` saves it as written, `workers:schedule` queues it as written, and neither asks for confirmation. To change the wording first, rewrite it with `posts:remix` or `tools:rephrase` and save your version with `scheduled:create` instead, then `workers:dismiss` the original so the list stays clean.
+- `workers:schedule` requires `--at` in UTC ISO-8601. The post does NOT inherit the account's Default Post Settings: it carries only what the call passes, which from the CLI is nothing beyond the time, so no auto retweet, auto plug, auto delete or auto DM. Add those afterwards with `scheduled:update`, which is also how you retime it; `scheduled:delete` cancels it.
+- One suggestion can only be saved once. A second `workers:draft` or `workers:schedule` on the same id is a 400, as is acting on a dismissed one. An id belonging to another account's Worker is a 404.
+- `workers:draft` and `workers:schedule` land the post in the same Drafts and Queue the rest of the CLI reads: `scheduled:list --status draft` shows a drafted suggestion, newest first, and the response gives you its `post_id` directly.
+- Endpoints behind these commands: `GET /v1/workers`, `GET /v1/workers/suggestions`, `POST /v1/workers/suggestions/{id}/draft`, `POST /v1/workers/suggestions/{id}/schedule`, `POST /v1/workers/suggestions/{id}/dismiss`. The three POSTs need a key with the **write** scope. Every command here takes `--account` for an account you own (main or linked); an account someone shared with you is read-only, so a write against it returns 403 `writes_main_account_only`.
+
 ### Scheduling
 
 ```bash
@@ -809,7 +832,7 @@ Full recipes with flags and MCP tool chains: [PLAYBOOKS.md](./PLAYBOOKS.md). Pic
 1. **Naive timestamps are rejected (400)**. Always include `Z` or an offset: `2026-08-01T15:00:00Z`, not `2026-08-01T15:00:00`.
 2. **Schedule window**: `--at` must be at least 60 seconds in the future and within 18 months.
 3. **Read-only keys cannot write**: `scheduled:create`/`scheduled:delete` with a read-only key returns 403 `insufficient_scope`. Check `superx me` for the key's scopes.
-4. **Shared accounts are read-only for writes**: writes work on your main account or any linked account (pass the same `--account` you used to read it). Accounts shared with you by other people return 403 `writes_main_account_only` for post, article, signal and contact-list member writes. `context:*` and `queue:set` are per-account settings that do accept a shared account.
+4. **Shared accounts are read-only for writes**: writes work on your main account or any linked account (pass the same `--account` you used to read it). Accounts shared with you by other people return 403 `writes_main_account_only` for post, article, signal and contact-list member writes, and for `posts:draft`. `context:*` and `queue:set` are per-account settings that do accept a shared account.
 5. **Images need an upload first**: `--media` takes `object_key`s from `media:upload`, never file paths or URLs. Unknown keys return 400 `invalid_media`; a presign whose bytes were never PUT returns 400 `media_not_uploaded`. Video is not supported.
 6. **Size caps**: max 25 thread parts, 25,000 characters total.
 7. **Rate limited (429)**: `rate_limited` on stderr with a retry delay. Back off; do not hammer.
@@ -858,7 +881,7 @@ Full recipes with flags and MCP tool chains: [PLAYBOOKS.md](./PLAYBOOKS.md). Pic
 49. **Nothing in the outreach chain sends a DM.** `datasets:outreach-drafts` writes message TEXT onto a research dataset and stops there; a person reviews and sends them from the SuperX app. Never say messages were sent and never offer to send them. If the user explicitly asks, you may QUEUE them with `dm:campaign` (one recipient entry per person, each with its own `message`), which is still an enqueue: the app sends. Ask the user for the `--format`; never invent one. Re-running overwrites every draft, `generic` counts messages written with no personal claims (that brief had no usable hook), and `contaminated` counts drafts discarded for naming a different recipient - run it again to retry those rows.
 50. **`signals:search` saves nothing and `datasets:research` charges per profile.** A search creates no agent and no stored leads, so keep what the user needs from that response; use `signals:create-agent` when they want leads to keep arriving. Research is a flat 1 credit per profile ACTUALLY researched (handles that cannot be resolved, and people with no recent posts, come back in `skipped` and are refunded), and over 5 profiles it runs in the background: never state a brief count from a `collecting` result. `datasets:refine` also creates a dataset, so it spends one of the same 10 collections a day.
 51. **`ai_action_limited` has two scopes.** Read `error.scope` before telling the user anything: `"account"` is their plan's own daily cap for that action, `"platform"` is a fair-use ceiling on live-data actions shared by every SuperX account. On `"platform"` their own allowance is untouched, so wait for `reset_at` and retry rather than reporting them as out of quota.
-52. **The writing helpers draft, they never publish.** `engage:reply-draft`, `posts:remix`, `tools:inline-edit`, `tools:rephrase`, `tools:factcheck` and `tools:predict` all return TEXT and stop there - nothing is posted, scheduled or sent. Show the output, let the user edit it, and use `posts:draft`, `scheduled:create` or `posts:publish` when they say so. A `tools:factcheck` verdict is a model reading two search results: report it with its sources, never as settled fact.
+52. **The writing helpers draft, they never publish.** `engage:reply-draft`, `posts:remix`, `tools:inline-edit`, `tools:rephrase`, `tools:factcheck` and `tools:predict` all return TEXT and stop there - nothing is posted, scheduled or sent. Unlike `posts:draft`, they also accept an account shared with you. Show the output, let the user edit it, and use `posts:draft`, `scheduled:create` or `posts:publish` when they say so. A `tools:factcheck` verdict is a model reading two search results: report it with its sources, never as settled fact.
 53. **The free helpers cost nothing but are not unlimited.** `context:regenerate-style-guide` is once an hour per account and does not override a manual style-guide setting; `context:scrape-product` and `signals:expand-icp --url` share 20 page reads a day with the SuperX app, and `--url` also inherits the app's limit of 10 prefills per 10 minutes (that one comes back as `rate_limited` and clears in about a minute, so retry rather than reporting a daily budget); `signals:suggest-keywords` and `signals:expand-icp --text` have no ceiling of their own, so do not loop them - each one is a model call. All five send `X-Credits-Remaining` but no `X-Credits-Charged`, because nothing was charged. All four commands still need a key with the write scope: they are POSTs, and every non-GET API route needs it.
 54. **A DM campaign is an ENQUEUE, not a send.** `dm:campaign` returns counts of what was QUEUED; the SuperX app's scheduler sends them later, within the account's daily and monthly DM limits, so never report messages as delivered from that response - `dm:campaign-status` and `dm:queue` show what actually went out. Confirm the recipient list and the exact text with the user first: they are responsible for these messages under X's automation rules. Cancel the unsent ones with `dm:cancel`; anything already sent cannot be recalled.
 

package/dist/index.js

@@ -317,6 +317,26 @@ var SuperXAPI = class {
   async setLeadFeedback(leadId, body) {
     return (await this.request(`/signals/leads/${leadId}/feedback`, { method: "POST", body })).json;
   }
+  // --- Workers ---
+  async listWorkers(query = {}) {
+    return (await this.request("/workers", { query })).json;
+  }
+  /** The posts your Workers have written, newest first. */
+  async listWorkerSuggestions(query = {}) {
+    return (await this.request("/workers/suggestions", { query })).json;
+  }
+  /** Save one suggestion as a draft. Nothing is posted. */
+  async draftWorkerSuggestion(id, body) {
+    return (await this.request(`/workers/suggestions/${id}/draft`, { method: "POST", body })).json;
+  }
+  /** Save one suggestion as a scheduled post. */
+  async scheduleWorkerSuggestion(id, body) {
+    return (await this.request(`/workers/suggestions/${id}/schedule`, { method: "POST", body })).json;
+  }
+  /** Clear one suggestion out of the To review list. */
+  async dismissWorkerSuggestion(id, body) {
+    return (await this.request(`/workers/suggestions/${id}/dismiss`, { method: "POST", body })).json;
+  }
   // --- Engage ---
   async listEngageFeeds(query = {}) {
     return (await this.request("/engage/feeds", { query })).json;
@@ -1189,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));
@@ -1318,6 +1341,47 @@ async function signalsExpandIcp(argv) {
   printJson(url ? await api.expandIcpFromUrl(body) : await api.expandIcp(body));
 }
 
+// src/commands/workers.ts
+async function workersList(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.listWorkers({ account_id: argv.account }));
+}
+async function workersSuggestions(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.listWorkerSuggestions({
+      account_id: argv.account,
+      status: argv.status,
+      worker_id: argv.worker,
+      limit: argv.limit,
+      page: argv.page
+    })
+  );
+}
+async function workersDraft(argv) {
+  const body = {};
+  if (argv.account) body.account_id = argv.account;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.draftWorkerSuggestion(argv.id, body));
+}
+async function workersSchedule(argv) {
+  if (typeof argv.at !== "string" || argv.at.length === 0) {
+    note("--at is required: the UTC ISO-8601 time to post, for example 2026-09-15T14:00:00Z.");
+    process.exit(1);
+    return;
+  }
+  const body = { scheduled_for: argv.at };
+  if (argv.account) body.account_id = argv.account;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.scheduleWorkerSuggestion(argv.id, body));
+}
+async function workersDismiss(argv) {
+  const body = {};
+  if (argv.account) body.account_id = argv.account;
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.dismissWorkerSuggestion(argv.id, body));
+}
+
 // src/commands/engage.ts
 async function engageFeeds(argv) {
   const api = new SuperXAPI(getConfig());
@@ -2354,7 +2418,7 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
     describe: "How many drafts to write, 1 to 3 (default 1). Each one costs credits",
     type: "number"
   }).option("voice", {
-    describe: "Whose voice to write in",
+    describe: "Whose voice to write in; mine is the voice of the account passed in --account, or your main account if --account is omitted",
     type: "string",
     choices: ["mine", "creator", "hybrid"]
   }).option("creator", {
@@ -2784,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(
@@ -2916,6 +2983,49 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
   "Delete a signal agent (its saved leads and contact list stay untouched)",
   (y) => y.positional("id", { describe: "Agent id (from signals:agents)", type: "number" }),
   run(signalsDeleteAgent)
+).command(
+  "workers:list",
+  "List your Workers (the agents that write posts for you on a schedule)",
+  (y) => accountOption(y).example("$0 workers:list", "Your Workers, their schedules and next run times").epilogue(
+    "Workers are created, edited and run in the SuperX app. This reads them so you can tell which Worker a suggestion came from."
+  ),
+  run(workersList)
+).command(
+  "workers:suggestions",
+  "List the posts your Workers have written, newest first",
+  (y) => paginationOptions(accountOption(y)).option("status", {
+    describe: "to_review (default) = waiting on you; drafted / scheduled = already saved; dismissed = cleared; all = everything",
+    type: "string",
+    choices: ["to_review", "drafted", "scheduled", "dismissed", "all"]
+  }).option("worker", { describe: "Narrow to one Worker by its numeric id (from workers:list)", type: "number" }).example("$0 workers:suggestions --limit 10", "Ten newest posts waiting for review").example("$0 workers:suggestions --worker 3 --status all", "Everything Worker 3 has written").epilogue(
+    "Reading suggestions costs nothing and changes nothing. Act on one with workers:draft, workers:schedule or workers:dismiss."
+  ),
+  run(workersSuggestions)
+).command(
+  "workers:draft <id>",
+  "Save one Worker suggestion as a draft (nothing is posted)",
+  (y) => accountOption(y).positional("id", { describe: "Suggestion id (from workers:suggestions)", type: "number" }).example("$0 workers:draft 4821", "Move it into Drafts, where scheduled:list --status draft finds it").epilogue(
+    "The draft keeps the Worker's text as written. Edit it with scheduled:update, or rewrite it first with posts:remix and then save your own version."
+  ),
+  run(workersDraft)
+).command(
+  "workers:schedule <id>",
+  "Schedule one Worker suggestion to post at a given time",
+  (y) => accountOption(y).positional("id", { describe: "Suggestion id (from workers:suggestions)", type: "number" }).option("at", {
+    describe: "When to post, UTC ISO-8601 (for example 2026-09-15T14:00:00Z)",
+    type: "string",
+    demandOption: true
+  }).example("$0 workers:schedule 4821 --at 2026-09-15T14:00:00Z", "Queue it for Tuesday afternoon").epilogue(
+    "The post does not inherit your Default Post Settings: it carries only what this call passes, which is nothing beyond the time. Add auto retweet, auto plug or auto delete afterwards with scheduled:update, which also retimes it; scheduled:delete cancels it."
+  ),
+  run(workersSchedule)
+).command(
+  "workers:dismiss <id>",
+  "Clear one Worker suggestion out of the To review list",
+  (y) => accountOption(y).positional("id", { describe: "Suggestion id (from workers:suggestions)", type: "number" }).example("$0 workers:dismiss 4821", "Skip this one").epilogue(
+    "Dismissing drops it from the default to_review list. It stays readable with --status dismissed, and nothing already drafted or scheduled is affected."
+  ),
+  run(workersDismiss)
 ).command(
   "engage:feeds",
   "List the Engage feeds set up in the app",

package/package.json

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