From 356a11d3d1c3502f91673d862bfffc7bf604dcb1 Mon Sep 17 00:00:00 2001 From: hyoshi <4027404+hyoshi@users.noreply.github.com> Date: Sat, 2 May 2026 10:09:51 +0900 Subject: [PATCH] docs: unify 'Real-API' / 'real-api' / 'real API' as 'Live API' across docs and comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit User feedback noted that 'Live API' (in some places) and 'Real-API' (in others) referred to the same concept — direct OAuth-authenticated calls to Google Ads / Meta Ads / GA4 / Search Console. Standardizing on 'Live API' for clarity. Touched: README.md, README.ja.md, AGENTS.md, CHANGELOG.md, docs/{architecture,cli,byod,byod.ja}.md, scripts/sheet-template/README.md, 4 skill SKILL.md files (canonical + packaged), 5 BYOD-related Python files (docstrings/comments only — no logic change), tests/test_byod.py docstrings. 1581 tests pass (broader regression). Pure terminology rename. --- AGENTS.md | 2 +- CHANGELOG.md | 2 +- README.ja.md | 10 +++--- README.md | 10 +++--- docs/architecture.md | 4 +-- docs/byod.ja.md | 36 +++++++++---------- docs/byod.md | 32 ++++++++--------- docs/cli.md | 4 +-- mureo/_data/skills/daily-check/SKILL.md | 2 +- mureo/_data/skills/rescue/SKILL.md | 2 +- .../_data/skills/search-term-cleanup/SKILL.md | 2 +- mureo/_data/skills/sync-state/SKILL.md | 2 +- mureo/byod/adapters/google_ads.py | 4 +-- mureo/byod/bundle.py | 2 +- mureo/byod/clients.py | 4 +-- mureo/cli/byod_cmd.py | 6 ++-- mureo/mcp/_client_factory.py | 2 +- scripts/sheet-template/README.md | 2 +- skills/daily-check/SKILL.md | 2 +- skills/rescue/SKILL.md | 2 +- skills/search-term-cleanup/SKILL.md | 2 +- skills/sync-state/SKILL.md | 2 +- tests/test_byod.py | 4 +-- 23 files changed, 70 insertions(+), 70 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e382707..a988799 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -249,7 +249,7 @@ This rule was reinforced after PR #20 (2026-04-19, OAuth helper extraction — 6 ## BYOD Mode (Bring Your Own Data) -`mureo byod import .xlsx` lets a user analyze their real ad-account data locally without OAuth. The bundle importer (`mureo/byod/bundle.py`) opens the workbook with openpyxl, dispatches recognized adapters by header signature, and writes per-platform CSVs under `~/.mureo/byod//`. When `~/.mureo/byod/manifest.json` registers a platform, `mureo/mcp/_client_factory.py` routes that platform's MCP tool calls to a CSV-backed client (`mureo/byod/clients.py`) instead of the live API. Per-platform: imported platforms = BYOD; un-imported = real API (or `_no_creds` error if no credentials). Supported BYOD platforms: `google_ads`, `meta_ads`. GA4 and Search Console remain on the real-API OAuth path. +`mureo byod import .xlsx` lets a user analyze their real ad-account data locally without OAuth. The bundle importer (`mureo/byod/bundle.py`) opens the workbook with openpyxl, dispatches recognized adapters by header signature, and writes per-platform CSVs under `~/.mureo/byod//`. When `~/.mureo/byod/manifest.json` registers a platform, `mureo/mcp/_client_factory.py` routes that platform's MCP tool calls to a CSV-backed client (`mureo/byod/clients.py`) instead of the live API. Per-platform: imported platforms = BYOD; un-imported = Live API (or `_no_creds` error if no credentials). Supported BYOD platforms: `google_ads`, `meta_ads`. GA4 and Search Console remain on the Live API OAuth path. When working on mureo: - New ad-platform handlers MUST call `mureo/mcp/_client_factory.get_*_client(...)` for the BYOD path; real-mode dispatch can call `create_*_client` directly to keep test mocks at `mureo.mcp._handlers_*.create_*_client` working. diff --git a/CHANGELOG.md b/CHANGELOG.md index a2c16b4..2d02778 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,7 +49,7 @@ PyPI re-publish of v0.7.0 with the post-#54 fixes folded in. The original `0.7.0 - **Richer Google Ads analysis from BYOD bundles**: `ByodGoogleAdsClient.get_search_terms_report` is now backed by the bundle's `search_terms.csv` (was `return []`), and new `get_auction_insights` / `analyze_auction_insights` methods read `auction_insights.csv`. Together these surface query-level performance and competitor share metrics through the existing `google_ads_search_terms_report` / `google_ads.auction_insights.{get,analyze}` MCP tools — turning the v0.6 BYOD path's "Campaign × Day rollup only" into something `/daily-check` can actually reason about. ### Changed -- `mureo byod` CLI — `mureo byod import ` now requires an XLSX (Sheet bundle). The previous per-platform CSV path is gone; flags `--google-ads / --meta-ads / --search-console / --as` were removed from `import` because the workbook tab names determine which adapter runs. `status` and `remove` cover the BYOD-supported platforms (`--google-ads` / `--meta-ads`); GA4 and Search Console remain on the existing real-API OAuth path and are not part of the bundle pipeline. +- `mureo byod` CLI — `mureo byod import ` now requires an XLSX (Sheet bundle). The previous per-platform CSV path is gone; flags `--google-ads / --meta-ads / --search-console / --as` were removed from `import` because the workbook tab names determine which adapter runs. `status` and `remove` cover the BYOD-supported platforms (`--google-ads` / `--meta-ads`); GA4 and Search Console remain on the existing Live API OAuth path and are not part of the bundle pipeline. - MCP tool descriptions rewritten for 49 tools across Google Ads and Meta Ads — `google_ads.campaigns.*`, `google_ads.ad_groups.*`, `google_ads.ads.*`, `google_ads.budget.*`, `google_ads.accounts.*`, `google_ads.keywords.*`, `google_ads.negative_keywords.*`, `meta_ads.campaigns.*`, `meta_ads.ad_sets.*`, `meta_ads.ads.*`. Each description now covers verb + resource + returned fields + side effects (read-only / mutating / reversible via `rollback_apply`) + sibling tool differentiation, following the new `docs/tdqs-style-guide.md`. Targets improving Glama's Tool Definition Quality Score from C (3.1 avg) toward B+. No behavioral changes — descriptions and parameter hints only. - MCP tool descriptions rewritten for the remaining ~51 Meta Ads tools — `meta_ads.creatives.*` (including the TDQS lowest-scoring `meta_ads_creatives_list`), `meta_ads.images.*`, `meta_ads.videos.*`, `meta_ads.audiences.*`, `meta_ads.pixels.*`, `meta_ads.insights.*`, `meta_ads.analysis.*`, `meta_ads.catalogs.*`, `meta_ads.products.*`, `meta_ads.feeds.*`, `meta_ads.conversions.*`, `meta_ads.lead_forms.*`, `meta_ads.leads.*`, `meta_ads.split_tests.*`, `meta_ads.ad_rules.*`, `meta_ads.page_posts.*`, `meta_ads.instagram.*`. Same TDQS template as PR #43. No behavioral changes. - The OAuth-URL validation now runs **before** any wizard session mutation, so a rejected redirect cannot leave the wizard with half-populated auth material. diff --git a/README.ja.md b/README.ja.md index 0999da8..40b3ce4 100644 --- a/README.ja.md +++ b/README.ja.md @@ -45,9 +45,9 @@ mureo は **3 つのモード**(どのデータを使うか)× **3 つのホス 各行の詳細手順(XLSX の取得方法、置き場所、取込み方を含む): **[はじめかた →](docs/getting-started.ja.md)** -## BYOD と Real-API の違い +## BYOD と Live API の違い -> **Google Cloud Console や Meta for Developers に慣れていない方へ。** OAuth フロー / Developer Token の発行 / Business app 登録は、これらのコンソールを使ったことがない方には難しく感じるかもしれません。**まずは BYOD から始めてください** — 数分で mureo がどう動くかが分かります。それから real-API のセットアップに踏み込むかどうか判断すれば OK です。 +> **Google Cloud Console や Meta for Developers に慣れていない方へ。** OAuth フロー / Developer Token の発行 / Business app 登録は、これらのコンソールを使ったことがない方には難しく感じるかもしれません。**まずは BYOD から始めてください** — 数分で mureo がどう動くかが分かります。それから Live API のセットアップに踏み込むかどうか判断すれば OK です。 ### モード A: BYOD — 5分で最初の診断、OAuth 不要 @@ -66,9 +66,9 @@ XLSX の生成はプラットフォームごとの一回限りのセットアッ - **Google Ads** — Apps Script テンプレートで自分の Google スプレッドシートに出力 → XLSX としてダウンロード（約5分）。[ガイドを見る →](docs/byod.ja.md#step-2a--google-ads-script-を実行任意) - **Meta Ads** — 広告マネージャの保存済みレポート → 2クリックで書き出し。**9言語に対応**（English / 日本語 / 简体中文 / 繁體中文 / 한국어 / Español / Português / Deutsch / Français）。広告マネージャUIを英語に切り替える必要はありません。[ガイドを見る →](docs/byod.ja.md#step-2b--meta-広告マネージャからエクスポート任意) -**設計として読み取り専用**。すべての変更系ツール（`/rescue`、`/budget-rebalance`、`/creative-refresh`）は `{"status": "skipped_in_byod_readonly"}` を返します — エージェントは分析・提案はしますが、実アカウントへの書き込みは決してしません。後から real API に切り替えるには `mureo byod remove --google-ads`（プラットフォーム単位）または `mureo byod clear`（全削除）。 +**設計として読み取り専用**。すべての変更系ツール（`/rescue`、`/budget-rebalance`、`/creative-refresh`）は `{"status": "skipped_in_byod_readonly"}` を返します — エージェントは分析・提案はしますが、実アカウントへの書き込みは決してしません。後から Live API に切り替えるには `mureo byod remove --google-ads`（プラットフォーム単位）または `mureo byod clear`（全削除）。 -### モード B: Real-API OAuth — 全機能対応 +### モード B: Live API OAuth — 全機能対応 mureo を Google Ads / Meta Ads API に直接接続します。**実際に変更を実行する場合**（`/rescue`、`/budget-rebalance`、`/creative-refresh`、`mureo rollback apply`）、および GA4 / Search Console を使う場合は**必須**です。 @@ -83,7 +83,7 @@ mureo setup claude-code # MCP + ワークフローコマンド ### どちらのモードが合うか -| 機能 | モード A: BYOD | モード B: Real API | +| 機能 | モード A: BYOD | モード B: Live API | |----------------------------------------------------|-----------------------------------------|------------------| | **初回セットアップ時間** | **プラットフォームごとに5〜10分** | 30〜60分 | | **承認・待機リスク** | **なし** | Google審査1〜3週間、却下される場合あり | diff --git a/README.md b/README.md index 692a260..72ebd5f 100644 --- a/README.md +++ b/README.md @@ -45,9 +45,9 @@ mureo has **3 modes** (where the data comes from) and runs across **3 hosts** (w Full per-row walkthroughs (including how to obtain your XLSX, where to put it, and how to import it): **[Getting Started →](docs/getting-started.md)**. -> **Not familiar with Google Cloud Console or Meta for Developers?** OAuth flows, developer-token registration, and Business-app sign-ups can feel intimidating if you have never used those consoles before. **Start with BYOD** — you will see what mureo can do for your account in a few minutes, then decide whether the real-API path is worth setting up. +> **Not familiar with Google Cloud Console or Meta for Developers?** OAuth flows, developer-token registration, and Business-app sign-ups can feel intimidating if you have never used those consoles before. **Start with BYOD** — you will see what mureo can do for your account in a few minutes, then decide whether the Live API path is worth setting up. -## BYOD vs Real-API at a glance +## BYOD vs Live API at a glance ### Mode A: BYOD — 5 minutes to first diagnosis, no OAuth @@ -66,9 +66,9 @@ Producing the XLSX is a one-time setup per platform: - **Google Ads** — Apps Script template populates a Google Sheet you own; download as XLSX (~5 min). [See guide →](docs/byod.md#google-ads-setup) - **Meta Ads** — Saved Report in Ads Manager → 2-click export. **Recognized in 9 languages** (English / 日本語 / 简体中文 / 繁體中文 / 한국어 / Español / Português / Deutsch / Français), so you do not need to switch Ads Manager UI to English. [See guide →](docs/byod.md#meta-ads-setup) -**Read-only by construction.** Every mutation tool (`/rescue`, `/budget-rebalance`, `/creative-refresh`) returns `{"status": "skipped_in_byod_readonly"}` — the agent analyzes and recommends but never writes to your real account. Upgrade a platform to the real API later with `mureo byod remove --google-ads` (one platform) or `mureo byod clear` (all). +**Read-only by construction.** Every mutation tool (`/rescue`, `/budget-rebalance`, `/creative-refresh`) returns `{"status": "skipped_in_byod_readonly"}` — the agent analyzes and recommends but never writes to your real account. Upgrade a platform to the Live API later with `mureo byod remove --google-ads` (one platform) or `mureo byod clear` (all). -### Mode B: Real-API OAuth — full functionality +### Mode B: Live API OAuth — full functionality Connect mureo directly to Google Ads / Meta Ads APIs. **Required to actually execute changes** (`/rescue`, `/budget-rebalance`, `/creative-refresh`, `mureo rollback apply`) and for GA4 / Search Console support. @@ -83,7 +83,7 @@ Prerequisites: Google Ads Developer Token + OAuth Client; Meta App ID + Secret. ### Which mode fits? -| Capability | Mode A: BYOD | Mode B: Real API | +| Capability | Mode A: BYOD | Mode B: Live API | |----------------------------------------------------|-----------------------------------------|------------------| | **First-time setup time** | **5–10 min per platform** | 30–60 min | | **Approval / waiting risk** | **None** | 1–3 weeks Google review, sometimes rejected | diff --git a/docs/architecture.md b/docs/architecture.md index 003ac0a..6a27cc6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -195,14 +195,14 @@ Credentials are loaded from `~/.mureo/credentials.json` or environment variables When `~/.mureo/byod/manifest.json` registers a platform, the MCP server's per-tool `_client_factory.py` dispatches the BYOD CSV-backed client (`mureo/byod/clients.py`) instead of the live API client — **per platform, decided at every call**. Real credentials are never read for that platform; mutations are blocked at the client level (every method whose name starts with `create_`, `update_`, `delete_`, `pause_`, `resume_`, etc. returns `{"status": "skipped_in_byod_readonly"}`). The activation signal is purely the manifest's existence — there is no `--byod` flag, and `mureo setup claude-code` does not need to be re-run when a user starts or stops importing data. -The user-facing input is a single XLSX bundle: either the mureo Google Ads Script's Sheet output (`scripts/sheet-template/google-ads-script.js`) or a Meta Ads Manager Saved Report export. The bundle importer (`mureo/byod/bundle.py`) opens the workbook with openpyxl, dispatches each adapter (`mureo/byod/adapters/.py`) by header signature, and writes per-platform CSVs to `~/.mureo/byod//`. Manifest update is atomic with rollback on partial failure. GA4 and Search Console are **not** part of the BYOD bundle pipeline — they remain on the real-API OAuth path. See `docs/byod.md` for the user-facing walkthrough. +The user-facing input is a single XLSX bundle: either the mureo Google Ads Script's Sheet output (`scripts/sheet-template/google-ads-script.js`) or a Meta Ads Manager Saved Report export. The bundle importer (`mureo/byod/bundle.py`) opens the workbook with openpyxl, dispatches each adapter (`mureo/byod/adapters/.py`) by header signature, and writes per-platform CSVs to `~/.mureo/byod//`. Manifest update is atomic with rollback on partial failure. GA4 and Search Console are **not** part of the BYOD bundle pipeline — they remain on the Live API OAuth path. See `docs/byod.md` for the user-facing walkthrough. ``` Claude Code ─MCP──▶ mureo MCP server │ ▼ _client_factory.py per-platform routing byod_has(p)? yes──▶ Byod*Client (CSV) ──▶ ~/.mureo/byod//*.csv - no ──▶ create_*_client (real API) ──▶ Google Ads / Meta / SC / GA4 API + no ──▶ create_*_client (Live API) ──▶ Google Ads / Meta / SC / GA4 API ``` ### Defense-in-Depth for AI Agents diff --git a/docs/byod.ja.md b/docs/byod.ja.md index 7f68177..d063f7c 100644 --- a/docs/byod.ja.md +++ b/docs/byod.ja.md @@ -11,7 +11,7 @@ mureo がこの XLSX を **ローカルのファイルとして読むだけ** > **対応状況 (Phase 2)** Google Ads（mureo の Google Ads Script 経由）と > Meta Ads（広告マネージャの Excel エクスポート経由）の 2 プラットフォーム -> を Sheet bundle で取り込めます。GA4 / Search Console は引き続き real-API +> を Sheet bundle で取り込めます。GA4 / Search Console は引き続き Live API > 認証で接続するパスを使ってください（`docs/authentication.md` 参照）。 --- @@ -58,7 +58,7 @@ Google Ads にログイン → **ツールと設定 → 一括操作 → スク / `keywords`）が書き込まれれば成功です。Auction insights は意図的に外し ています — Google Ads Scripts からこのデータには到達できないため、 `/competitive-scan` で競合分析を行いたい場合は `mureo auth setup` で -real-API 経由を使ってください。 +Live API 経由を使ってください。 ### Step 2b — Meta 広告マネージャからエクスポート（任意） @@ -150,14 +150,14 @@ mureo の MCP サーバーが取り込み済みのデータを自動検出しま |---|---| | `mureo byod import ` | Sheet bundle を取り込む。対象プラットフォームに既にデータがあると拒否される | | `mureo byod import --replace` | 既存の BYOD データを上書きして取り込む | -| `mureo byod status` | プラットフォーム別のモード（BYOD / real API / 未設定）を表示 | +| `mureo byod status` | プラットフォーム別のモード（BYOD / Live API / 未設定）を表示 | | `mureo byod remove --` | 1 プラットフォームの BYOD データを削除（`--google-ads` / `--meta-ads`） | | `mureo byod clear` | `~/.mureo/byod/` をまるごと削除 | | `mureo byod clear --yes` | 確認プロンプトをスキップ | `--byod` のような有効化フラグはどこにもありません。各ツール呼び出しの タイミングで `~/.mureo/byod/manifest.json` の有無を見て、プラットフォーム -ごとに自動判定しています。BYOD と real-API 認証の両方を同時に使うことも +ごとに自動判定しています。BYOD と Live API 認証の両方を同時に使うことも できます（次の節を参照）。 --- @@ -192,22 +192,22 @@ mureo の MCP サーバーが取り込み済みのデータを自動検出しま 4. `~/.mureo/byod//` ディレクトリが実際にディスクにある `~/.mureo/byod/google_ads/` を手動で消したのに manifest を残したまま、 -といった食い違いがあると mureo は警告を出して real-API モードにフォール +といった食い違いがあると mureo は警告を出して Live API モードにフォール バックします。 --- -## BYOD と real API を併用するパターン +## BYOD と Live API を併用するパターン | 状態 | 動作 | |---|---| -| Google Ads だけ取り込み済 / Meta は未設定 | Google Ads = bundle / Meta = real API | -| Meta だけ取り込み済 / Google Ads は未設定 | Meta = bundle / Google Ads = real API | +| Google Ads だけ取り込み済 / Meta は未設定 | Google Ads = bundle / Meta = Live API | +| Meta だけ取り込み済 / Google Ads は未設定 | Meta = bundle / Google Ads = Live API | | 両方取り込み済 | 両方 = bundle | -| 何も取り込まない | 全部 real API | -| `mureo byod clear` 実行後 | 全部 real API | +| 何も取り込まない | 全部 Live API | +| `mureo byod clear` 実行後 | 全部 Live API | -GA4 と Search Console は常に real-API 経由です。Sheet bundle の対象 +GA4 と Search Console は常に Live API 経由です。Sheet bundle の対象 プラットフォームには含まれません。 --- @@ -226,7 +226,7 @@ mureo BYOD は **設計レベルで read-only** です。エージェントは --- -## real API モードに戻す +## Live API モードに戻す ```bash mureo byod remove --google-ads # 1 プラットフォームだけ戻す @@ -235,13 +235,13 @@ mureo byod clear # 全 BYOD データを削除 ``` `mureo byod clear` は `~/.mureo/credentials.json` には触りません。 -real-API の OAuth トークンは BYOD のリセットを跨いで残ります。削除後は +Live API の OAuth トークンは BYOD のリセットを跨いで残ります。削除後は Claude Code を再起動してください — mureo MCP サーバーが起動時に manifest の不在を検知し、自動的に credentials.json ベースに切り替えます。 `not configured` と表示されたプラットフォームについては、 `mureo auth setup`（または `mureo auth setup --web`）で -`~/.mureo/credentials.json` を埋めれば real API で動き始めます。 +`~/.mureo/credentials.json` を埋めれば Live API で動き始めます。 --- @@ -280,14 +280,14 @@ Google Ads アダプタは上記タブのうち最低 1 つが含まれていれ ## BYOD では取れないもの -- **GA4 / Search Console** は real-API 認証（`mureo auth setup`）で。 +- **GA4 / Search Console** は Live API 認証（`mureo auth setup`）で。 Sheet bundle のパイプラインには含まれません - **`/rescue` の予算操作などミューテーション系**: 提案までは出ますが 実行はブロックされます — BYOD は read-only です - **OAuth トークンの自動更新**: BYOD はトークン自体を持たないため 発生しません -real API の全機能を使いたくなったときは、`mureo auth setup`（または +Live API の全機能を使いたくなったときは、`mureo auth setup`（または `mureo auth setup --web`）でクレデンシャルを設定し、`mureo byod clear` で BYOD モードを抜けてください。 @@ -304,7 +304,7 @@ Sheet bundle の `search_terms` タブは、既存の Google Ads MCP ツール `google_ads_auction_insights_get` / `analyze` は BYOD では空を返します （Google Ads Scripts からこのデータが取れないため）。競合シェアを見たい -場合は `mureo auth setup` で real API に切り替えてください。 +場合は `mureo auth setup` で Live API に切り替えてください。 --- @@ -342,4 +342,4 @@ but X is missing on disk」という警告が出ていないか確認してく - スクリプトテンプレート: `scripts/sheet-template/README.md` - CLI リファレンス: `docs/cli.md` - アーキテクチャ: `docs/architecture.md` -- real API 認証: `docs/authentication.md` +- Live API 認証: `docs/authentication.md` diff --git a/docs/byod.md b/docs/byod.md index 3f64757..c048d49 100644 --- a/docs/byod.md +++ b/docs/byod.md @@ -16,7 +16,7 @@ only ever reads the local XLSX file.** > **Status (Phase 2):** Google Ads (via the mureo Google Ads Script) > and Meta Ads (via the Ads Manager Excel export) are both supported > through the Sheet bundle pipeline. GA4 and Search Console remain on -> the existing real-API OAuth path (see `docs/authentication.md`) — +> the existing Live API OAuth path (see `docs/authentication.md`) — > they are **not** part of the BYOD bundle. --- @@ -137,13 +137,13 @@ search-term gaps, keyword quality scores, etc. |---|---| | `mureo byod import ` | Import a Sheet bundle. Aborts if the target platform already has BYOD data. | | `mureo byod import --replace` | Overwrite existing BYOD data for the platform present in the bundle. | -| `mureo byod status` | Show per-platform mode (BYOD / real API / not configured). | +| `mureo byod status` | Show per-platform mode (BYOD / Live API / not configured). | | `mureo byod remove --` | Remove BYOD data for one platform (`--google-ads` / `--meta-ads`). | | `mureo byod clear` | Wipe `~/.mureo/byod/` entirely. | | `mureo byod clear --yes` | Skip the confirmation prompt. | There is **no `--byod` flag** anywhere. mureo decides per-platform at -each tool call by checking `~/.mureo/byod/manifest.json`. Real-API +each tool call by checking `~/.mureo/byod/manifest.json`. Live API credentials and BYOD imports coexist freely — see the next section. --- @@ -177,22 +177,22 @@ credentials and BYOD imports coexist freely — see the next section. 4. `~/.mureo/byod//` actually exists on disk If you remove `~/.mureo/byod/google_ads/` out of band but leave the -manifest, mureo logs a warning and falls back to real-API mode for +manifest, mureo logs a warning and falls back to Live API mode for that platform. --- -## Mixing BYOD and real API +## Mixing BYOD and Live API | Setup | Result | |---|---| -| Bundle imported for Google Ads; meta_ads not configured | Google Ads = bundle, Meta = real API | -| Bundle imported for Meta Ads; google_ads not configured | Meta = bundle, Google Ads = real API | +| Bundle imported for Google Ads; meta_ads not configured | Google Ads = bundle, Meta = Live API | +| Bundle imported for Meta Ads; google_ads not configured | Meta = bundle, Google Ads = Live API | | Bundles imported for both | Both = bundle | -| Nothing imported | All platforms = real API | -| `mureo byod clear` | All platforms = real API | +| Nothing imported | All platforms = Live API | +| `mureo byod clear` | All platforms = Live API | -GA4 and Search Console always go through the real-API OAuth path — +GA4 and Search Console always go through the Live API OAuth path — the bundle pipeline does not cover them. --- @@ -211,7 +211,7 @@ name prefixes returns `{"status": "skipped_in_byod_readonly", ...}`: --- -## Switching back to the real API +## Switching back to the Live API ```bash mureo byod remove --google-ads # remove just one platform @@ -220,7 +220,7 @@ mureo byod clear # remove all BYOD data ``` `mureo byod clear` does **not** touch `~/.mureo/credentials.json`, -so your real-API OAuth tokens survive a BYOD reset. After removal, +so your Live API OAuth tokens survive a BYOD reset. After removal, restart Claude Code; the MCP server detects the missing manifest at startup and falls back to credentials.json automatically. @@ -265,7 +265,7 @@ adapter's data. ## What's *not* in BYOD -- **GA4 / Search Console.** Use the real-API OAuth path +- **GA4 / Search Console.** Use the Live API OAuth path (`mureo auth setup`); they are not part of the bundle pipeline. - **`/rescue` budget operations.** The agent can recommend rescues but cannot execute them — BYOD is read-only. @@ -288,7 +288,7 @@ treats the cost column as a single coherent unit. For the full live-account experience, run `mureo auth setup` (or `mureo auth setup --web`) and `mureo byod clear` to switch back to -real-API mode. +Live API mode. --- @@ -303,7 +303,7 @@ Google Ads MCP surface: `google_ads_auction_insights_get` / `analyze` return empty under BYOD (the data isn't available from Google Ads Scripts). Use -`mureo auth setup` for the real-API path if competitor share data is +`mureo auth setup` for the Live API path if competitor share data is required. --- @@ -341,4 +341,4 @@ directory was deleted out of band, run - Sheet template scripts: `scripts/sheet-template/README.md` - CLI reference: `docs/cli.md` - Architecture: `docs/architecture.md` -- Real-API auth: `docs/authentication.md` +- Live API auth: `docs/authentication.md` diff --git a/docs/cli.md b/docs/cli.md index 2e7904c..2ba5737 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -180,7 +180,7 @@ Analyse your ad-account data locally without OAuth or a developer token. The imp |---|---| | `mureo byod import .xlsx` | Import a Sheet bundle. Aborts if any platform present in the workbook is already imported. | | `mureo byod import .xlsx --replace` | Overwrite existing BYOD data for any platform present in the bundle. | -| `mureo byod status` | Show per-platform mode (BYOD / real API / not configured); warns about stale entries from older mureo versions. | +| `mureo byod status` | Show per-platform mode (BYOD / Live API / not configured); warns about stale entries from older mureo versions. | | `mureo byod remove --google-ads` / `--meta-ads` | Remove BYOD data for one platform. | | `mureo byod clear` | Wipe `~/.mureo/byod/` (prompts for confirmation). | | `mureo byod clear --yes` | Skip the confirmation prompt. | @@ -189,7 +189,7 @@ Analyse your ad-account data locally without OAuth or a developer token. The imp The MCP server checks each platform independently at every tool dispatch. With `google_ads` imported but `meta_ads` not, a single `/daily-check` call uses the BYOD CSVs for Google Ads and the live API for Meta Ads. `mureo byod status` shows the active mix. -GA4 and Search Console are **not** part of the BYOD bundle pipeline — they remain on the real-API OAuth path. +GA4 and Search Console are **not** part of the BYOD bundle pipeline — they remain on the Live API OAuth path. ### Read-only guarantee diff --git a/mureo/_data/skills/daily-check/SKILL.md b/mureo/_data/skills/daily-check/SKILL.md index a2ac192..00bd371 100644 --- a/mureo/_data/skills/daily-check/SKILL.md +++ b/mureo/_data/skills/daily-check/SKILL.md @@ -23,7 +23,7 @@ Run a daily health check on all marketing accounts using the strategy context. 3. **Sync state**: For each platform in STATE.json `platforms`, fetch current campaign data via `google_ads_campaigns_list` / `meta_ads_campaigns_list` and update STATE.json. Both tools work in BYOD mode — do **not** look for raw CSVs in the project directory; mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools. 4. **Platform health checks**: Run health diagnostics on each configured ad platform: - - **Google Ads**: `google_ads_performance_report` (campaign-level metrics — works in BYOD), `google_ads_health_check_all` (returns `[]` in BYOD; only meaningful with real-API), `google_ads_cost_increase_investigate` (per-campaign anomaly check), `google_ads_monitoring_zero_conversions` (per-campaign). + - **Google Ads**: `google_ads_performance_report` (campaign-level metrics — works in BYOD), `google_ads_health_check_all` (returns `[]` in BYOD; only meaningful with Live API), `google_ads_cost_increase_investigate` (per-campaign anomaly check), `google_ads_monitoring_zero_conversions` (per-campaign). - **Meta Ads**: `meta_ads_insights_report` — surfaces a `result_indicator` field per campaign (`actions:link_click` vs `actions:offsite_conversion.fb_pixel_lead`); use this to detect CV-definition mismatches across campaigns where one campaign's "results" are clicks while another's are real leads. - In BYOD some tools return `[]` for unsupported features (auction insights, ad performance) — that's by design, not missing data; carry on with the rest of the diagnostics. - Present a unified health summary across all platforms. diff --git a/mureo/_data/skills/rescue/SKILL.md b/mureo/_data/skills/rescue/SKILL.md index 75d0b33..076f744 100644 --- a/mureo/_data/skills/rescue/SKILL.md +++ b/mureo/_data/skills/rescue/SKILL.md @@ -23,7 +23,7 @@ Run an emergency performance rescue workflow for underperforming campaigns. 3. **Diagnose: platform-side or site-side?** (if GA4 is available): Before making ad changes, check if the performance problem is platform-side or site-side. If LP conversion rates dropped in GA4 too, the issue may be the landing page, not the ads. Recommend LP investigation before ad changes. 4. **Identify problem campaigns across all platforms**: For each configured ad platform: - - **Google Ads**: Call `google_ads_health_check_all` (eligibility / serving issues — meaningful only with real-API; returns `[]` in BYOD), then iterate campaigns from `google_ads_campaigns_list` and call `google_ads_monitoring_zero_conversions` and `google_ads_cost_increase_investigate` per campaign_id, plus `google_ads_campaigns_diagnose` for structural issues. + - **Google Ads**: Call `google_ads_health_check_all` (eligibility / serving issues — meaningful only with Live API; returns `[]` in BYOD), then iterate campaigns from `google_ads_campaigns_list` and call `google_ads_monitoring_zero_conversions` and `google_ads_cost_increase_investigate` per campaign_id, plus `google_ads_campaigns_diagnose` for structural issues. - **Meta Ads**: Call `meta_ads_insights_report` and inspect each campaign's `result_indicator` (PR #61): a `link_click`-optimized campaign with high "results" but zero `pixel_lead` is a tracking issue, not a creative one — flag for measurement fix before any rescue action. - mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools — do **not** look for raw CSVs in the project directory. diff --git a/mureo/_data/skills/search-term-cleanup/SKILL.md b/mureo/_data/skills/search-term-cleanup/SKILL.md index 4345c41..17d24ea 100644 --- a/mureo/_data/skills/search-term-cleanup/SKILL.md +++ b/mureo/_data/skills/search-term-cleanup/SKILL.md @@ -21,7 +21,7 @@ Review and clean up search terms and keywords across all platforms. 2. **Discover platforms**: Identify all configured platforms that support search term data from STATE.json `platforms`. 3. **Review search terms**: For each ad platform that supports search term data: - - **Google Ads**: Call `google_ads_search_terms_report` for the raw query rows, then `google_ads_search_terms_review` (rule-based scoring) and `google_ads_search_terms_analyze` (intent classification) per campaign. **These tools work in both real-API and BYOD mode.** In BYOD they read from `~/.mureo/byod/google_ads/search_terms.csv` (the Apps Script bundle output) — do **not** look for raw CSVs in the project directory; mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools. + - **Google Ads**: Call `google_ads_search_terms_report` for the raw query rows, then `google_ads_search_terms_review` (rule-based scoring) and `google_ads_search_terms_analyze` (intent classification) per campaign. **These tools work in both Live API and BYOD mode.** In BYOD they read from `~/.mureo/byod/google_ads/search_terms.csv` (the Apps Script bundle output) — do **not** look for raw CSVs in the project directory; mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools. - **Meta Ads**: Skip — Meta is interest/audience-targeted and has no search-query data. - Analyze N-gram patterns and user intent across the returned rows. diff --git a/mureo/_data/skills/sync-state/SKILL.md b/mureo/_data/skills/sync-state/SKILL.md index 6c5e10e..7c2f5e0 100644 --- a/mureo/_data/skills/sync-state/SKILL.md +++ b/mureo/_data/skills/sync-state/SKILL.md @@ -21,7 +21,7 @@ Synchronize STATE.json with the current state of all marketing platforms. 2. **Discover platforms**: Identify all platforms registered in STATE.json `platforms`. 3. **Fetch platform data**: For each registered platform: - - **Google Ads**: Call `google_ads_campaigns_list`, then `google_ads_performance_report` for the current period (last 30 days). Both work in BYOD and real-API modes. + - **Google Ads**: Call `google_ads_campaigns_list`, then `google_ads_performance_report` for the current period (last 30 days). Both work in BYOD and Live API modes. - **Meta Ads**: Call `meta_ads_campaigns_list`, then `meta_ads_insights_report` for the current period — capture `result_indicator` per campaign so STATE.json reflects whether each campaign's "results" are clicks or real leads. - mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools — do **not** look for raw CSVs in the project directory. diff --git a/mureo/byod/adapters/google_ads.py b/mureo/byod/adapters/google_ads.py index 73eb6cc..6616cc7 100644 --- a/mureo/byod/adapters/google_ads.py +++ b/mureo/byod/adapters/google_ads.py @@ -25,7 +25,7 @@ Google Ads Scripts does not expose the GAQL ``auction_insight_domain`` resource, and the legacy AWQL ``AUCTION_INSIGHT_PERFORMANCE_REPORT`` returns "Report not mapped" — neither surface works from inside Ads -Scripts. Use the existing real-API path (``mureo auth setup``) for +Scripts. Use the existing Live API path (``mureo auth setup``) for ``/competitive-scan`` if competitor share data is needed. Campaign / ad-group identity is synthesized from name (deterministic @@ -340,7 +340,7 @@ def normalize_from_workbook( # auction_insight_domain GAQL resource (returns "Could not # identify resource") and the legacy AWQL report # AUCTION_INSIGHT_PERFORMANCE_REPORT returns "Report not - # mapped". `/competitive-scan` falls back to the real-API + # mapped". `/competitive-scan` falls back to the Live API # path or returns an empty result for BYOD users. all_dates.sort() diff --git a/mureo/byod/bundle.py b/mureo/byod/bundle.py index 4194926..194a754 100644 --- a/mureo/byod/bundle.py +++ b/mureo/byod/bundle.py @@ -16,7 +16,7 @@ GA4 and Search Console BYOD paths were removed in Phase 1 of the BYOD redesign — those platforms remain accessible via the existing -real-API OAuth path. Meta Ads BYOD will land in a follow-up. +Live API OAuth path. Meta Ads BYOD will land in a follow-up. Manifest update is atomic. Either the dispatched platform's section is written to ``manifest.json`` together with on-disk files, or nothing diff --git a/mureo/byod/clients.py b/mureo/byod/clients.py index 28445df..9549a70 100644 --- a/mureo/byod/clients.py +++ b/mureo/byod/clients.py @@ -365,7 +365,7 @@ async def get_search_terms_report( ``search_terms.csv``. The Apps Script does not stamp the rows with a date (it aggregates over its own DAYS_LOOKBACK), so the ``period`` kwarg is accepted for signature parity with the - real-API client but does not actually filter rows. + Live API client but does not actually filter rows. ``campaign_id`` / ``ad_group_id`` filter against the synthetic IDs (``camp_`` / ``ag_``) the adapter assigns. @@ -398,7 +398,7 @@ async def get_search_terms_report( conversions = _to_float(r.get("conversions")) ctr = (clicks / impressions) if impressions else 0 avg_cpc = (cost / clicks) if clicks else 0 - # Schema parity: the real-API client's map_search_term in + # Schema parity: the Live API client's map_search_term in # mureo/google_ads/mappers.py returns metrics as a nested # dict so downstream consumers (_analysis_search_terms, # _analysis_performance) can read `t["metrics"]["cost"]`. diff --git a/mureo/cli/byod_cmd.py b/mureo/cli/byod_cmd.py index 6be0ccd..61a5092 100644 --- a/mureo/cli/byod_cmd.py +++ b/mureo/cli/byod_cmd.py @@ -41,7 +41,7 @@ def _print_status_block() -> None: if not manifest: if creds_ok: typer.echo( - " No BYOD data installed. mureo will use real API " + " No BYOD data installed. mureo will use Live API " "(credentials present at ~/.mureo/credentials.json)." ) else: @@ -62,7 +62,7 @@ def _print_status_block() -> None: ) else: if creds_ok: - typer.echo(f" {p:15s} real API (credentials present)") + typer.echo(f" {p:15s} Live API (credentials present)") else: typer.echo( f" {p:15s} not configured " "(no BYOD data, no credentials.json)" @@ -141,7 +141,7 @@ def import_( @byod_app.command("status") # type: ignore[untyped-decorator, unused-ignore] def status() -> None: - """Show which platforms are in BYOD mode vs real-API mode.""" + """Show which platforms are in BYOD mode vs Live API mode.""" typer.echo("=== mureo byod status ===\n") _print_status_block() diff --git a/mureo/mcp/_client_factory.py b/mureo/mcp/_client_factory.py index 4a47bb5..6ded1d2 100644 --- a/mureo/mcp/_client_factory.py +++ b/mureo/mcp/_client_factory.py @@ -51,7 +51,7 @@ def get_meta_ads_client( def get_search_console_client(creds: Any, throttler: Any | None = None) -> Any: - """Return a Search Console client (real-API only). + """Return a Search Console client (Live API only). BYOD path was removed in Phase 1 of the BYOD redesign; SC is reached only via the existing OAuth credentials. diff --git a/scripts/sheet-template/README.md b/scripts/sheet-template/README.md index 13bf16b..f217f67 100644 --- a/scripts/sheet-template/README.md +++ b/scripts/sheet-template/README.md @@ -25,7 +25,7 @@ account on Google's infrastructure. ## Scope This BYOD path covers **Google Ads only**. GA4 and Search Console are -reached via the existing real-API OAuth credentials (see +reached via the existing Live API OAuth credentials (see `docs/authentication.md`); attempting to feed those datasets through the Sheet bundle is not supported. Meta Ads BYOD ships in a follow-up PR. diff --git a/skills/daily-check/SKILL.md b/skills/daily-check/SKILL.md index a2ac192..00bd371 100644 --- a/skills/daily-check/SKILL.md +++ b/skills/daily-check/SKILL.md @@ -23,7 +23,7 @@ Run a daily health check on all marketing accounts using the strategy context. 3. **Sync state**: For each platform in STATE.json `platforms`, fetch current campaign data via `google_ads_campaigns_list` / `meta_ads_campaigns_list` and update STATE.json. Both tools work in BYOD mode — do **not** look for raw CSVs in the project directory; mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools. 4. **Platform health checks**: Run health diagnostics on each configured ad platform: - - **Google Ads**: `google_ads_performance_report` (campaign-level metrics — works in BYOD), `google_ads_health_check_all` (returns `[]` in BYOD; only meaningful with real-API), `google_ads_cost_increase_investigate` (per-campaign anomaly check), `google_ads_monitoring_zero_conversions` (per-campaign). + - **Google Ads**: `google_ads_performance_report` (campaign-level metrics — works in BYOD), `google_ads_health_check_all` (returns `[]` in BYOD; only meaningful with Live API), `google_ads_cost_increase_investigate` (per-campaign anomaly check), `google_ads_monitoring_zero_conversions` (per-campaign). - **Meta Ads**: `meta_ads_insights_report` — surfaces a `result_indicator` field per campaign (`actions:link_click` vs `actions:offsite_conversion.fb_pixel_lead`); use this to detect CV-definition mismatches across campaigns where one campaign's "results" are clicks while another's are real leads. - In BYOD some tools return `[]` for unsupported features (auction insights, ad performance) — that's by design, not missing data; carry on with the rest of the diagnostics. - Present a unified health summary across all platforms. diff --git a/skills/rescue/SKILL.md b/skills/rescue/SKILL.md index 75d0b33..076f744 100644 --- a/skills/rescue/SKILL.md +++ b/skills/rescue/SKILL.md @@ -23,7 +23,7 @@ Run an emergency performance rescue workflow for underperforming campaigns. 3. **Diagnose: platform-side or site-side?** (if GA4 is available): Before making ad changes, check if the performance problem is platform-side or site-side. If LP conversion rates dropped in GA4 too, the issue may be the landing page, not the ads. Recommend LP investigation before ad changes. 4. **Identify problem campaigns across all platforms**: For each configured ad platform: - - **Google Ads**: Call `google_ads_health_check_all` (eligibility / serving issues — meaningful only with real-API; returns `[]` in BYOD), then iterate campaigns from `google_ads_campaigns_list` and call `google_ads_monitoring_zero_conversions` and `google_ads_cost_increase_investigate` per campaign_id, plus `google_ads_campaigns_diagnose` for structural issues. + - **Google Ads**: Call `google_ads_health_check_all` (eligibility / serving issues — meaningful only with Live API; returns `[]` in BYOD), then iterate campaigns from `google_ads_campaigns_list` and call `google_ads_monitoring_zero_conversions` and `google_ads_cost_increase_investigate` per campaign_id, plus `google_ads_campaigns_diagnose` for structural issues. - **Meta Ads**: Call `meta_ads_insights_report` and inspect each campaign's `result_indicator` (PR #61): a `link_click`-optimized campaign with high "results" but zero `pixel_lead` is a tracking issue, not a creative one — flag for measurement fix before any rescue action. - mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools — do **not** look for raw CSVs in the project directory. diff --git a/skills/search-term-cleanup/SKILL.md b/skills/search-term-cleanup/SKILL.md index 4345c41..17d24ea 100644 --- a/skills/search-term-cleanup/SKILL.md +++ b/skills/search-term-cleanup/SKILL.md @@ -21,7 +21,7 @@ Review and clean up search terms and keywords across all platforms. 2. **Discover platforms**: Identify all configured platforms that support search term data from STATE.json `platforms`. 3. **Review search terms**: For each ad platform that supports search term data: - - **Google Ads**: Call `google_ads_search_terms_report` for the raw query rows, then `google_ads_search_terms_review` (rule-based scoring) and `google_ads_search_terms_analyze` (intent classification) per campaign. **These tools work in both real-API and BYOD mode.** In BYOD they read from `~/.mureo/byod/google_ads/search_terms.csv` (the Apps Script bundle output) — do **not** look for raw CSVs in the project directory; mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools. + - **Google Ads**: Call `google_ads_search_terms_report` for the raw query rows, then `google_ads_search_terms_review` (rule-based scoring) and `google_ads_search_terms_analyze` (intent classification) per campaign. **These tools work in both Live API and BYOD mode.** In BYOD they read from `~/.mureo/byod/google_ads/search_terms.csv` (the Apps Script bundle output) — do **not** look for raw CSVs in the project directory; mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools. - **Meta Ads**: Skip — Meta is interest/audience-targeted and has no search-query data. - Analyze N-gram patterns and user intent across the returned rows. diff --git a/skills/sync-state/SKILL.md b/skills/sync-state/SKILL.md index 6c5e10e..7c2f5e0 100644 --- a/skills/sync-state/SKILL.md +++ b/skills/sync-state/SKILL.md @@ -21,7 +21,7 @@ Synchronize STATE.json with the current state of all marketing platforms. 2. **Discover platforms**: Identify all platforms registered in STATE.json `platforms`. 3. **Fetch platform data**: For each registered platform: - - **Google Ads**: Call `google_ads_campaigns_list`, then `google_ads_performance_report` for the current period (last 30 days). Both work in BYOD and real-API modes. + - **Google Ads**: Call `google_ads_campaigns_list`, then `google_ads_performance_report` for the current period (last 30 days). Both work in BYOD and Live API modes. - **Meta Ads**: Call `meta_ads_campaigns_list`, then `meta_ads_insights_report` for the current period — capture `result_indicator` per campaign so STATE.json reflects whether each campaign's "results" are clicks or real leads. - mureo BYOD data is centralized in the workspace `byod/` directory (or `~/.mureo/byod/` for legacy CLI users) and is only accessible through MCP tools — do **not** look for raw CSVs in the project directory. diff --git a/tests/test_byod.py b/tests/test_byod.py index e5863ff..7c0c8eb 100644 --- a/tests/test_byod.py +++ b/tests/test_byod.py @@ -7,7 +7,7 @@ - manifest read/write resilience (missing / corrupt / wrong schema) - BYOD clients reading the CSVs produced by the bundle importer - Mutation guards on every BYOD client class - - MCP factory routing (BYOD active → BYOD client; otherwise real API) + - MCP factory routing (BYOD active → BYOD client; otherwise Live API) - CLI surface (``mureo byod import / status / remove / clear``) - No-outbound-network guarantee under BYOD-mode tool dispatch """ @@ -682,7 +682,7 @@ def test_byod_meta_get_performance_report_exposes_result_indicator( def test_byod_meta_client_phase3_readers(tmp_path, fake_home): """ByodMetaAdsClient exposes the Phase 3 CSVs through async - readers that mirror the real-API method shapes daily-check expects: + readers that mirror the Live API method shapes daily-check expects: get_metrics_daily / get_ad_set_insights_daily / get_ad_insights_daily / get_breakdown_report (demographics) / get_creatives. """