Guided onboarding wizard

You are running the first-run / re-entry wizard that produces and maintains ~/.claude-ads/profile.json. This is the canonical entry point for new users and the only place the user re-edits their saved context. The wizard never auto-invokes other /ads commands — at the end it suggests the next command and exits.

Core rules

1. One question at a time. Each step uses ONE AskUserQuestion block with 2–4 options, then writes the answer to the profile via python3 scripts/profile.py set <dot.path> <value> BEFORE asking the next question. Partial completion must be recoverable.
2. Step-by-step verification. For OAuth / MCP setup, dictate one step at a time, wait for the user's "done", run a verification call, diagnose errors. Cap retries at 3 per platform before offering "skip + come back later".
3. Never store secrets in the profile. Tokens, API keys, refresh tokens live in environment variables only. The profile records api_key_present: true/false, never the value.
4. The wizard is inert at the end. Suggest the next command in plain text, do NOT execute it.

Subcommand routing

Read the user's argument (if any):

Phase A — Detect first-run vs re-entry

A.1 Run python3 scripts/profile.py get and capture exit code.

• Exit 2 (no profile) → first-run: print the welcome banner below, then go to Phase B.
• Exit 0 (profile exists) → re-entry: print a 5-line summary (industry, spend bracket, active platforms, last command) and go to A.4.

A.2 First-run welcome (print verbatim, adapt to user's language):

Welcome to claude-ads. I'll walk you through 4 quick steps:

  1. Tell me about your business (~1 min)
  2. Connect Meta / Google / TikTok — one at a time, step by step (~2-10 min each)
  3. Optional: Zernio for publishing creatives, Meta for Developers
  4. Pick your first action

Nothing leaves your machine. Tokens go to env vars, not the profile.
You can re-run /ads start edit anytime to change settings, or /ads start reset
to start over.

A.3 First-run: run python3 scripts/profile.py init and continue to Phase B.

A.4 Re-entry edit selector — AskUserQuestion:

"What do you want to change?"

• Business context — re-run Phase B.
• Meta connection — re-run Phase C for Meta only.
• Google connection — re-run Phase C for Google only.
• TikTok connection — re-run Phase C for TikTok only.
• Zernio publishing — re-run Phase D Zernio block.

(AskUserQuestion will add "Other" — treat it as cancel.)

After completing the selected edit, write last_command_at via python3 scripts/profile.py set last_command_at $(date -u +%FT%TZ) and exit with a one-line "Saved." confirmation.

Phase B — Business context (first-run or edit context)

Four sequential AskUserQuestion blocks. Save EACH answer immediately.

B.1 Industry — AskUserQuestion (single-select)

Options: Ecommerce · Local service · Real estate · Healthcare · Finance · Agency / multiple clients · Other.

Map to profile values: ecommerce, local-service, real-estate, healthcare, finance, agency, other.

Then: python3 scripts/profile.py set context.industry <value>.

B.2 Monthly ad spend — AskUserQuestion (single-select)

Options: Under $500/mo · $500–$2,000/mo · $2,000–$10,000/mo · $10,000+/mo. (User can pick "Other" and type an exact figure — coerce to a number.)

Map bracket → midpoint USD: 250, 1250, 6000, 25000. If user gave an exact number, use it.

Then: python3 scripts/profile.py set context.monthly_spend_usd <number>.

B.3 Primary goal — AskUserQuestion (single-select)

Options: Sales / revenue · Leads / signups · App installs · Phone calls · Brand awareness.

Map → sales, leads, app-installs, calls, brand.

Then: python3 scripts/profile.py set context.primary_goal <value>.

B.4 Active platforms — AskUserQuestion (multiSelect: true)

"Which platforms do you actively run (or plan to run) ads on?"

Options: Meta (Facebook + Instagram) · Google Ads (incl. YouTube) · TikTok Ads.

Require ≥1. Map to ["meta","google","tiktok"] subset.

Then: python3 scripts/profile.py set context.active_platforms '<json>'.

Phase C — Per-platform connection wizard

For each platform in context.active_platforms (in order Meta → Google → TikTok, only those selected in B.4), run the loop below.

C.1 Tier selection — AskUserQuestion (single-select)

"How do you want to connect <PLATFORM>?"

If manual or skipped: write the tier, write connected_at to now, skip C.2-C.4, continue to the next platform.

C.2 Load the platform setup walkthrough

Read the relevant reference file:

Each file has Sections A (MCP), B (Direct API), C (Manual). Jump to the section that matches the user's tier choice. Within that section, walk the steps in order.

C.3 Step-by-step verified walkthrough

For each STEP in the chosen section:

1. Print the step verbatim: its Goal, the exact URL/action under "Do this", and what they should "Expect to see".
2. AskUserQuestion → "Done with step N?" with options:
   • Done — next step
   • Hit an error
   • Cancel and skip this platform
3. On Done: continue to the next step.
4. On Hit an error: read the step's "On error" branch and ask the user to describe what they saw. Suggest the most likely fix from the reference. Retry the step. Cap at 3 attempts → offer to skip.
5. On Cancel: set connections.<p>.tier = "skipped" and continue to next platform.

After the LAST step, run the verification call:

(If the MCP tool isn't present in this session — e.g., the user hasn't enabled it on claude.ai — fall back to asking the user to paste the account ID manually and skip the live call. Record last_verified_at: null so /ads next knows to re-verify next time.)

C.4 Save the connection

On verification success:

python3 scripts/profile.py set connections.<platform>.ad_account_id "<id>"
python3 scripts/profile.py set connections.<platform>.connected_at "$(date -u +%FT%TZ)"
python3 scripts/profile.py set connections.<platform>.last_verified_at "$(date -u +%FT%TZ)"

Print ✓ confirmation with the account ID. Continue to next platform.

Phase D — Optional account-creation walkthr