@koda-sl/baker-cli 0.5.1 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @koda-sl/baker-cli
 
-AI-agent-first CLI for interacting with Baker. Designed for programmatic use by AI agents with structured JSON output, schema introspection, and input hardening. Supports images and videos.
+AI-agent-first CLI for interacting with Baker. Designed for programmatic use by AI agents with structured JSON output, schema introspection, self-correcting errors, and built-in caching.
 
 ## Installation
 
@@ -12,15 +12,19 @@ pnpm add @koda-sl/baker-cli
 
 ## Authentication
 
-Set two environment variables:
+Set environment variables:
 
 ```bash
 export BAKER_API_KEY="bk_your_api_key_here"
 export BAKER_API_URL="https://your-baker-instance.convex.site"
+
+# Optional: default customer ID for Google Ads commands
+export BAKER_GOOGLE_ADS_CUSTOMER_ID="1234567890"
 ```
 
 - `BAKER_API_KEY` must start with `bk_`
 - `BAKER_API_URL` is your Convex site URL
+- `BAKER_GOOGLE_ADS_CUSTOMER_ID` — default Google Ads customer ID (10 digits). Used when `--customer-id` is not passed.
 
 ## Output Format
 
@@ -30,8 +34,14 @@ All commands return a JSON envelope:
 // Success
 { "ok": true, "data": { ... } }
 
-// Error
-{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Image not found" } }
+// Success with field descriptions
+{ "ok": true, "data": [...], "fields": { "campaign.name": "Campaign display name", "metrics.clicks": "Total clicks" } }
+
+// Success with data disclaimer (research commands)
+{ "ok": true, "data": [...], "fields": { ... }, "note": "Estimates based on third-party SERP data — not exact figures. Use for directional insights, not precise measurement." }
+
+// Error with self-correction (ads commands)
+{ "ok": false, "error": { "code": "FIELD_NOT_FOUND", "message": "...", "fix": { "action": "retry_with_modified_query", "correctedCommand": "baker ads google query \"...\"", "explanation": "..." }, "retryable": false, "gaqlExecuted": "SELECT ..." } }
 
 // Dry-run
 { "ok": true, "dryRun": true, "operation": "images.delete", "params": { "id": "abc123" } }
@@ -39,39 +49,668 @@ All commands return a JSON envelope:
 
 Use `--output` to change format:
 
-| Format  | Description                        | Best for        |
-|---------|------------------------------------|-----------------|
-| `json`  | Structured JSON envelope (default) | AI agents       |
-| `files` | Tab-separated, one row per result  | Piping / shell  |
-| `md`    | Markdown table                     | Human reading   |
+| Format  | Description                        | Best for           |
+|---------|------------------------------------|--------------------|
+| `json`  | Structured JSON envelope (default) | AI agents          |
+| `csv`   | RFC 4180 comma-separated values    | Analysis tools     |
+| `jsonl` | One JSON object per line           | Streaming/appending |
+| `files` | Tab-separated, one row per result  | Piping / shell     |
+| `md`    | Markdown table                     | Human reading      |
 
 ## Commands
 
-### `baker status`
+### Ad Platforms (`baker ads`)
+
+Multi-platform ad data commands. Currently supports Google Ads, with Meta, LinkedIn, and TikTok coming.
+
+---
+
+### `baker ads google accounts`
+
+List all accessible Google Ads accounts. Run this first to find account IDs.
+
+```bash
+baker ads google accounts
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": [
+    { "id": "3343516765", "name": "My Company", "access_type": "direct", "level": 0 },
+    { "id": "4106495409", "name": "Client Account", "access_type": "managed", "manager_id": "2292659431", "level": 1 }
+  ]
+}
+```
+
+**Flags:**
+
+| Flag         | Description           |
+|--------------|-----------------------|
+| `--no-cache` | Skip cache (1h TTL)   |
+
+---
+
+### `baker ads google currency`
+
+Get the account currency. Call before interpreting `cost_micros` values.
+
+```bash
+baker ads google currency --customer-id 5904042878
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": { "currency_code": "EUR", "customer_id": "5904042878" }
+}
+```
+
+**Flags:**
+
+| Flag            | Description                                    |
+|-----------------|------------------------------------------------|
+| `--customer-id` | Google Ads customer ID (10 digits, no dashes). Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
+| `--no-cache`    | Skip cache (24h TTL)                           |
+
+---
+
+### `baker ads google query`
+
+Run arbitrary GAQL queries. The most powerful command.
+
+```bash
+# Raw GAQL
+baker ads google query "SELECT campaign.name, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status = 'ENABLED' ORDER BY metrics.cost_micros DESC" --customer-id 1234567890
+
+# Use a preset (saves tokens)
+baker ads google query --preset campaign-performance --customer-id 1234567890
+
+# Export to CSV
+baker ads google query --preset search-terms --customer-id 1234567890 --out results.csv
+
+# Auto-paginate large datasets
+baker ads google query "SELECT ..." --customer-id 1234567890 --all --out /tmp/export.csv
+
+# List available presets
+baker ads google query --list-presets
+```
+
+**Response (JSON):**
+
+```json
+{
+  "ok": true,
+  "data": [
+    { "campaign.name": "Brand US", "metrics.clicks": 4521, "metrics.cost_micros": 2850000000 }
+  ],
+  "fields": {
+    "campaign.name": "Campaign display name",
+    "metrics.clicks": "Total clicks (integer)",
+    "metrics.cost_micros": "Total cost in micros (÷ 1,000,000 for actual currency)"
+  }
+}
+```
+
+**Response (with pagination):**
+
+```json
+{
+  "ok": true,
+  "data": [...],
+  "fields": { ... },
+  "pagination": { "hasMore": true, "cursor": "eyJwYWdl..." }
+}
+```
+
+**Response (file output, stdout only):**
+
+```json
+{
+  "ok": true,
+  "fields": { ... },
+  "file": "/tmp/results.csv",
+  "rows": 12847
+}
+```
+
+**Flags:**
+
+| Flag            | Description                                                  |
+|-----------------|--------------------------------------------------------------|
+| `--customer-id` | Google Ads customer ID (10 digits, no dashes). Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
+| `--preset`      | Named query template (see presets below)                     |
+| `--date-range`  | Override preset date range (LAST_7_DAYS, LAST_30_DAYS, etc.) |
+| `--limit`       | Max rows per page (default 200)                              |
+| `--cursor`      | Pagination cursor from previous response                     |
+| `--all`         | Auto-paginate all results                                    |
+| `--out`         | Write data to file (format from extension: .csv, .jsonl, .json) |
+| `--append`      | Append to existing file (skip CSV headers)                   |
+| `--output`      | Output format: `json` \| `csv` \| `jsonl` \| `md`           |
+| `--no-cache`    | Skip cache                                                   |
+| `--list-presets`| List all available presets                                   |
+
+**Presets:**
+
+| Preset                 | Description                              | Default date range |
+|------------------------|------------------------------------------|--------------------|
+| `campaign-performance` | Campaign metrics overview                | LAST_30_DAYS       |
+| `keyword-analysis`     | Keyword performance with match type      | LAST_30_DAYS       |
+| `search-terms`         | Actual user queries triggering ads       | LAST_7_DAYS        |
+| `ad-copy-performance`  | Ad headline/description effectiveness    | LAST_30_DAYS       |
+| `asset-performance`    | PMax asset performance labels            | LAST_30_DAYS       |
+| `shopping-products`    | Product-level shopping metrics           | LAST_30_DAYS       |
+| `account-summary`      | Account-level totals                     | LAST_30_DAYS       |
+
+**Pre-flight auto-fixes:**
+
+The CLI automatically corrects common GAQL mistakes before hitting the API:
+
+| Pattern | Auto-fix | Warning emitted |
+|---------|----------|-----------------|
+| Missing LIMIT | Adds `LIMIT 200` | `"Added LIMIT 200. Use --limit to override."` |
+| `keyword.text` | `ad_group_criterion.keyword.text` | `"keyword.text → ad_group_criterion.keyword.text"` |
+| `shopping_performance_view.product_*` | `segments.product_*` | Field renamed |
+| `campaign.status = 'ACTIVE'` | `= 'ENABLED'` | Enum corrected |
+
+Auto-fixed queries proceed normally. Warnings appear in the response:
+
+```json
+{ "ok": true, "data": [...], "warnings": [{ "code": "FIELD_RENAMED", "message": "keyword.text → ad_group_criterion.keyword.text" }] }
+```
+
+**Self-correcting errors:**
+
+When a query fails, the error includes a `fix` object with the exact corrected command:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "INVALID_OPERATOR",
+    "message": "GAQL does not support CONTAINS. Use LIKE with % wildcards.",
+    "fix": {
+      "action": "change_operator",
+      "correctedCommand": "baker ads google query \"SELECT campaign.name FROM campaign WHERE campaign.name LIKE '%brand%' LIMIT 200\" --customer-id 1234567890",
+      "explanation": "GAQL uses LIKE '%value%' for substring matching, not CONTAINS()"
+    },
+    "retryable": false
+  }
+}
+```
+
+---
 
-Check API key validity and connection health.
+### `baker ads google changes`
+
+Get recent change logs for an account.
+
+```bash
+baker ads google changes --customer-id 1234567890
+baker ads google changes --customer-id 1234567890 --days 14 --resource-type CAMPAIGN
+```
+
+**Flags:**
+
+| Flag              | Description                                                   |
+|-------------------|---------------------------------------------------------------|
+| `--customer-id`   | Google Ads customer ID. Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
+| `--days`          | Lookback days (default 7, max 90)                             |
+| `--resource-type` | Filter: CAMPAIGN, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION   |
+| `--limit`         | Max results (default 50)                                      |
+| `--output`        | Format: `json` \| `csv` \| `jsonl` \| `md`                   |
+
+---
+
+### `baker ads google keywords discover`
+
+Discover keyword ideas from seed keywords or URLs.
+
+```bash
+baker ads google keywords discover --customer-id 1234567890 --seeds "running shoes,athletic footwear"
+baker ads google keywords discover --customer-id 1234567890 --url "https://competitor.com" --limit 50
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "keywords": [
+      {
+        "keyword": "student services",
+        "avg_monthly_searches": "1000",
+        "competition": "LOW",
+        "competition_index": "4",
+        "low_top_of_page_bid_micros": 0,
+        "high_top_of_page_bid_micros": 0,
+        "monthly_search_volumes": [
+          { "year": "2025", "month": "APRIL", "monthly_searches": "590" }
+        ]
+      }
+    ],
+    "total_results": 10,
+    "next_page_token": "..."
+  },
+  "fields": {
+    "keyword": "Suggested keyword text",
+    "avg_monthly_searches": "Average monthly search volume",
+    "competition": "Competition level: LOW, MEDIUM, HIGH, UNKNOWN",
+    "competition_index": "Competition index 0-100 (higher = more competitive)",
+    "low_top_of_page_bid_micros": "Low-range CPC bid in micros (÷ 1,000,000 for currency)",
+    "high_top_of_page_bid_micros": "High-range CPC bid in micros (÷ 1,000,000 for currency)"
+  }
+}
+```
+
+**Flags:**
+
+| Flag            | Description                                   |
+|-----------------|-----------------------------------------------|
+| `--customer-id` | Google Ads customer ID. Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
+| `--seeds`       | Comma-separated seed keywords (max 10)        |
+| `--url`         | URL to extract keyword ideas from             |
+| `--location`    | Geo target ID (default: 2840 for US)          |
+| `--language`    | Language ID (default: 1000 for English)       |
+| `--limit`       | Max results (default 20)                      |
+| `--cursor`      | Pagination cursor from previous response (`next_page_token`) |
+| `--no-cache`    | Skip cache (24h TTL)                          |
+| `--output`      | Format: `json` \| `csv` \| `jsonl` \| `md`   |
+
+---
+
+### `baker ads google keywords metrics`
+
+Get historical metrics for specific keywords.
+
+```bash
+baker ads google keywords metrics --customer-id 1234567890 --keywords "running shoes,nike shoes,adidas shoes"
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "historical_metrics": [
+      {
+        "keyword": "running shoes",
+        "avg_monthly_searches": "1000",
+        "competition": "LOW",
+        "competition_index": "4",
+        "low_top_of_page_bid_micros": 0,
+        "high_top_of_page_bid_micros": 0,
+        "monthly_search_volumes": [
+          { "year": "2025", "month": "APRIL", "monthly_searches": "590" }
+        ]
+      }
+    ]
+  },
+  "fields": { ... }
+}
+```
+
+**Flags:**
+
+| Flag            | Description                                   |
+|-----------------|-----------------------------------------------|
+| `--customer-id` | Google Ads customer ID. Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
+| `--keywords`    | Comma-separated keywords to analyze (max 200) |
+| `--location`    | Geo target ID (default: 2840 for US)          |
+| `--language`    | Language ID (default: 1000 for English)       |
+| `--no-cache`    | Skip cache (24h TTL)                          |
+| `--output`      | Format: `json` \| `csv` \| `jsonl` \| `md`   |
+
+---
+
+### Caching
+
+Google Ads data is cached at two levels:
+
+**Server-side (ActionCache)** — shared across all CLI instances and agents for the same company:
+
+| Data type | TTL | Cache name |
+|-----------|-----|------------|
+| Account list | 1 hour | `ads-accounts-v1` |
+| Currency | 7 days | `ads-currency-v1` |
+| GAQL queries | 1 hour | `ads-query-v1` |
+| Keyword ideas | 1 day | `ads-keyword-ideas-v1` |
+| Keyword metrics | 1 day | `ads-keyword-metrics-v1` |
+
+**Client-side (local file cache)** — per-machine at `~/.baker/cache/ads/`:
+
+| Data type | TTL | Reason |
+|-----------|-----|--------|
+| GAQL (LAST_30_DAYS, BETWEEN) | 6 hours | Historical data is immutable |
+| GAQL (LAST_7_DAYS) | 1 hour | Recent data updates less frequently |
+| GAQL (TODAY) | 15 minutes | Today's data changes in real-time |
+
+Use `--no-cache` on any command to bypass **both** the local file cache and the server-side ActionCache, forcing a fresh API call.
+
+---
+
+### Google Ads Error Codes
+
+| Code | Retryable | Meaning |
+|------|-----------|---------|
+| `FIELD_NOT_FOUND` | No | Invalid field in GAQL query |
+| `WRONG_RESOURCE` | No | Field queried from wrong resource |
+| `INVALID_OPERATOR` | No | Unsupported operator (e.g. CONTAINS) |
+| `CUSTOMER_NOT_FOUND` | No | Invalid customer ID — run `baker ads google accounts` to find valid IDs |
+| `MISSING_MANAGER_ID` | No | Account not accessible (may need MCC login-customer-id) |
+| `INCOMPATIBLE_FIELDS` | No | Fields can't be in same query |
+| `OPEN_ENDED_DATE` | No | Date range must be finite |
+| `READ_ONLY` | No | Only SELECT queries allowed |
+| `QUOTA_EXCEEDED` | Yes (30s) | API rate limit hit |
+| `TIMEOUT` | Yes (5s) | Query too broad |
+| `AUTH_ERROR` | No | Token expired or missing |
+
+All errors include a `fix` object with `action`, `correctedCommand` (when applicable), and `explanation`.
+
+---
+
+### Competitive Intelligence (`baker research`)
+
+Market and competitor research powered by DataForSEO. Shows who's competing for keywords, search intent classification, competitor keyword strategies, keyword gaps, and landing page performance.
+
+All research responses include a `note` field indicating that data is estimated from third-party SERP scraping and should be used for directional insights, not precise measurement.
+
+---
+
+### `baker research advertisers "keyword"`
+
+Find domains competing for a keyword in Google SERPs.
 
 ```bash
-baker status
-# { "ok": true, "data": { "authenticated": true, "apiUrl": "https://..." } }
+baker research advertisers "running shoes"
+baker research advertisers "crm software" --location uk --limit 10
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": [
+    { "domain": "www.adidas.com", "avg_position": 1, "rating": 99, "etv": 111872, "visibility": 1 }
+  ],
+  "fields": {
+    "domain": "Competing domain",
+    "avg_position": "Average SERP position (1 = top)",
+    "rating": "Domain relevance rating (0-100)",
+    "etv": "Estimated traffic value (USD)",
+    "visibility": "SERP visibility score (0-1)"
+  }
+}
 ```
 
+**Flags:**
+
+| Flag         | Description                          |
+|--------------|--------------------------------------|
+| `--location` | Country code (us, uk, es, de...) or numeric code. Default: us |
+| `--language` | Language code or name (en, spanish, french...). Default: en |
+| `--limit`    | Max results (default: 20)            |
+| `--no-cache` | Skip cache (6h TTL)                  |
+| `--output`   | Format: json\|csv\|md\|jsonl         |
+
+---
+
+### `baker research intent "kw1,kw2,kw3"`
+
+Classify Google Search intent for keywords.
+
+```bash
+baker research intent "buy running shoes,best running shoes 2026,how to tie shoes"
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": [
+    { "keyword": "buy running shoes", "intent": "transactional", "probability": 0.96 }
+  ],
+  "fields": {
+    "keyword": "The keyword analyzed",
+    "intent": "Primary Google Search intent: informational, navigational, commercial, transactional",
+    "probability": "Confidence score 0.0-1.0"
+  }
+}
+```
+
+**Flags:**
+
+| Flag         | Description                          |
+|--------------|--------------------------------------|
+| `--language` | Language code or name (en, spanish, french...). Default: en |
+| `--no-cache` | Skip cache (7d TTL)                  |
+| `--output`   | Format: json\|csv\|md\|jsonl         |
+
+---
+
+### `baker research keywords-for-site "domain.com"`
+
+Get keywords a competitor targets. Use `--type paid` to see only paid keywords, `--type organic` for organic only.
+
+```bash
+baker research keywords-for-site "competitor.com"
+baker research keywords-for-site "competitor.com" --type paid --limit 20
+baker research keywords-for-site "competitor.com" --type organic --location uk
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": [
+    { "keyword": "running shoes online", "search_volume": 12000, "cpc": 1.85, "competition": "HIGH", "competition_index": 82 }
+  ],
+  "fields": {
+    "keyword": "Keyword the site targets",
+    "search_volume": "Monthly search volume",
+    "cpc": "Cost per click in USD",
+    "competition": "LOW, MEDIUM, or HIGH",
+    "competition_index": "Competition score 0-100"
+  }
+}
+```
+
+**Flags:**
+
+| Flag         | Description                                              |
+|--------------|----------------------------------------------------------|
+| `--location` | Country code (us, uk, es, de...) or numeric code. Default: us |
+| `--language` | Language code (default: en)                              |
+| `--sort`     | Sort: relevance, search_volume, competition, cpc         |
+| `--type`     | Filter: paid, organic, all (default: all)                |
+| `--limit`    | Max results (default: 50)                                |
+| `--no-cache` | Skip cache (6h TTL)                                      |
+| `--output`   | Format: json\|csv\|md\|jsonl                             |
+
+---
+
+### `baker research keyword-gap "them.com" "us.com"`
+
+Keywords the competitor has that you don't.
+
+```bash
+baker research keyword-gap "competitor.com" "mysite.com"
+baker research keyword-gap "competitor.com" "mysite.com" --type paid --limit 100
+baker research keyword-gap "competitor.com" "mysite.com" --offset 50 --limit 50
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "your_domain": "mysite.com",
+  "competitor_domain": "competitor.com",
+  "data": [
+    { "keyword": "marathon shoes", "search_volume": 8500, "cpc": 2.10, "their_position": 2 }
+  ],
+  "fields": {
+    "keyword": "Keyword in the gap (they rank, you don't)",
+    "search_volume": "Monthly search volume",
+    "cpc": "Cost per click USD",
+    "their_position": "Competitor's ranking position"
+  },
+  "note": "Estimates based on third-party SERP data — not exact figures. Use for directional insights, not precise measurement.",
+  "total_count": 342,
+  "pagination": {
+    "offset": 0,
+    "limit": 50,
+    "has_more": true,
+    "next_offset": 50
+  }
+}
+```
+
+**Flags:**
+
+| Flag         | Description                                |
+|--------------|--------------------------------------------|
+| `--location` | Country code (us, uk, es, de...) or numeric code. Default: us |
+| `--language` | Language code (default: en)                |
+| `--type`     | Filter: paid, organic, all (default: all)  |
+| `--limit`    | Max results (default: 50, max: 1000)       |
+| `--offset`   | Pagination offset (default: 0)             |
+| `--no-cache` | Skip cache (6h TTL)                        |
+| `--output`   | Format: json\|csv\|md\|jsonl               |
+
+---
+
+### `baker research lighthouse "https://url"`
+
+Landing page performance audit. Metrics affecting Google Ads Quality Score.
+
+```bash
+baker research lighthouse "https://example.com/landing"
+baker research lighthouse "https://example.com" --mobile false
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "url": "https://example.com/landing",
+    "performance_score": 72,
+    "fcp_ms": 1200,
+    "lcp_ms": 2800,
+    "cls": 0.05,
+    "speed_index_ms": 3200,
+    "interactive_ms": 4500
+  },
+  "fields": {
+    "url": "URL that was audited",
+    "performance_score": "Lighthouse performance score 0-100 (aim for 90+)",
+    "fcp_ms": "First Contentful Paint in ms (good: < 1800)",
+    "lcp_ms": "Largest Contentful Paint in ms (good: < 2500)",
+    "cls": "Cumulative Layout Shift (good: < 0.1)",
+    "speed_index_ms": "Speed Index in ms (good: < 3400)",
+    "interactive_ms": "Time to Interactive in ms (good: < 3800)"
+  }
+}
+```
+
+**Flags:**
+
+| Flag         | Description                          |
+|--------------|--------------------------------------|
+| `--mobile`   | Test as mobile (default: true)       |
+| `--output`   | Format: json\|csv\|md\|jsonl         |
+| `--no-cache` | Skip cache (24h TTL)                 |
+
+---
+
+### `baker research countries`
+
+List all supported country codes for `--location` flag.
+
+```bash
+baker research countries
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": [
+    { "code": "us", "name": "United States" },
+    { "code": "uk", "name": "United Kingdom" },
+    { "code": "es", "name": "Spain" }
+  ],
+  "fields": {
+    "code": "Country code to pass as --location",
+    "name": "Country name"
+  }
+}
+```
+
+---
+
+### `baker research languages`
+
+List all supported language codes for `--language` flag.
+
+```bash
+baker research languages
+```
+
+**Response:**
+
+```json
+{
+  "ok": true,
+  "data": [
+    { "code": "en", "name": "english" },
+    { "code": "es", "name": "spanish" }
+  ],
+  "fields": {
+    "code": "Language code to pass as --language",
+    "name": "Language name (also accepted by --language)"
+  }
+}
+```
+
+---
+
+### Research Caching
+
+Research data is cached server-side (shared across all callers). No local cache files. Use `--no-cache` on any research command to bypass the server cache and force a fresh API call.
+
+| Command           | TTL     | Reason                              |
+|-------------------|---------|-------------------------------------|
+| advertisers       | 6 hours | SERP landscape changes slowly       |
+| intent            | 7 days  | Intent classification is very stable |
+| keywords-for-site | 6 hours | Keyword targeting changes weekly    |
+| keyword-gap       | 6 hours | Same                                |
+| lighthouse        | 24 hours| Page performance stable day-to-day  |
+
+---
+
+### Assets (`baker images`, `baker videos`, `baker testimonials`)
+
 ### `baker images search <query>`
 
 Semantic search using hybrid BM25 + vector + reranking. Only returns ready images.
 
 ```bash
-# Basic search
 baker images search "hero banner"
-
-# Filter by aspect ratio and tags
 baker images search "logo" --aspect-ratio 1:1 --tags logo
-
-# Limit results and set minimum relevance
 baker images search "team photo" --limit 5 --min-score 0.3
-
-# Full metadata with markdown output
-baker images search "product shot" --full --output md
 ```
 
 **Flags:**
@@ -92,49 +731,19 @@ Get a single image by ID.
 
 ```bash
 baker images get j571abc123def
-
-# With full metadata
 baker images get j571abc123def --full
-
-# Alternative flag syntax
-baker images get --image-id j571abc123def
 ```
 
-**Flags:**
-
-| Flag         | Description                                  |
-|--------------|----------------------------------------------|
-| `--image-id` | Image ID (alternative to positional arg)     |
-| `--output`   | Output format: `json` \| `files` \| `md`    |
-| `--fields`   | Comma-separated field names to include       |
-| `--full`     | Include full metadata                        |
-
 ### `baker images upload <file>`
 
-Upload an image file. Content type is auto-detected from the file extension.
+Upload an image file.
 
 ```bash
-# Upload with auto-detected content type
 baker images upload ./logo.png
-
-# Specify source
 baker images upload ./banner.jpg --source uploaded
-
-# Override content type
-baker images upload ./image.bin --content-type image/webp
-
-# Preview what would happen without uploading
 baker images upload ./logo.png --dry-run
 ```
 
-**Flags:**
-
-| Flag             | Description                                    |
-|------------------|------------------------------------------------|
-| `--source`       | Source identifier                               |
-| `--content-type` | MIME type (auto-detected from extension)        |
-| `--dry-run`      | Preview the operation without executing         |
-
 Supported extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.avif`
 
 ### `baker images delete <id>`
@@ -142,168 +751,115 @@ Supported extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.avif`
 Delete an image by ID.
 
 ```bash
-# Preview deletion
 baker images delete j571abc123def --dry-run
-# { "ok": true, "dryRun": true, "operation": "images.delete", "params": { "id": "j571abc123def" } }
-
-# Execute deletion
 baker images delete j571abc123def
 ```
 
-**Flags:**
-
-| Flag         | Description                                  |
-|--------------|----------------------------------------------|
-| `--image-id` | Image ID (alternative to positional arg)     |
-| `--dry-run`  | Preview the operation without executing       |
-
 ### `baker videos search <query>`
 
-Semantic search videos using hybrid BM25 + vector + reranking.
+Semantic search videos.
 
 ```bash
-# Basic search
 baker videos search "product demo"
-
-# Filter by tags and limit results
 baker videos search "tutorial" --tags explainer,ugc --limit 5
-
-# Full metadata with markdown output
-baker videos search "testimonial" --full --output md
 ```
 
-**Flags:**
-
-| Flag       | Description                              |
-|------------|------------------------------------------|
-| `--limit`  | Max results (default 20)                 |
-| `--tags`   | Comma-separated tags to filter by        |
-| `--output` | Output format: `json` \| `files` \| `md` |
-| `--fields` | Comma-separated field names to include   |
-| `--full`   | Include full metadata                    |
-
 ### `baker videos get <id>`
 
 Get a single video by ID.
 
-```bash
-baker videos get j571abc123def
-
-# With full metadata
-baker videos get j571abc123def --full
-
-# Alternative flag syntax
-baker videos get --video-id j571abc123def
-```
-
 ### `baker videos upload <file>`
 
-Upload a video file via Mux direct upload. Content type is auto-detected from the file extension.
+Upload a video file via Mux direct upload.
 
 ```bash
-# Upload with auto-detected content type
 baker videos upload ./demo.mp4
-
-# Override content type
-baker videos upload ./video.bin --content-type video/mp4
-
-# Preview what would happen without uploading
 baker videos upload ./demo.mp4 --dry-run
 ```
 
-**Flags:**
-
-| Flag             | Description                                    |
-|------------------|------------------------------------------------|
-| `--content-type` | MIME type (auto-detected from extension)        |
-| `--dry-run`      | Preview the operation without executing        |
-
 Supported extensions: `.mp4`, `.mov`, `.webm`, `.avi`, `.mkv`
 
 ### `baker videos delete <id>`
 
 Delete a video by ID.
 
-```bash
-# Preview deletion
-baker videos delete j571abc123def --dry-run
+### `baker testimonials search <query>`
+
+Semantic search testimonials.
 
-# Execute deletion
-baker videos delete j571abc123def
+```bash
+baker testimonials search "great service"
+baker testimonials search "fast delivery" --rating-min 4 --tags quality
 ```
 
-**Flags:**
+### `baker testimonials get <id>`
+
+Get a single testimonial by ID.
+
+### `baker testimonials list`
 
-| Flag        | Description                              |
-|-------------|------------------------------------------|
-| `--dry-run` | Preview the operation without executing  |
+List testimonials with optional filters.
+
+```bash
+baker testimonials list --source google --sentiment positive --limit 20
+```
+
+---
 
 ### `baker schema [command]`
 
 Inspect command argument schemas for AI agent introspection.
 
 ```bash
-# List all available commands
-baker schema
-# { "ok": true, "data": { "commands": ["images.search", "images.get", ...] } }
-
-# Get schema for a specific command
-baker schema images.search
-# { "ok": true, "data": { "command": "images.search", "args": { ... } } }
+baker schema                    # List all commands
+baker schema ads.google.query   # Get query command schema
+baker schema images.search      # Get image search schema
 ```
 
-## Compact vs Full Output
+## Help & Discovery
 
-By default, responses include only essential fields to minimize token usage:
+Every command supports `--help` for usage info:
 
-**Images:**
+```bash
+baker --help                        # All top-level commands
+baker ads --help                    # Available platforms
+baker ads google --help             # All Google Ads subcommands
+baker ads google query --help       # All flags for the query command
+```
 
-| Mode      | Fields                                                     |
-|-----------|------------------------------------------------------------|
-| Default   | `_id`, `name`, `imageUrl`, `description`, `tags`           |
-| `--full`  | All fields: width, height, aspectRatio, dominantColor, imagePalette, source, createdAt |
+For machine-readable introspection, use `baker schema` (see below).
 
-**Videos:**
+## For AI Agents
 
-| Mode      | Fields                                    |
-|-----------|-------------------------------------------|
-| Default   | `_id`, `name`, `thumbnailUrl`, `description`, `tags`, `status` |
-| `--full`  | All fields: duration, muxPlaybackId, source, timestamps |
+This CLI is designed for AI agent consumption. Key patterns:
 
-## Error Codes
+1. **Start with `baker ads google accounts`** to discover available Google Ads accounts
+2. **Use `baker ads google query --list-presets`** to see available query templates (saves tokens)
+3. **Use presets** (`--preset campaign-performance`) instead of writing full GAQL when possible
+4. **Read the `fields` object** in responses to understand what each column means
+5. **Check `fix.correctedCommand`** on errors — copy-paste it to retry
+6. **Use `--all --out file.csv`** for large exports to avoid filling context window
+7. **Use `--no-cache`** when you need guaranteed fresh data
+8. **Start with `baker schema`** to discover all available commands and their arguments
+9. **Use `--dry-run`** on mutations to preview before executing
+10. **Parse the JSON envelope** — check `ok` field before accessing `data`
 
-| Code               | Description                          |
-|--------------------|--------------------------------------|
-| `UNAUTHORIZED`     | Invalid or missing API key           |
-| `NOT_FOUND`        | Resource not found                   |
-| `VALIDATION_ERROR` | Invalid input (bad ID, missing args) |
-| `RATE_LIMITED`     | Too many requests                    |
-| `NETWORK_ERROR`    | Connection failed                    |
-| `INTERNAL_ERROR`   | Unexpected server error              |
+## Publishing
 
-## Available Image Tags
+### Auto-publish (CI)
 
-Use these with `--tags` to filter image search results. Multiple tags can be comma-separated.
+Pushing to `main` with changes in `packages/cli/` triggers the GitHub Actions workflow, which publishes to npm with the `latest` tag.
 
-| Tag                | Description                                                  |
-|--------------------|--------------------------------------------------------------|
-| `logo`             | Singular company, product, or organizational logo            |
-| `profile-picture`  | Portrait-style image featuring a person's face               |
-| `illustration`     | Stylized, drawn, or vector artwork                           |
-| `software`         | UI, dashboards, app interfaces, or software captures         |
-| `product-shot`     | Focused depiction of a tangible product                      |
-| `team-photo`       | Group of people posed together, such as company team imagery |
-| `environment`      | Backgrounds or scenes showcasing locations, offices, spaces  |
-| `iconography`      | Icons, symbols, or small graphical elements                  |
-| `textures`         | Patterns, textures, or abstract visual surfaces              |
+### Manual publish
 
-## For AI Agents
+```bash
+./scripts/publish-package.sh cli        # Publish as @latest
+./scripts/publish-package.sh cli next   # Publish as @next (pre-release)
+```
 
-This CLI is designed for AI agent consumption. Key patterns:
+### Testing a pre-release in sandboxes
 
-1. **Start with `baker schema`** to discover available commands and their arguments
-2. **Use `--dry-run`** on mutations to preview before executing
-3. **Use `--fields`** to request only the data you need (context window discipline)
-4. **Parse the JSON envelope** — check `ok` field before accessing `data`
-5. **Use `--output files`** for compact, pipe-friendly output
-6. **Check `baker status`** first to verify connectivity
+```bash
+npx convex env set BAKER_CLI_VERSION <version>   # Override sandbox version
+npx convex env remove BAKER_CLI_VERSION          # Clean up after testing
+```