@koda-sl/baker-cli 0.377.0-dev.f659d5b84 → 0.378.0-dev.87d538e4b

package/README.md

@@ -3313,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 |
@@ -3492,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
@@ -3683,6 +3688,12 @@ No write surface against HubSpot itself — a form's fields, redirect, or consen
 
 ---
 
+### Shopify sign-up offers
+
+`baker shopify signup-offers` lists active, ended and this chat's staged offers, permissions, codes given and recent refused sign-ups. Stage an offer with `baker shopify change signup-offer set welcome-10 --name "Welcome" --percent 10 --valid-days 14 --max-codes 1000`; use `--amount` instead of `--percent` for a fixed amount, `--products` or `--collections` for eligibility, and `--minimum`, `--ends`, `--prefix` or `--combines` for its terms. `--json` / `--file` also accept the terms. `baker shopify change signup-offer end welcome-10` stops giving new codes after Publish; existing codes keep their terms. Both changes require the user's approval.
+
+Forms use the `shopifyCustomer` side effect: map its `customer` fields with `baker flows map`, name an optional offer handle and show the result with `<ShopifySignupCode form="newsletter" />`. Email and SMS consent each require a separate optional, visible, initially unticked checkbox. Every lead receives at most one code for an offer; Shopify shows one discount per lead.
+
 ### `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.
@@ -3708,15 +3719,15 @@ baker shopify best-sellers --view repeat           # what sells (--view products
 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, each with a resume verdict
+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. `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.
+**`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` — the link for a page's buy button, 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).
+**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.
@@ -3732,14 +3743,52 @@ baker shopify stock-holds --product <id>           # ads Baker paused because th
 - **`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>` or an option id, 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), `data.remembered` (the read was kept for this Session — only then is a pause staged from it undone when the product is back). `--full` adds ids, accounts, campaign / ad group / ad set ids, the Google `resource` and the URL.
+**`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). `data.holds[]` — one per paused entity and product, with `verdict` (`resumable` · `still_out_of_stock` · `changed_since` · `already_active` · `still_promotes_out_of_stock` · `cannot_confirm`) read live from the ad platform; `data.pending_sessions[]` — out-of-stock work still waiting for review that would pause this product's ads.
+**`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.