---
name: social-autoposter-setup
description: "Set up social-autoposter for a new user end to end. Installs/repairs the runtime, discovers product and voice context, connects X/Twitter, seeds search topics, schedules the draft autopilot, and verifies it produces a draft. Use when: 'set up social autoposter', 'install social autoposter', 'configure social posting'."
---

# Social Autoposter Setup

Set up social-autoposter end to end. Treat the user's setup request as a terminal
goal, not as the beginning of an interview.

## Operating contract

- Keep taking the next safe setup action until the system is working end to end.
- Do not ask whether to run setup, install a dependency, inspect status, connect
  X, scan the profile, research the website, save inferred fields, seed topics,
  or retry a recoverable failure. Do them.
- An explicit request to set up social-autoposter authorizes its owned local
  runtime installation and importing only x.com/twitter.com session cookies
  into its managed browser. Briefly warn that macOS keychain prompts may appear,
  then proceed; do not wait for another yes/no reply.
- Use existing configuration, the user's message/context, their connected X
  profile, public website pages, and reasonable factual inference before asking
  for information.
- Ask at most one bundled blocking question, and only when required information
  cannot be discovered or safely inferred. The usual legitimate blocker is:
  there is no configured project, no clear product URL in context or the X
  profile, and no way to identify what product to market.
- Never post a draft during setup unless the user explicitly asked for that.
- Never hand-run the X cycle. Do not run `run-twitter-cycle.sh`,
  `claude_job.py`, or any cycle script directly, and never offer to "trigger a
  cycle" or "run one now" so a draft appears faster. Only the launchd kicker may
  fire the cycle, with its required environment. A manual kick produces an
  empty-plan artifact and blocks the autopilot. Verification means scheduling
  the autopilot and letting the kicker drive it; you wait and poll, you never
  trigger.
- Do not edit the MCP server, plugin source, or an unrelated user workspace to
  work around setup failures. Use the product's setup/install tools.

## Definition of done

Do not report setup complete until all of these are true:

1. The owned runtime is installed and ready.
2. At least one project is ready with name, website, description, ICP, voice,
   and search topics. For the personal-brand persona, the search topics and the
   grounding corpus come from the user's dictation interview (below), not from
   the profile scan alone.
3. Search topics have been seeded into the backend. Seeding is POSTPONED until
   after the dictation interview so the topics reflect what the user wants to be
   in conversations about, not only what they already posted.
4. X is connected and the real handle has been auto-detected.
5. The draft autopilot is scheduled and has produced a draft card without
   posting. A returned/pending review batch is the strongest success signal. If X
   simply has no matching supply, report that precise result only after
   configuration/auth/runtime checks pass.

## Architecture

- **Config**: `~/social-autoposter/config.json` — `projects[]` (what to post
  about) and `accounts` (where to post).
- **Data + stats**: backend HTTP API at `https://s4l.ai`, scoped by a stable
  per-install identity in `identity.json`. There is no local Postgres or
  `DATABASE_URL`.
- **Search topics**: the X cycle reads `project_search_topics`, seeded
  automatically from each project's `search_topics`. No topics means nothing
  to scan. `search_topics` is the ONLY field that changes what gets scanned;
  every other persona field only shapes the draft after a thread is found. For
  the persona, the profile scan is backward-looking (only what the user already
  posted), so topics are sourced primarily from the dictation interview.

## Choose the path

- If the social-autoposter MCP tools are connected (`project_config`, `runtime`,
  `queue_setup`, `approve_drafts`, `get_stats`, `dashboard`), use the MCP path.
  Do not hand-edit `config.json`.
- If only the CLI/skill is installed, use the CLI fallback.

## MCP path

### 1. Inspect and repair the environment

Call `project_config` in status mode and `runtime` (action:'status') immediately.

If the runtime is not ready:

1. Call `runtime` with action:'install'.
2. Poll `runtime` (action:'status') until it succeeds or returns a concrete failure.
3. For a recoverable/partial failure, call `runtime` action:'install' again and continue.
   Do not send the user away to install Chrome, Python, uv, Chromium, or
   browser-harness manually; the owned installer handles them.

Preserve any already-ready project or X connection. Resume from the first
incomplete milestone instead of restarting the interview.

### 2. Connect X and learn the user's voice

If X is not connected:

1. Call `project_config` with `action:'detect_x_sources'`.
2. Choose `recommended`, preferring a source whose `x_session` is present.
   Do not ask the user to choose a browser profile when the tool can choose.
3. Tell the user in one short progress update that macOS may show browser Safe
   Storage prompts and they should enter their Mac password and click **Allow**
   or **Always Allow**.
4. Immediately call `project_config` with `action:'connect_x', confirm:true` and the
   selected `x_source`. The setup request itself is authorization; do not add a
   separate consent round-trip.
5. If the result is transient, retry. If it opens managed Chrome in
   `needs_login`, tell the user to finish signing in to x.com in that window.
   This is an unavoidable user action, not a product-choice question. Re-run
   `connect_x` after sign-in and continue.

Once connected, call `project_config` with `action:'profile_scan'`. Treat the returned
bio, links, recent posts, and replies as grounding truth for the VOICE, not as the
primary source of topics (the scan only shows what they already posted):

- profession/identity;
- voice, casing, phrasing, and tone;
- ICP;
- wording or claims the user avoids;
- recurring themes (reinforcement for topics, not the origin).

Do not ask the user to approve the inferred voice during initial setup. Save a
specific, conservative best draft and mention afterward that it can be edited.

Then run the DICTATION INTERVIEW before extracting topics or seeding. This is
where the persona's `search_topics` and grounding corpus come from. Keep the
framing CHILL: this is a casual brain-dump, not a form. Invite the user to
answer the following in ONE spoken dictation (the Claude input box already
supports dictation, so they talk once and you split the answers into fields),
and make clear there is no pressure: they can answer as much or as little as
they like, skip anything, and come back to the rest whenever they feel like it.
Preface the list with one short low-key line saying exactly that (e.g. "No
pressure here, ramble as much or as little as you want; you can always come
back to this later."), then ask verbatim as a single numbered list:

1. Who are you, and what do you want to be known for? (→ description)
2. What subjects could you talk about for an hour, work and non-work? (→
   `search_topics`; this is the load-bearing answer, it is the only thing that
   decides what gets scanned on X)
3. Your most contrarian takes — what does everyone in your field get wrong, and
   what did you used to believe that you have reversed on? (→ content_angle +
   corpus)
4. What can you explain in 5 minutes that took you years, and what mistake do you
   watch beginners make over and over? (→ content_angle + corpus)
5. Best or worst thing that happened to you recently, and a failure you learned
   the most from? (→ corpus, keeps drafts current)
6. Who do you love or hate reading online, and any lines or phrases you say a
   lot? (→ voice calibration)
7. Anything off-limits (topics, companies, people), and how spicy can we get —
   safe, opinionated, or provocative? (→ content_guardrails + voice.never)

From the dictation, synthesize the fields: `search_topics` primarily from answer
2 (fold in recurring scan themes only as reinforcement), the rest from the other
answers. Keep the RAW transcript VERBATIM as the persona corpus (do not
paraphrase; the actual numbers, opinions, and phrasing are what make drafts sound
like them). Pass it as `content_corpus` when you call `engagement_mode` (or
`project_config`); it is stored in the `persona_corpus.txt` sidecar, not
config.json. If the user answers only some questions, take what they gave,
continue setup without nagging for the rest, and mention once that they can
answer the remaining questions any time later to make drafts sound more like
them. If the user declines or gives nothing usable, fall back to scan-derived
topics.

Only after the dictation is captured do you set the engagement mode / save the
persona, which seeds the topics. Do not seed topics from the scan before the
dictation.

### 3. Discover and research the product

Find the product URL in this order:

1. an existing project/config;
2. the user's setup request and conversation context;
3. the connected X profile URL/bio/recent posts;
4. a clearly associated public product discovered with web research.

When one product is clearly supported by the evidence, use it without asking.
If several are plausible and no primary product is evident, choose the one most
prominent in the current context/profile. Ask one bundled blocking question
only if no defensible product can be identified.

Visit the product site with your own browser/fetch tools and read at least five
pages when available: homepage, pricing, features/product, about, docs,
changelog/blog, FAQ, and customer/case-study pages. From what you actually read,
derive:

- `name`: short lowercase machine slug;
- `website`;
- `description`;
- `differentiator`;
- `icp`;
- `get_started_link`;
- `content_guardrails`;
- `voice` and `search_topics`, grounded in the profile scan.

Do not invent features, metrics, customers, or guarantees. If the site is thin,
save a conservative factual description rather than stopping for optional
details.

### 4. Save and seed

Call `project_config` once with the complete inferred project whenever possible. It
merges fields, reports missing required fields, seeds `search_topics` into
`project_search_topics`, and expands them into search queries.

If required fields remain, first attempt to derive them from the sources already
collected. Ask the user only if a genuinely unknowable required field blocks
readiness. Optional/recommended fields never justify stopping setup.

### 5. Schedule the autopilot + verify end to end

Schedule the draft autopilot: call `queue_setup`, then for EACH returned task
call the host tool `create_scheduled_task` (taskId, cronExpression, prompt
verbatim; "already exists" is fine). The autopilot then drafts on its own — the
launchd kicker fires a draft-only cycle and the queue worker drafts the replies;
nothing posts. Then wait: poll the `dashboard` tool until the pending-draft
count rises; a returned review batch is the strongest success signal.

Do not hand-run a cycle to make this happen faster, and do not offer the user to
trigger one. Scheduling the autopilot is the only sanctioned way to produce the
verification draft; the kicker drives it on its own minute-by-minute schedule.

If no card appears, diagnose the fixable reason, fix it, and let the autopilot
retry on its next scheduled cycle:

- missing topics: derive/add topics through `project_config`, then retry;
- runtime/browser-harness/Chrome issue: run/repair the owned runtime, then retry;
- stale X session: reconnect X, then retry;
- transient backend/network issue: retry once;
- Claude CLI login/usage limit or an interactive X login: report the exact
  blocker and the single user action required.

Do not enable autopilot automatically. Offer it only after setup is verified,
or enable it when the user's original request explicitly included hands-free
posting.

Once verification passes (or you reach a precise blocker), call the `dashboard`
tool so the user sees the finished setup rendered visually, then give the
completion summary below.

## CLI fallback

Use only when MCP tools are unavailable. Execute the flow yourself rather than
turning it into instructions for the user.

1. Install/repair: `npx -y social-autoposter@latest init`
2. Inspect `~/social-autoposter/config.json` and preserve existing projects.
3. Discover the product and voice using the same evidence order above. For a
   personal-brand persona, run the dictation interview (the 7 questions above)
   and take `search_topics` + the raw corpus from it, scan themes as backup.
4. Write a complete project with name, website, description, ICP, voice, and
   `search_topics`.
5. Seed topics:
   `python3 ~/social-autoposter/scripts/seed_search_topics.py --project <name>`
6. Connect X:
   `python3 ~/social-autoposter/scripts/setup_twitter_auth.py connect`
   The user may need to approve a macOS keychain prompt or sign in once in the
   managed browser; continue automatically afterward.
7. Do not load launchd/autopilot jobs unless explicitly requested, and never
   hand-run `run-twitter-cycle.sh` or any cycle script to "verify." A manual
   kick produces an empty-plan artifact and blocks the autopilot. The cycle runs
   only when the launchd autopilot is scheduled and the kicker fires it. In CLI
   fallback, setup is configured once the project is saved, topics are seeded,
   and X is connected; the first draft appears after the autopilot is scheduled.

## Completion summary

Render the `dashboard` tool once setup is verified, then report outcomes (not a
recap of every prompt):

```text
Social Autoposter Setup Complete

Runtime:       ready
Project:       NAME — ready
Topics seeded: N
X/Twitter:     @HANDLE
Verification:  autopilot produced a draft (not posted)
Autopilot:     off
Stats:         https://s4l.ai/stats/HANDLE
```

If setup is blocked, do not call it complete. State the exact completed
milestones, the blocker, and the one user action needed to resume.