@koda-sl/baker-cli 0.477.0-dev.55c09e3e8 → 0.495.0-dev.c2b64ccca

package/README.md

@@ -1972,15 +1972,21 @@ Ads start from what customers said. Three commands carry the process; the agent
 ```bash
 baker creatives brief [--adset <id>] [--account-id act_<id>] [--no-research]   # one read: viewer, account bottleneck, what works, taste, customer quotes, ideas on file
 baker creatives ideas [--full]                                 # check and rank src/creatives/_ideas/*.md; build_next
-baker creatives make <idea> [--slug <s>] [--adset <id>] [--reference <adId> [--platform meta|linkedin|tiktok|google]] [--spec <beats.json>] [--from-idea] [--series <lead>]
+baker creatives make <idea> [--slug <s>] [--adset <id>] [--reference <adId> [--platform meta|linkedin|tiktok|google]] [--avatar <handle>] [--spec <beats.json>] [--from-idea] [--series <lead>]
 baker creatives translate --slug <ad> --to es-MX,es-CO,pt-BR [--copy-file <json>] [--note "<brief>"] [--again]   # the same ad in other languages, one design
 baker creatives learn [--days <n>] [--dry-run]                 # what each idea's ads did, written back onto the idea
+baker creatives rules list [--kind static|video] [--product <slug>] [--all]   # the company's standing rules for every ad
+baker creatives rules add --candidate <rc-…> | --text "<rule>" --strength never|must|prefer --applies <what> …   # a rule the person agreed to
+baker creatives rules retire <id> [--by <id>|BRAND.md]
+baker creatives check [--slug <s>]                             # which ads already made break a rule now in force
 ```
 
+- **Creative rules.** Every step of an ad reads one company (`engine/creative-context`): its reading of COMPANY.md (cached per edit), its BRAND.md (name, fonts, colours, voice, imagery, logo usage) and the rules that hold for the ad: BRAND.md's own (read by `google/gemini-3.5-flash`, cached per BRAND.md edit) and the ones a person taught, one file each in `src/content/creative-rules/`. Rules are read when a call runs, never copied into an ad's files; the compiled prompts carry them in a `<company_rules>` block the source fingerprint leaves out, so a rule edit re-renders on the next run and marks nothing stale. A never or a must is held before anything renders on the ad's words (`rule_broken`: whole phrases, accents, case and spacing folded, in the rule's language) and on its cast (`cast_not_decided` for an Avatar made for a role under a rule that only real people appear), and after on the finished ad: the rules a person taught are checked on a static's sizes and a video's frames by a vision model (each blocking break given a second look), and a video's voice, sound and subtitle rules by the watch pass. BRAND.md's rules are told to every render and its banned words are checked, but they never block a finished ad by eye. An ad departs from a rule only through `waive` in its prompt.json, which the source fingerprint covers; a rule three ads waive is flagged to retire. `feedback record` drafts the rules a rejection's words state for every ad (`ruleCandidates`, only where the words say it holds beyond this ad) and names reasons repeated across ads; `rules add` saves one only once the person agreed, after checking it duplicates and contradicts none of theirs, catches the version it came from and blocks none they approved. Each run record names the rules it was made against (`rules: { digest, ids }`). A correction (`--fix`, the spec repair) also reads the creative's case file: every rejection on it, in the person's words.
+
 - `brief` returns a verdict, not raw numbers: `account.bottleneck` is `hook`, `after_click`, `none` or `too_little_data`. A part that cannot be read says `unavailable`; the market searches (the followed brands, and the library for what COMPANY.md's first line says the company sells, in a few words) run at once and get 12 seconds, so a slow ad library leaves them out rather than holding the brief. With few customer quotes on file it runs `research customers` itself alongside the reads (about 30 s) and returns what it wrote; `--no-research` skips that. With no ideas on file, its hint lists the values `awareness`, `angle` and `format` take. `market` says what competitors' ads already say (the followed brands, else the library), how sophisticated the market is, and which awareness stages nobody speaks to.
 - `ideas` is local and nearly free: two readings of the words go to the decision model (a fraction of a cent, billed with the workspace's next run, answers kept in `canvas/.cache/`). An insight filed as `observed` reads as `interpreted` when its source cannot be opened or its quote is a statistic about people rather than someone's words ("39% de los propietarios…"), and a new idea is warned when its message says what a failed idea said, however reworded or translated. Without an answer, an insight keeps its status and only the same words count as the same message. An idea's `evidence` resolves to `src/content/insights/` entries, or it is an `explore` bet. Numbers must be in the Knowledge or our own customers' quotes (a Reddit, forum or web quote never sources a claim), no two ideas may share an angle and format, and a review or testimonial format needs a quote from our own customer.
 - `learn` pools each built idea's creatives, judges them against the rest of the account's cost per result and writes `status` (`winner`, `failed`, `inconclusive`, `testing`) and a frozen `result` onto the idea. `ideas` then warns when a new idea repeats a failed one.
-- `make` builds one idea, on a proven winning ad whenever one fits. A static searches the idea's container on the idea's message for our viewer, then for the container's strongest winners from any category (no query, by winner score), pools the candidates (each ad once, the better search first), checks up to six with `winning-ads fit`, three at a time (the next only once one does not fit), and keeps the best-ranked one that fits as soon as it and every better one have answered. The fit says what made that ad a winner, so what the creative carries of it (`reference.carry`: `whole_ad`, `layout`, `hook` or `angle`); make seeds it into `prompt.json` as `concept`, the canvas keeps the ad as its `original` node, and the renders see it for its structure only at `whole_ad` or `layout`. The first hint names the ad and what it carries (for a `--reference` chosen by hand, only the ad: nothing checked what made it win); if the concept could not be written into `prompt.json`, a hint says so and how to write it from the fit already made. For a new creative it starts scaffolding the best-ranked one while the fits are asked (kept when it fits, stopped and removed whole when another or none is kept). Finding, checking and describing a reference gets 150 seconds; past that the build is stopped and the static starts from the idea (`REFERENCE_SLOW`). A creative whose ad is already written is never built over (`ALREADY_MADE`): edit its `prompt.json`, or pass `--slug` for another ad of the same idea. A video idea takes its beats spec. Either way it records the idea on `_definition.md`, writes a `## Thinking` outline into its body (open `[TODO: …]` questions, seeded with the fit's read: what the reference is and why it won, or why the bet should work; whether it fits the viewer; our hook; the angle and the call to action; who appears; what must survive; the plan), sets `prompt.json`'s `message` and syncs the definition. `canvas run` and `canvas validate` refuse to render while a thinking question is open (`definition_not_thought`), so the definition is thought before the ad is written; a creative made before the outline existed is never asked. Drafted copy lines claiming a figure the company never wrote come back first in `hints`. Only when no proven ad fits (or with `--from-idea`) does a static start from the idea itself, and the first hint says why (none in the container, what the ones checked won on that the company lacks, the time ran out, or the proven ad it picked could not be read; a `--reference` chosen by hand that cannot be read fails instead): `prompt.json` holds the message and placeholders, and `canvas run` refuses to render until the scene and copy are written.
+- `make` builds one idea, on a proven winning ad whenever one fits. A static first reads a reference brief: one small model (`google/gemini-3.5-flash-lite`, about a second, cached per company notes and idea under `canvas/.cache/reference-brief/`) reads COMPANY.md and the idea and says what this ad sells, its industry and its people in the plain English the library files ads under, the market it runs in, who buys (consumer, small business, enterprise), whether the brand jokes (these and its own brand names from the company's reading, read once per COMPANY.md), what its rules forbid (its never-rules), and up to four wider searches, closest first (an adjacent product the same buyer weighs, the same buyer buying something else, the same kind of decision: for a padel-court builder, tennis courts, sports club owners, turnkey business investment). Without an answer it falls back to COMPANY.md's first line, its market line (English, Spanish, French, German or Italian) and the persona. It then searches for ads of what this ad sells, in its market and then anywhere, first in the idea's container for our viewer and then in any static container; then ads made for the same people whatever they sell; then the wider searches; then ads of the broader industry; then the idea's message; then the container's strongest winners from any category (no query, by winner score), in the market and then anywhere (a search that fails is asked once more; when every search for this ad's topic fails, the library's browse of any category's winners is never built on: the static starts from the idea, `REFERENCE_SEARCH_UNAVAILABLE`, and make can be run again later). It pools the candidates (one ad per brand, the better search first, ads whose run barely proves them after the proven ones, the company's own ads left out), reads up to 24 of them against the ad being made with the decision model (made for our kind of buyer? would our viewer see themselves in it? could our brand run something like it?) and checks the best six in that order, checks up to six with `winning-ads fit`, three at a time, each judged for the ad being made (the idea's persona from the Knowledge, its message, awareness, angle and the customers' words it cites; a reference the fit says our viewer would scroll past does not fit, and a fit made for one idea is never reused for another) (the next only once one does not fit), and, when more than one fits, looks at all of them side by side for the viewer (`~google/gemini-pro-latest`, one call) and keeps the one it prefers, saying why (`reference.chosen_because`, also in the first hint and the thinking's first read). The same look says, as a media buyer would, which element our ad takes from which of them (the hook, the visual, who appears, the proof, the layout, the call to action) and what it must not copy (a fake news page, dated urgency, another brand's marks); every picture is saved under `canvas/references/` and the thinking lays them out as a question to settle; measured on 14 production companies, judged blind by another model, the reference kept went from 5.0 to 6.9 out of 10. The fit says what made that ad a winner, so what the creative carries of it (`reference.carry`: `whole_ad`, `layout`, `hook` or `angle`); make seeds it into `prompt.json` as `concept`, the canvas keeps the ad as its `original` node, and the renders see it for its structure only at `whole_ad` or `layout`. The first hint names the ad and what it carries (for a `--reference` chosen by hand, only the ad: nothing checked what made it win); if the concept could not be written into `prompt.json`, a hint says so and how to write it from the fit already made. For a new creative it starts scaffolding the best-ranked one while the fits are asked (kept when it fits, stopped and removed whole when another or none is kept). Finding, checking and describing a reference gets 150 seconds; past that the build is stopped and the static starts from the idea (`REFERENCE_SLOW`). A creative whose ad is already written is never built over (`ALREADY_MADE`): edit its `prompt.json`, or pass `--slug` for another ad of the same idea. A video idea takes its beats spec. Either way it records the idea on `_definition.md`, saves a proven ad's picture under `canvas/references/`, writes a `## Thinking` outline into its body (open `[TODO: …]` questions, the first sending the agent to that picture, seeded with the fit's read: what the reference is and why it won, or why the bet should work; whether it fits the viewer; our hook; the angle and the call to action; who appears and what we show, listing what the company has: its ready Avatars (real people and ones made for a role), up to three customers' own words for this message from the testimonials, how to make the founder's Avatar, where to get product pictures, and its logos, and closing with three decision lines, `- Cast:`, `- Product shown:`, `- Logo:`; what must survive; the plan, which settles the format when the proven ad's container differs from the idea's), sets `prompt.json`'s `message` and `viewer.who` (the idea's persona, title and segment, never a placeholder: the image prompt, the casting check and the viewer check read it) and syncs the definition. `canvas run` and `canvas validate` refuse to render while a thinking question is open (`definition_not_thought`), so the definition is thought before the ad is written; a creative made before the outline existed is never asked. They also refuse a cast that is not ours (`cast_not_decided`): the cast must be an Avatar (`@handle`), a real customer, real footage or nobody, the product a library picture, a capture, a Hyperframe, footage or none, the logo a brand file or none; and on a static, an Avatar cast must be one `prompt.json` grounds a person on. `--avatar <handle>` (`@eduard` or `eduard,lucia`) casts the ad's people as those Avatars: run again with it once the thinking decides, before `prompt.json` is written; it rebuilds the canvas and keeps the thinking. Drafted copy lines claiming a figure the company never wrote come back first in `hints`. Only when no proven ad fits (or with `--from-idea`) does a static start from the idea itself, and the first hint says why (none in the container, what the ones checked won on that the company lacks, the time ran out, or the proven ad it picked could not be read; a `--reference` chosen by hand that cannot be read fails instead): `prompt.json` holds the message and placeholders, and `canvas run` refuses to render until the scene and copy are written.
 - `make --series <lead>` makes a static idea as another ad of a series: several messages in one style. Nothing is searched or rendered; the ad's `_definition.md` names its lead (`series: <lead>`), its `prompt.json` starts as the lead's ready version with the idea's message, and only its `copy` is written. Its canvas is written from the lead's on every run: the lead's finished picture with this ad's words, every other size the lead's own size with the same words. `baker canvas run --series <lead>` renders every ad of the series at once, one reviewed and corrected run each, skipping an ad already ready from the lead's current version.
 - `translate --slug <ad> --to <langs>` makes the ad in other languages as ads of the series it leads: one creative per language or country variant, `<ad>-<lang>` (the BCP-47 tag in lowercase: `-es-mx`), whose `_definition.md` says `series: <ad>` and `language: <lang>` (canonical case, `es-MX`, as the spec's market and the dashboard store it; tags are compared without case) and whose `prompt.json` is the ad's as last drawn with its words translated. Every language is translated in one text call (transcreated, each regional tag in that country's own variety and form of address, `es-MX` and `es-CO` two ads, each line keeping its role and about its length, brand names, prices and numbers kept, a customer's quote and the name on it never translated, and the ad's `message` translated with the lines; the spend is billed with the workspace's next run), or read from `--copy-file`: `{"<lang>": ["line 1", …]}` is every line with no model call, `{"<lang>": {"headline": "…", "3": "…"}}` only the lines given (by role or number), the model writing the rest. `--note` is the agent's brief for the translator (tone, form of address, terms to keep). Each made language lists the lines it `kept` as a customer said them, and the answer warns when the ad's `prompt.json` changed after its last render, since translations are made from the version rendered. The ad may itself be an ad of a series (an angle ad), so angles × languages stay one design. A language already made is left as it is, so adding one later re-renders nothing; `--again` translates it again. Then `baker canvas run --series <ad>` renders them; a new version of the ad reaches every language on the next `--series` run.
 

package/dist/account-5VPZ3XQ3.js

@@ -0,0 +1,79 @@
+import {
+  csvOrJson,
+  handleLinkedinError,
+  resolveAccountIdArg
+} from "./chunk-NG2DMLU6.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-OTNGMKI6.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-ELNN4SNW.js";
+import "./chunk-MV2J73HP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-I2DNBEV6.js";
+import {
+  apiGet
+} from "./chunk-OSWCEDFE.js";
+import "./chunk-D53AAUG4.js";
+import "./chunk-FZKUUI3F.js";
+import "./chunk-4WYEGE4N.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/linkedin/account.ts
+import { defineCommand } from "citty";
+var accountDetailCommand = defineCommand({
+  meta: {
+    name: "detail",
+    description: `Single LinkedIn ad account detail (currency, status, type).
+
+Examples:
+  baker ads linkedin account --account-id 503001492
+  baker ads linkedin account --account-urn urn:li:sponsoredAccount:503001492 --output md`
+  },
+  args: {
+    "account-id": { type: "string", description: "Numeric account ID or urn:li:sponsoredAccount:N" },
+    "account-urn": { type: "string", description: "Alias for --account-id" },
+    "no-cache": NO_CACHE_ARG,
+    output: { type: "string", description: "json|csv|jsonl|md", default: "json" }
+  },
+  run: async ({ args }) => {
+    const accountId = resolveAccountIdArg(args);
+    try {
+      const params = { "account-id": accountId };
+      if (args["no-cache"]) params["skip-cache"] = "true";
+      const data = await apiGet("/api/ads/linkedin/account", params);
+      const fmt = csvOrJson(args);
+      if (fmt !== "json") {
+        writeAdsOutput([data], fmt);
+        return;
+      }
+      writeAdsJson({ ok: true, data });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+var accountCommand = defineCommand({
+  meta: {
+    name: "account",
+    description: `LinkedIn ad account: its detail, and the settings that apply across every ad set in it.
+
+Examples:
+  baker ads linkedin account --account-id 503001492                          \u2014 currency, status, type
+  baker ads linkedin account url-params --param utm_source=linkedin          \u2014 UTMs for every ad in the account`
+  },
+  subCommands: {
+    detail: accountDetailCommand,
+    "url-params": () => import("./write-commands-4KWMNH6A.js").then((m) => m.accountUrlParamsCommand)
+  },
+  args: accountDetailCommand.args,
+  default: "detail"
+});
+export {
+  accountCommand
+};
+//# sourceMappingURL=account-5VPZ3XQ3.js.map

package/dist/account-SYUEXERA.js

@@ -0,0 +1,49 @@
+import {
+  handleMetaError,
+  resolveAccountIdArg
+} from "./chunk-NFHUJRDE.js";
+import {
+  writeAdsJson
+} from "./chunk-OTNGMKI6.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-ELNN4SNW.js";
+import {
+  apiGet
+} from "./chunk-OSWCEDFE.js";
+import "./chunk-D53AAUG4.js";
+import "./chunk-FZKUUI3F.js";
+import "./chunk-4WYEGE4N.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/meta/account.ts
+import { defineCommand } from "citty";
+var accountCommand = defineCommand({
+  meta: {
+    name: "account",
+    description: `Show single Meta ad account detail (currency, timezone, balance, business).
+
+Examples:
+  baker ads meta account --account-id act_123
+  BAKER_META_AD_ACCOUNT_ID=act_123 baker ads meta account`
+  },
+  args: {
+    "account-id": { type: "string", description: "Meta ad account ID (act_...)" },
+    "no-cache": NO_CACHE_ARG
+  },
+  run: async ({ args }) => {
+    const accountId = resolveAccountIdArg(args);
+    try {
+      const params = { "account-id": accountId };
+      if (args["no-cache"]) params["skip-cache"] = "true";
+      const data = await apiGet("/api/ads/meta/account", params);
+      writeAdsJson({ ok: true, data });
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+export {
+  accountCommand
+};
+//# sourceMappingURL=account-SYUEXERA.js.map

package/dist/account-ZQH535IP.js

@@ -0,0 +1,80 @@
+import {
+  CHATGPT_ADS_REFERENCE,
+  runChatgptRead
+} from "./chunk-LF3MFO2N.js";
+import "./chunk-OTNGMKI6.js";
+import {
+  apiGet
+} from "./chunk-OSWCEDFE.js";
+import "./chunk-D53AAUG4.js";
+import "./chunk-FZKUUI3F.js";
+import {
+  registerSchema
+} from "./chunk-4WYEGE4N.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/chatgpt/account.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ads.chatgpt.account",
+  description: "The connected ChatGPT Ads account: name, currency, timezone, status, and the brand and account reviews that decide whether anything in it can serve.",
+  args: {
+    full: { type: "boolean", description: "Return ChatGPT Ads' own account object", required: false }
+  }
+});
+function accountHints(account) {
+  const hints = [];
+  if (account.brandReview.status !== "approved") {
+    const reason = account.brandReview.reason ? ` (${account.brandReview.reason})` : "";
+    hints.push(
+      `Brand review is ${account.brandReview.status}${reason}: nothing in this account serves until it is approved. Fix it in ChatGPT Ads Manager before changing campaigns.`
+    );
+  }
+  if (account.accountReview && account.accountReview.status !== "approved") {
+    hints.push(`A separate account review is ${account.accountReview.status}; delivery can wait on it too.`);
+  }
+  if (account.status === "paused") {
+    hints.push("The whole account is paused, so no campaign in it serves whatever its own status says.");
+  }
+  return hints;
+}
+var SHOW_ARGS = {
+  full: { type: "boolean", description: "Return ChatGPT Ads' own account object", required: false }
+};
+var accountShowCommand = defineCommand({
+  meta: {
+    name: "show",
+    description: "The connected ChatGPT Ads account. Example: baker ads chatgpt account"
+  },
+  args: SHOW_ARGS,
+  run: async ({ args }) => {
+    await runChatgptRead(
+      CHATGPT_ADS_REFERENCE.account,
+      () => apiGet("/api/ads/chatgpt/account", args.full ? { full: "true" } : void 0),
+      (account) => args.full ? [] : accountHints(account)
+    );
+  }
+});
+var accountCommand = defineCommand({
+  meta: {
+    name: "account",
+    description: `The connected ChatGPT Ads account. Start here: currency and timezone for every figure, and whether reviews let anything serve.
+
+Examples:
+  baker ads chatgpt account
+  baker ads chatgpt account --full
+  baker ads chatgpt account update --favicon-url https://example.com/icon.png   \u2014 staged; applies on publish`
+  },
+  subCommands: {
+    show: accountShowCommand,
+    update: () => import("./account-writes-DLCRTL6Y.js").then((m) => m.accountUpdateCommand)
+  },
+  // A parent must never declare `run`: citty falls through to it after the matched subcommand.
+  args: SHOW_ARGS,
+  default: "show"
+});
+export {
+  accountCommand,
+  accountHints
+};
+//# sourceMappingURL=account-ZQH535IP.js.map

package/dist/account-reads-GUYNJEZA.js

@@ -0,0 +1,218 @@
+import {
+  exitWithServiceReadError
+} from "./chunk-OCBAKPHH.js";
+import {
+  failWriteValidation,
+  listFlag,
+  requireCustomerId
+} from "./chunk-HDNZSVJJ.js";
+import "./chunk-ERSX3MKH.js";
+import "./chunk-5ZIGEHQQ.js";
+import "./chunk-4NZ47VXO.js";
+import "./chunk-D5FY4FAK.js";
+import "./chunk-MMU6XHCH.js";
+import "./chunk-SEPPFM5S.js";
+import {
+  getManagerIdForCustomer,
+  writeJsonEnvelope
+} from "./chunk-OTNGMKI6.js";
+import "./chunk-6FHP2HIK.js";
+import "./chunk-DS2ZRTAL.js";
+import "./chunk-4TBDEV7X.js";
+import "./chunk-EIJDXZW5.js";
+import "./chunk-2WRK44LZ.js";
+import "./chunk-3FFJYMKM.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-I2DNBEV6.js";
+import {
+  apiPost
+} from "./chunk-OSWCEDFE.js";
+import "./chunk-D53AAUG4.js";
+import "./chunk-FZKUUI3F.js";
+import {
+  registerSchema
+} from "./chunk-4WYEGE4N.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/google/account-reads.ts
+import { defineCommand } from "citty";
+function register(command, description, args) {
+  registerSchema({
+    command,
+    description,
+    args: Object.fromEntries(
+      Object.entries(args).map(([name, arg]) => [
+        name,
+        { type: arg.type, description: arg.description, required: false }
+      ])
+    )
+  });
+}
+async function serviceRead(path, customerId, body) {
+  const managerId = getManagerIdForCustomer(customerId);
+  const { data } = await apiPost(path, {
+    customerId,
+    ...managerId ? { managerId } : {},
+    ...body
+  });
+  return data;
+}
+var CUSTOMER_ARG = {
+  "customer-id": { type: "string", description: "Google Ads customer ID (10 digits, no dashes)" }
+};
+var INVOICE_ARGS = {
+  ...CUSTOMER_ARG,
+  month: { type: "string", description: "Issue month, YYYY-MM (default: last month)" }
+};
+register(
+  "ads.google.invoices",
+  "List the invoices Google issued in one month (accounts on monthly invoicing only): id, dates, service period, subtotal/tax/total in micros, PDF link. Start here: `baker ads google invoices --customer-id 1234567890 --month 2026-09`. An account that pays automatically has no invoices \u2014 the error's fix says where its receipts are; carry on.",
+  INVOICE_ARGS
+);
+var invoicesCommand = defineCommand({
+  meta: {
+    name: "invoices",
+    description: `List one month's invoices (monthly-invoicing accounts only). Read-only.
+
+Example:
+  baker ads google invoices --customer-id 1234567890 --month 2026-09`
+  },
+  args: INVOICE_ARGS,
+  run: async ({ args }) => {
+    const customerId = requireCustomerId(args);
+    try {
+      const data = await serviceRead("/api/ads/google/invoices", customerId, {
+        ...args.month ? { month: args.month } : {}
+      });
+      const hints = data.invoices.length === 0 ? [`No invoice was issued in ${data.month}. Try the month before with --month.`] : [
+        "Amounts are micros in each invoice's currency_code (divide by 1,000,000). pdf_url needs the user's Google sign-in."
+      ];
+      writeJsonEnvelope({ ok: true, data, hints });
+    } catch (err) {
+      exitWithServiceReadError(err);
+    }
+  }
+});
+register(
+  "ads.google.identity-verification",
+  "Advertiser identity verification status: each program's status (PENDING_USER_ACTION, PENDING_REVIEW, SUCCESS, FAILURE), deadlines and the link where the user completes it. Start here: `baker ads google identity-verification --customer-id 1234567890`. Google only answers for accounts on monthly invoicing \u2014 otherwise the error's fix says where the user reads it; carry on.",
+  CUSTOMER_ARG
+);
+var identityVerificationCommand = defineCommand({
+  meta: {
+    name: "identity-verification",
+    description: `Advertiser identity verification status and deadlines. Read-only.
+
+Example:
+  baker ads google identity-verification --customer-id 1234567890`
+  },
+  args: CUSTOMER_ARG,
+  run: async ({ args }) => {
+    const customerId = requireCustomerId(args);
+    try {
+      const data = await serviceRead(
+        "/api/ads/google/identity-verification",
+        customerId,
+        {}
+      );
+      const pending = data.programs.filter((program) => program.status === "PENDING_USER_ACTION");
+      const hints = pending.length > 0 ? [
+        `Verification is waiting on the advertiser${pending[0]?.completion_deadline ? ` (deadline ${pending[0].completion_deadline})` : ""}: give the user the action_url \u2014 ads stop serving if it lapses.`
+      ] : [];
+      writeJsonEnvelope(hints.length > 0 ? { ok: true, data, hints } : { ok: true, data });
+    } catch (err) {
+      exitWithServiceReadError(err);
+    }
+  }
+});
+var PREVIEW_ARGS = {
+  ...CUSTOMER_ARG,
+  ads: {
+    type: "string",
+    description: "Comma-separated video ads of Video campaigns as {adGroupId}~{adId} (from `ads list`) \u2014 previewed live on YouTube"
+  },
+  "asset-groups": {
+    type: "string",
+    description: "Comma-separated Performance Max asset group ids (from `asset-groups list`) \u2014 previewed on Google's preview page"
+  }
+};
+register(
+  "ads.google.previews",
+  "Shareable preview links for Performance Max asset groups (Google's preview page) and video ads (live on YouTube) that already exist in the account \u2014 a link the user can open or forward. Start here: `baker ads google previews --customer-id 1234567890 --asset-groups 6743268912`. Returns { previews: [{ target, url, youtube_tv_url, expires_at }] }. Only video ads of Video campaigns can be previewed by ad (search, display and Demand Gen ads have no shareable preview); staged (unpublished) changes cannot be previewed.",
+  PREVIEW_ARGS
+);
+var previewsCommand = defineCommand({
+  meta: {
+    name: "previews",
+    description: `Shareable preview links for existing Performance Max asset groups and video ads. Read-only.
+
+Examples:
+  baker ads google previews --customer-id 1234567890 --asset-groups 6743268912
+  baker ads google previews --customer-id 1234567890 --ads 195752489650~826812181091   # a video ad, live on YouTube`
+  },
+  args: PREVIEW_ARGS,
+  run: async ({ args }) => {
+    const customerId = requireCustomerId(args);
+    const ads = listFlag(args.ads);
+    const assetGroups = listFlag(args["asset-groups"]);
+    if (!ads?.length && !assetGroups?.length) failWriteValidation("pass --ads and/or --asset-groups");
+    try {
+      const data = await serviceRead("/api/ads/google/previews", customerId, {
+        ...ads ? { ads } : {},
+        ...assetGroups ? { assetGroups } : {}
+      });
+      writeJsonEnvelope({
+        ok: true,
+        data,
+        hints: [
+          "Each link expires (expires_at). It shows what is live in the account now, not anything staged in this chat."
+        ]
+      });
+    } catch (err) {
+      exitWithServiceReadError(err);
+    }
+  }
+});
+var BRAND_ARGS = {
+  ...CUSTOMER_ARG,
+  prefix: { type: "string", description: "The start of the brand's name (at least 2 letters)" }
+};
+register(
+  "ads.google.brands",
+  "Find a brand's Google entity id \u2014 what a BRANDS list member names (`keyword-lists add --brand /g/\u2026`). Start here: `baker ads google brands --customer-id 1234567890 --prefix nike`. Several brands can share a name: pick by the URL. Read-only.",
+  BRAND_ARGS
+);
+var brandsCommand = defineCommand({
+  meta: {
+    name: "brands",
+    description: `Find brand entity ids for a brand list (BRANDS). Read-only.
+
+Example:
+  baker ads google brands --customer-id 1234567890 --prefix nike`
+  },
+  args: BRAND_ARGS,
+  run: async ({ args }) => {
+    const customerId = requireCustomerId(args);
+    if (typeof args.prefix !== "string" || args.prefix.trim().length < 2) {
+      failWriteValidation("--prefix needs at least the first 2 letters of the brand");
+    }
+    try {
+      const data = await serviceRead("/api/ads/google/brands", customerId, {
+        prefix: args.prefix
+      });
+      const hints = data.brands.length > 0 ? [
+        "Several brands can share a name \u2014 pick the one whose URL is the brand you mean, then `keyword-lists add --list-ref <BRANDS list> --brand <entity_id>`."
+      ] : ["No brand starts with that \u2014 try a shorter or different prefix."];
+      writeJsonEnvelope({ ok: true, data, hints });
+    } catch (err) {
+      exitWithServiceReadError(err);
+    }
+  }
+});
+export {
+  brandsCommand,
+  identityVerificationCommand,
+  invoicesCommand,
+  previewsCommand
+};
+//# sourceMappingURL=account-reads-GUYNJEZA.js.map

package/dist/account-writes-DLCRTL6Y.js

@@ -0,0 +1,66 @@
+import {
+  compact,
+  schemaArgs,
+  stageChatgptOp
+} from "./chunk-GTOHNTTI.js";
+import {
+  CHATGPT_ADS_REFERENCE,
+  chatgptFailure
+} from "./chunk-LF3MFO2N.js";
+import {
+  writeJsonEnvelope
+} from "./chunk-OTNGMKI6.js";
+import {
+  apiGet
+} from "./chunk-OSWCEDFE.js";
+import "./chunk-D53AAUG4.js";
+import "./chunk-FZKUUI3F.js";
+import {
+  registerSchema
+} from "./chunk-4WYEGE4N.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/chatgpt/account-writes.ts
+import { defineCommand } from "citty";
+var REFERENCE = CHATGPT_ADS_REFERENCE.account;
+var UPDATE_ARGS = {
+  name: { type: "string", description: "The advertiser name shown on every card" },
+  "favicon-url": { type: "string", description: "https:// square icon, at least 128 \xD7 128 px" }
+};
+registerSchema({
+  command: "ads.chatgpt.account.update",
+  description: "Stage a change to the advertiser's brand name or icon. It applies when the chat is published and starts a new brand review; nothing in the account serves until it is approved.",
+  args: schemaArgs(UPDATE_ARGS)
+});
+var accountUpdateCommand = defineCommand({
+  meta: {
+    name: "update",
+    description: `Stage a change to the brand name or icon (applies when the chat is published).
+
+Examples:
+  baker ads chatgpt account update --favicon-url https://example.com/icon.png
+  baker ads chatgpt account update --name "GreenLeaf Energy"`
+  },
+  args: UPDATE_ARGS,
+  run: async ({ args }) => {
+    let account;
+    try {
+      account = await apiGet("/api/ads/chatgpt/account");
+    } catch (err) {
+      writeJsonEnvelope({ ...chatgptFailure(err, REFERENCE) });
+      process.exit(1);
+    }
+    await stageChatgptOp(
+      {
+        kind: "account.update",
+        target: account.id,
+        payload: compact({ name: args.name, faviconUrl: args["favicon-url"] })
+      },
+      REFERENCE
+    );
+  }
+});
+export {
+  accountUpdateCommand
+};
+//# sourceMappingURL=account-writes-DLCRTL6Y.js.map

package/dist/accounts-3TNEMLLC.js

@@ -0,0 +1,115 @@
+import {
+  NO_X_ACCOUNTS_EXPLANATION
+} from "./chunk-6VI2DDGZ.js";
+import {
+  connectedResourceHints
+} from "./chunk-P4NSJS54.js";
+import {
+  AVAILABLE_ARG,
+  writeAvailableAccounts
+} from "./chunk-UKMG6YWX.js";
+import {
+  cacheGet,
+  cacheSet,
+  handleConnectionError,
+  needsConnectionFix,
+  writeAdsJson,
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-OTNGMKI6.js";
+import {
+  ApiError,
+  apiGet
+} from "./chunk-OSWCEDFE.js";
+import "./chunk-D53AAUG4.js";
+import "./chunk-FZKUUI3F.js";
+import {
+  registerSchema
+} from "./chunk-4WYEGE4N.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/x/accounts.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ads.x.accounts",
+  description: "List the X Ads accounts this company connected \u2014 there can be several, and every one of them is yours to work in. Returns accounts with id (base36), name, approval_status, timezone, currency. Run this first to find account IDs for other commands.",
+  args: {
+    "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
+    output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" },
+    available: AVAILABLE_ARG
+  }
+});
+function accountHints(accounts) {
+  if (accounts.length === 0) return [NO_X_ACCOUNTS_EXPLANATION];
+  return connectedResourceHints({
+    plural: "X Ads accounts",
+    singular: "X Ads account",
+    flag: "--account-id",
+    resources: accounts.map((account) => ({ id: account.id, label: account.name }))
+  });
+}
+function handleAccountsError(err) {
+  if (err instanceof ApiError) {
+    if (needsConnectionFix(err.code, err.message)) {
+      handleConnectionError("x_ads", err.message);
+    }
+    const envelope = {
+      ok: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        fix: { action: "reject", explanation: err.message },
+        retryable: false
+      }
+    };
+    writeAdsJson(envelope);
+    process.exit(1);
+  }
+  writeAdsJson({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error" } });
+  process.exit(1);
+}
+var accountsCommand = defineCommand({
+  meta: {
+    name: "accounts",
+    description: `List accessible X Ads accounts. Returns account IDs needed for all other commands.
+
+Examples:
+  baker ads x accounts
+  baker ads x accounts --available   # every account the login reaches, selected or not`
+  },
+  args: {
+    "no-cache": { type: "boolean", description: "Skip cache", required: false },
+    output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" },
+    available: AVAILABLE_ARG
+  },
+  run: async ({ args }) => {
+    if (args.available) return writeAvailableAccounts("x-ads", handleAccountsError);
+    const useCache = !args["no-cache"];
+    if (useCache) {
+      const cached = cacheGet("x-accounts", "list");
+      if (cached) {
+        writeJsonEnvelope({ ok: true, data: cached.data, cached: true, hints: accountHints(cached.data) });
+        return;
+      }
+    }
+    try {
+      const params = !useCache ? { "skip-cache": "true" } : void 0;
+      const data = await apiGet("/api/ads/x/accounts", params);
+      if (useCache) {
+        cacheSet("x-accounts", "list", data, 60 * 60 * 1e3);
+      }
+      const format = args.output || "json";
+      if (format !== "json") {
+        writeAdsOutput(data, format);
+        return;
+      }
+      writeJsonEnvelope({ ok: true, data, hints: accountHints(data) });
+    } catch (err) {
+      handleAccountsError(err);
+    }
+  }
+});
+export {
+  accountsCommand
+};
+//# sourceMappingURL=accounts-3TNEMLLC.js.map