@koda-sl/baker-cli 0.111.0-dev.4a58faec8 → 0.111.0-dev.94fd3a2a1

package/README.md

@@ -653,6 +653,39 @@ baker ads google library search-competitors "crm software" --location uk
 
 ---
 
+### Staged writes (`baker ads google budgets|campaigns|...`)
+
+Write commands **never touch the Google Ads API at stage time**. Each command stages a create/update/pause/resume/remove op against the current chat's draft (`BAKER_CHAT_ID`); the dashboard shows it as a pending "Google Ads" change, and the whole draft applies as one atomic `GoogleAdsService.Mutate` when the chat is published. Feature-flagged per company (`companies.googleAdsWriteEnabled`) — off by default = a fully simulated publish with zero real API calls.
+
+Reference not-yet-created resources with `g_temp_*` refs returned by earlier `create` commands (they map to Google's temporary negative-ID resource names inside one atomic batch).
+
+```bash
+# Build a Search campaign bottom-up, chaining temp refs
+baker ads google budgets create --customer-id 1234567890 --name "Search budget" --amount 50
+# → { ref: "g_temp_ab12", ... }
+baker ads google campaigns create --customer-id 1234567890 --name "Brand — Search" \
+  --channel-type SEARCH --budget-ref g_temp_ab12 --bidding-strategy MANUAL_CPC
+baker ads google ad-groups create --customer-id 1234567890 --name "Brand terms" --campaign-ref g_temp_<campaign>
+baker ads google keywords add --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> --text "brand name" --match-type EXACT
+# Shared negative keyword list → attach to the campaign
+baker ads google keyword-lists create --customer-id 1234567890 --name "Brand exclusions"
+baker ads google keyword-lists add --customer-id 1234567890 --list-ref g_temp_<list> --text "free" --match-type BROAD
+baker ads google keyword-lists attach --customer-id 1234567890 --campaign-ref g_temp_<campaign> --list-ref g_temp_<list>
+# Responsive search ad
+baker ads google ads create --customer-id 1234567890 --ad-group-ref g_temp_<adgroup> \
+  --headlines "Fast Widgets,Buy Online,Free Shipping" --descriptions "Best widgets around.,Ships tomorrow." \
+  --final-url https://example.com
+
+# Review / undo staged changes
+baker ads google draft list
+baker ads google draft remove g_temp_ab12   # cascades to dependents
+baker ads google draft clear
+```
+
+Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remove), `negative-keywords`, `keyword-lists`, `ads`, `assets`, `audiences`, `conversions`, `bidding-strategies`, `labels`, `campaign-criteria`, and `draft`. Amounts are in major currency units (converted to micros). Money/bids: `--amount`, `--cpc-bid`, `--target-cpa` take major units; `--target-roas` a ratio. Less-common ops accept a `--file <payload.json>` (flags override file keys). Updates target a resource name or bare id as the positional argument; a target that names an op staged earlier **amends it in place**.
+
+---
+
 ### Caching
 
 Google Ads data is cached at two levels:
@@ -2487,24 +2520,6 @@ Permissions enforced server-side:
 
 ---
 
-### `baker mcp list | add | remove`
-
-Manage **custom MCP servers** — point the agent at any remote HTTPS MCP endpoint. Registered tools appear as `mcp__<name>__*` on the next chat message.
-
-```bash
-baker mcp list
-baker mcp add --name weather --url https://mcp.example.com/mcp
-baker mcp add --name acme --url https://acme.dev/mcp --header "Authorization: Bearer sk-…"
-baker mcp add --name mine --url https://my.dev/mcp --scope user
-baker mcp remove --name weather
-```
-
-- `--url` must be HTTPS and public; loopback / private / cloud-metadata hosts are rejected.
-- `--scope company` (default) shares with every chat in the company; `--scope org` needs an admin API key; `--scope user` binds to the current message sender (requires running inside a chat turn — the bridge supplies the sender via `BAKER_ACTING_USER_ID`).
-- Repeat `--header "Key: Value"` for multiple auth headers. Header values are stored server-side and ride the MCP transport — `list` returns only the header keys, never the values.
-
----
-
 ### `baker schema [command]`
 
 Inspect command argument schemas for AI agent introspection.
@@ -3842,8 +3857,8 @@ The two scaffold passes are billed (the full `video_deconstruct` is the heavy on
 
 Turn a source/inspiration image into a **runnable, self-validated static-ad canvas** — the static counterpart of `scaffold-video`. Like the video scaffold, this runs **billed Gemini passes** up front:
 
-1. **`image_describe`** (`~google/gemini-pro-latest`) — reverse-engineers the image into a blueprint JSON, written next to the canvas as **`prompt.json`**. This is the editable "prompt": you rewrite it by hand into the ad you want (palette, copy, claims, subjects). It feeds the generator directly — there is **no automatic brand-transform step**. The blueprint also names the **`winning_mechanisms`** — the special sauce that makes the ad a candidate winner, each tagged `kind` (verbal: rhyme/pun/rhythm; visual: unexpected crop, visual gag, juxtaposition, pattern interrupt, before/after; structural: hook order/reveal) with a `device` and `why_it_works` — so your rewrite rebuilds the mechanism that makes the ad win instead of adapting only the surface and losing it.
-2. **element selection** (`~google/gemini-flash-latest`) — picks the **main, identity-critical** elements (the brand logo, a showcased product, a trust badge) **plus any foreground/hero person or animal** — the emotional focal point — even a generic one, because a free-generated face/muzzle reads as AI and grows artifacts; the emotional hero always gets a real-reference slot. Background extras are dropped. Each is stamped back onto its blueprint entry as a `reference_image` label so the JSON self-documents which slot grounds which subject.
+1. **`image_describe`** (`~google/gemini-pro-latest`) — reverse-engineers the image into a blueprint JSON, written next to the canvas as **`prompt.json`**. This is the editable "prompt": you rewrite it by hand into the ad you want (palette, copy, claims, subjects). It feeds the generator directly — there is **no automatic brand-transform step**.
+2. **element selection** (`~google/gemini-flash-latest`) — picks only the **main, identity-critical** elements (the brand logo, a showcased product, a foreground person/animal, a trust badge); background extras are dropped. Each is stamped back onto its blueprint entry as a `reference_image` label so the JSON self-documents which slot grounds which subject.
 3. **global layout** (`~google/gemini-flash-latest`) — produces a structured `layout` block in `prompt.json`: the column/row grid, each region's `x_pct`/`y_pct` bounds, panel splits, background/shape, and every text block's relative size/weight/case/alignment. This is what gives the generator a precise composition to rebuild.
 
 It then scaffolds a canvas that ingests `prompt.json`, wires **one `[TODO]` ingest slot per detected element** (plus an optional brand-font → type-specimen) into `image_generate`, and wires the original image in for composition only. The canvas is validated before it's written. stdout returns `{ ok, canvas_path, prompt_path, models, layout_regions, stats, checklist }` — the **checklist** lists every real asset to drop in.