ads-start

ガイド付きオンボーディングウィザード

初回実行／再訪問ウィザードを実行しています。このウィザードは ~/.claude-ads/profile.json を作成し、維持します。これは新規ユーザー向けの標準的なエントリーポイントであり、保存済みのコンテキストをユーザーが再編集できる唯一の場所です。ウィザードがほかの /ads コマンドを自動で呼び出すことはありません。最後に次のコマンドを提案して終了します。

基本ルール

1. 質問は一度に1つです。 各ステップでは2～4個の選択肢を含む AskUserQuestion ブロックを1つだけ使用し、次の質問をする前に、回答を python3 scripts/profile.py set <dot.path> <value> でプロファイルに書き込みます。途中まで完了した状態から再開できるようにします。
2. 手順ごとに確認します。 OAuth／MCP のセットアップでは、手順を1つずつ案内し、ユーザーの「完了」を待ってから検証の呼び出しを実行し、エラーを診断します。プラットフォームごとの再試行は3回までとし、その後は「スキップして後で再開」を提示します。
3. プロファイルにシークレットを保存しません。 トークン、API キー、リフレッシュトークンは環境変数のみに保存します。プロファイルには api_key_present: true/false を記録し、値は記録しません。
4. ウィザードは最後に何も実行しません。 次のコマンドをプレーンテキストで提案しますが、実行してはいけません。

サブコマンドの振り分け

ユーザーの引数（ある場合）を読み取ります。

引数	動作
(なし)	フェーズA — 初回実行か再訪問かを判定します。
status	python3 scripts/profile.py get を実行し、5行の概要を表示して終了します。
edit	フェーズAのウェルカムメッセージをスキップし、フェーズA.4の編集選択へ進みます。
reset	AskUserQuestion で確認 → python3 scripts/profile.py reset --yes を呼び出す → フェーズAから再開します。

---

フェーズA — 初回実行か再訪問かを判定

A.1 python3 scripts/profile.py get を実行し、終了コードを取得します。

• 終了コード 2（プロファイルなし）→ 初回実行：以下のウェルカムバナーを表示してから、フェーズBへ進みます。
• 終了コード 0（プロファイルあり）→ 再訪問：5行の概要（業種、支出の範囲、アクティブなプラットフォーム、最後のコマンド）を表示し、A.4へ進みます。

A.2 初回実行時のウェルカムメッセージ（原文のまま表示し、ユーザーの言語に合わせます）：

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 初回実行時：python3 scripts/profile.py init を実行し、フェーズBへ進みます。

A.4 再訪問時の編集選択 — AskUserQuestion：

「何を変更しますか？」

• ビジネスコンテキスト — フェーズBを再実行します。
• Meta 接続 — Meta のみフェーズCを再実行します。
• Google 接続 — Google のみフェーズCを再実行します。
• TikTok 接続 — TikTok のみフェーズCを再実行します。
• Zernio パブリッシング — フェーズDの Zernio ブロックを再実行します。

（AskUserQuestion は「その他」を追加します。これが選択された場合はキャンセルとして扱います。）

選択した編集の完了後、python3 scripts/profile.py set last_command_at $(date -u +%FT%TZ) で last_command_at を書き込み、1行の「保存しました。」という確認を表示して終了します。

---

フェーズB — ビジネスコンテキスト（初回実行または edit context）

AskUserQuestion ブロックを4回、順番に実行します。各回答はすぐに保存します。

B.1 業種 — AskUserQuestion（単一選択）

選択肢：Eコマース · 地域密着型サービス · 不動産 · 医療 · 金融 · 代理店／複数のクライアント · その他。

プロファイルの値へのマッピング：ecommerce、local-service、real-estate、 healthcare、finance、agency、other。

続いて：python3 scripts/profile.py set context.industry <value>。

B.2 月間広告費 — AskUserQuestion（単一選択）

選択肢：月500ドル未満 · 月500～2,000ドル · 月2,000～10,000ドル · 月10,000ドル以上。（ユーザーは「その他」を選んで正確な金額を入力できます。その場合は数値に変換します。）

金額の範囲 → 米ドルの中央値：250、1250、6000、25000。ユーザーが正確な 数値を入力した場合は、その値を使用します。

続いて：python3 scripts/profile.py set context.monthly_spend_usd <number>。

B.3 主な目標 — AskUserQuestion（単一選択）

選択肢：販売／売上 · リード／登録 · アプリのインストール · 電話での問い合わせ · ブランド認知度。

値へのマッピング：sales、leads、app-installs、calls、brand。

続いて：python3 scripts/profile.py set context.primary_goal <value>。

B.4 使用中のプラットフォーム — AskUserQuestion (multiSelect: true)

「広告を現在配信している（または配信する予定の）プラットフォームはどれですか？」

選択肢：Meta (Facebook + Instagram) · Google Ads (incl. YouTube) · TikTok Ads。

1つ以上必須です。["meta","google","tiktok"] の部分集合にマッピングします。

続いて：python3 scripts/profile.py set context.active_platforms '<json>'。

---

フェーズ C — プラットフォームごとの接続ウィザード

context.active_platforms に含まれる各プラットフォーム（Meta → Google → TikTok の順。B.4 で選択されたもののみ）について、以下のループを実行します。

C.1 ティアの選択 — AskUserQuestion（単一選択）

「<PLATFORM> をどのように接続しますか？」

選択肢	connections.<p>.tier に保存	備考
MCP server (recommended)	Meta は mcp_claude_ai · Google は mcp_cohnen · TikTok は mcp_adsmcp	レベル 1。最速です。
Direct API (free, OAuth once)	direct_api	レベル 2。完全に制御できます。
Manual exports for now	manual	レベル 3。セットアップ不要で、常に機能します。
Skip — set this up later	skipped	未設定のままにします。

manual または skipped の場合：ティアを書き込み、connected_at に現在時刻を書き込み、C.2〜C.4 をスキップして、次のプラットフォームに進みます。

C.2 プラットフォームのセットアップ手順を読み込む

該当するリファレンスファイルを読み込みます。

プラットフォーム	リファレンス
Meta	ads/references/setup-meta.md
Google	ads/references/setup-google.md
TikTok	ads/references/setup-tiktok.md

各ファイルにはセクション A（MCP）、B（Direct API）、C（Manual）があります。ユーザーが選択したティアに該当するセクションに進みます。そのセクション内の手順を順に進めます。

C.3 手順ごとの確認付きガイド

選択したセクションの各 STEP について、次のようにします。

1. 手順をそのまま表示します：「Goal」、"Do this" にある正確な URL／操作、および「Expect to see」に記載された内容を表示します。
2. AskUserQuestion → 「ステップ N は完了しましたか？」 として、次の選択肢を提示します。
   • Done — next step
   • Hit an error
   • Cancel and skip this platform
3. Done の場合：次の手順に進みます。
4. Hit an error の場合：手順の「On error」分岐を読み込み、ユーザーに何が表示されたか説明してもらいます。リファレンスにある最も可能性の高い修正方法を提案します。手順を再試行します。試行は最大 3 回までとし、その後スキップするか確認します。
5. Cancel の場合：connections.<p>.tier = "skipped" に設定し、次のプラットフォームに進みます。

最後の手順の後、検証呼び出しを実行します。

プラットフォーム	ティア A（MCP）の検証	ティア B（Direct API）の検証
Meta	mcp__claude_ai_Facebook__ads_get_ad_accounts を呼び出します	python3 scripts/api/meta_fetch.py --account-id <id> --what account
Google	mcp__cohnen_google_ads__list_customers を呼び出します（利用可能な場合）。利用できない場合は、ユーザーに customer_id を貼り付けてもらいます	python3 scripts/api/google_fetch.py --customer-id <id> --what account
TikTok	MCP ツールで広告主を一覧表示します。利用できない場合は、ユーザーに advertiser_id を貼り付けてもらいます	python3 scripts/api/tiktok_fetch.py --advertiser-id <id> --what account

（このセッションで MCP ツールが利用できない場合（例：ユーザーが claude.ai で有効にしていない場合）は、代わりにアカウント ID を手動で貼り付けてもらい、ライブ呼び出しをスキップします。last_verified_at: null を記録し、次回 /ads の実行時に再検証が必要だと分かるようにします。）

C.4 接続を保存する

検証に成功した場合：

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)"

アカウント ID とともに ✓ の確認メッセージを表示します。次のプラットフォームに進みます。

---

フェーズ D — 任意のアカウント作成ガイド

D.1 Meta for Developers（Meta のティアが direct_api の場合のみ）

AskUserQuestion：

「Meta for Developers アカウントをすでにお持ちですか？（Meta Direct API を利用するには必要です。）」

選択肢：Yes — I have one · No — walk me through it · Skip。

No の場合：ads/references/setup-meta-developers.md を読み込み、手順ごとのループ（C.3 と同じ形式）を実行します。ユーザーがアプリを作成し、Marketing API プロダクトを追加したら、setup-meta.md の Direct API セクションの C.3 ステップ 1 に戻ります。

D.2 Zernio による公開（ティアにかかわらず、Phase C の最後に一度だけ質問します）

AskUserQuestion:

「生成したクリエイティブを 14 以上のソーシャルネットワークに投稿するために、/ads publish を有効にしますか？ Zernio の無料プランでは、クレジットカードなしで 2 つのアカウントを無期限に接続できます。」

選択肢：はい — Zernio の登録手順を案内してください · 後で検討する — スキップ · すでにアカウントを持っています。

• はい：ads/references/setup-zernio.md を読み込み、ステップループを実行します。成功したら zernio.signed_up = true を書き込みます。ユーザーが API キーを ZERNIO_API_KEY に 保存したと報告した場合は、zernio.api_key_present = true も書き込みます。
• すでにアカウントを持っています：ZERNIO_API_KEY がエクスポートされているかだけを質問します。 zernio.signed_up = true を書き込み、zernio.api_key_present には回答に応じた値を設定します。
• スキップ：デフォルト値（false）のままにします。

---

Phase E — 最初に実行する項目のおすすめ

1 画面に収まる概要を表示します。

✓ Profile saved to ~/.claude-ads/profile.json
✓ Connected:  <platform list with tier>
✓ Zernio:     <on / off>

次に AskUserQuestion を実行します。

「セットアップが完了しました。最初に何を実行しますか？」

選択肢（ユーザーが実際に設定した項目に絞ります）：

• /ads audit — 全プラットフォームの監査（接続済みプラットフォームが 2 つ以上で、 ティアが「スキップ」以外の場合におすすめ）。
• /ads <single-platform> — 1 つのプラットフォームを詳しく分析（接続した プラットフォームから 1 つ選択）。
• /ads plan <industry> — 業界テンプレートから戦略プランを作成 （ユーザーの context.industry を使用し、設定されていない場合は generic を使用）。
• 終了 — 自分で確認します。

入力する次のコマンドを正確に表示します（実行はしません）。例：

「では、次のコマンドを入力してください：/ads audit」

完了処理：python3 scripts/profile.py set last_command "/ads start" && python3 scripts/profile.py set last_command_at "$(date -u +%FT%TZ)"。

---

ステータスモード（/ads start status）

python3 scripts/profile.py get を実行して、次を表示します。

claude-ads profile
  Industry:           <context.industry or "—">
  Monthly spend:      ~$<context.monthly_spend_usd>/mo
  Goal:               <context.primary_goal>
  Active platforms:   <comma list>
  Meta:               <tier> · <ad_account_id or "—"> · last verified <relative time>
  Google:             <tier> · <ad_account_id or "—"> · last verified <relative time>
  TikTok:             <tier> · <ad_account_id or "—"> · last verified <relative time>
  Zernio:             <on/off> · API key <present/missing>
  Last command:       <last_command> (<relative time>)

追加の質問をせずに終了します。

---

エラー処理

• python3 scripts/profile.py を実行できない場合は、python3 scripts/profile.py … として実行します（これがデフォルトです）。
• ~/.claude-ads/ が読み取り専用の場合は、パスを表示し、再試行する前に 権限を修正するようユーザーに依頼します。
• AskUserQuestion が有用なテキストを伴わずに「その他」を返した場合、そのステップはキャンセルとして扱います。

出力仕様

ウィザードはレポートファイルを生成しません。~/.claude-ads/profile.json への書き込みと、 ユーザー向けの文章の出力のみを行います。その他の /ads コマンドは python3 scripts/profile.py get を使用してプロファイルを読み取ります。