@koda-sl/baker-cli 0.244.0 → 0.246.0

package/README.md

@@ -278,7 +278,31 @@ baker ads google query --list-presets
 }
 ```
 
-Read it before interpreting any null. It does not fire on the `--out` path (rows stream to disk), and `.resource_name` is never reported (the server strips it from every row).
+Read it before interpreting any null. Field coverage is folded page by page on the `--out` path too, so the file summary reports it; `.resource_name` is never reported (the server strips it from every row).
+
+**A page is not the data set.** Without `--all`, a query returns one page capped by `--limit` (default 200, or the `LIMIT` in the statement, whichever is smaller). With `--all` every page is followed, but the statement's `LIMIT` still caps the read — and preflight adds one at `--limit` to any query that arrives without it, so `--all` on its own still stops at 200 rows. When the rows fill whichever cap is in force, or the API returns a cursor the run did not follow, the response carries a `TRUNCATED_RESULTS` warning:
+
+```json
+{
+  "ok": true,
+  "warnings": [{ "code": "TRUNCATED_RESULTS", "message": "INCOMPLETE READ — ..." }],
+  "pagination": { "hasMore": true, "cursor": "eyJwYWdl..." },
+  "data": [...],
+  "notice": "Read the \"warnings\" above before using these rows: TRUNCATED_RESULTS."
+}
+```
+
+Never total or count from a response carrying it — re-run with `--all --limit 10000 --out data.csv` (the API accepts page sizes up to 10,000) and check the re-run came back without the warning. Warnings reach every output format, so no `--output` choice can hide one:
+
+| `--output` | Where warnings land |
+|------------|---------------------|
+| `json`     | `warnings` and `pagination` **before** `data`, one-line `notice` last |
+| `csv`      | `# baker <CODE>: …` comment lines under the header and after the last row |
+| `md`       | `> **<CODE>** — …` blockquote above and below the table |
+| `jsonl`    | a `{"_baker_warning":{…}}` line first and last |
+| `--out`    | the file summary carries `complete: true|false`, every warning, and the `notice` |
+
+The same lines also go to stderr. A read with nothing to report prints none of it.
 
 **Response (with pagination):**
 
@@ -311,7 +335,7 @@ Read it before interpreting any null. It does not fire on the `--out` path (rows
 | `--include-paused` | Include paused entities in preset results. Off by default: presets return only actually-serving entities (enabled campaign **and** ad group **and** ad). Google Ads has no single serving flag, so the whole chain must be `ENABLED` for an entity to serve. |
 | `--limit`       | Max rows per page (default 200)                              |
 | `--cursor`      | Pagination cursor from previous response                     |
-| `--all`         | Auto-paginate all results                                    |
+| `--all`         | Auto-paginate all results. Exhausts the pages, not the statement's `LIMIT` — pair it with a `--limit` above the expected row count, and a read that still fills its cap is flagged `TRUNCATED_RESULTS` either way |
 | `--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`           |
@@ -337,7 +361,7 @@ Read it before interpreting any null. It does not fire on the `--out` path (rows
 
 Every preset except the negatives lists and `account-summary` filters to **actually-serving entities** by default — the full status chain (`campaign.status = 'ENABLED' AND ad_group.status = 'ENABLED' AND ad_group_ad.status = 'ENABLED'`, as applicable) — and selects the status columns so you can see them. Pass `--include-paused` to widen to `!= 'REMOVED'` (keeps paused, still drops removed). Raw GAQL (no `--preset`) has no such default: a query over a serving-hierarchy resource without a status filter emits a `SERVING_SCOPE` warning reminding you to add the chain, because Google Ads has no single serving flag.
 
-**"Eligible (Limited)" keywords:** an enabled keyword that barely shows is invisible in the performance presets — near-zero impressions look the same whether it is outbid, low quality, or rarely searched. `--preset keyword-serving` reads the signals behind Google Ads' status column: `ad_group_criterion.primary_status` and `primary_status_reasons` (the status enum has no `LIMITED` value — "(Limited)" lives in the reasons while the status stays `ELIGIBLE`), `position_estimates.first_page_cpc_micros` (the number in "Below first page bid (€3.63)"), the max CPC actually in force and where it comes from, quality score split into ad relevance / landing page / expected CTR, approval status, and `system_serving_status`. Any read whose rows carry those fields — preset or raw GAQL — comes back with a `KEYWORD_SERVING_LIMITED` warning naming the affected keywords (each by its ad group, since one keyword's copies share a criterion id) and the bid each would need. Below-first-page-bid and low-quality want opposite fixes (raise the bid vs. improve relevance), so the warning reports them separately. On `--out` the verdict is folded across pages as they stream to disk and returned on the file summary; as with `MISSING_FIELDS`, `--output csv|jsonl|md` emits rows only and carries no warnings.
+**"Eligible (Limited)" keywords:** an enabled keyword that barely shows is invisible in the performance presets — near-zero impressions look the same whether it is outbid, low quality, or rarely searched. `--preset keyword-serving` reads the signals behind Google Ads' status column: `ad_group_criterion.primary_status` and `primary_status_reasons` (the status enum has no `LIMITED` value — "(Limited)" lives in the reasons while the status stays `ELIGIBLE`), `position_estimates.first_page_cpc_micros` (the number in "Below first page bid (€3.63)"), the max CPC actually in force and where it comes from, quality score split into ad relevance / landing page / expected CTR, approval status, and `system_serving_status`. Any read whose rows carry those fields — preset or raw GAQL — comes back with a `KEYWORD_SERVING_LIMITED` warning naming the affected keywords (each by its ad group, since one keyword's copies share a criterion id) and the bid each would need. Below-first-page-bid and low-quality want opposite fixes (raise the bid vs. improve relevance), so the warning reports them separately. On `--out` the verdict is folded across pages as they stream to disk and returned on the file summary; like every other warning it also travels in `--output csv|jsonl|md`.
 
 The warning defers to Google: when the query selects `primary_status_reasons`, a keyword Google did not flag is not reported, even if its bid sits under the first-page estimate — the estimate is advisory and the bid may not be the criterion's to set under a portfolio strategy. Only an estimates-only read (no reasons selected) falls back to inferring the limit from the bid gap.
 
@@ -432,13 +456,14 @@ baker ads google keywords discover --customer-id 1234567890 --url "https://compe
   "data": {
     "keywords": [
       {
+        "source": "keyword_planner_estimate",
         "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": [
+        "planner_avg_monthly_searches": "1000",
+        "planner_competition": "LOW",
+        "planner_competition_index": "4",
+        "planner_low_top_of_page_bid_micros": 0,
+        "planner_high_top_of_page_bid_micros": 0,
+        "planner_monthly_search_volumes": [
           { "year": "2025", "month": "APRIL", "monthly_searches": "590" }
         ]
       }
@@ -447,12 +472,13 @@ baker ads google keywords discover --customer-id 1234567890 --url "https://compe
     "next_page_token": "..."
   },
   "fields": {
+    "source": "Always \"keyword_planner_estimate\" — these rows are Keyword Planner ESTIMATES of total market search volume, NOT this account's data",
     "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)"
+    "planner_avg_monthly_searches": "ESTIMATE: average monthly searches across the whole market",
+    "planner_competition": "ESTIMATE: competition level — LOW, MEDIUM, HIGH, UNKNOWN",
+    "planner_competition_index": "ESTIMATE: competition index 0-100 (higher = more competitive)",
+    "planner_low_top_of_page_bid_micros": "ESTIMATE: low-range CPC bid in micros (÷ 1,000,000 for currency)",
+    "planner_high_top_of_page_bid_micros": "ESTIMATE: high-range CPC bid in micros (÷ 1,000,000 for currency)"
   }
 }
 ```
@@ -491,13 +517,14 @@ baker ads google keywords metrics --customer-id 1234567890 --keywords "running s
   "data": {
     "historical_metrics": [
       {
+        "source": "keyword_planner_estimate",
         "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": [
+        "planner_avg_monthly_searches": "1000",
+        "planner_competition": "LOW",
+        "planner_competition_index": "4",
+        "planner_low_top_of_page_bid_micros": 0,
+        "planner_high_top_of_page_bid_micros": 0,
+        "planner_monthly_search_volumes": [
           { "year": "2025", "month": "APRIL", "monthly_searches": "590" }
         ]
       }
@@ -5623,7 +5650,7 @@ baker landing inspiration scrape <url> --out .baker/<dir>   # capture any page n
 - **`add` studies in the background; `scrape` returns with the page on disk.** `add` grows the shared library and takes minutes, so it can never answer "build our page like this one" within the same turn. `scrape` runs the identical capture locally and blocks until it finishes, writing section screenshots, standalone markup, a whole-page reproduction and `report.html`. `--no-motion` is the single biggest lever on runtime; `--no-mobile`, `--no-code` and `--no-report` skip further passes.
 - **Filming is the expensive pass, and it runs three sections at a time.** Every moving section is filmed in its own fresh page load — the only way to catch an entrance animation before it fires — so a page with ten moving sections pays for ten full loads. Measured on one heavy page, filming was 74% of the capture. The takes are independent, so they overlap; a page that cannot be captured inside the library's budget now says so instead of timing out silently.
 - **A page we can't open says why.** A dead certificate, an address that doesn't resolve, a site that won't answer or one that is simply too slow each produce their own plain-language reason rather than a browser error.
-- **Inspiration, never a clipboard.** Both `code` and `scrape` record what was consulted, and `critique`'s `originality` family blocks a publish that reuses a reference's copy verbatim.
+- **Inspiration, never a clipboard.** A reference's structure and mechanism are the lesson; write the client's own words.
 - **A capture has to land in `.baker/`, and `scrape` refuses anywhere else in a workspace.** `--out` is free-form and the directory is the agent's choice, but a capture is tens of MB of lossless PNG whose individual files clear every size gate — written to a tracked directory it becomes a permanent part of the client's repo, force-cloned into every later session. `.baker/` is gitignored precisely so a capture costs nothing. The refusal is scoped to the workspace: outside a git work tree — a local run against `/tmp` — any path is allowed, because there is no history to bloat.
 
 ### `baker landing critique`
@@ -5645,9 +5672,7 @@ baker landing critique spring-offer summer-offer claude  # score three landings
 
 - **Agent washing is a copy tell.** A page that claims autonomy ("fully autonomous", "while you sleep", "no human intervention") and never says anywhere what the buyer approves, overrides, or audits scores an `agent-washing` warn. One signal about oversight of the agent's actions — approval, review, override, undo/rollback, audit log, escalation — anywhere on the page clears it; the rule is page-scope precisely because the hero can defer the trust story to a section below it. Generic privacy boilerplate ("GDPR", "encrypted", "your data") deliberately does **not** clear it, since it appears in most footers and says nothing about who is in charge of the agent.
 
-- **The `originality` family compares your copy against inspiration sections you actually consulted.** It fires only on sections opened with `baker landing inspiration code`, so it flags facts rather than resemblances. Reusing a reference's headline, subhead, or CTA verbatim is block-tier.
-
-Output is the standard envelope `{ ok, data, hints }` with `data = { advisory, slug, overall, counts, dimensions, findings }`. `dimensions` scores eight design families (typography, color, borders_depth, motion, spacing, copy, integrity, originality) 0–1 (higher is better); `counts` is the block/warn/advisory tally.
+Output is the standard envelope `{ ok, data, hints }` with `data = { advisory, slug, overall, counts, dimensions, findings }`. `dimensions` scores seven design families (typography, color, borders_depth, motion, spacing, copy, integrity) 0–1 (higher is better); `counts` is the block/warn/advisory tally.
 
 ## Brand Fonts (`baker brand fonts`)