superx-cli 0.2.0 → 0.4.0

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`) 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 28 goal-shaped recipes (`PLAYBOOKS.md`) so agents do not just schedule posts, they follow a strategy that works
 
 ---
 
@@ -80,7 +80,7 @@ superx me         # Key owner, plan tier, key name and scopes
 superx accounts   # X accounts this key can read (main account first)
 ```
 
-Read commands accept `--account <id>` (an id from `superx accounts`) to select a linked or shared account. Omitting it means the main account.
+Read commands accept `--account <id>` (an id from `superx accounts`) to select a linked or shared account. Write commands accept it too for your main or linked accounts; accounts shared with you by other people are read-only (403 `writes_main_account_only`). Omitting it means the main account.
 
 ### Posts
 
@@ -124,7 +124,7 @@ superx inspiration:search "indie hackers" --sort outlier --min-likes 500
 superx inspiration:search "AI tools" --min-followers 1000 --max-followers 50000
 ```
 
-Searches a library of 50M+ real high-performing posts by topic. Options: `--sort relevant|recent|likes|reposts|impressions|outlier`, `--min-likes/--min-reposts/--min-replies/--min-bookmarks/--min-impressions`, `--min-followers/--max-followers` (author size), `--since/--until` (UTC ISO-8601), `--lang` (default en), `--exclude-topics "crypto,politics"`, `--limit` (max 50), `--page` (1-7). Each result carries an `outlier_score`: how far the post outperformed the norm for its author's follower tier. Results are intentionally varied between runs; use them for structures and hooks to remix, never to copy.
+Searches a library of 50M+ real high-performing posts by topic. Options: `--sort relevant|recent|likes|reposts|impressions|outlier`, `--min-likes/--min-reposts/--min-replies/--min-bookmarks/--min-impressions`, `--min-followers/--max-followers` (author size), `--since/--until` (UTC ISO-8601), `--lang` (default en), `--exclude-topics "crypto,politics"`, `--limit` (max 50), `--page` (1-7). Each result carries an `outlier_score`: how far the post outperformed the norm for its author's follower tier. Results are relevance-ranked, strongest matches first, with weak and promotional matches filtered out, so a page may return fewer than `--limit` posts. Use them for structures and hooks to remix, never to copy.
 
 ### Contacts (who engages with you)
 
@@ -142,7 +142,24 @@ superx lists:add-member <list-id> --handle levelsio  # or --x-user-id 44196397
 superx lists:remove-member <list-id> <member-id>
 ```
 
-Lists are the saved people-collections from the SuperX app. System lists (Followers, Following, Repliers, Reposters) appear in `lists:list` but are read-only and their members are not available through the API (400 `system_list_not_supported`). Adding someone already in a list is harmless: the API returns the existing member with `"duplicate": true` and writes nothing. Member writes are main account only.
+Lists are the saved people-collections from the SuperX app. System lists (Followers, Following, Repliers, Reposters) appear in `lists:list` but are read-only and their members are not available through the API (400 `system_list_not_supported`). Adding someone already in a list is harmless: the API returns the existing member with `"duplicate": true` and writes nothing. Member writes work on your main or linked accounts with `--account`; shared accounts are read-only.
+
+### Engage (feed posts to reply to)
+
+```bash
+superx engage:feeds                                  # the feeds saved in the app's Engage tab
+superx engage:posts <feed-id> --limit 50             # one big page of candidate posts
+superx engage:posts <feed-id> --mode latest --fresh true
+superx engage:posts <feed-id> --exclude 1234567890,1234567891   # next batch, minus what you have
+```
+
+Engage feeds are the keyword and list feeds set up in the SuperX app. `engage:feeds` returns each feed's `id`, `name`, `type` (`keywords`, `list`, or `x_list`), `active` flag, and `fetch_units` (what one fetch of it costs: 1 for a keyword feed, at most 3 for list feeds, and an imported X list charges 1 at fetch time). Feeds are created and edited in the app, not through the API.
+
+`engage:posts <feed-id>` returns candidate posts with text, author (handle, bio, follower counts), engagement metrics, and post time, plus `has_more` and the `feed` it came from. Results are for review: replies are written and sent by a person in SuperX, so there is no reply command. Sending replies that read as inauthentic can get an X account suspended under X's inauthentic-behavior rules and a SuperX account terminated; AI output must be reviewed and meaningfully edited by a person before it is posted, and reply activity is logged and may be audited.
+
+`--limit` (1-50, default 20) applies to keyword feeds. List feeds ignore it upstream and return one page per fetch, about 10 posts for a member list and 20 to 25 for an imported X list, with `--limit` only trimming that page; page those with `--exclude` instead. On a keyword feed a 50-post page costs the same as a 20-post page, so ask for 50 a few times a day and filter locally rather than polling. Feeds refresh over hours, so fetching more often than hourly returns the same posts. `--mode top|latest` defaults to `top`; `--fresh true` skips the cache; `--include-replied true` keeps posts already replied to, skipped, or blocked and flags them with `replied`. `--exclude` takes up to 100 post ids and is how you page.
+
+Feed fetches have their own per-plan daily allowance (Trial 20, Pro 60, Advanced 120, Ultra 300 per day), separate from the read budget; per minute: trial 2, pro 5, advanced 10, ultra 15. A list feed that rotates its members counts as up to 3 fetches, every other feed as 1; `engage:feeds` never touches the allowance. Over the cap you get 429 `rate_limited`: the API returns `remaining_day`; the CLI prints the message and the retry delay. Fetches also run a few at a time across all API users, so a 429 with a retry delay can mean busy rather than out of allowance; wait and retry. Posts a fetch returns count as seen and are demoted in later fetches, in the app as well as the API. An unknown feed id returns 404 `feed_not_found`.
 
 ### Signals (automated lead finding)
 
@@ -152,7 +169,7 @@ superx signals:leads --limit 20                      # newest leads across all a
 superx signals:leads --agent 3 --deposited false     # new leads from one agent
 superx signals:leads --since "2026-07-01T00:00:00Z"  # leads discovered since July
 
-# Create an agent (main account only, write scope)
+# Create an agent (write scope; main or linked account via --account)
 superx signals:create-agent \
   --name "Build in public founders" \
   --icp "Indie founders building SaaS in public, sharing MRR and launches" \
@@ -218,7 +235,7 @@ superx scheduled:update <post-id> --clear-tags --clear-title --clear-scratchpad
 
 A new `--at` time alone never schedules a draft; pass `--status scheduled` explicitly. CAUTION: replacement text is a full replace, media included. `--text` without `--media` removes any images the post carried; re-list the current `object_key`s (visible in `scheduled:list`) to keep them. Title, scratchpad, tag, and time edits never touch media.
 
-Write constraints in the current API version: main account only; images via `media:upload` (no video); one of `--text`, `--part`, or `--parts-json`. Idempotent replays add `"replayed": true` to the output. Note that drafts have no scheduled time, so `--from/--to` filters exclude them.
+Write constraints in the current API version: main or linked accounts via `--account` (shared accounts are read-only; tags are workspace-wide and main account only); images via `media:upload` (no video); one of `--text`, `--part`, or `--parts-json`. Idempotent replays add `"replayed": true` to the output. Note that drafts have no scheduled time, so `--from/--to` filters exclude them.
 
 ### Advanced settings
 
@@ -327,6 +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.
 - **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.
@@ -380,6 +398,8 @@ The CLI talks to these SuperX API endpoints (base `https://api.superx.so/v1`):
 | `/signals/agents/:id` | PATCH | `signals:pause-agent <id>` / `signals:resume-agent <id>` |
 | `/signals/agents/:id` | DELETE | `signals:delete-agent <id>` |
 | `/signals/leads` | GET | `signals:leads` |
+| `/engage/feeds` | GET | `engage:feeds` |
+| `/engage/feeds/:id/posts` | GET | `engage:posts <feedId>` |
 | `/media` | POST | `media:upload <file>` |
 | `/scheduled-posts` | GET | `scheduled:list` |
 | `/scheduled-posts` | POST | `scheduled:create` |
@@ -476,6 +496,7 @@ src/
     ├── contacts.ts   # contacts:list / contacts:replies
     ├── lists.ts      # lists:list / lists:members / lists:add-member / lists:remove-member
     ├── signals.ts    # signals:agents / signals:leads / signals:create-agent / signals:pause-agent / signals:resume-agent / signals:delete-agent
+    ├── engage.ts     # engage:feeds / engage:posts
     ├── media.ts      # media:upload
     ├── scheduled.ts  # scheduled:list / scheduled:create / scheduled:update / scheduled:delete
     ├── tags.ts       # tags:list / tags:create / tags:update / tags:delete
@@ -485,8 +506,6 @@ src/
     └── docs.ts       # docs
 ```
 
-Maintainer note: `SKILL.md` (repo root) and `skills/superx/SKILL.md` must stay byte-identical. Edit the root file and copy it over the nested one.
-
 ---
 
 ## Quick reference
@@ -513,18 +532,20 @@ superx lists:list
 superx lists:members <list-id> --q "founder"
 superx signals:agents
 superx signals:leads --agent 3 --deposited false
+superx engage:feeds
+superx engage:posts <feed-id> --limit 50
 
-# Contact list writes (main account)
+# Contact list writes (main or linked account)
 superx lists:add-member <list-id> --handle levelsio
 superx lists:remove-member <list-id> <member-id>
 
-# Signal agent writes (main account)
+# Signal agent writes (main or linked account)
 superx signals:create-agent --name "..." --icp "..." --keyword "..."
 superx signals:pause-agent <id>
 superx signals:resume-agent <id>
 superx signals:delete-agent <id>
 
-# Writes (main account)
+# Writes (main or linked account via --account)
 superx scheduled:create --text "Post"                                # Draft
 superx scheduled:create --text "Post" --at "2026-08-01T15:00:00Z"    # Scheduled
 superx scheduled:create --part "1/" --part "2/" --at "..."           # Thread