@koda-sl/baker-cli 0.374.0 → 0.375.0-dev.71ce37ace

package/README.md

@@ -110,22 +110,6 @@ question — and nothing in the output said so. Both spellings of an option work
 that lists every option: `baker schema <command>` (`check_schema`) when the command
 registers a schema, `baker <command> --help` (`check_help`) when it does not.
 
-### Narrowing a result: `--fields`
-
-`--fields a,b,c` works on every command that prints the JSON envelope. It keeps only
-those keys of each record in `data` — the rows when `data` is a list or wraps one
-(`baker chats list --fields id,title`), `data` itself when it is a single record
-(`baker experiment plan ... --fields traffic,warning`). Naming a key of the wrapper beside
-keys of its rows narrows both. `meta`, `hints` and warnings are
-kept, and a name no record carries is reported in `hints` alongside the keys that do
-exist. Commands that declare `--fields` themselves keep their own meaning
-(`ads meta insights` chooses which metrics to request; `ads linkedin creatives` takes dotted
-paths; `actions draft` picks the columns of `--output md|files` and leaves its JSON
-whole). A command whose default output is text needs `--output json` for there to be an
-envelope to narrow; without it a note on stderr says the flag changed nothing. A success
-that prints its result beside `ok` rather than under `data` (`canvas validate`,
-`canvas critique`) comes back whole, with a hint saying `--fields` was not applied.
-
 ### Fresh reads: `--no-cache`
 
 Every command that caches takes `--no-cache`, and it skips **both** cache layers — the
@@ -721,7 +705,7 @@ Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remo
 
 **Amending a staged op** — `draft amend <ref> (--file patch.json | --patch '<json>')` merges a JSON patch into an already-staged op's payload (objects deep-merge, `null` deletes a key, arrays/scalars replace) and re-validates it in full. Always prefer this over removing and re-staging — it preserves the op's ref (so dependents don't break) and its position in the draft. `draft show <ref>` prints the full staged payload (including warnings/annotations) so you can verify a change looks right before publish.
 
-**Reading an earlier chat's changes** — `draft list` and `draft show` take `--chat <chat-id>` to read another chat in the same company instead of the current one. Every staged-draft family accepts it: `ads google|meta|linkedin draft list|show`, `tag-manager draft list|show`, `actions draft`, `tags draft`, and `scheduled-agents list|get` (`list` leaves briefs out; `get <id>` or `list --full` returns them). A published draft is kept in full, so this returns what that chat actually wrote — every headline, bid and target — plus each op's outcome and error. Use it when asked to redo or reapply earlier work rather than reconstructing copy from a summary. Read-only: staging, `amend`, `remove` and `clear` stay bound to `BAKER_CHAT_ID`, so one chat can never edit another's draft. To re-run only the changes a publish failed to land, use the chat's **Retry** control in the dashboard — it re-sends exactly those and leaves the ones that applied untouched.
+**Reading an earlier chat's changes** — `draft list` and `draft show` take `--chat <chat-id>` to read another chat in the same company instead of the current one. Every staged-draft family accepts it: `ads google|meta|linkedin draft list|show`, `tag-manager draft list|show`, `actions draft`, `tags draft`, and `scheduled-agents list|get`. A published draft is kept in full, so this returns what that chat actually wrote — every headline, bid and target — plus each op's outcome and error. Use it when asked to redo or reapply earlier work rather than reconstructing copy from a summary. Read-only: staging, `amend`, `remove` and `clear` stay bound to `BAKER_CHAT_ID`, so one chat can never edit another's draft. To re-run only the changes a publish failed to land, use the chat's **Retry** control in the dashboard — it re-sends exactly those and leaves the ones that applied untouched.
 
 **Already-satisfied writes aren't staged** — an update or pause/resume whose every field already holds the requested value on the live account is dropped instead of staged: the envelope returns `"staged": false, "noop": true` with a `reason` ("this ad is already Paused on Google Ads"), plus a hint. This is a success, not an error — there is nothing to publish. Only a positively-read live snapshot can trigger it; a failed or empty read always stages. Batch responses list the dropped ops under `skipped`, and `count` reflects what actually entered the draft.
 
@@ -959,8 +943,7 @@ baker ads meta creatives create   --account-id act_123 --page 555 --instagram-us
 baker ads meta ads create         --account-id act_123 --name "Ad 1" --adset meta_temp_as --creative meta_temp_cr
 
 # review + edit before publish
-baker ads meta draft                       # one line per op: ref · kind · summary · after <refs>, then advisories
-baker ads meta draft --json                # raw JSON envelope for scripting
+baker ads meta draft
 baker ads meta draft show meta_temp_cr     # full staged payload — the receipt before publish
 baker ads meta draft remove meta_temp_cr   # removing a create cascades to dependents
 baker ads meta draft clear
@@ -1306,9 +1289,6 @@ baker analytics map --platform google --set kw=keyword    # name a parameter, se
 baker analytics map --platform google --remove kw         # take that answer back
 baker analytics conversions               # what counts, what each produced, and which Forms count nothing
 baker analytics conversions --candidates --output md  # everything these pages do, and which of it is counted, as tables
-baker analytics conversions --candidates             # the same as compact JSON: one line per page event, Form keys folded onto `flows`
-baker analytics conversions --candidates --flow contact             # only that Form's event keys, one line each
-baker analytics conversions --candidates --full --output json       # every field of every candidate, Form keys unfolded
 baker analytics conversions --flow contact          # one Form's endings as event keys, traffic or not
 baker analytics conversions --event page:request_demo --name "Demo requested"
 baker analytics conversions --event page:a --event submit:b --name "Lead"   # both, as one number
@@ -1360,7 +1340,7 @@ Shared flags: `--days <n>` (default 30) or `--start-date` / `--end-date` (`YYYY-
 
 **Paging the list reports.** `people`, `submissions` and `delivery` are lists of individual things rather than breakdowns — `delivery` and `submissions` are the ones the CLI exposes, `people` backs the People section of the dashboard's landing Analytics screen over the same wire — and only they take `--page <n>` (1-based) and `--page-size <n>` (up to 200, default 50). The response carries `pageInfo` with `hasMore` — when it is true there **are** more rows, so a total must never be reported from one page. Pass neither flag and a list comes back at the size it always did. A value that is not a whole positive number (`--page /pricing`) is refused before any request, naming `--landing` as the flag that narrows a report to one page of the site.
 
-**A conversion is a company-level named event, not a property of a Form.** `baker analytics conversions` is the only place "what counts" is decided, and an empty `definitions` list means every conversion number in every other report is zero — not because nobody converted, but because nothing is named as an outcome and Baker never guesses which event is the point of a page. `--candidates` lists every event these pages actually produced — each Form step and trigger, every `data-baker-*` event, every outbound destination — with volume and whether it is already counted; that list is where an event key comes from, so never invent one. The JSON is compact by default: each page or system event is one line (`eventKey`, `events`, `sessions`, `countedAs` when counted), and a Form's keys fold onto its `flows` row as `keys` fired and `events` — dropping that row's empty `counted` and `noConversion` — or onto a `formCandidates` row for a Form not in `flows`. `--candidates --flow <slug>` narrows the list to that Form's keys, and `--full` returns every field (`origin`, `nodeType`, `flowSlug`, `lastSeen`, `sources`, `doors`) of every key, unfolded. `--output md` always folds a Form's keys into one row per Form. `--event <key> --name "Booked a call"` starts counting it **immediately and retroactively**: the whole stored history is rescored, so naming the right event today also fixes last month. Nothing here is staged and publishing is not involved. Two events given the same `--name` become one row and one number, which is how a call booked on three different Forms reads as one outcome. `--count-mode every_time` is for the outcomes people genuinely repeat (a guide downloaded twice is two downloads); the default counts once per visit.
+**A conversion is a company-level named event, not a property of a Form.** `baker analytics conversions` is the only place "what counts" is decided, and an empty `definitions` list means every conversion number in every other report is zero — not because nobody converted, but because nothing is named as an outcome and Baker never guesses which event is the point of a page. `--candidates` lists every event these pages actually produced — each Form step and trigger, every `data-baker-*` event, every outbound destination — with volume and whether it is already counted; that list is where an event key comes from, so never invent one. `--event <key> --name "Booked a call"` starts counting it **immediately and retroactively**: the whole stored history is rescored, so naming the right event today also fixes last month. Nothing here is staged and publishing is not involved. Two events given the same `--name` become one row and one number, which is how a call booked on three different Forms reads as one outcome. `--count-mode every_time` is for the outcomes people genuinely repeat (a guide downloaded twice is two downloads); the default counts once per visit.
 
 **The name is the grouping, so the CLI defends it.** Repeat `--event` to count several events under one `--name` in a single call; `--rename "<old>" --to "<new>"` renames every event under an outcome, and renaming *onto* a name that already exists **merges** them into one row and one number — the fix for a company whose Forms each invented their own word for the same thing. `--remove-name` drops an outcome entirely, `--remove` a single event key. A name that differs from one already counted only by case, accent, punctuation or a plural is **refused**: Baker groups by exact name, so "Booked a Call" beside "Booked a call" is a number split in half with both halves plausible. Every answer leads with the names already in use, and a company that has named nothing gets a standard set to start from — after which the rule is reuse, in that company's own language.
 
@@ -3312,10 +3292,8 @@ baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --top-n 10 --out
 A Scheduled agent is a **trigger** and a **prompt**. When the trigger fires, a Session opens with that prompt and does the job — there is no Task in between. `create`, `update`, and `delete` stage draft ops on `BAKER_CHAT_ID` and apply when the chat is published. `unstage` takes back what this chat staged on one item before Publish (`--index <n>` for one change only, by its index in `list` → `draft.ops`). `list` and `get` include draft state when `BAKER_CHAT_ID` is set; `get` on a published item also returns `runsAs` — who each run acts as and which tools it loads. `run` fires a published item immediately and does not require a chat id. Publishing every run unreviewed is switched on by the user on the item, never through the CLI: `--auto-publish` is refused with an `ask_user` fix.
 
 ```bash
-baker scheduled-agents triggers                    # every trigger kind, by group, compact
-baker scheduled-agents triggers --trigger experiment.decided   # one kind (or a family: --trigger experiment) in full, with its payload fields
-baker scheduled-agents triggers --group tasks      # one group in full; --full for the whole catalog
-baker scheduled-agents list                        # id, name, trigger, status; briefs left out (--full for everything)
+baker scheduled-agents triggers                    # every trigger there is
+baker scheduled-agents list
 baker scheduled-agents get <id-or-temp_agent_id>
 
 baker scheduled-agents create --name "Weekly report" --description "Prepare report" --prompt "Review last week's spend." --cron "0 9 * * MON" --timezone Europe/Madrid
@@ -3335,8 +3313,11 @@ baker scheduled-agents run <id>
 baker scheduled-agents templates --list                  # every recipe this company can run
 baker scheduled-agents templates --category measurement  # one group only
 baker scheduled-agents create --template baker-ads --name "Weekly ad review" --description "..." --cron "0 8 * * MON"
+baker scheduled-agents create --template baker-store-out-of-stock   # --name and --description default to the recipe's own
 ```
 
+With `--template`, `--name`, `--description` and `--prompt` are optional: the recipe's name, line and brief are used, and `--prompt` is appended to the brief. An item on a stock event whose name or line says it acts automatically is refused — every run's ad changes wait for review.
+
 Triggers:
 
 | `--trigger` | Fires when | Narrow it with |
@@ -3478,8 +3459,7 @@ baker actions list                         # default: bucketed (claimable, myCla
 # then most recent. The `blocked` bucket is ordered closest-to-ready first.
 baker actions list --bucketed=false --status pending
 baker actions list --bucketed=false --sort priority   # flat list, do-first order (default); use --sort recent for newest-first
-baker actions list --output md             # id-first Markdown; each bucket's guidance on its heading, blockers/holder under a row; flat rows add a one-line summary
-baker actions list --full                  # whole descriptions and full records (large on a real backlog)
+baker actions list --output md             # id-first Markdown; works for both the bucketed and flat shapes
 baker actions list --search "conversion goal" --output md   # find Tasks by words in name/description/tags (flat, best match first)
 # With BAKER_CHAT_ID, the bucketed list folds in THIS chat's draft: staged creates appear in
 # `draftCreates`; published actions being completed/discarded/updated carry a `draftStatus` marker.
@@ -3515,6 +3495,8 @@ baker actions create --name "Build hero" --priority high --tags landing,creative
 # fuller fan-out hint: re-read the draft and merge actions that touch the same system into one.
 # If no --tags are passed, create emits a MISSING --tags hint — the action is invisible to the backlog's tag filter.
 # If no --priority is passed, create emits a MISSING --priority hint — the action ranks as normal/medium in the do-first order.
+# If the name or description holds a shell name such as /bin/bash or bash where a `$0` stood (double quotes let the
+# shell expand `$` amounts), create leads with a hint to fix it with `baker actions update <tempId>` in single quotes.
 baker actions update <action-id> --name "Better name" --tags google-ads,strategy  # --tags REPLACES the set; '' clears
 baker actions update <action-id> --priority urgent                              # urgent|high|medium|low; 'none' clears
 baker actions update <tempId> --description "..."   # a tempId from `create` in THIS chat edits the still-staged task in place
@@ -3706,6 +3688,101 @@ No write surface against HubSpot itself — a form's fields, redirect, or consen
 
 ---
 
+### `baker shopify store | products | product | collections | stock | sales | buyers | buyer | countries | best-sellers | cohorts | segments | promotions | stock-holds`
+
+Read-only view of the company's **connected Shopify store**, from **Baker's own copy** of its catalog and the store's own orders — never a live call to Shopify. Baker keeps the copy current from the store (a change usually shows within about a minute) and checks the whole catalog daily; product photos are already in the image library.
+
+```bash
+baker shopify store                                # name, currency, home country, counts, prices by country, the Products page link
+baker shopify products --search "snowboard"        # what the store sells: price, sale price, stock, where it can be bought
+baker shopify products --stock out_of_stock        # --stock in_stock|partly_out|out_of_stock, --collection <handle|id>
+baker shopify products --limit 10 --cursor <c>     # page with meta.next_cursor (25 by default, up to 100)
+baker shopify product <id|handle|link>             # one product: options with buyUrl, prices by country, stock, photos, videos
+baker shopify product <handle> --content           # its whole details: description, custom fields, subscriptions, translations
+baker shopify product <handle> --field "Size chart" # one custom field, whole
+baker shopify product <handle> --quantity 2        # buy links that put 2 of the option in the cart
+baker shopify product <id> --out-of-stock          # only the options that are out of stock (page with --variants-cursor)
+baker shopify collections --search "summer"        # collections, with the handle --collection takes (--full: descriptions, images)
+baker shopify stock --limit 20                     # every product with every option out, and every product with some out
+baker shopify sales --days 7 --by campaign         # what sold and which campaigns brought it (--by day|product|campaign|landing)
+baker shopify sales --all --by weekday             # when buyers order, in the store's time (--by hour|month|month_of_year)
+baker shopify buyers --days 90 --by channel        # who buys: new and returning, repeat rate, segments, value per acquisition
+baker shopify buyer 1042                           # one numbered customer: profile, every order, what they bought
+baker shopify countries --country DE               # where buyers are: by country, a country's regions (--region for cities)
+baker shopify best-sellers --view repeat           # what sells (--view products|variants|trend|together|repeat|momentum)
+baker shopify segments                             # best, loyal, at risk, new, one-time, with this store's own rules
+baker shopify cohorts --months 12                  # buyers by first-order month: who came back, spend per buyer
+baker shopify promotions <id|handle|link>          # what advertises a product: ads (via page, buy link, landing), landings, Shopping
+baker shopify stock-holds --product <id>           # ads Baker paused because the product ran out: what to resume, and what to tell the user
+```
+
+**`meta.store`** is on every answer: `connection` (`connected` · `needs_reconnect` · `disconnected`), `catalog` (`starting` · `importing` · `ready` · `failed`, with `importProgress` while importing), `unreadable` (products Baker couldn't read; `unreadableCapped` past 100), `checksFailing` (Baker couldn't check the store for changes lately), `storefront` (`online_store`, or `own` for a store that sells through its own site) and `lastActivity` (when Baker last heard from the store — not a promise the copy is current). `hints[]` turn each of these into what to tell the user.
+**`store`:** `--full` adds the admin link and every country. `canChange` (`products`, `publishing`, `discounts`, `redirects`, `marketing`) says which kinds of store change the store allows Baker to stage; a `false` one is allowed by the user in Shopify. `capped: true` means a count stopped at its ceiling — `outOfStock` and `partlyOut` at 100, `collections` at 500 — so that count reads "that many or more"; a hint says which.
+**`products`:** `--search <words>`, `--collection <handle|id>`, `--stock`, `--limit <1-100>`, `--cursor`; `--full` adds vendor, type, option count, photo link, visibility and status. Every price, here and in `product` (`price`, `compareAt`, each option's price, `pricesByCountry`), is one string with its currency beside each amount: `"USD 785.95"`, `"USD 9.95 – USD 49.95"`. A row's `availability` is absent when the product is on the store, `link_only` when it is buyable only through its link, `not_for_sale` (with `status`) when it can't be bought on the online store.
+**`product`:** positional `<ref>` — the numeric id, the handle, a store product link (`…/products/<handle>`, even an all-digit handle), a Baker Products link, a Shopify admin product link (`admin.shopify.com/store/<shop>/products/<n>`), or `gid://shopify/Product/<n>`. Returns options (50 per page, `--variants-cursor` for more; 250 with `--full`), `outOptions` (up to 50, `outOptionsMore` for the rest), `pricesByCountry` when the store sells at more than one price, `photos[]` (`imageId` + a Baker-hosted `url`, never a Shopify link), `url` (the product's page in Baker) and `storeUrl` (the product's page on the store — never a buy button's link). `--full` adds the whole description, SEO, category, the admin link and each option's SKU, barcode, feed id and prices by country. `NOT_FOUND` carries a hint to search instead.
+
+**Details and buy links (`product`):** every option carries `buyUrl` — its buy link for ads, emails and messages (a landing places `<ShopifyProduct product="…" />` instead, which shows the options, price and stock and hands the shopper to the store), following the store's own setting (`buyDestination`: `checkout`, `store_cart` or `product_page`) — with `buyUrlKind`, `unavailable` when it can't be bought, and `notes` for what a link can't do (`password_protected`, `subscription_only`, `subscription_optional`, `own_storefront`, `details_pending`). `--quantity <1-99>` sets how many it adds. `videos[]` lists the product's videos in the library (`videoId`, `playbackId`); `contentSummary` names what else Baker keeps. `--content` adds `content`: the formatted description, every custom field by its name (long values previewed, `truncated: true`), the rating, subscriptions, bundle, YouTube/Vimeo and 3D links, translations, and `unreadable` for content the store owner hasn't let Baker read yet. `--field <name|namespace.key>` returns one field whole. `--full` adds `--content`, all three links per option and each option's weight, unit price, shipping and tax. `store` adds `buyDestination`, `passwordProtected`, `languages`, `policies` (`--full`: their text, and the store's brand).
+**`collections`:** `--search <words>`; each row has `handle`, Shopify's product count and, on a store with an online store, `onStore`.
+**`stock`:** `--collection`, `--limit <1-200>` (default 50 per list), `--full` (SKUs and Baker links). Options that keep selling at zero or don't track stock are not out of stock.
+**`sales`:** `--days <1-395>` (default 30), `--by day|product|campaign|landing` (default `day`), `--limit <1-100>`, `--full` (each row's source, medium, campaign, click platform, landing or product id). `data.totals` (`orders`, `sales`, `added`, `refunded`, `net`) in `data.currency`; `data.rows[]` with a `label` and, by campaign or landing, a `credit` (`campaign` · `order` · `landing` · `unattributed` · `before_baker` · `other`), adding up to the totals. A sale counts when it is paid, at what was received; by day and product each fact counts when it happened, by campaign and landing each order paid in the period carries what was added and refunded on it since. `meta.salesReporting` (`meta`, `google`: `baker` · `shopify_channel` · `undecided`) says who reports the sales to the ad platforms; `meta.history` is `importing` while past orders still come in.
+
+**`sales --by weekday|hour|month|month_of_year`:** orders placed in the period by when they were placed, in the store's timezone (`data.window.timezone`), from the store's whole order history — `--days` up to 3650 or `--all` (only these breakdowns take them).
+
+**Buyers, countries and best sellers** (`buyers`, `buyer`, `countries`, `best-sellers`, `cohorts`, `segments`) read the store's whole order history as Baker keeps it. Every answer carries `meta.window` (local `from`/`to`, `days` or `"all"`, the store's `timezone`), `meta.history` (`state`: `importing` · `done` · `failed` · `none`; `reach`: `all` or `60_days`; the first day held) and `meta.basis` (`all_orders`, or `last_60_days` when the store lets Baker read only its last 60 days — then a buyer whose earlier orders are older counts as new). The period is orders **placed** in it, with what was refunded on them since. A buyer is a numbered customer (`Customer #1042`) with a country, region and city — never a name or an email; guest orders count in money, never as buyers. Shared flags: `--days <1-3650>` (default 365) or `--all`, `--country <ISO2>`, `--full`.
+
+- **`buyers`:** `data.summary` (buyers, new and returning, guest orders, orders, net, average order, new/returning orders and net, repeat rate, median days to a second order), `data.segments`, `data.thresholds`, `data.buyers[]` (`--sort net|orders|recent|first`, `--limit`, `--offset`, `--segment best|loyal|at_risk|new|one_time`, `--channel <key>`), and with `--by campaign|channel` `data.acquisition.rows[]` (buyers whose first order is in the period, first-order net, lifetime net per buyer, average orders, repeat rate). Baker keeps no ad spend.
+- **`buyer <number>`:** `1042`, `#1042` or `Customer #1042`. A buyer erased by their store or merged into another answers `NOT_FOUND` "This buyer is no longer in Baker."
+- **`countries`:** `data.total`, `data.rows[]` (orders, buyers, new buyers, net, average order, share, growth against the period before, the currency paid in), `data.unknown` (no readable address) and `data.other` (past `--limit`), adding up to the total; `--country` for its regions, `--region` for a region's cities, `--product <id|handle>` for one product's orders and money.
+- **`best-sellers`:** `--view products` (default; units ordered beside refunded units, orders, buyers, revenue, refunds, refund rate, growth; `--sort units|revenue|orders`) · `variants` (with `--product`) · `trend` · `together` · `repeat` · `momentum`.
+- **`cohorts`:** `--months <3-36>` (default 12); retention at months 1, 2, 3, 6, 12 and net per buyer by month 12 (`--full`: every month).
+- **`segments`:** each segment's buyers, share, net, average orders, days since the last order, top countries and first products, and its rule in this store's numbers.
+
+**`promotions`:** positional `<ref>` like `product`. Reads the product, scans this workspace's `src/pages/*` (import graph, ≤ 300 pages, files ≤ 256 KB) for its buy link, `/products/<handle>`, an option id or a `<ShopifyProduct>` / `<ShopifyBuyButton>` naming it (evidence `buy_button`), then `POST /api/shopify/promotions` with the linked landings. `data.ads[]` (`platform`, `level` ad|asset_group, `name`, `campaign`, `status` active|paused, `via` product_page|buy_link|landing), `data.landings[]` (`published`, `via` links_to_product|visitors_went_on), `data.shopping[]`, `data.catalog_ads`, `data.checked` (`not_checked` names a platform it could not read). A read made outside a Session says so in `hints`: only a read that carried a Session and named an ad lets “Restart ads when a product is back” later stage turning a pause from it back on, for review. `--full` adds ids, accounts, campaign / ad group / ad set ids, the Google `resource`, the URL and `data.remembered`.
+
+**`stock-holds`:** `--product <ref>`, `--all` (resolved holds too). Compact: `data.resume[]` — the one command to stage per ad Baker may turn back on now (`{ ad, command }`); `data.tell_user[]` — one sentence per ad, and per piece of out-of-stock work still waiting for review, written for the marketer; `data.pages[]` — landings the out-of-stock run changed, with the `baker chats diff … --surface landings` read of those changes. With `--product` it speaks only of that product's ads, including the ones Baker did not pause when it ran out. `--full` adds the codes behind each sentence: `holds[]` with each `verdict` read live from the ad platform, `pending_sessions[]`, `recently_closed[]`, `not_paused[]`, `pages_changed[]`.
+
+**Refusals:** `NO_SHOPIFY_CONNECTION` — no store is connected; `error.fix.action` is `request_connection` (`{ platform: "shopify" }`). `SHOPIFY_NOT_AVAILABLE` — Shopify can't be connected on this Baker yet; `error.fix.action` is `continue_without`. Both exit 1.
+
+---
+
+### `baker shopify change | draft | changes | undo | tracking`
+
+**Changes to the connected store, staged on the Session (`BAKER_CHAT_ID`)** and made only when the user publishes it — reviewed first in the chat's Store tab. Nothing here calls Shopify to change anything mid-Session; every applied change can be put back by `undo`, through another publish.
+
+```bash
+baker shopify change product update the-snowboard --title "The Snowboard" --seo-title "…" --add-tags summer
+baker shopify change variant update 456 --sku SNOW-L --barcode 4006381333931 --weight 1.5 --weight-unit kg   # kg, g, lb or oz
+baker shopify change variant update 456 --price 18.95 --sale-price none          # money: the user says yes first
+baker shopify change field set product:the-snowboard custom.care --value "Hand wash"
+baker shopify change collection create --title "Summer boards" --products a,b    # shown on the online store unless --hidden
+baker shopify change collection hide summer-boards                                # also update, show, delete, add, remove
+baker shopify change discount create --code SPRING10 --percent 10 --ends <iso>   # money
+baker shopify change discount stop SPRING10                                       # money
+baker shopify change discount dates SPRING10 --starts <iso> --ends never          # money
+baker shopify change redirect create --from /old --to /new
+baker shopify change redirect remove /old
+baker shopify change campaign add --platform google-ads --account … --campaign … # show a Baker campaign in Shopify Marketing
+baker shopify change measurement reconnect                                        # the fix `tracking audit` names
+baker shopify change product update --json '[{"kind":"shopify.product.update","target":"<handle>","payload":{"addTags":["summer"]}}, …]'
+baker shopify draft list                                                          # also show <ref>, remove <ref>, clear
+baker shopify draft amend <ref> --patch '{…}'
+baker shopify changes --limit 20                                                  # applied changes, each with its changeId
+baker shopify undo <changeId>…                                                    # stage putting them back, as one batch
+baker shopify tracking audit                                                      # read-only: is the store's tracking right?
+```
+
+**Money.** A price, a sale price or a discount code changes money: the first call exits 1 with `NEEDS_USER_APPROVAL` and `error.fix.askUserQuestion` — the exact question to ask with AskUserQuestion. When the user answers "Yes, make these changes", run the same command again; a declined one is refused, still carrying the question in case the user asks for it again later. `amend` of a price asks again, and publish refuses any money change whose lines are not the approved ones.
+
+**Stage-time checks.** Each change is read against the live store when it is staged (the "before" the Store tab shows), checked, and refused with a reason the agent can act on — a collection whose undo could not rebuild it (rules, an image, custom fields, a discount or menu pointing at it), descriptions with scripts or frames, unknown products. Publish re-reads each target first: a change made in Shopify since staging is not overwritten; the op is marked failed with why. Up to 100 changes per call, 250 per Session.
+
+**Undo.** `changes` lists what Baker applied (`changeId`, `undoable`, why not). `undo` stages the inverses in one batch, read from the store as it was before each change; a money undo asks once for all its lines. A deleted collection comes back with the same address, content and products (as a new collection).
+
+**`tracking audit`:** reads only. `data.checks[]` (`measurement`, `theme_switch`, `visitor_on_orders`, `sales_reporting`, `consent`, `storefront`) each with a `status` and a `fix` that is `staged` (a command to stage), `merchant` (something the user does in Shopify) or `decision` (a choice only the user makes).
+
+**Refusals:** `SHOPIFY_PERMISSION_NEEDED` — the store has not allowed this kind of change yet; `error.fix.action` is `request_connection` (`{ platform: "shopify", reason }`) and the user allows it in Shopify. `NEEDS_USER_APPROVAL` — the money answer: `fix.action` `ask_user` with the question, or `continue_without` after a no. A payload with a key its kind doesn't take (`--json`, `draft amend --patch`) is refused naming the keys it takes. All exit 1.
+
+---
+
 ### `baker chats list | view | transcript | diff`
 
 Read-only inspection of **other Sessions (chats) on the same account** — so an agent can reuse prior work ("like we did in that other chat, but for X"). Same-account only; never crosses a company boundary and has no write surface.
@@ -3933,19 +4010,12 @@ baker canvas validate my-canvas.json
 #    or the same ad rendered once per aspect ratio instead of one hero + a terminal
 #    image_aspect_adapt (IMAGE_PARALLEL_FORMAT_RENDERS — separate renders drift in type,
 #    crop, and color, so the sizes stop matching).
-#    A generator prompt is measured with its {{slots}} filled from text nodes and local
-#    prompt.json/text ingests: past the model's character cap it is refused as
-#    PROMPT_OVER_MODEL_LIMIT, naming the node and the overshoot, before anything bills.
-#    `scaffold-static-ad` runs the same check on the prompt.json it writes and, when it is over,
-#    still writes the canvas and returns the overshoot in `hints[]` — trim prompt.json, then validate.
 
 # 2. Run (executes nodes, writes files to ./canvas/<run_id>/)
 baker canvas run my-canvas.json
 #    Advisory warnings print as `[warn] <CODE>: …` before anything bills.
 #    Only nodes reachable from the declared output execute (orphaned nodes are skipped,
 #    not billed). Add --keep-runs N to prune old r_* run dirs, keeping the N newest.
-#    A failed run reports `error.code: "input_invalid"` when the backend refused a node's
-#    own input (it fails the same way until the input changes), `"runtime"` otherwise.
 
 # 2b. Independent nodes ALREADY fan out in parallel — every node in the same
 #     topological layer (e.g. all the per-clip video_generate nodes) runs concurrently

package/dist/{chunk-ZI7TPBXB.js → chunk-2QXMPTHG.js}

@@ -1,10 +1,10 @@
 import {
   ApiError,
   apiGet
-} from "./chunk-MF7YA62W.js";
+} from "./chunk-UMIALY2G.js";
 import {
   getEnv
-} from "./chunk-HJEMOSPH.js";
+} from "./chunk-7YNOGIWQ.js";
 
 // src/error-handler.ts
 var REQUEST_CONNECTION_PLATFORM = {
@@ -297,4 +297,4 @@ export {
   writeAdsOutput,
   resolveCustomerId
 };
-//# sourceMappingURL=chunk-ZI7TPBXB.js.map
+//# sourceMappingURL=chunk-2QXMPTHG.js.map