@koda-sl/baker-cli 0.122.0-dev.ab8c14ab5 → 0.122.0-dev.fff192e73

package/README.md

@@ -397,6 +397,262 @@ baker ads google keywords metrics --customer-id 1234567890 --keywords "running s
 
 ---
 
+### Google Ads Library (`baker ads google library`)
+
+Manage and search the Google Ads Transparency Center. Track competitor advertisers, browse their ad creatives, and discover who's bidding on keywords.
+
+**Typical workflow:** `search-advertiser` → `track` → `search-ads`
+
+---
+
+### `baker ads google library search-advertiser "query"`
+
+Search for an advertiser on the Google Ads Transparency Center.
+
+> **Recommended:** use the domain running the ads (e.g. `example.com`) for more accurate results.
+
+```bash
+baker ads google library search-advertiser "example.com"
+baker ads google library search-advertiser "Nike"
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "results": [
+      { "advertiserId": "AR12345678901234567", "name": "Nike, Inc.", "region": "US", "format": "TEXT_IMAGE_VIDEO" }
+    ]
+  }
+}
+```
+
+**Flags:**
+
+| Flag       | Description                    |
+|------------|--------------------------------|
+| `--output` | Format: `json` \| `csv` \| `md` |
+
+---
+
+### `baker ads google library track <id> <name>`
+
+Track a new Google advertiser and wait for the initial ad sync to complete. Polls every 5 seconds with a 10-minute timeout. Progress is written to stderr.
+
+```bash
+baker ads google library track AR12345678901234567 "Nike, Inc."
+baker ads google library track AR12345678901234567 "Nike, Inc." --json
+```
+
+**Response (with `--json`):**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "advertiserId": "ar_abc123",
+    "accountId": "acc_def456",
+    "totalAdCount": 342,
+    "activeAdCount": 89
+  }
+}
+```
+
+**Flags:**
+
+| Flag     | Description          |
+|----------|----------------------|
+| `--json` | Output in JSON format |
+
+---
+
+### `baker ads google library list-advertisers`
+
+List all tracked Google advertisers and their accounts.
+
+```bash
+baker ads google library list-advertisers
+baker ads google library list-advertisers --output md
+```
+
+**Flags:**
+
+| Flag       | Description                    |
+|------------|--------------------------------|
+| `--output` | Format: `json` \| `csv` \| `md` |
+
+---
+
+### `baker ads google library sync-status <accountId>`
+
+Check the sync status and ad counts of a tracked account.
+
+```bash
+baker ads google library sync-status acc_def456
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "syncStatus": null,
+    "totalAdCount": 342,
+    "activeAdCount": 89
+  }
+}
+```
+
+`syncStatus` is `null` when idle, `"syncing"` during a sync, or `"error"` if the last sync failed.
+
+---
+
+### `baker ads google library search-ads <accountId>`
+
+Search and filter ads for a tracked account. Supports pagination.
+
+```bash
+baker ads google library search-ads acc_def456
+baker ads google library search-ads acc_def456 --search "summer sale" --isActive --mediaType image
+baker ads google library search-ads acc_def456 --sort newest --limit 50
+baker ads google library search-ads acc_def456 --cursor "eyJwYWdl..."
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "page": [
+      {
+        "_id": "abc123",
+        "platform": "google",
+        "externalId": "CR_1234567890",
+        "isActive": true,
+        "mediaType": "image",
+        "headline": "Summer Sale — 50% Off Everything",
+        "description": "Shop our biggest sale of the year. Free shipping on all orders.",
+        "destinationUrl": "https://example.com/summer-sale",
+        "bodyText": "Summer Sale — 50% Off Everything",
+        "pageName": "Example Store",
+        "impressionsMin": 100000,
+        "impressionsMax": 200000,
+        "startDate": "2025-06-01",
+        "endDate": "2025-06-30",
+        "firstSeenAt": 1717200000000,
+        "lastSeenAt": 1719792000000,
+        "publisherPlatforms": ["GOOGLE_ADS"],
+        "regionCodes": ["US", "GB"],
+        "variations": [
+          {
+            "headline": "Summer Sale — 50% Off",
+            "description": "Shop our biggest sale of the year.",
+            "destinationUrl": "https://example.com/summer-sale",
+            "imageUrl": "https://...",
+            "visibleUrl": "example.com"
+          }
+        ],
+        "regions": [
+          { "code": "US", "name": "United States" }
+        ],
+        "analysisStatus": "completed",
+        "aiAnalysis": {
+          "aiSummary": "Promotional display ad for a seasonal sale with urgency-driven CTA",
+          "hookAngle": "Discount/Price",
+          "offerType": "Percentage Discount",
+          "ctaStrategy": "Shop Now",
+          "funnelStage": "Bottom",
+          "targetAudience": "Price-sensitive shoppers",
+          "adFormat": "responsive_display",
+          "tags": ["sale", "discount", "ecommerce"],
+          "trustSignals": ["Free shipping"],
+          "keyMessages": ["50% off", "Free shipping"],
+          "competitiveAngle": "Price leadership",
+          "dominantColors": ["#FF5733", "#FFFFFF"],
+          "analyzedAt": 1719792000000
+        }
+      }
+    ],
+    "continueCursor": "eyJwYWdl...",
+    "isDone": false
+  }
+}
+```
+
+**Key response fields:**
+
+| Field | Description |
+|-------|-------------|
+| `headline`, `description` | Top-level ad copy (first variation) |
+| `variations[]` | All ad variations with copy, images, videos, and URLs |
+| `regions[]` | Geographic targeting regions |
+| `impressionsMin/Max` | Estimated impression range (Google Ads Transparency data) |
+| `publisherPlatforms` | Where the ad ran (GOOGLE_ADS, YOUTUBE, etc.) |
+| `analysisStatus` | AI analysis state: `pending`, `processing`, `completed`, `failed` |
+| `aiAnalysis` | AI-generated creative analysis (only present when `analysisStatus` is `completed`) |
+| `aiAnalysis.aiSummary` | One-line AI summary of the ad |
+| `aiAnalysis.hookAngle` | Creative hook (Discount, Fear, Social Proof, etc.) |
+| `aiAnalysis.funnelStage` | Funnel position: Top, Middle, Bottom |
+| `aiAnalysis.tags` | AI-generated tags for filtering |
+
+**Flags:**
+
+| Flag          | Description                                    |
+|---------------|------------------------------------------------|
+| `--search`    | Search term for ad text                        |
+| `--isActive`  | Filter by active ads only                      |
+| `--mediaType` | Filter by media type: `image`, `video`, `text` |
+| `--sort`      | Sort: `newest` or `oldest`                     |
+| `--limit`     | Max results per page (default 20, max 100)     |
+| `--cursor`    | Pagination cursor from previous response       |
+| `--output`    | Format: `json` \| `csv` \| `md`               |
+
+---
+
+### `baker ads google library sync <accountId>`
+
+Trigger an immediate re-sync for a tracked account. Polls every 5 seconds until complete (10-minute timeout). Progress is written to stderr.
+
+```bash
+baker ads google library sync acc_def456
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "totalAdCount": 350,
+    "activeAdCount": 92
+  }
+}
+```
+
+---
+
+### `baker ads google library search-competitors "keyword"`
+
+Search for competitors running Google ads for a keyword. Uses DataForSEO (same data as `baker research advertisers`).
+
+```bash
+baker ads google library search-competitors "running shoes"
+baker ads google library search-competitors "crm software" --location uk
+```
+
+**Flags:**
+
+| Flag         | Description                |
+|--------------|----------------------------|
+| `--location` | Location name or code      |
+| `--json`     | Output in JSON format      |
+
+---
+
 ### Staged writes (`baker ads google budgets|campaigns|...`)
 
 Write commands **never touch the Google Ads API at stage time**. Each command stages a create/update/pause/resume/remove op against the current chat's draft (`BAKER_CHAT_ID`); the dashboard shows it as a pending "Google Ads" change, and the whole draft applies as one atomic `GoogleAdsService.Mutate` when the chat is published. Feature-flagged per company (`companies.googleAdsWriteEnabled`) — off by default = a fully simulated publish with zero real API calls.
@@ -2161,17 +2417,13 @@ baker testimonials tags
 
 ### Winning Ads (`baker winning-ads`)
 
-Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`), and manage the brands your library tracks (`follow` / `following` / `unfollow`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
-
-> The corpus has **Meta + LinkedIn** connectors, so `--platform` inputs are limited to `meta,linkedin`. (Older result rows may still carry a legacy platform string.)
+Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
 
 > Backend env: the Convex deployment must have `AD_DNA_API_TOKEN` set (`npx convex env set AD_DNA_API_TOKEN …`). `AD_DNA_API_URL` is optional and defaults to `https://ads.withbaker.com`.
 
-> Replaces the old `baker ads google library` tree, which has been removed. Competitor-by-keyword discovery still lives at `baker research advertisers`.
-
 ### `baker winning-ads search <query>`
 
-Semantic search (dense recall + BM25 + rerank) → `POST /api/ad-library/winners/search`. The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`; plus top-level `pool_size`, `match_confidence` (`high|medium|low`), and `below_floor_count` (matches dropped under the relevance floor). `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
+Semantic search (dense recall + BM25 + rerank). The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`; plus top-level `pool_size` and `match_confidence`. `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
 
 > `media_url` is the creative itself: for `static` it's the image, for `video` it's the video file. ad-dna stores **no separate poster** for videos, so a video result has only the video URL.
 
@@ -2193,7 +2445,7 @@ baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00
 | `--limit <n>` | Max results 1–100 (**default 10** — shortlist size) |
 | `--max-per-advertiser <n>` | Cap results per advertiser 1–50 (default 3) |
 | `--min-relevance <0-1>` | Relevance floor; trims weak matches |
-| `--platform <list>` | `meta,linkedin` — pass a single value to search **only** that platform |
+| `--platform <list>` | One or many of `meta,tiktok,linkedin,google_search,google_display,youtube,reddit,x,pinterest,snapchat` — pass a single value to search **only** that platform |
 | `--format <list>` | `video,static,carousel` |
 | `--winner-category <list>` | `winner,scaled_winner,evergreen,rising,untested,dud,…` (default: all) |
 | `--awareness <list>` | `unaware,problem_aware,solution_aware,product_aware,most_aware` |
@@ -2208,66 +2460,13 @@ Reading the scores: **`relevance`** (0–1) = match of the creative to your quer
 
 ### `baker winning-ads advertisers <brand>`
 
-List corpus brands by name or domain → `GET /api/ad-library/advertisers`. Use it to find **your own** advertiser (to `--exclude-advertiser`) or a **competitor** (to `--advertiser-id` / `winners`). Lean default fields: `advertiser_id`, `label`, `platform_count`, `family_count`, `active_ad_count`, `total_ad_count`; `--full` adds `scraped_name`, `image_url`, `platforms`, `total_reach`, `last_synced_at`. Supports `--platform meta|linkedin`, `--limit`, `--offset`.
+Resolve a brand name → `advertiser_id`(s) in the corpus. Use it to find **your own** advertiser (to `--exclude-advertiser`) or a **competitor** (to `--advertiser-id`). Returns `advertiser_id`, `label`, `active_ads`, `total_ads`.
 
 ```bash
 baker winning-ads advertisers "Acme" --output md          # find our own advertiser id
 baker winning-ads advertisers "Deel" --platform meta --output md
 ```
 
-### `baker winning-ads follow "<domain | profile URL | brand>" --platform meta|linkedin`
-
-Add a brand's ads to your library → `POST /api/ad-library/follow`. `--platform` is **required**. The result `status` is one of:
-
-- `following` — the brand is already in the corpus; you're now subscribed (no wait).
-- `added` — a new brand was queued for ingestion; its ads appear as discovery completes (a `hints[]` note flags this).
-- `ambiguous` — the input mapped to multiple brands; pick one from `candidates` and re-run with a more specific domain/URL.
-
-```bash
-baker winning-ads follow "deel.com" --platform meta
-baker winning-ads follow "https://www.linkedin.com/company/acme" --platform linkedin --label "Acme (competitor)"
-```
-
-### `baker winning-ads following`
-
-List the brands you follow → `GET /api/ad-library/following`. Each row shows `status` (`ready` vs `adding…`) plus cached counts (`active_ad_count`, `total_ad_count`, `family_count`) and discovery progress (`adding_discovered`, `adding_enqueued`). `--full` adds `image_url` + `platforms`.
-
-```bash
-baker winning-ads following --output md
-```
-
-### `baker winning-ads winners <advertiser>`
-
-Top winning ads for one advertiser id → `GET /api/ad-library/advertiser-winners`. Same lean winner cards as `search` (add `--full` for DNA + longevity). Supports `--top N` and `--platform meta|linkedin`.
-
-```bash
-baker winning-ads winners adv_123 --top 15 --output md
-```
-
-### `baker winning-ads unfollow <advertiser>`
-
-Stop following a brand by advertiser id → `POST /api/ad-library/unfollow`. Returns `{ removed }`.
-
-```bash
-baker winning-ads unfollow adv_123
-```
-
-### `baker winning-ads brief`
-
-Generate a creative brief grounded in strategically-similar winners → `POST /api/ad-library/brief`. Optionally describe the target creative with `--dna` (a JSON object), steer with `--notes`, and cap references with `--k`. Returns `brief_markdown` + `reference_ad_ids`.
-
-```bash
-baker winning-ads brief --dna '{"angle":"cost savings","awareness_stage":"solution_aware"}' --notes "B2B, LinkedIn video" --k 8
-```
-
-### `baker winning-ads patterns --winners <adIds> --duds <adIds>`
-
-Mine what separates two cohorts of ads → `POST /api/ad-library/patterns`. Pass a comma-list of winning ad ids (`--winners`, cohort A) and weaker/dud ad ids (`--duds`, cohort B), plus optional `--top-n`. Returns each discriminating DNA field with the cohort it `favors` (`winners`/`duds`), a `score`, and the top values on each side.
-
-```bash
-baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --top-n 10 --output md
-```
-
 ---
 
 ### Scheduled Actions (`baker scheduled-actions`)
@@ -2312,13 +2511,12 @@ Read the client's marketing/analytics tags (Meta pixel, GA4, Google Ads, GTM, Cl
 `BAKER_CHAT_ID` must be set.
 
 ```bash
-baker tags list       # effective view: production + staged, full readable config + secret status
+baker tags list       # effective view: production + staged, with secret status
 baker tags draft      # review the staged changes awaiting publish
 ```
 
 Notes:
 
-- **`list` prints each tag's full readable config.** Every non-secret field is shown in full under the tag — the Clarity `projectId`, GA4 `measurementId`, the entire custom `code` snippet, etc. — so the agent reuses a stored value to pre-fill a follow-up change instead of asking the user for something already installed. Secrets are never among these fields. (`--json` emits the same data as the raw envelope.)
 - **Secrets never travel through this CLI or the chat.** Secret fields (`accessToken`, `apiSecret`, `authorizationToken`, `apiKey`, `conversionToken`, `oauthProviderId`) are entered only in the dashboard's secure tag form and flow straight into the staged draft; tool responses only ever name which secret fields are set/pending.
 - Staged creates get a server-generated `tag_temp_*` ref (returned in the tool result and printed by `list`). Use it (or a real tag id) as flow side-effect `tagIds` — the published tag keeps resolving under the temp ref.
 - Proposing a delete on a `tag_temp_*` ref drops the staged create instead.