@koda-sl/baker-cli 0.244.0 → 0.245.0

package/dist/cli.js

@@ -9679,7 +9679,7 @@ function renderAdvisories(data, lines) {
     return;
   }
   lines.push("");
-  lines.push("Advisories (non-blocking \u2014 build these out for a higher-performance campaign)");
+  lines.push("Advisories (non-blocking, checked across the whole draft \u2014 settle these before you publish)");
   for (const advisory of advisories) {
     lines.push(`  \u2022 ${advisory.message}`);
   }
@@ -10188,10 +10188,33 @@ function warnDefaults(ctx) {
   }
 }
 
+// src/commands/ads/google/keywords/provenance.ts
+var PLANNER_SOURCE = "keyword_planner_estimate";
+var IDENTITY_FIELDS = /* @__PURE__ */ new Set(["keyword"]);
+function stampPlannerRows(rows) {
+  return rows.map((row) => {
+    const stamped = { source: PLANNER_SOURCE };
+    for (const [key, value] of Object.entries(row)) {
+      stamped[IDENTITY_FIELDS.has(key) || key.startsWith("planner_") ? key : `planner_${key}`] = value;
+    }
+    return stamped;
+  });
+}
+var PLANNER_FIELD_DESCRIPTIONS = {
+  source: `Always "${PLANNER_SOURCE}". These rows are Keyword Planner ESTIMATES of total market search volume, NOT this account's data. Never report them as impressions, clicks or any account metric \u2014 read those from a query against the account.`,
+  keyword: "The keyword this estimate is for",
+  planner_avg_monthly_searches: "ESTIMATE: average monthly searches across the whole market (string), last 12 months",
+  planner_competition: "ESTIMATE: competition level \u2014 LOW, MEDIUM, HIGH",
+  planner_competition_index: "ESTIMATE: competition index 0-100 as string (higher = more competitive)",
+  planner_low_top_of_page_bid_micros: "ESTIMATE: low-range top-of-page CPC bid in micros (\xF7 1,000,000 for currency)",
+  planner_high_top_of_page_bid_micros: "ESTIMATE: high-range top-of-page CPC bid in micros (\xF7 1,000,000 for currency)",
+  planner_monthly_search_volumes: "ESTIMATE: monthly market search volume breakdown (array of {year, month, monthly_searches})"
+};
+
 // src/commands/ads/google/keywords/discover.ts
 registerSchema({
   command: "ads.google.keywords.discover",
-  description: "Discover keyword ideas from seed keywords or URLs. Returns { keywords, total_results, next_page_token? } with snake_case fields matching the Google Ads API. IMPORTANT: If --location and --language are omitted, defaults to United States (2840) and English (1000). The response includes a query_context object showing which location/language were used.",
+  description: 'Discover keyword ideas from seed keywords or URLs. Returns { source: "keyword_planner_estimate", keywords, total_results, next_page_token? }. THESE ARE ESTIMATES OF TOTAL MARKET SEARCH VOLUME, NOT THIS ACCOUNT\'S DATA: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Never report a planner_ number as impressions, clicks or any account metric \u2014 read those with `baker ads google query` against the account. IMPORTANT: If --location and --language are omitted, defaults to United States (2840) and English (1000). The response includes a query_context object showing which location/language were used.',
   args: {
     "customer-id": {
       type: "string",
@@ -10220,15 +10243,9 @@ registerSchema({
     "no-cache": { type: "boolean", description: "Skip cache", required: false }
   }
 });
-var KEYWORD_IDEA_FIELDS = {
-  keyword: "Suggested keyword text",
-  avg_monthly_searches: "Average monthly search volume (string)",
-  competition: "Competition level: LOW, MEDIUM, HIGH",
-  competition_index: "Competition index 0-100 as string (higher = more competitive)",
-  low_top_of_page_bid_micros: "Low-range CPC bid in micros (\xF7 1,000,000 for currency)",
-  high_top_of_page_bid_micros: "High-range CPC bid in micros (\xF7 1,000,000 for currency)",
-  monthly_search_volumes: "Monthly search volume breakdown (array of {year, month, monthly_searches})"
-};
+function stampDiscoverResponse(data) {
+  return { ...data, source: PLANNER_SOURCE, keywords: stampPlannerRows(data.keywords ?? []) };
+}
 function buildDiscoverBody(customerId, args) {
   const body = {
     customerId,
@@ -10269,6 +10286,8 @@ var discoverCommand = defineCommand23({
     name: "discover",
     description: `Discover new keyword ideas from seed keywords or competitor URLs.
 
+Returns Keyword Planner ESTIMATES of market search volume, not this account's numbers. Every row carries source=keyword_planner_estimate and planner_-prefixed metrics; keep those names when you quote a figure, and never present one as an impression or click count.
+
 Examples:
   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"
@@ -10303,7 +10322,7 @@ Examples:
       const cached = cacheGet("keywords", cacheKey);
       if (cached) {
         warnDefaults(queryContext);
-        writeAdsJson({ ok: true, data: cached.data, cached: true, query_context: queryContext });
+        writeAdsJson({ ok: true, data: stampDiscoverResponse(cached.data), cached: true, query_context: queryContext });
         return;
       }
     }
@@ -10313,12 +10332,13 @@ Examples:
         cacheSet("keywords", cacheKey, data, 24 * 60 * 60 * 1e3);
       }
       warnDefaults(queryContext);
+      const stamped = stampDiscoverResponse(data);
       const format = args.output || "json";
       if (format !== "json") {
-        writeAdsOutput(data.keywords, format);
+        writeAdsOutput(stamped.keywords, format);
         return;
       }
-      writeAdsJson({ ok: true, data, fields: KEYWORD_IDEA_FIELDS, query_context: queryContext });
+      writeAdsJson({ ok: true, data: stamped, fields: PLANNER_FIELD_DESCRIPTIONS, query_context: queryContext });
     } catch (err) {
       handleKeywordError(err);
     }
@@ -10371,7 +10391,7 @@ var locationsCommand = defineCommand25({
 import { defineCommand as defineCommand26 } from "citty";
 registerSchema({
   command: "ads.google.keywords.metrics",
-  description: "Get historical metrics for specific keywords. Returns { historical_metrics: [...] } with snake_case fields matching the Google Ads API. IMPORTANT: If --location and --language are omitted, defaults to United States (2840) and English (1000). The response includes a query_context object showing which location/language were used.",
+  description: 'Get historical market metrics for specific keywords. Returns { source: "keyword_planner_estimate", historical_metrics: [...] }. THESE ARE KEYWORD PLANNER ESTIMATES OF TOTAL MARKET SEARCH VOLUME, NOT THIS ACCOUNT\'S DATA: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Never report a planner_ number as impressions, clicks or any account metric \u2014 read those with `baker ads google query` against the account. IMPORTANT: If --location and --language are omitted, defaults to United States (2840) and English (1000). The response includes a query_context object showing which location/language were used.',
   args: {
     "customer-id": {
       type: "string",
@@ -10393,6 +10413,9 @@ registerSchema({
     "no-cache": { type: "boolean", description: "Skip cache", required: false }
   }
 });
+function stampMetricsResponse(data) {
+  return { ...data, source: PLANNER_SOURCE, historical_metrics: stampPlannerRows(data.historical_metrics ?? []) };
+}
 function handleMetricsError(err) {
   if (err instanceof ApiError) {
     if (isNotConnectedError(err.code, err.message)) {
@@ -10418,6 +10441,8 @@ var metricsCommand = defineCommand26({
     name: "metrics",
     description: `Get historical search metrics for specific keywords.
 
+Returns Keyword Planner ESTIMATES of market search volume, not this account's numbers. Every row carries source=keyword_planner_estimate and planner_-prefixed metrics; keep those names when you quote a figure, and never present one as an impression or click count.
+
 Examples:
   baker ads google keywords metrics --customer-id 1234567890 --keywords "running shoes,nike shoes,adidas shoes"
   baker ads google keywords metrics --customer-id 1234567890 --keywords "seo tools" --location 2826`
@@ -10454,7 +10479,7 @@ Examples:
       const cached = cacheGet("keywords", cacheKey);
       if (cached) {
         warnDefaults(queryContext);
-        writeAdsJson({ ok: true, data: cached.data, cached: true, query_context: queryContext });
+        writeAdsJson({ ok: true, data: stampMetricsResponse(cached.data), cached: true, query_context: queryContext });
         return;
       }
     }
@@ -10464,21 +10489,13 @@ Examples:
         cacheSet("keywords", cacheKey, data, 24 * 60 * 60 * 1e3);
       }
       warnDefaults(queryContext);
+      const stamped = stampMetricsResponse(data);
       const format = args.output || "json";
       if (format !== "json") {
-        writeAdsOutput(data.historical_metrics, format);
+        writeAdsOutput(stamped.historical_metrics, format);
         return;
       }
-      const fields = {
-        keyword: "The keyword analyzed",
-        avg_monthly_searches: "Average monthly search volume as string (last 12 months)",
-        competition: "Competition level: LOW, MEDIUM, HIGH",
-        competition_index: "Competition index 0-100 as string (higher = more competitive)",
-        low_top_of_page_bid_micros: "Low-range CPC bid in micros (\xF7 1,000,000 for currency)",
-        high_top_of_page_bid_micros: "High-range CPC bid in micros (\xF7 1,000,000 for currency)",
-        monthly_search_volumes: "Monthly search volume breakdown (array of {year, month, monthly_searches})"
-      };
-      writeAdsJson({ ok: true, data, fields, query_context: queryContext });
+      writeAdsJson({ ok: true, data: stamped, fields: PLANNER_FIELD_DESCRIPTIONS, query_context: queryContext });
     } catch (err) {
       handleMetricsError(err);
     }
@@ -10625,10 +10642,211 @@ function keywordServingWarnings(rows, options) {
   return renderKeywordLimits(collectKeywordLimits(rows, options));
 }
 
+// src/commands/ads/google/presets.ts
+var GAQL_DATE_RANGE_RE = /^(?:TODAY|YESTERDAY|LAST_7_DAYS|LAST_14_DAYS|LAST_30_DAYS|LAST_90_DAYS|THIS_MONTH|LAST_MONTH|THIS_QUARTER|LAST_QUARTER|THIS_YEAR|LAST_YEAR|ALL_TIME|BETWEEN\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}'\s+AND\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}')$/i;
+function isValidDateRange(value) {
+  return GAQL_DATE_RANGE_RE.test(value.trim());
+}
+var SERVING_CHAINS = {
+  keyword_view: ["campaign.status", "ad_group.status", "ad_group_criterion.status"],
+  ad_group_criterion: ["campaign.status", "ad_group.status", "ad_group_criterion.status"],
+  ad_group_ad: ["campaign.status", "ad_group.status", "ad_group_ad.status"],
+  search_term_view: ["campaign.status", "ad_group.status"],
+  ad_group: ["campaign.status", "ad_group.status"],
+  asset_group: ["campaign.status", "asset_group.status"],
+  asset_group_asset: ["campaign.status", "asset_group.status"]
+};
+var PRESETS = [
+  {
+    name: "campaign-performance",
+    description: "Campaign-level metrics overview",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value, metrics.ctr, metrics.average_cpc FROM campaign WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
+  },
+  {
+    name: "keyword-analysis",
+    description: "Keyword performance with match type and quality",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.id, ad_group.name, ad_group.status, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.quality_info.quality_score, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.ctr FROM keyword_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
+  },
+  {
+    name: "keyword-serving",
+    description: "Why a keyword is limited \u2014 Google Ads' 'Eligible (Limited) / Below first page bid' column, with the first-page bid estimate, the current max CPC and quality score",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.primary_status, ad_group_criterion.primary_status_reasons, ad_group_criterion.system_serving_status, ad_group_criterion.approval_status, ad_group_criterion.effective_cpc_bid_micros, ad_group_criterion.effective_cpc_bid_source, ad_group_criterion.position_estimates.first_page_cpc_micros, ad_group_criterion.position_estimates.top_of_page_cpc_micros, ad_group_criterion.quality_info.quality_score, ad_group_criterion.quality_info.creative_quality_score, ad_group_criterion.quality_info.post_click_quality_score, ad_group_criterion.quality_info.search_predicted_ctr FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = FALSE{statusScope} ORDER BY campaign.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500,
+    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
+  },
+  {
+    name: "positive-keywords",
+    description: "Positive (targeting) keywords only \u2014 excludes negatives",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.id, ad_group.name, ad_group.status, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.negative FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = FALSE{statusScope} ORDER BY campaign.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500,
+    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
+  },
+  {
+    name: "negative-keywords",
+    description: "Negative keywords only \u2014 campaign and ad group level",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.name, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.negative FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = TRUE AND campaign.status != 'REMOVED' ORDER BY campaign.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500
+  },
+  {
+    name: "negative-keyword-lists",
+    description: "Shared negative keyword lists and the terms inside them (SharedSet members)",
+    gaqlTemplate: `SELECT shared_set.id, shared_set.name, shared_criterion.keyword.text, shared_criterion.keyword.match_type FROM shared_criterion WHERE shared_set.type = 'NEGATIVE_KEYWORDS' AND shared_set.status = 'ENABLED' ORDER BY shared_set.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500
+  },
+  {
+    name: "negative-list-attachments",
+    description: "Which campaigns each shared negative keyword list is attached to",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, shared_set.id, shared_set.name FROM campaign_shared_set WHERE shared_set.type = 'NEGATIVE_KEYWORDS' AND campaign_shared_set.status = 'ENABLED' ORDER BY campaign.name LIMIT {limit}`,
+    defaultDateRange: "ALL_TIME",
+    defaultLimit: 500
+  },
+  {
+    name: "search-terms",
+    description: "Actual user search queries triggering ads",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.name, ad_group.status, search_term_view.search_term, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_7_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "ad_group.status"]
+  },
+  {
+    name: "ad-copy-performance",
+    description: "Ad headline and description effectiveness",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.status, ad_group_ad.status, ad_group_ad.ad.responsive_search_ad.headlines, ad_group_ad.ad.responsive_search_ad.descriptions, ad_group_ad.ad.final_urls, metrics.impressions, metrics.clicks, metrics.conversions, metrics.ctr FROM ad_group_ad WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "ad_group.status", "ad_group_ad.status"]
+  },
+  {
+    name: "asset-performance",
+    description: "Performance Max asset performance labels",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, asset_group.name, asset_group.status, asset_group_asset.field_type, asset_group_asset.performance_label, asset.type, asset.text_asset.text, asset.image_asset.full_size.url FROM asset_group_asset WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX' AND segments.date DURING {dateRange}{statusScope} LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status", "asset_group.status"]
+  },
+  {
+    name: "shopping-products",
+    description: "Product-level shopping performance metrics",
+    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, segments.product_title, segments.product_item_id, segments.product_brand, segments.product_type_l1, metrics.clicks, metrics.impressions, metrics.cost_micros, metrics.conversions FROM shopping_performance_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 200,
+    statusFields: ["campaign.status"]
+  },
+  {
+    name: "account-summary",
+    description: "Account-level totals for a date range",
+    gaqlTemplate: `SELECT customer.id, customer.descriptive_name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM customer WHERE segments.date DURING {dateRange} LIMIT 1`,
+    defaultDateRange: "LAST_30_DAYS",
+    defaultLimit: 1
+  }
+];
+function getPreset(name) {
+  return PRESETS.find((p) => p.name === name);
+}
+function buildStatusScope(statusFields, includePaused) {
+  if (!statusFields || statusFields.length === 0) return "";
+  const predicate = includePaused ? "!= 'REMOVED'" : "= 'ENABLED'";
+  return statusFields.map((field) => ` AND ${field} ${predicate}`).join("");
+}
+function expandPreset(preset, params) {
+  const dateRange = params.dateRange ?? preset.defaultDateRange;
+  const limit = params.limit ?? preset.defaultLimit;
+  if (!isValidDateRange(dateRange)) {
+    return {
+      query: "",
+      dateRangeError: `Invalid date range: "${dateRange}". Use a GAQL date literal (e.g. LAST_30_DAYS, TODAY) or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'.`
+    };
+  }
+  const statusScope = buildStatusScope(preset.statusFields, params.includePaused ?? false);
+  const query = preset.gaqlTemplate.replace(/\{dateRange\}/g, dateRange).replace(/\{limit\}/g, String(limit)).replace(/\{statusScope\}/g, statusScope);
+  return { query };
+}
+
 // src/commands/ads/google/preflight.ts
 function buildCommand2(query, customerId) {
   return `baker ads google query "${query}" --customer-id ${customerId}`;
 }
+var RUNG_PIN_FIELDS = {
+  "campaign.status": ["campaign.id", "campaign.resource_name"],
+  "ad_group.status": ["ad_group.id", "ad_group.resource_name"],
+  "ad_group_criterion.status": ["ad_group_criterion.criterion_id", "ad_group_criterion.resource_name"],
+  "ad_group_ad.status": ["ad_group_ad.ad.id", "ad_group_ad.resource_name"],
+  "asset_group.status": ["asset_group.id", "asset_group.resource_name"]
+};
+function whereClause(query) {
+  const match = query.match(/\bWHERE\b([\s\S]*)$/i);
+  if (!match?.[1]) return "";
+  let rest = match[1];
+  for (const trailing of [/\bORDER\s+BY\b/i, /\bLIMIT\b/i, /\bPARAMETERS\b/i]) {
+    const idx = rest.search(trailing);
+    if (idx !== -1) rest = rest.slice(0, idx);
+  }
+  return rest;
+}
+function selectClause(query) {
+  return query.split(/\bFROM\b/i)[0] ?? "";
+}
+function mentions(clause, field) {
+  return new RegExp(`(?<![\\w.])${field.replace(/\./g, "\\.")}\\b`, "i").test(clause);
+}
+function analyzeServingChain(query) {
+  const resource = fromResource(query);
+  const chain = resource ? SERVING_CHAINS[resource] : void 0;
+  if (!chain) return null;
+  const where = whereClause(query);
+  if (/ad_group_criterion\.negative\s*=\s*TRUE/i.test(where)) return null;
+  const unscoped = chain.filter((rung) => {
+    if (mentions(where, rung)) return false;
+    return !(RUNG_PIN_FIELDS[rung] ?? []).some((pin) => mentions(where, pin));
+  });
+  const assertsServing = chain.some(
+    (rung) => new RegExp(`${rung.replace(/\./g, "\\.")}\\s*=\\s*'ENABLED'`, "i").test(where)
+  );
+  return { chain, unscoped, assertsServing };
+}
+function rejectPartialChain(query, customerId, analysis) {
+  if (!analysis.assertsServing || analysis.unscoped.length === 0) return null;
+  const added = analysis.unscoped.map((rung) => `${rung} = 'ENABLED'`).join(" AND ");
+  const fixed = query.replace(/\bWHERE\b/i, `WHERE ${added} AND`);
+  return {
+    ok: false,
+    error: {
+      code: "INCOMPLETE_STATUS_CHAIN",
+      message: `This query filters on serving status but leaves ${analysis.unscoped.join(", ")} unscoped. Google Ads has no single serving flag \u2014 a row is live only when its whole chain (${analysis.chain.join(" \u2192 ")}) is ENABLED, so rows under a paused parent will come back looking live.`,
+      fix: {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand2(fixed, customerId),
+        explanation: `Add the missing rungs: ${added}. To look at paused entities on purpose, scope every rung explicitly instead (e.g. ${analysis.unscoped.map((rung) => `${rung} != 'REMOVED'`).join(" AND ")}), or use --preset ... --include-paused.`
+      },
+      retryable: false
+    }
+  };
+}
+function annotateUnscopedChain(query, analysis) {
+  if (analysis.assertsServing || analysis.unscoped.length === 0) return { query, warnings: [] };
+  const select = selectClause(query);
+  const missing = analysis.unscoped.filter((rung) => !mentions(select, rung));
+  if (missing.length === 0) return { query, warnings: [] };
+  return {
+    query: query.replace(/SELECT\s+/i, `SELECT ${missing.join(", ")}, `),
+    warnings: [
+      {
+        code: "SERVING_STATUS_ADDED",
+        message: `Added ${missing.join(", ")} to SELECT \u2014 this query does not scope ${analysis.unscoped.join(", ")}, so it returns paused-parent rows that are not serving. Read those columns before calling any row live; filter every rung = 'ENABLED' to get serving rows only.`
+      }
+    ]
+  };
+}
 var SINGLE_ROW_RESOURCES = ["customer"];
 function fromResource(query) {
   const match = query.match(/\bFROM\s+([A-Za-z_][A-Za-z0-9_]*)/i);
@@ -10641,10 +10859,10 @@ function isSingleRowRead(query) {
 }
 function addRequiredCampaignFields(query) {
   if (!/FROM\s+campaign_budget\b/i.test(query)) return { query, warnings: [] };
-  const whereClause2 = query.split(/\bWHERE\b/i)[1] ?? "";
-  const selectClause = query.split(/\bFROM\b/i)[0] ?? "";
-  const selectFields = new Set(selectClause.match(/campaign\.[\w.]+/g) ?? []);
-  const missing = [...new Set(whereClause2.match(/campaign\.[\w.]+/g) ?? [])].filter(
+  const whereClause3 = query.split(/\bWHERE\b/i)[1] ?? "";
+  const selectClause2 = query.split(/\bFROM\b/i)[0] ?? "";
+  const selectFields = new Set(selectClause2.match(/campaign\.[\w.]+/g) ?? []);
+  const missing = [...new Set(whereClause3.match(/campaign\.[\w.]+/g) ?? [])].filter(
     (field) => !selectFields.has(field)
   );
   if (missing.length === 0) return { query, warnings: [] };
@@ -10794,128 +11012,13 @@ function validatePreflight(query, customerId, limit) {
   }
   const { query: autoFixed, warnings: autoFixWarnings } = applyAutoFixes(corrected, limit);
   warnings.push(...autoFixWarnings);
-  return { valid: true, correctedQuery: autoFixed, warnings };
-}
-
-// src/commands/ads/google/presets.ts
-var GAQL_DATE_RANGE_RE = /^(?:TODAY|YESTERDAY|LAST_7_DAYS|LAST_14_DAYS|LAST_30_DAYS|LAST_90_DAYS|THIS_MONTH|LAST_MONTH|THIS_QUARTER|LAST_QUARTER|THIS_YEAR|LAST_YEAR|ALL_TIME|BETWEEN\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}'\s+AND\s+'[0-9]{4}-[0-9]{2}-[0-9]{2}')$/i;
-function isValidDateRange(value) {
-  return GAQL_DATE_RANGE_RE.test(value.trim());
-}
-var PRESETS = [
-  {
-    name: "campaign-performance",
-    description: "Campaign-level metrics overview",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value, metrics.ctr, metrics.average_cpc FROM campaign WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
-    defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200,
-    statusFields: ["campaign.status"]
-  },
-  {
-    name: "keyword-analysis",
-    description: "Keyword performance with match type and quality",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.id, ad_group.name, ad_group.status, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.quality_info.quality_score, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.ctr FROM keyword_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
-    defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200,
-    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
-  },
-  {
-    name: "keyword-serving",
-    description: "Why a keyword is limited \u2014 Google Ads' 'Eligible (Limited) / Below first page bid' column, with the first-page bid estimate, the current max CPC and quality score",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.primary_status, ad_group_criterion.primary_status_reasons, ad_group_criterion.system_serving_status, ad_group_criterion.approval_status, ad_group_criterion.effective_cpc_bid_micros, ad_group_criterion.effective_cpc_bid_source, ad_group_criterion.position_estimates.first_page_cpc_micros, ad_group_criterion.position_estimates.top_of_page_cpc_micros, ad_group_criterion.quality_info.quality_score, ad_group_criterion.quality_info.creative_quality_score, ad_group_criterion.quality_info.post_click_quality_score, ad_group_criterion.quality_info.search_predicted_ctr FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = FALSE{statusScope} ORDER BY campaign.name LIMIT {limit}`,
-    defaultDateRange: "ALL_TIME",
-    defaultLimit: 500,
-    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
-  },
-  {
-    name: "positive-keywords",
-    description: "Positive (targeting) keywords only \u2014 excludes negatives",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.id, ad_group.name, ad_group.status, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.negative FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = FALSE{statusScope} ORDER BY campaign.name LIMIT {limit}`,
-    defaultDateRange: "ALL_TIME",
-    defaultLimit: 500,
-    statusFields: ["campaign.status", "ad_group.status", "ad_group_criterion.status"]
-  },
-  {
-    name: "negative-keywords",
-    description: "Negative keywords only \u2014 campaign and ad group level",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, ad_group.name, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.negative FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.negative = TRUE AND campaign.status != 'REMOVED' ORDER BY campaign.name LIMIT {limit}`,
-    defaultDateRange: "ALL_TIME",
-    defaultLimit: 500
-  },
-  {
-    name: "negative-keyword-lists",
-    description: "Shared negative keyword lists and the terms inside them (SharedSet members)",
-    gaqlTemplate: `SELECT shared_set.id, shared_set.name, shared_criterion.keyword.text, shared_criterion.keyword.match_type FROM shared_criterion WHERE shared_set.type = 'NEGATIVE_KEYWORDS' AND shared_set.status = 'ENABLED' ORDER BY shared_set.name LIMIT {limit}`,
-    defaultDateRange: "ALL_TIME",
-    defaultLimit: 500
-  },
-  {
-    name: "negative-list-attachments",
-    description: "Which campaigns each shared negative keyword list is attached to",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, shared_set.id, shared_set.name FROM campaign_shared_set WHERE shared_set.type = 'NEGATIVE_KEYWORDS' AND campaign_shared_set.status = 'ENABLED' ORDER BY campaign.name LIMIT {limit}`,
-    defaultDateRange: "ALL_TIME",
-    defaultLimit: 500
-  },
-  {
-    name: "search-terms",
-    description: "Actual user search queries triggering ads",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.name, ad_group.status, search_term_view.search_term, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
-    defaultDateRange: "LAST_7_DAYS",
-    defaultLimit: 200,
-    statusFields: ["campaign.status", "ad_group.status"]
-  },
-  {
-    name: "ad-copy-performance",
-    description: "Ad headline and description effectiveness",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, ad_group.status, ad_group_ad.status, ad_group_ad.ad.responsive_search_ad.headlines, ad_group_ad.ad.responsive_search_ad.descriptions, ad_group_ad.ad.final_urls, metrics.impressions, metrics.clicks, metrics.conversions, metrics.ctr FROM ad_group_ad WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.impressions DESC LIMIT {limit}`,
-    defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200,
-    statusFields: ["campaign.status", "ad_group.status", "ad_group_ad.status"]
-  },
-  {
-    name: "asset-performance",
-    description: "Performance Max asset performance labels",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, asset_group.name, asset_group.status, asset_group_asset.field_type, asset_group_asset.performance_label, asset.type, asset.text_asset.text, asset.image_asset.full_size.url FROM asset_group_asset WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX' AND segments.date DURING {dateRange}{statusScope} LIMIT {limit}`,
-    defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200,
-    statusFields: ["campaign.status", "asset_group.status"]
-  },
-  {
-    name: "shopping-products",
-    description: "Product-level shopping performance metrics",
-    gaqlTemplate: `SELECT campaign.id, campaign.name, campaign.status, segments.product_title, segments.product_item_id, segments.product_brand, segments.product_type_l1, metrics.clicks, metrics.impressions, metrics.cost_micros, metrics.conversions FROM shopping_performance_view WHERE segments.date DURING {dateRange}{statusScope} ORDER BY metrics.cost_micros DESC LIMIT {limit}`,
-    defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 200,
-    statusFields: ["campaign.status"]
-  },
-  {
-    name: "account-summary",
-    description: "Account-level totals for a date range",
-    gaqlTemplate: `SELECT customer.id, customer.descriptive_name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM customer WHERE segments.date DURING {dateRange} LIMIT 1`,
-    defaultDateRange: "LAST_30_DAYS",
-    defaultLimit: 1
-  }
-];
-function getPreset(name) {
-  return PRESETS.find((p) => p.name === name);
-}
-function buildStatusScope(statusFields, includePaused) {
-  if (!statusFields || statusFields.length === 0) return "";
-  const predicate = includePaused ? "!= 'REMOVED'" : "= 'ENABLED'";
-  return statusFields.map((field) => ` AND ${field} ${predicate}`).join("");
-}
-function expandPreset(preset, params) {
-  const dateRange = params.dateRange ?? preset.defaultDateRange;
-  const limit = params.limit ?? preset.defaultLimit;
-  if (!isValidDateRange(dateRange)) {
-    return {
-      query: "",
-      dateRangeError: `Invalid date range: "${dateRange}". Use a GAQL date literal (e.g. LAST_30_DAYS, TODAY) or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'.`
-    };
-  }
-  const statusScope = buildStatusScope(preset.statusFields, params.includePaused ?? false);
-  const query = preset.gaqlTemplate.replace(/\{dateRange\}/g, dateRange).replace(/\{limit\}/g, String(limit)).replace(/\{statusScope\}/g, statusScope);
-  return { query };
+  const analysis = analyzeServingChain(autoFixed);
+  if (!analysis) return { valid: true, correctedQuery: autoFixed, warnings };
+  const rejection = rejectPartialChain(autoFixed, customerId, analysis);
+  if (rejection) return { valid: false, warnings: [], error: rejection };
+  const annotated = annotateUnscopedChain(autoFixed, analysis);
+  warnings.push(...annotated.warnings);
+  return { valid: true, correctedQuery: annotated.query, warnings };
 }
 
 // src/commands/ads/google/query.ts
@@ -10944,12 +11047,17 @@ registerSchema({
       description: "Include paused entities in preset results. Off by default: presets return only actually-serving entities. Google Ads has no single serving flag \u2014 an entity serves only when its whole chain (campaign, ad group, ad) is ENABLED, so recommendations should target serving entities unless the user asks about paused ones.",
       required: false
     },
-    limit: { type: "number", description: "Max rows (default 200)", required: false, default: 200 },
+    limit: {
+      type: "number",
+      description: "Max rows in ONE page (default 200), AND the LIMIT added to a query that has none \u2014 so it caps the whole read with --all too. Values up to 10000 are accepted. Any read that fills this cap comes back flagged TRUNCATED_RESULTS \u2014 never count or total from one.",
+      required: false,
+      default: 200
+    },
     "list-presets": { type: "boolean", description: "List all available query presets", required: false },
     cursor: { type: "string", description: "Pagination cursor from previous response", required: false },
     all: {
       type: "boolean",
-      description: "Auto-paginate all results (use with --out for large datasets)",
+      description: "Follow every page until the data set is exhausted (use with --out for large datasets). Needed for a read you may count or total, but not sufficient: it exhausts the pages, not the statement's LIMIT, so pair it with a --limit above the row count you expect (or your own LIMIT) and check the read came back without TRUNCATED_RESULTS.",
       required: false
     },
     out: {
@@ -11004,53 +11112,117 @@ function writeRowsToFile(filePath, rows, fields, append) {
     writeFileSync(filePath, JSON.stringify(rows, null, 2), "utf-8");
   }
 }
+function effectiveRowLimit(finalQuery, limit, all = false) {
+  const match = finalQuery.match(/\bLIMIT\s+(\d+)/i);
+  const statementLimit = match?.[1] ? Number(match[1]) : void 0;
+  if (all) return statementLimit;
+  return statementLimit === void 0 ? limit : Math.min(limit, statementLimit);
+}
+function warningLines(warnings, format) {
+  return warnings.map((w) => {
+    const message = w.message.replace(/\s*\n\s*/g, " ");
+    if (format === "jsonl") return JSON.stringify({ _baker_warning: { code: w.code, message } });
+    if (format === "md") return `> **${w.code}** \u2014 ${message}`;
+    return `# baker ${w.code}: ${message}`;
+  });
+}
+function completenessWarnings(read) {
+  const cap3 = read.effectiveLimit;
+  const filledTheCap = cap3 !== void 0 && cap3 > 0 && read.rowCount >= cap3;
+  if (!read.hasMore && !filledTheCap) return [];
+  const cause = read.hasMore ? `More rows are waiting: the account returned a next-page cursor this run did not follow.` : `The ${read.rowCount} rows returned exactly fill the row cap in force (${cap3}).`;
+  const fix = read.all ? `Every page was followed, so the cap is the LIMIT in the statement itself \u2014 raise it above ${cap3}, or drop it and pass a larger --limit, then re-run.` : `Re-run with --all --out <file> to page through everything, or raise --limit above ${cap3}.`;
+  return [
+    {
+      code: "TRUNCATED_RESULTS",
+      message: `INCOMPLETE READ \u2014 ${cause} These rows are a page, not the data set. Do NOT count, total or describe them as the whole picture. ${fix}`
+    }
+  ];
+}
 function buildQueryEnvelope(rows, fieldDescs, warnings, options) {
-  const envelope = { ok: true, data: rows };
-  if (options.full && Object.keys(fieldDescs).length > 0) {
-    envelope.fields = fieldDescs;
-  }
-  if (options.nextCursor) {
-    envelope.pagination = { hasMore: true, cursor: options.nextCursor };
-  }
-  if (warnings.length > 0) {
-    envelope.warnings = warnings;
-  }
-  if (options.cached) {
-    envelope.cached = true;
-  }
-  return envelope;
+  const notice = summariseWarnings(warnings);
+  return {
+    ok: true,
+    ...options.cached ? { cached: true } : {},
+    ...warnings.length > 0 ? { warnings } : {},
+    ...options.nextCursor ? { pagination: { hasMore: true, cursor: options.nextCursor } } : {},
+    data: rows,
+    ...options.full && Object.keys(fieldDescs).length > 0 ? { fields: fieldDescs } : {},
+    ...notice ? { notice } : {}
+  };
 }
-function outputResults(rows, fieldDescs, warnings, args, cached, nextCursor) {
-  const format = args.output || "json";
-  const fields = Object.keys(rows[0] ?? {});
-  if (format === "csv") {
-    process.stdout.write(`${toCsvRow(fields)}
-`);
-    for (const row of rows) {
-      process.stdout.write(`${toCsvRow(fields.map((f) => String(row[f] ?? "")))}
+function summariseWarnings(warnings) {
+  if (warnings.length === 0) return void 0;
+  const codes = [...new Set(warnings.map((w) => w.code))].join(", ");
+  return `Read the "warnings" above before using these rows: ${codes}.`;
+}
+function buildFileSummary(input) {
+  const notice = summariseWarnings(input.warnings);
+  return {
+    ok: true,
+    fields: {},
+    file: input.file,
+    rows: input.rows,
+    complete: input.complete,
+    ...input.warnings.length > 0 ? { warnings: input.warnings } : {},
+    ...notice ? { notice } : {}
+  };
+}
+var REPEAT_NOTICE_ABOVE_ROWS = 20;
+function emitToStderr(notices) {
+  for (const line of notices) process.stderr.write(`${line}
 `);
-    }
-    return;
-  }
-  if (format === "jsonl") {
-    for (const row of rows) {
-      process.stdout.write(`${JSON.stringify(row)}
+}
+function writeLine(line) {
+  process.stdout.write(`${line}
 `);
-    }
-    return;
+}
+var writeCsvRows = (rows, fields, notices) => {
+  writeLine(toCsvRow(fields));
+  for (const line of notices) writeLine(line);
+  for (const row of rows) writeLine(toCsvRow(fields.map((f) => String(row[f] ?? ""))));
+};
+var writeJsonlRows = (rows, _fields, notices) => {
+  for (const line of notices) writeLine(line);
+  for (const row of rows) writeLine(JSON.stringify(row));
+};
+var writeMdRows = (rows, fields, notices) => {
+  for (const line of notices) writeLine(line);
+  writeLine(`| ${fields.join(" | ")} |`);
+  writeLine(`| ${fields.map(() => "---").join(" | ")} |`);
+  for (const row of rows) writeLine(`| ${fields.map((f) => String(row[f] ?? "")).join(" | ")} |`);
+};
+var ROW_WRITERS = { csv: writeCsvRows, jsonl: writeJsonlRows, md: writeMdRows };
+function writeRows(format, rows, notices) {
+  const write2 = ROW_WRITERS[format] ?? writeMdRows;
+  write2(rows, Object.keys(rows[0] ?? {}), notices);
+  if (rows.length > REPEAT_NOTICE_ABOVE_ROWS) {
+    for (const line of notices) writeLine(line);
   }
-  if (format === "md") {
-    process.stdout.write(`| ${fields.join(" | ")} |
-`);
-    process.stdout.write(`| ${fields.map(() => "---").join(" | ")} |
-`);
-    for (const row of rows) {
-      process.stdout.write(`| ${fields.map((f) => String(row[f] ?? "")).join(" | ")} |
-`);
-    }
+}
+function outputResults(rows, fieldDescs, warnings, args, cached, read) {
+  const format = args.output || "json";
+  const allWarnings = [
+    ...warnings,
+    ...completenessWarnings({
+      rowCount: rows.length,
+      effectiveLimit: read.effectiveLimit,
+      all: read.all,
+      hasMore: Boolean(read.nextCursor)
+    })
+  ];
+  emitToStderr(warningLines(allWarnings, "csv"));
+  if (format === "json") {
+    writeAdsJson(
+      buildQueryEnvelope(rows, fieldDescs, allWarnings, {
+        full: Boolean(args.full),
+        cached,
+        nextCursor: read.nextCursor
+      })
+    );
     return;
   }
-  writeAdsJson(buildQueryEnvelope(rows, fieldDescs, warnings, { full: Boolean(args.full), cached, nextCursor }));
+  writeRows(format, rows, warningLines(allWarnings, format));
 }
 function resolveGaql(args, limit) {
   if (args.preset) {
@@ -11099,8 +11271,8 @@ var SERVING_HIERARCHY_RESOURCES = [
   "search_term_view",
   "shopping_performance_view",
   "asset_group_asset"
-];
-function whereClause(upperQuery) {
+].filter((resource) => !(resource in SERVING_CHAINS));
+function whereClause2(upperQuery) {
   const whereIdx = upperQuery.indexOf(" WHERE ");
   if (whereIdx === -1) return "";
   let rest = upperQuery.slice(whereIdx + 7);
@@ -11124,7 +11296,7 @@ function servingScopeWarnings(args, finalQuery) {
   const fromMatch = upper2.match(/\bFROM\s+([A-Z_]+)/);
   const resource = fromMatch?.[1]?.toLowerCase();
   const hierarchical = resource ? SERVING_HIERARCHY_RESOURCES.includes(resource) : false;
-  const filtersStatus = whereClause(upper2).includes(".STATUS");
+  const filtersStatus = whereClause2(upper2).includes(".STATUS");
   if (hierarchical && !filtersStatus) {
     return [
       {
@@ -11141,11 +11313,12 @@ function parseSelectedFields(gaql) {
   if (!list) return [];
   return list.split(",").map((field) => field.trim()).filter((field) => /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)*$/.test(field));
 }
-function unobservedSelectedFields(gaql, rows) {
-  const observed = /* @__PURE__ */ new Set();
+function foldObservedFields(rows, observed) {
   for (const row of rows) {
     for (const key of Object.keys(row)) observed.add(key);
   }
+}
+function unobservedFields(gaql, observed) {
   return parseSelectedFields(gaql).filter((field) => {
     if (field.endsWith(".resource_name")) return false;
     if (observed.has(field)) return false;
@@ -11153,8 +11326,13 @@ function unobservedSelectedFields(gaql, rows) {
   });
 }
 function missingFieldWarnings(gaql, rows) {
-  if (rows.length === 0) return [];
-  const missing = unobservedSelectedFields(gaql, rows);
+  const observed = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, observed);
+  return missingFieldWarningsFor(gaql, observed, rows.length);
+}
+function missingFieldWarningsFor(gaql, observed, rowCount2) {
+  if (rowCount2 === 0) return [];
+  const missing = unobservedFields(gaql, observed);
   if (missing.length === 0) return [];
   return [
     {
@@ -11171,6 +11349,7 @@ async function fetchAllPages(body, args, servingOptions) {
   let pageToken = args.cursor;
   let totalRowsWritten = 0;
   let keywordLimits;
+  const observedFields = /* @__PURE__ */ new Set();
   do {
     const requestBody2 = { ...body };
     if (pageToken) requestBody2.pageToken = pageToken;
@@ -11178,11 +11357,11 @@ async function fetchAllPages(body, args, servingOptions) {
     const rows = response.rows ?? [];
     pageToken = response.pageToken;
     if (args.out) {
-      const filePath = resolve(args.out);
       const shouldAppend = args.append || totalRowsWritten > 0;
-      writeRowsToFile(filePath, rows, extractFields(rows), shouldAppend);
+      writeRowsToFile(resolve(args.out), rows, extractFields(rows), shouldAppend);
       totalRowsWritten += rows.length;
       keywordLimits = collectKeywordLimits(rows, servingOptions, keywordLimits);
+      foldObservedFields(rows, observedFields);
     } else {
       allRows = allRows.concat(rows);
     }
@@ -11192,7 +11371,8 @@ async function fetchAllPages(body, args, servingOptions) {
     allRows,
     lastPageToken: pageToken,
     totalRowsWritten,
-    keywordLimits: keywordLimits ?? collectKeywordLimits([], servingOptions)
+    keywordLimits: keywordLimits ?? collectKeywordLimits([], servingOptions),
+    observedFields
   };
 }
 async function executeQuery(finalQuery, args, customerId, limit, warnings, useCache, cacheKey) {
@@ -11202,12 +11382,33 @@ async function executeQuery(finalQuery, args, customerId, limit, warnings, useCa
   if (args.cursor) body.pageToken = args.cursor;
   if (!useCache) body.skipCache = true;
   const servingOptions = keywordServingOptions(finalQuery);
-  const { allRows, lastPageToken, totalRowsWritten, keywordLimits } = await fetchAllPages(body, args, servingOptions);
+  const { allRows, lastPageToken, totalRowsWritten, keywordLimits, observedFields } = await fetchAllPages(
+    body,
+    args,
+    servingOptions
+  );
   if (args.out) {
-    const summary = { ok: true, fields: {}, file: resolve(args.out), rows: totalRowsWritten };
-    const limitWarnings = renderKeywordLimits(keywordLimits);
-    if (limitWarnings.length > 0) summary.warnings = limitWarnings;
-    writeAdsJson(summary);
+    const truncation = completenessWarnings({
+      rowCount: totalRowsWritten,
+      effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args.all)),
+      all: Boolean(args.all),
+      hasMore: Boolean(lastPageToken)
+    });
+    const fileWarnings = [
+      ...warnings,
+      ...renderKeywordLimits(keywordLimits),
+      ...missingFieldWarningsFor(finalQuery, observedFields, totalRowsWritten),
+      ...truncation
+    ];
+    emitToStderr(warningLines(fileWarnings, "csv"));
+    writeAdsJson(
+      buildFileSummary({
+        file: resolve(args.out),
+        rows: totalRowsWritten,
+        warnings: fileWarnings,
+        complete: truncation.length === 0
+      })
+    );
     return;
   }
   if (useCache && allRows.length > 0) {
@@ -11221,9 +11422,16 @@ async function executeQuery(finalQuery, args, customerId, limit, warnings, useCa
     [...warnings, ...missingFieldWarnings(finalQuery, allRows), ...keywordServingWarnings(allRows, servingOptions)],
     args,
     false,
-    lastPageToken
+    {
+      effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args.all)),
+      all: Boolean(args.all),
+      nextCursor: lastPageToken
+    }
   );
 }
+function shouldReadCache(args) {
+  return !args["no-cache"] && !args.out;
+}
 async function validateArgs(args) {
   const customerId = await resolveCustomerId(args);
   const limit = args.limit ? Number(args.limit) : 200;
@@ -11286,10 +11494,14 @@ Examples:
       description: "Include paused entities in preset results (default: serving entities only)",
       required: false
     },
-    limit: { type: "string", description: "Max rows (default 200)", required: false },
+    limit: {
+      type: "string",
+      description: "Max rows in one page (default 200); without --all the read stops there",
+      required: false
+    },
     "list-presets": { type: "boolean", description: "List available presets", required: false },
     cursor: { type: "string", description: "Pagination cursor", required: false },
-    all: { type: "boolean", description: "Auto-paginate all results", required: false },
+    all: { type: "boolean", description: "Follow every page (use with --out for large datasets)", required: false },
     out: { type: "string", description: "File path for output", required: false },
     append: { type: "boolean", description: "Append to file", required: false },
     output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
@@ -11313,7 +11525,7 @@ Examples:
     const validated = await validateArgs(args);
     if (!validated) return;
     const { customerId, limit, finalQuery, warnings, useCache, cacheKey } = validated;
-    if (useCache) {
+    if (shouldReadCache(args)) {
       const cached = cacheGet("queries", cacheKey);
       if (cached) {
         const fields = extractFields(cached.data);
@@ -11326,7 +11538,8 @@ Examples:
             ...keywordServingWarnings(cached.data, keywordServingOptions(finalQuery))
           ],
           args,
-          true
+          true,
+          { effectiveLimit: effectiveRowLimit(finalQuery, limit, Boolean(args.all)), all: Boolean(args.all) }
         );
         return;
       }
@@ -13402,9 +13615,16 @@ var customerIdArg = { "customer-id": { type: "string", description: "10-digit Go
 var fileArg = {
   file: { type: "string", description: "JSON file with the full op payload (flags override)" }
 };
+var BUDGET_DEMAND_HINTS = [
+  "Check this daily budget against the search volume you measured for these keywords, not against the plan you had before you measured it. A budget many times larger than the traffic the target pool can absorb never spends, and reads to the client as a number nobody costed.",
+  "No volume measured yet? Pull it first \u2014 `baker ads google query --preset search-terms` for what the account already captures, `baker ads google keywords metrics` for the market estimate (those are planner figures, never account performance)."
+];
 var budgetsCommand = defineCommand30({
   meta: { name: "budgets", description: "Stage campaign budget create/update" },
   subCommands: {
+    // Fires where the budget is actually set, rather than on whatever the chat happened to stage
+    // first. A budget several times what the target pool can absorb never spends, and reads to the
+    // client as a plan nobody costed.
     create: defineCommand30({
       meta: { name: "create", description: "Stage a campaign budget" },
       args: {
@@ -13423,7 +13643,7 @@ var budgetsCommand = defineCommand30({
           deliveryMethod: args.delivery,
           explicitlyShared: args.shared || void 0
         });
-        await stageCreate("google.budget.create", customerId, payload);
+        await stageCreate("google.budget.create", customerId, payload, BUDGET_DEMAND_HINTS);
       }
     }),
     update: defineCommand30({
@@ -13443,7 +13663,7 @@ var budgetsCommand = defineCommand30({
           amountMicros: microsFlag(args.amount, "--amount"),
           deliveryMethod: args.delivery
         });
-        await stageUpdate("google.budget.update", customerId, target, payload);
+        await stageUpdate("google.budget.update", customerId, target, payload, BUDGET_DEMAND_HINTS);
       }
     })
   }