@commercelayer/agent-cli 0.2.1 → 0.2.3

package/README.md

@@ -14,14 +14,17 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 ## Commands
 | Command | Does |
 | --- | --- |
-| `init [--name <business name>]` | Create a sandbox store, with no login. The name (the folder name when absent) names the organization; the org slug and store hostname derive from it, numbered when taken. Writes `store.yml` (a commented template) and `credentials`. Reuses the store if they exist. |
+| `init [--name <business name>]` | Create a sandbox store, with no login. The name (the folder name when absent) names the organization; the org slug and store hostname derive from it, numbered when taken. Writes `store.yml` (a commented template) and `credentials`, plus a short `AGENTS.md` and `CLAUDE.md` section (appended to an existing file, never twice) that sends later agents in the repo to [commercelayer.ai/skills.md](https://commercelayer.ai/skills.md). Reuses the store if they exist. |
 | `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, images, and the store's name, policies and theme. `missing_images` lists `img/<file>` references with no file in `.commercelayer/img/` (`apply` refuses them); `unused_images` lists files there that nothing references. |
-| `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused; While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
+| `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused. While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
 | `catalog pull` | Read the products from the catalog source in `store.yml` (a Supabase table, a Google Sheet or a Google Merchant Center feed) into `.commercelayer/products/catalog.csv`. Then `plan` and `apply` as usual. |
 | `storefront init [--force]` | Custom storefronts only. Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. Product images are the store's, at `/img/<file>` (from `.commercelayer/img/`, uploaded by `apply`); products with no image get a neutral tile. The site's own files go in `storefront/assets/`. Refuses to overwrite without the flag; with it, rewrites the three files. |
 | `storefront publish` | Custom storefronts only. Upload the folder at `storefront.path` (default `storefront`) to the store host, where it replaces the hosted theme, leaving out dotfiles. `/img/` on the store host is always the store's images, so files under the folder's `img/` are not served: publish lists them as `not_served`. |
 | `storefront check` | Custom storefronts only. Read the published storefront at the preview URL and check it: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product and none for unknown skus, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides (no dead `::part` rules), title, `lang`, viewport, description, and whether the folder changed since publish. Prints `{ status, summary, checks: [{ id, kind, status: pass\|warn\|fail, message, fix, items }], render }` and exits 1 when a check fails; warnings do not fail. `kind` is `static` today; a later rendering phase adds `render` checks and fills `render`. |
-| `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order and every step. |
+| `promotions list` · `show <id>` | The store's promotions, live in Commerce Layer: id, name, status, rules, actions, uses, dates; `managed: false` for ones made in the dashboard. |
+| `promotions create` · `update <id>` | Create a promotion, or replace one, from a spec in YAML or JSON on stdin or `-f <file>` (see [Promotions](#promotions)). Prints the promotion and the `orders test` call that checks it. |
+| `promotions enable <id>` · `disable <id>` · `delete <id>` | Turn a promotion on or off, or delete it (ask the human first). |
+| `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order, the `discounts` applied (promotions and codes, in minor units like the totals) and every step. |
 | `orders list` | The orders placed in the store, newest first, as UCP order entities. |
 | `orders show <id or number>` | One order. |
 | `ucp profile [--agent]` | The store's UCP business profile (`/.well-known/ucp`); with `--agent`, this CLI's own platform profile. |
@@ -65,6 +68,24 @@ policies:
   terms_of_service: https://example.com/terms
   returns: https://example.com/returns
 ```
+### Promotions
+Promotions are live settings in Commerce Layer, not store files: the `promotions` commands create and change them directly, and nothing about them is committed. A spec, in YAML or JSON on stdin or with `-f <file>`:
+
+```yaml
+id: welcome10            # the handle: lowercase letters, digits, dashes; unique
+name: Welcome, 10% off
+rules: [{ coupon: WELCOME10 }]
+actions: [{ percentage: 10 }]
+```
+
+Optional: `market` (a market code; without it, every market), `starts` and `ends` (a day, or a UTC time; a bare `ends` day runs to 23:59:59Z; without them the promotion is always on), `limit` (total uses), `priority` (lowest first), `exclusive`, `enabled`.
+
+- Rules, one of each kind at most, all matching: `coupon: CODE` or a list (8 to 40 letters, digits, `-`, `_`), `order_amount: { min }` (the items total), `skus: [...]` or `category: A > B`. A category becomes the skus of its products in store.yml when the command runs: after adding products to it, run `update` again.
+- Actions: `percentage: 10` (with `skus` or `category` to limit it), `fixed_amount: 5`, `free_shipping`, `fixed_price: { price, skus|category }`, `free_gift: { skus|category, quantity }`, `buy_x_pay_y: { x, y, cheapest_free?, skus|category }`. Actions without their own skus take the rule's. Amounts are in major units, like prices; in a store with several currencies, a promotion with an amount names its `market`. Commerce Layer gets one promotion per action.
+- `flex: { rules: [...] }` holds a Commerce Layer Rules Engine promotion as written (amounts in cents), in place of `rules` and `actions`. Sandboxes have no Rules Engine: `create` answers `flex_unavailable` and creates nothing.
+
+`list` and `show` print each promotion in the normalized form plus `status` (`active`, `scheduled`, `expired`, `disabled`, `used_up`) and `uses`; that output can be edited and sent back to `update`. Promotions made outside c11r (the dashboard, the sandbox's `SANDBOX10`) are listed with `managed: false` and Commerce Layer's id: `enable`, `disable` and `delete` work on them, `update` answers `promotion_not_managed`. `percentage` is a whole number from 1 to 100; a promotion takes at most 20 codes, a free gift at most 25 SKUs. More than 10 active promotion actions without a coupon gives a `warnings` entry (Commerce Layer applies 10). `orders test --code <CODE>` proves one: its `discounts` lists what was taken off, automatic promotions with `automatic: true`, and a code that applied nothing is a `discount_code_invalid` warning in `messages`.
+
 ### The products folder
 Beyond a handful of products, put the catalog in `.commercelayer/products/` and leave `products` out of `store.yml`. Every file in the folder is merged into the catalog by sku, in file-name order:
 - `<name>.yml`: a list of products in the shape above (one file per collection, or one per product, as you like).
@@ -96,7 +117,7 @@ One rule for images: `img/<file>` anywhere in `store.yml` (product `image_url`,
 
 A custom storefront replaces the theme: `storefront.path` in `store.yml` names its folder, `storefront init` writes a drop-in.js scaffold, `storefront publish` uploads it, `storefront check` checks it. Its pages link product images at `/img/`; its own files (fonts, icons, styles) go in `assets/`, not `img/`.
 
-Error codes: `invalid_theme`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
+Error codes: `invalid_theme`, `invalid_promotion`, `promotion_exists`, `promotion_not_managed`, `flex_unavailable`, `promotions_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:
 | What | Where |

package/dist/api/client.js

@@ -1,5 +1,5 @@
 // The client for the management API at api.commercelayer.ai.
-import { fail } from '../output.js';
+import { CliError, fail } from '../output.js';
 import { apiUrl, DEFAULT_API_URL, send } from './transport.js';
 export function createApi(auth) {
     const base = apiUrl() === 'stub' ? DEFAULT_API_URL : apiUrl().replace(/\/$/, '');
@@ -27,7 +27,38 @@ export function createApi(auth) {
             fail(err.code, err.message, err.hint);
         fail('api_error', `The API answered ${res.status}.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
     };
+    // Promotions: on an API older than them, the collection route is an unknown route (404 not_found).
+    const promotions = () => `${org()}/promotions`;
+    const one = (id) => `${promotions()}/${encodeURIComponent(id)}`;
+    const unsupported = async (call) => {
+        try {
+            return await call;
+        }
+        catch (e) {
+            if (e instanceof CliError && (e.code === 'not_found' || (e.code === 'api_error' && /\b404\b/.test(e.message))))
+                fail('promotions_unsupported', 'This API does not manage promotions yet.', 'Try again later; tell the human if it persists.');
+            throw e;
+        }
+    };
+    const found = async (id, call) => {
+        try {
+            return await call;
+        }
+        catch (e) {
+            if (e instanceof CliError && e.code === 'not_found')
+                fail('not_found', `There is no promotion ${id}.`, 'Run `c11r promotions list` for the ids, or `c11r promotions create` to make it.');
+            throw e;
+        }
+    };
     return {
+        listPromotions: () => unsupported(request('GET', promotions())),
+        createPromotion: (spec) => unsupported(request('POST', promotions(), spec)),
+        getPromotion: (id) => found(id, request('GET', one(id))),
+        updatePromotion: (id, spec) => found(id, request('PUT', one(id), spec)),
+        setPromotionEnabled: (id, enabled) => found(id, request('POST', `${one(id)}/${enabled ? 'enable' : 'disable'}`)),
+        deletePromotion: async (id) => {
+            await found(id, request('DELETE', one(id)));
+        },
         createSandbox: (name) => request('POST', '/sandboxes', { name }),
         getStore: () => request('GET', org()),
         applyStore: (body) => request('PUT', `${org()}/resources`, body),

package/dist/api/stub/management.js

@@ -39,6 +39,26 @@ function advance(r) {
     }
     delete r.pending;
 }
+function withDefaults(spec) {
+    return { ...spec, starts: spec.starts ?? '2000-01-01T00:00:00Z', ends: spec.ends ?? '2100-01-01T00:00:00Z', exclusive: spec.exclusive ?? false, enabled: spec.enabled ?? true };
+}
+/** As the API lists it: the spec plus status and uses. */
+function listed(p) {
+    const now = Date.now();
+    const status = !p.enabled ? 'disabled' : p.limit !== undefined && p.uses >= p.limit ? 'used_up' : Date.parse(p.ends) <= now ? 'expired' : Date.parse(p.starts) > now ? 'scheduled' : 'active';
+    return { ...p, status, managed: true };
+}
+/** The API checks skus against the last applied catalog. */
+function unknownSkus(r, spec) {
+    const known = r.applied?.products ?? {};
+    const where = [['rules.skus', spec.rules?.skus], ...(spec.actions ?? []).map((a, i) => [`actions[${i}].skus`, 'skus' in a ? a.skus : undefined])];
+    for (const [path, list] of where) {
+        const i = (list ?? []).findIndex((sku) => !(sku in known));
+        if (i >= 0)
+            return error(422, 'invalid_promotion', `${path}[${i}]: ${list[i]} is not a product of the store.`, 'Use skus of applied products: run `c11r apply` first if you just added them.');
+    }
+    return undefined;
+}
 export function handleManagement(req) {
     const db = readDb();
     const path = req.url.pathname;
@@ -140,6 +160,57 @@ export function handleManagement(req) {
         writeDb(db);
         return json(202, publicState(record));
     }
+    // Promotions: live, synchronous, keyed by id. Sandboxes have no Rules Engine.
+    if (rest === '/promotions' || rest.startsWith('/promotions/')) {
+        const store = (record.promotions ??= {});
+        const [, , rawId, verb] = rest.split('/');
+        const id = rawId === undefined ? undefined : decodeURIComponent(rawId);
+        const save = () => writeDb(db);
+        const flexRefused = (spec) => (spec.flex ? error(422, 'flex_unavailable', 'Flex promotions need the Rules Engine, which this organization does not have.', 'Tell the human flex promotions need a Commerce Layer plan with the Rules Engine; build the promotion from the standard rules and actions if you can.') : undefined);
+        if (id === undefined) {
+            if (req.method === 'GET')
+                return json(200, { promotions: Object.keys(store).sort().map((k) => listed(store[k])) });
+            if (req.method === 'POST') {
+                const spec = readJson(req);
+                if (store[spec.id])
+                    return error(409, 'promotion_exists', `There is already a promotion ${spec.id}.`, 'Use `c11r promotions update <id>` to change it, or pick another id.');
+                const refused = flexRefused(spec) ?? unknownSkus(record, spec);
+                if (refused)
+                    return refused;
+                store[spec.id] = { ...withDefaults(spec), uses: 0 };
+                save();
+                return json(201, listed(store[spec.id]));
+            }
+        }
+        else {
+            const p = store[id];
+            if (!p)
+                return error(404, 'not_found', `There is no promotion ${id}.`, 'Run `c11r promotions list`.');
+            if (verb === undefined && req.method === 'GET')
+                return json(200, listed(p));
+            if (verb === undefined && req.method === 'PUT') {
+                const spec = readJson(req);
+                if (spec.id !== id)
+                    return error(422, 'invalid_promotion', `id: the body has ${spec.id}, the path ${id}.`, 'An id never changes.');
+                const refused = flexRefused(spec) ?? unknownSkus(record, spec);
+                if (refused)
+                    return refused;
+                store[id] = { ...withDefaults(spec), uses: p.uses };
+                save();
+                return json(200, listed(store[id]));
+            }
+            if (verb === undefined && req.method === 'DELETE') {
+                delete store[id];
+                save();
+                return { status: 204, headers: {}, body: '' };
+            }
+            if ((verb === 'enable' || verb === 'disable') && req.method === 'POST') {
+                p.enabled = verb === 'enable';
+                save();
+                return json(200, listed(p));
+            }
+        }
+    }
     if (req.method === 'PUT' && rest === '/assets') {
         const { files } = readJson(req);
         let total = 0;

package/dist/api/stub/shopping.js

@@ -208,23 +208,85 @@ function buildLines(ctx, market, requested, existing = []) {
     });
     return { lines, messages };
 }
-/** Apply discount codes: the sandbox code is 10% off the items; anything else is rejected with a warning. */
-function discounts(ctx, body, lines, messages) {
-    if (!ctx.shared.has('dev.ucp.shopping.discount') || body.discounts === undefined)
-        return undefined;
-    const codes = (body.discounts.codes ?? []).map((c) => String(c));
+/** The promotions that match these lines and codes, as Commerce Layer applies them: by priority, an exclusive one alone. */
+function promotionDiscounts(ctx, market, lines, codes, shipping) {
+    const now = Date.now();
     const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
-    const appliedList = [];
-    codes.forEach((code, i) => {
-        if (code.toUpperCase() === SANDBOX_CODE) {
-            if (appliedList.length)
-                messages.push(warn('discount_code_already_applied', `${code} is already applied.`, `$.discounts.codes[${i}]`));
+    const upper = codes.map((c) => c.toUpperCase());
+    const used = new Set();
+    const matching = [];
+    for (const p of Object.values(ctx.record.promotions ?? {})) {
+        if (!p.enabled || p.flex || !p.actions || Date.parse(p.starts) > now || Date.parse(p.ends) <= now)
+            continue;
+        if (p.market && p.market !== market.code)
+            continue;
+        const r = p.rules ?? {};
+        const code = r.coupons?.find((c) => upper.includes(c.toUpperCase()));
+        if (r.coupons && !code)
+            continue;
+        if (code)
+            used.add(code.toUpperCase());
+        if (r.order_amount && subtotal < toMinor(r.order_amount.min, market.currency))
+            continue;
+        if (r.skus && !lines.some((l) => r.skus.includes(l.item.id)))
+            continue;
+        matching.push({ p, code });
+    }
+    matching.sort((a, b) => (a.p.priority ?? Infinity) - (b.p.priority ?? Infinity));
+    const exclusive = matching.find((m) => m.p.exclusive);
+    const applied = [];
+    for (const { p, code } of exclusive ? [exclusive] : matching) {
+        let amount = 0;
+        for (const a of p.actions) {
+            const on = (skus) => lines.filter((l) => !skus || skus.includes(l.item.id));
+            const units = (skus) => on(skus).flatMap((l) => Array(l.quantity).fill(l.item.price)).sort((x, y) => x - y);
+            if (a.type === 'percentage')
+                amount += Math.floor((on(a.skus).reduce((s, l) => s + l.totals[0].amount, 0) * a.value) / 100);
+            else if (a.type === 'fixed_amount')
+                amount += Math.min(toMinor(a.value, market.currency), subtotal);
+            else if (a.type === 'free_shipping')
+                amount += shipping ?? 0;
+            else if (a.type === 'fixed_price')
+                amount += on(a.skus).reduce((s, l) => s + Math.max(0, l.item.price - toMinor(a.price, market.currency)) * l.quantity, 0);
+            else if (a.type === 'free_gift')
+                amount += units(a.skus).slice(0, a.quantity).reduce((s, x) => s + x, 0);
+            else if (a.cheapest_free) {
+                const all = units(a.skus);
+                amount += all.slice(0, Math.floor(all.length / a.x) * (a.x - a.y)).reduce((s, x) => s + x, 0);
+            }
             else
-                appliedList.push({ code: SANDBOX_CODE, title: '10% off', amount: Math.floor(subtotal / 10), method: 'across' });
+                amount += on(a.skus).reduce((s, l) => s + Math.floor(l.quantity / a.x) * (a.x - a.y) * l.item.price, 0);
         }
-        else
+        if (amount > 0)
+            applied.push({ ...(code ? { code } : {}), title: p.name, amount, ...(code ? {} : { automatic: true }), method: 'across' });
+    }
+    return { applied, used };
+}
+/**
+ * Discounts: the store's promotions (automatic ones, and those whose code was entered) plus the
+ * sandbox code, 10% off the items. A code that applies nothing is reported with a warning.
+ */
+function discounts(ctx, body, lines, messages, market, shipping) {
+    if (!ctx.shared.has('dev.ucp.shopping.discount'))
+        return undefined;
+    const codes = (body.discounts?.codes ?? []).map((c) => String(c));
+    const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
+    const { applied: appliedList, used } = promotionDiscounts(ctx, market, lines, codes, shipping);
+    const seen = new Set();
+    codes.forEach((code, i) => {
+        const key = code.toUpperCase();
+        if (seen.has(key))
+            messages.push(warn('discount_code_already_applied', `${code} is already applied.`, `$.discounts.codes[${i}]`));
+        else if (key === SANDBOX_CODE)
+            appliedList.push({ code: SANDBOX_CODE, title: '10% off', amount: Math.floor(subtotal / 10), method: 'across' });
+        else if (!used.has(key))
             messages.push(warn('discount_code_invalid', `${code} is not a valid code.`, `$.discounts.codes[${i}]`));
+        else if (!appliedList.some((d) => d.code?.toUpperCase() === key))
+            messages.push(warn('discount_code_invalid', `${code} does not apply to this order.`, `$.discounts.codes[${i}]`));
+        seen.add(key);
     });
+    if (body.discounts === undefined && !appliedList.length)
+        return undefined;
     return { codes, applied: appliedList };
 }
 function consent(ctx, buyer) {
@@ -251,7 +313,7 @@ function totals(lines, discount, shipping) {
 function cartFrom(ctx, body, existing) {
     const market = pickMarket(ctx, body.context ?? existing?.context);
     const { lines, messages } = buildLines(ctx, market, body.line_items, existing?.line_items);
-    const discount = discounts(ctx, body, lines, messages);
+    const discount = discounts(ctx, body, lines, messages, market);
     const cart = {
         ucp: envelope(ctx, 'cart'),
         id: existing?.id ?? id('cart'),
@@ -315,11 +377,6 @@ function evaluate(ctx, ck, requested) {
     ck.line_items = lines;
     if (lines.length === 0)
         messages.push(err('item_unavailable', 'The checkout has no purchasable items.', '$.line_items'));
-    const discount = discounts(ctx, requested, lines, messages);
-    if (discount)
-        ck.discounts = discount;
-    else
-        delete ck.discounts;
     if (!ck.buyer?.email)
         messages.push(err('missing', 'An email address is needed for the order confirmation.', '$.buyer.email'));
     let shipping;
@@ -353,6 +410,11 @@ function evaluate(ctx, ck, requested) {
     }
     else
         shipping = 0;
+    const discount = discounts(ctx, requested, lines, messages, market, shipping);
+    if (discount)
+        ck.discounts = discount;
+    else
+        delete ck.discounts;
     ck.totals = totals(lines, discount, shipping);
     const blocking = messages.some((m) => m.type === 'error');
     ck.status = blocking ? 'incomplete' : 'ready_for_complete';

package/dist/bin.js

@@ -4,13 +4,17 @@
 // Output is always JSON; exit code 1 on an error or a failed check.
 import * as cmd from './commands.js';
 import { CliError, print } from './output.js';
-const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code']);
+const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file']);
 const argv = process.argv.slice(2);
 const flags = new Set();
 const values = {};
 const args = [];
 for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
+    if (a === '-f' && i + 1 < argv.length) {
+        values.file = argv[++i];
+        continue;
+    }
     if (!a.startsWith('--')) {
         args.push(a);
         continue;
@@ -53,6 +57,20 @@ async function run() {
             if (sub === 'check')
                 return cmd.storefrontCheckCmd();
             throw new CliError('unknown_command', `There is no command "storefront ${sub ?? ''}".`, 'Use `c11r storefront init`, `storefront publish` or `storefront check`.');
+        case 'promotions':
+            if (sub === 'list')
+                return cmd.promotionsList();
+            if (sub === 'show')
+                return cmd.promotionsShow(args[2]);
+            if (sub === 'create')
+                return cmd.promotionsCreate(values);
+            if (sub === 'update')
+                return cmd.promotionsUpdate(args[2], values);
+            if (sub === 'enable' || sub === 'disable')
+                return cmd.promotionsEnable(args[2], sub === 'enable');
+            if (sub === 'delete')
+                return cmd.promotionsDelete(args[2]);
+            throw new CliError('unknown_command', `There is no command "promotions ${sub ?? ''}".`, 'Use `c11r promotions list`, `show <id>`, `create`, `update <id>`, `enable <id>`, `disable <id>` or `delete <id>`.');
         case 'orders':
             if (sub === 'test')
                 return cmd.ordersTest(flags, values);

package/dist/commands.js

@@ -4,12 +4,14 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createApi } from './api/client.js';
-import { ignoreCredentials, paths, readCredentials, requireCredentials, writeCredentials } from './files.js';
+import { ignoreCredentials, paths, readCredentials, requireCredentials, writeAgentNotes, writeCredentials } from './files.js';
 import { CliError, fail, progress } from './output.js';
 import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
 import { storefrontFiles } from './storefront.js';
 import { imageNotes, planAssets, uploadAssets } from './assets.js';
 import { pull } from './catalog.js';
+import { ACTIVE_LIMIT, activeWithoutCoupon, checkPromotion } from './promotions.js';
+import YAML from 'yaml';
 import { storefrontCheck } from './check.js';
 import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
@@ -18,14 +20,21 @@ import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
 /** The package version, read from package.json so a release bumps it in one place. */
 export const VERSION = createRequire(import.meta.url)('../package.json').version;
 export const HELP = {
-    init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials. Reuses the store if store.yml already exists.',
+    init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials, and a section in AGENTS.md and CLAUDE.md (created, or appended once) that points later agents in this repo to the skills: commit them. Reuses the store if store.yml already exists.',
     plan: 'Show what apply would create, update or delete: markets, products, images, and the store\'s name, policies and theme; missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
     apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/: markets, products, the theme (its settings, and the images in .commercelayer/img/ that the theme and products reference, uploaded when new or changed), name and policies. The store\'s website is live at preview_url after apply. Refuses deletes unless --allow-delete is given. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
     'catalog pull': 'Read the products from the catalog source in store.yml (catalog: { source: supabase | sheets | merchant, url, table }) and write them to .commercelayer/products/catalog.csv; then plan and apply as usual. Columns: sku, name, description, image_url, category and one price column per market currency, in lowercase (eur, usd). Supabase reads C11R_SUPABASE_URL and C11R_SUPABASE_KEY (the anon key) from .commercelayer/credentials or the environment; a Google Sheet needs its CSV link or a link anyone can open; a Merchant Center feed is RSS/XML or TSV.',
     'storefront init': 'Custom storefronts only: the hosted theme needs none of this (set theme: in store.yml and apply). Write a static storefront on drop-in.js, no build step: storefront/index.html (the products by category, a minicart that opens on add to cart, the hosted cart and checkout, and a product page at #/p/<sku>), styles.css (theme tokens first) and app.js. Product images are the store\'s, at /img/ (.commercelayer/img/, uploaded by apply); the site\'s own files go in storefront/assets/. Refuses to overwrite unless --force is given.',
     'storefront check': 'Custom storefronts only. Check the published storefront at the preview URL: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides, title, lang, viewport, description, and whether the folder changed since publish. Prints { status, summary, checks: [{ id, kind, status: pass|warn|fail, message, fix, items }] }; exits 1 when a check fails.',
     'storefront publish': 'Custom storefronts only: upload the storefront folder (store.yml storefront.path, default storefront) to the preview URL, where it replaces the hosted theme.',
-    'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline.',
+    'promotions list': 'The store\'s promotions, live in Commerce Layer (not in store files): id, name, status (active, scheduled, expired, disabled, used_up), rules, actions, uses, starts, ends; managed: false marks one made in the dashboard (its id is Commerce Layer\'s), which can be enabled, disabled or deleted but not updated. warnings flags more than 10 active promotion actions without a coupon (Commerce Layer applies 10).',
+    'promotions show': 'One promotion by id, as list shows it: c11r promotions show <id>.',
+    'promotions create': "Create a promotion from a spec in YAML or JSON, on stdin (c11r promotions create <<'EOF' ... EOF) or with -f <file>: { id, name, market, starts, ends, limit, priority, exclusive, enabled, rules: [{ coupon | order_amount: { min } | skus | category }], actions: [{ percentage | fixed_amount | free_shipping | fixed_price | free_gift | buy_x_pay_y }] } or flex: { rules } in place of rules and actions. id is the handle, unique. Amounts are in the market currency, in major units. A category becomes the skus of its products in store.yml now: after adding products to it, run update again. Errors: invalid_promotion (the message starts with the path in the spec), promotion_exists, flex_unavailable (no Rules Engine: nothing is created). Check it with orders test --code.",
+    'promotions update': 'Replace a promotion with a whole spec, same as create, on stdin or -f <file>: c11r promotions update <id>. The id stays the same. What show prints can be edited and sent back. A promotion made in the dashboard (managed: false) cannot be updated: promotion_not_managed; enable, disable and delete work on it.',
+    'promotions enable': 'Turn a promotion on: c11r promotions enable <id>.',
+    'promotions disable': 'Turn a promotion off without deleting it: c11r promotions disable <id>.',
+    'promotions delete': 'Delete a promotion from Commerce Layer: c11r promotions delete <id>. Ask the human first; to pause one, disable it.',
+    'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline. discounts lists what promotions and codes took off; a code that applied nothing is a discount_code_invalid warning in messages.',
     'orders list': 'List the orders placed in the store, newest first, as UCP order entities.',
     'orders show': 'Show one order: c11r orders show <id or number>.',
     'ucp profile': 'Show the store\'s UCP business profile (/.well-known/ucp). With --agent, this CLI\'s own platform profile instead.',
@@ -53,7 +62,8 @@ export async function init(values) {
     const existing = readCredentials();
     if (existing && fs.existsSync(paths.store)) {
         const s = await createApi(existing).getStore();
-        return { status: 'reused', org: s.org, claim_url: s.claim_url, expires_at: s.expires_at, preview_url: s.preview_url };
+        const notes = writeAgentNotes();
+        return { status: 'reused', org: s.org, claim_url: s.claim_url, expires_at: s.expires_at, preview_url: s.preview_url, files: notes.length ? notes : undefined };
     }
     // The business name becomes the organization's name; the platform derives the
     // org slug (and so the store hostname) from it. The folder name is the fallback.
@@ -68,6 +78,7 @@ export async function init(values) {
     const files = [paths.store, paths.credentials];
     if (ignoreCredentials())
         files.push('.gitignore');
+    files.push(...writeAgentNotes());
     return {
         status: 'created',
         org: sandbox.org,
@@ -254,8 +265,10 @@ export async function ordersTest(flags, values) {
     return {
         status: p.checkout.status === 'completed' ? 'paid' : p.checkout.status,
         order: p.order,
+        // What the promotions took off, in minor units like the totals; a code that applied nothing is in messages.
+        discounts: (p.checkout.discounts ?? p.ready.discounts)?.applied?.length ? (p.checkout.discounts ?? p.ready.discounts).applied : undefined,
         checkout_id: p.checkout.id,
-        messages: p.checkout.messages,
+        messages: p.checkout.messages ?? p.ready.messages,
         payment_handler: 'ai.commercelayer.sandbox (test payments only)',
         steps: p.steps,
     };
@@ -334,3 +347,89 @@ export async function claim() {
         next: 'Ask the human to open verification_url and enter user_code, then run `c11r status`.',
     };
 }
+// ---------- promotions: live settings in Commerce Layer, not store files
+/** The fields list, show and the writes print, in a stable order. */
+const READ_ONLY = ['status', 'uses', 'managed'];
+/** The spec from -f <file> or stdin, YAML or JSON, validated against store.yml's markets and products. */
+async function readSpec(values) {
+    let text = "";
+    if (values.file) {
+        if (!fs.existsSync(values.file))
+            fail('missing_argument', `There is no file ${values.file}.`, 'Give the promotion as YAML or JSON with -f <file>, or on stdin.');
+        text = fs.readFileSync(values.file, 'utf8');
+    }
+    else if (!process.stdin.isTTY) {
+        // A stream read: readFileSync(0) fails with EAGAIN on a pipe whose writer is still running.
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        text = Buffer.concat(chunks).toString('utf8');
+    }
+    else
+        fail('missing_argument', 'No promotion given.', "Give the promotion as YAML or JSON on stdin (c11r promotions create <<'EOF' ... EOF) or with -f <file>.");
+    if (!text.trim())
+        fail('missing_argument', 'No promotion given: the input is empty.', "Give the promotion as YAML or JSON on stdin (c11r promotions create <<'EOF' ... EOF) or with -f <file>.");
+    let raw;
+    try {
+        raw = YAML.parse(text);
+    }
+    catch (e) {
+        fail('invalid_promotion', `promotion: not valid YAML or JSON: ${e.message.split('\n')[0]}`, 'Fix the syntax and run the command again.');
+    }
+    // What show prints can be edited and sent back: the read-only fields are dropped.
+    if (raw && typeof raw === 'object' && !Array.isArray(raw))
+        for (const k of READ_ONLY)
+            delete raw[k];
+    const store = loadStore();
+    return checkPromotion(raw, store.markets, store.products);
+}
+/** Warn when more promotion actions without a coupon are live than Commerce Layer applies. */
+async function activeWarning(api) {
+    const { promotions } = await api.listPromotions();
+    const live = promotions.filter((p) => p.status === 'active' || p.status === 'scheduled');
+    const active = activeWithoutCoupon(live);
+    return active.count > ACTIVE_LIMIT ? [`${active.count} promotions without a coupon are active or scheduled (one per action, in ${active.ids.join(', ')}): Commerce Layer applies at most ${ACTIVE_LIMIT}, the ones with the lowest priority number. Give the rest a coupon, an end date, or disable them.`] : undefined;
+}
+const checkNext = (p) => p.rules?.coupons?.length ? `Check it: c11r orders test --code ${p.rules.coupons[0]}, and read discounts.` : p.flex ? undefined : 'Check it: c11r orders test with an order that matches the rules (--sku, --quantity), and read discounts.';
+export async function promotionsList() {
+    const api = createApi(requireCredentials());
+    const { promotions } = await api.listPromotions();
+    return { count: promotions.length, promotions, warnings: await activeWarning(api) };
+}
+export async function promotionsShow(id) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions show <id>`; `c11r promotions list` has the ids.');
+    return createApi(requireCredentials()).getPromotion(id);
+}
+export async function promotionsCreate(values) {
+    const api = createApi(requireCredentials());
+    const spec = await readSpec(values);
+    const created = await api.createPromotion(spec);
+    return { status: 'created', promotion: created, warnings: await activeWarning(api), next: checkNext(created) };
+}
+export async function promotionsUpdate(id, values) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions update <id>` with the whole promotion on stdin or -f <file>.');
+    const api = createApi(requireCredentials());
+    // A promotion made outside c11r has Commerce Layer's id, which is no spec id: say what it is first.
+    if ((await api.getPromotion(id)).managed === false)
+        fail('promotion_not_managed', `Promotion ${id} was made outside c11r, in the dashboard.`, 'Create a c11r promotion with `c11r promotions create` and delete this one with `c11r promotions delete`, or edit it in the dashboard.');
+    const spec = await readSpec(values);
+    if (spec.id !== id)
+        fail('invalid_promotion', `id: the spec has id ${spec.id}, the command ${id}.`, 'An id never changes: use the same id, or create a new promotion and delete the old one.');
+    const updated = await api.updatePromotion(id, spec);
+    return { status: 'updated', promotion: updated, warnings: await activeWarning(api), next: checkNext(updated) };
+}
+export async function promotionsEnable(id, enabled) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', `Use \`c11r promotions ${enabled ? 'enable' : 'disable'} <id>\`.`);
+    const api = createApi(requireCredentials());
+    const p = await api.setPromotionEnabled(id, enabled);
+    return { status: enabled ? 'enabled' : 'disabled', promotion: p, warnings: enabled ? await activeWarning(api) : undefined };
+}
+export async function promotionsDelete(id) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions delete <id>`, after asking the human.');
+    await createApi(requireCredentials()).deletePromotion(id);
+    return { status: 'deleted', id };
+}

package/dist/files.js

@@ -61,3 +61,24 @@ export function ignoreCredentials() {
     fs.appendFileSync('.gitignore', `${sep}${paths.credentials}\n`);
     return true;
 }
+/** The note that sends a future agent in this repo to the skills. No skill names: it never goes stale. */
+const AGENT_NOTE_HEADING = '# Store on Commerce Layer';
+export const AGENT_NOTE = `${AGENT_NOTE_HEADING}
+This store is managed with \`c11r\` (\`npx @commercelayer/agent-cli\`), configured in \`.commercelayer/store.yml\`. Before any task about the store (products, prices, markets, storefront, orders, promotions, agents), fetch \`https://commercelayer.ai/skills.md\` with \`curl -fsSL\` and load the skill for the task from \`skills/<name>.md\`; follow it rather than calling the Commerce Layer API directly. If \`.commercelayer/store.yml\` is missing, start from \`https://commercelayer.ai/start.md\`.
+`;
+/**
+ * Write the note to AGENTS.md and CLAUDE.md (Claude Code reads that name) in the repo root:
+ * created when absent, appended as a section when the file has other content, left alone
+ * when the section is already there. Returns the files written.
+ */
+export function writeAgentNotes() {
+    const written = [];
+    for (const file of ['AGENTS.md', 'CLAUDE.md']) {
+        const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+        if (before.split('\n').some((line) => line.trim() === AGENT_NOTE_HEADING))
+            continue;
+        fs.writeFileSync(file, before.trim() ? `${before.replace(/\s*$/, '')}\n\n${AGENT_NOTE}` : AGENT_NOTE);
+        written.push(file);
+    }
+    return written;
+}

package/dist/promotions.js

@@ -0,0 +1,291 @@
+// promotions: in store.yml. The CLI validates the YAML sugar (single-key rules and actions,
+// categories, date-only days) and sends one normalized object per promotion in PUT /resources;
+// the API maps each to Commerce Layer promotions. Amounts stay in major units, like prices;
+// flex rules pass through as written (Rules Engine syntax, cents).
+import { fail } from './output.js';
+/** Commerce Layer needs both dates: without them the promotion runs from 2000 to 2100. */
+export const DEFAULT_STARTS = '2000-01-01T00:00:00Z';
+export const DEFAULT_ENDS = '2100-01-01T00:00:00Z';
+/** Promotions without a coupon that can be active at once: Commerce Layer's limit. */
+export const ACTIVE_LIMIT = 10;
+const KEYS = ['id', 'name', 'market', 'starts', 'ends', 'limit', 'priority', 'exclusive', 'enabled', 'rules', 'actions', 'flex'];
+const RULES = ['coupon', 'order_amount', 'skus', 'category'];
+const ACTIONS = ['percentage', 'fixed_amount', 'free_shipping', 'fixed_price', 'free_gift', 'buy_x_pay_y'];
+const SHAPE_HINT = 'See the promotions skill for the shape: https://commercelayer.ai/skills/promotions.md';
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const isInt = (v, min) => Number.isInteger(v) && v >= min;
+const list = (v) => (Array.isArray(v) ? v : [v]);
+/** A date or a date-time, as ISO UTC. A bare day starts at 00:00:00Z and ends at 23:59:59Z. */
+function isoDate(v, end, bad) {
+    const s = v instanceof Date ? v.toISOString().replace(/\.000Z$/, 'Z') : String(v);
+    const hint = 'Write a day, 2026-12-01, or a time in UTC, 2026-12-01T09:00:00Z.';
+    if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+        if (Number.isNaN(Date.parse(s)))
+            bad(`"${s}" is not a date.`, hint);
+        return `${s}T${end ? '23:59:59' : '00:00:00'}Z`;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(s) || Number.isNaN(Date.parse(s)))
+        bad(`"${s}" is not a date.`, hint);
+    return new Date(s).toISOString().replace(/\.000Z$/, 'Z');
+}
+/**
+ * The normalized shape (what list and show print) back to the YAML shorthand, so a promotion
+ * read with show can be edited and sent to update: rules as an object, actions with a type.
+ */
+function fromListed(p) {
+    const out = { ...p };
+    if (isObj(p.rules)) {
+        const r = p.rules;
+        out.rules = [
+            ...(r.coupons !== undefined ? [{ coupon: r.coupons }] : []),
+            ...(r.order_amount !== undefined ? [{ order_amount: r.order_amount }] : []),
+            ...(r.skus !== undefined ? [{ skus: r.skus }] : []),
+            ...Object.keys(r).filter((k) => !['coupons', 'order_amount', 'skus'].includes(k)).map((k) => ({ [k]: r[k] })),
+        ];
+    }
+    if (Array.isArray(p.actions)) {
+        out.actions = p.actions.map((a) => {
+            if (!isObj(a) || typeof a.type !== 'string')
+                return a;
+            const { type, ...rest } = a;
+            if (type === 'free_shipping')
+                return 'free_shipping';
+            if (type === 'percentage' || type === 'fixed_amount') {
+                const { value, ...targets } = rest;
+                return { [type]: value, ...targets };
+            }
+            return { [type]: rest };
+        });
+    }
+    return out;
+}
+/**
+ * Validate one promotion spec (YAML or JSON, as given to promotions create or update) and
+ * normalize it to the wire shape, or fail invalid_promotion naming the path inside the spec.
+ * Categories become their products' skus as they are now, from store.yml.
+ */
+export function checkPromotion(raw, markets, products) {
+    const skus = new Set(products.map((p) => p.sku));
+    const currencies = new Set(markets.map((m) => m.currency));
+    const at = 'promotion';
+    const bad = (msg, hint, path = at) => fail('invalid_promotion', `${path}: ${msg}`, hint);
+    {
+        const p = raw;
+        if (!isObj(p))
+            bad('is not a map.', `A promotion is a map with id, rules and actions. ${SHAPE_HINT}`);
+        const pr = fromListed(p);
+        if (typeof pr.id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(pr.id))
+            bad(`id is ${pr.id === undefined ? 'missing' : `"${String(pr.id)}"`}.`, 'Give the promotion an id of lowercase letters, digits and dashes, such as welcome10: the handle for show, update, enable, disable and delete.');
+        const id = pr.id;
+        for (const k of Object.keys(pr))
+            if (!KEYS.includes(k))
+                bad(`unknown key ${k}.`, `A promotion's keys are ${KEYS.join(', ')}.`);
+        const promo = { id, name: pr.name === undefined ? id : String(pr.name), starts: DEFAULT_STARTS, ends: DEFAULT_ENDS, exclusive: false, enabled: true };
+        if (!promo.name.trim() || promo.name.length > 255)
+            bad('name is empty or longer than 255 characters.', 'Write a short name the human will recognize in the dashboard.');
+        let currency;
+        if (pr.market !== undefined) {
+            const m = markets.find((x) => x.code === pr.market);
+            if (!m)
+                bad(`market ${String(pr.market)} is not in markets.`, `Use the code of one of the store's markets: ${markets.map((x) => x.code).join(', ')}.`);
+            promo.market = m.code;
+            currency = m.currency;
+        }
+        if (pr.starts !== undefined)
+            promo.starts = isoDate(pr.starts, false, (m, h) => bad(`starts ${m}`, h));
+        if (pr.ends !== undefined)
+            promo.ends = isoDate(pr.ends, true, (m, h) => bad(`ends ${m}`, h));
+        if (Date.parse(promo.ends) <= Date.parse(promo.starts))
+            bad('ends is not after starts.', 'Make the end date later than the start date.');
+        if (pr.limit !== undefined) {
+            if (!isInt(pr.limit, 1))
+                bad(`limit is ${String(pr.limit)}.`, 'limit is the total number of uses, a whole number of 1 or more.');
+            promo.limit = pr.limit;
+        }
+        if (pr.priority !== undefined) {
+            if (!isInt(pr.priority, 1))
+                bad(`priority is ${String(pr.priority)}.`, 'priority is a whole number of 1 or more; the lowest runs first.');
+            promo.priority = pr.priority;
+        }
+        for (const k of ['exclusive', 'enabled']) {
+            if (pr[k] !== undefined && typeof pr[k] !== 'boolean')
+                bad(`${k} is ${String(pr[k])}.`, `${k} is true or false.`);
+            if (pr[k] !== undefined)
+                promo[k] = pr[k];
+        }
+        if (pr.flex !== undefined) {
+            if (pr.rules !== undefined || pr.actions !== undefined)
+                bad('has flex and rules or actions.', 'A flex promotion keeps its rules and actions inside flex: remove the other rules and actions, or remove flex.');
+            const f = pr.flex;
+            if (!isObj(f) || !Array.isArray(f.rules) || f.rules.length === 0)
+                bad('flex has no rules.', 'Write flex: { rules: [...] }, each rule with conditions and actions. See docs.commercelayer.io/rules-engine.');
+            f.rules.forEach((r, j) => {
+                const path = `flex.rules[${j}]`;
+                if (!isObj(r) || !Array.isArray(r.conditions) || !r.conditions.length || !Array.isArray(r.actions) || !r.actions.length)
+                    bad('needs a list of conditions and a list of actions.', 'Each flex rule has conditions (field, matcher, value) and actions (type, selector, value).', path);
+            });
+            promo.flex = f;
+            return promo;
+        }
+        // Rules: a list of single-key maps; none means every order.
+        const rules = {};
+        let ruleSkus;
+        const seen = new Set();
+        const resolve = (v, kind, path) => {
+            if (kind === 'category') {
+                const name = String(v).split('>').map((s) => s.trim()).filter(Boolean).join(' > ');
+                const found = products.filter((x) => x.category === name || x.category?.startsWith(`${name} > `)).map((x) => x.sku);
+                if (!name || !found.length)
+                    bad(`no product is in category "${String(v)}".`, `Use a category of the store's products, written as in the products: ${[...new Set(products.map((x) => x.category).filter(Boolean))].join(', ') || 'none has a category yet'}.`, path);
+                return found.sort();
+            }
+            const l = list(v).map(String);
+            if (!l.length)
+                bad('skus is empty.', 'List one or more SKUs.', path);
+            for (const s of l)
+                if (!skus.has(s))
+                    bad(`${s} is not a product.`, 'Use SKUs of the store\'s products.', path);
+            return [...new Set(l)].sort();
+        };
+        const rawRules = pr.rules === undefined ? [] : pr.rules;
+        if (!Array.isArray(rawRules))
+            bad('rules is not a list.', `Write rules as a list: rules: [{ coupon: CODE }]. ${SHAPE_HINT}`);
+        rawRules.forEach((r, j) => {
+            const path = `rules[${j}]`;
+            if (!isObj(r) || Object.keys(r).length !== 1)
+                bad('is not a single rule.', `Each rule is one of ${RULES.join(', ')}, written as a one-key map: { coupon: CODE }.`, path);
+            const [k, v] = Object.entries(r)[0];
+            if (!RULES.includes(k))
+                bad(`unknown rule ${k}.`, `Rules are ${RULES.join(', ')}. For anything else, write a flex promotion.`, path);
+            const kind = k === 'category' ? 'skus' : k;
+            if (seen.has(kind))
+                bad(`has two ${kind === 'skus' ? 'skus or category' : k} rules.`, kind === 'skus' ? 'Use skus or category once per promotion: list every SKU in one rule, or make two promotions.' : `Use one ${k} rule per promotion; a coupon rule takes a list of codes.`, path);
+            seen.add(kind);
+            if (k === 'coupon') {
+                const l = list(v).map(String);
+                for (const c of l) {
+                    if (!/^[A-Za-z0-9_-]{8,40}$/.test(c))
+                        bad(`coupon "${c}" is not 8 to 40 letters, digits, - or _.`, 'Commerce Layer codes have 8 to 40 characters: WELCOME10, not WELCOME.', path);
+                }
+                if (!l.length)
+                    bad('coupon has no code.', 'Write coupon: CODE, or a list of codes.', path);
+                if (new Set(l).size > 20)
+                    bad(`coupon has ${new Set(l).size} codes.`, 'A promotion takes at most 20 codes: split them across promotions.', path);
+                rules.coupons = [...new Set(l)];
+            }
+            else if (k === 'order_amount') {
+                if (isObj(v) && v.max !== undefined)
+                    bad('order_amount has a max.', 'Commerce Layer promotions match a minimum order amount only: remove max, or write a flex promotion.', path);
+                if (!isObj(v) || Object.keys(v).some((x) => x !== 'min') || !isNum(v.min) || v.min <= 0)
+                    bad('order_amount needs min, a positive amount.', 'Write order_amount: { min: 50 }, the minimum items total, in the market currency, in major units.', path);
+                rules.order_amount = { min: v.min };
+            }
+            else {
+                ruleSkus = resolve(v, k, path);
+                rules.skus = ruleSkus;
+            }
+        });
+        // Actions: one or more, a single-key map or the bare free_shipping.
+        if (!Array.isArray(pr.actions) || pr.actions.length === 0)
+            bad('has no actions.', `Add actions: what the promotion does, such as actions: [{ percentage: 10 }]. ${SHAPE_HINT}`);
+        const actions = [];
+        const types = new Set();
+        let needsCurrency = Boolean(rules.order_amount);
+        pr.actions.forEach((a, j) => {
+            const path = `actions[${j}]`;
+            const entry = a === 'free_shipping' ? { free_shipping: true } : a;
+            if (!isObj(entry))
+                bad('is not an action.', `Each action is one of ${ACTIONS.join(', ')}: { percentage: 10 }, or free_shipping.`, path);
+            const [k, v] = Object.entries(entry)[0] ?? [];
+            if (!ACTIONS.includes(k))
+                bad(`unknown action ${k ?? '(none)'}.`, `Actions are ${ACTIONS.join(', ')}. For anything else, write a flex promotion.`, path);
+            if (types.has(k))
+                bad(`has two ${k} actions.`, 'Use each action once per promotion.', path);
+            types.add(k);
+            const extra = Object.keys(entry).filter((x) => x !== k);
+            // Targets: skus or category next to the action, or inside its map; else the rule's.
+            const target = (o, required) => {
+                if (o.skus !== undefined && o.category !== undefined)
+                    bad('has skus and category.', 'Use one of them.', path);
+                if (o.skus !== undefined)
+                    return resolve(o.skus, 'skus', path);
+                if (o.category !== undefined)
+                    return resolve(o.category, 'category', path);
+                if (required && !ruleSkus)
+                    bad(`${k} needs the SKUs it applies to.`, `Add skus: [...] or category: ... to the action, or a skus or category rule.`, path);
+                return ruleSkus;
+            };
+            const only = (o, allowed) => {
+                for (const x of Object.keys(o))
+                    if (!allowed.includes(x))
+                        bad(`unknown key ${x} in ${k}.`, `${k} takes ${allowed.join(', ')}.`, path);
+            };
+            if (k === 'percentage') {
+                only(entry, ['percentage', 'skus', 'category']);
+                if (!isInt(v, 1) || v > 100)
+                    bad(`percentage is ${String(v)}.`, 'percentage is a whole number from 1 to 100: 10 is 10% off. To make shipping free, use free_shipping.', path);
+                const t = target(entry, false);
+                actions.push({ type: 'percentage', value: v, ...(t ? { skus: t } : {}) });
+            }
+            else if (k === 'fixed_amount') {
+                only(entry, ['fixed_amount']);
+                if (!isNum(v) || v <= 0)
+                    bad(`fixed_amount is ${String(v)}.`, 'fixed_amount is the amount off the order, in major units: 5 is 5 euros.', path);
+                actions.push({ type: 'fixed_amount', value: v });
+                needsCurrency = true;
+            }
+            else if (k === 'free_shipping') {
+                if (extra.length || (v !== true && v !== null && !(isObj(v) && !Object.keys(v).length)))
+                    bad('free_shipping takes no settings.', 'Write free_shipping on its own.', path);
+                actions.push({ type: 'free_shipping' });
+            }
+            else {
+                if (extra.length)
+                    bad(`${k} has keys next to it: ${extra.join(', ')}.`, `Put them inside: ${k}: { ... }.`, path);
+                if (!isObj(v))
+                    bad(`${k} is not a map.`, SHAPE_HINT, path);
+                const o = v;
+                if (k === 'fixed_price') {
+                    only(o, ['price', 'skus', 'category']);
+                    if (!isNum(o.price) || o.price <= 0)
+                        bad(`fixed_price.price is ${String(o.price)}.`, 'price is the price the SKUs sell at, in major units: 9.90.', path);
+                    actions.push({ type: 'fixed_price', price: o.price, skus: target(o, true) });
+                    needsCurrency = true;
+                }
+                else if (k === 'free_gift') {
+                    only(o, ['skus', 'category', 'quantity']);
+                    if (o.skus === undefined && o.category === undefined)
+                        bad('free_gift needs the SKUs given away.', 'Write free_gift: { skus: [GIFT-SKU], quantity: 1 }.', path);
+                    if (o.quantity !== undefined && !isInt(o.quantity, 1))
+                        bad(`free_gift.quantity is ${String(o.quantity)}.`, 'quantity is a whole number of 1 or more.', path);
+                    const gifts = target(o, true);
+                    if (gifts.length > 25)
+                        bad(`free_gift has ${gifts.length} skus.`, 'A free gift takes at most 25 SKUs: narrow the list or the category.', path);
+                    actions.push({ type: 'free_gift', skus: gifts, quantity: o.quantity ?? 1 });
+                }
+                else {
+                    only(o, ['x', 'y', 'cheapest_free', 'skus', 'category']);
+                    if (!isInt(o.x, 2) || !isInt(o.y, 1) || o.y >= o.x)
+                        bad(`buy_x_pay_y is x ${String(o.x)}, y ${String(o.y)}.`, 'x and y are whole numbers with x above y and y at least 1: { x: 3, y: 2 } is 3 for 2.', path);
+                    if (o.cheapest_free !== undefined && typeof o.cheapest_free !== 'boolean')
+                        bad('cheapest_free is not true or false.', 'cheapest_free is true or false.', path);
+                    actions.push({ type: 'buy_x_pay_y', x: o.x, y: o.y, cheapest_free: o.cheapest_free ?? false, skus: target(o, true) });
+                }
+            }
+        });
+        if (needsCurrency && !currency && currencies.size > 1)
+            bad('has an amount but no market, in a store with several currencies.', 'Set market: so the amount has a currency, or use a percentage.');
+        promo.rules = rules;
+        promo.actions = actions;
+        return promo;
+    }
+}
+/**
+ * Commerce Layer promotions active without a coupon: each action of an enabled promotion that
+ * has not ended is one (the API makes one per action). Commerce Layer applies at most 10.
+ */
+export function activeWithoutCoupon(promotions, now = Date.now()) {
+    const live = promotions.filter((p) => p.enabled && !p.flex && !p.rules?.coupons && Date.parse(p.ends) > now);
+    return { count: live.reduce((n, p) => n + (p.actions?.length ?? 1), 0), ids: live.map((p) => p.id) };
+}

package/dist/store.js

@@ -136,6 +136,8 @@ export function loadStore() {
             }
         }
     }
+    if (doc.promotions !== undefined)
+        fail('invalid_store', 'store.yml has promotions:, which is not part of the store files.', 'Promotions are live settings in Commerce Layer: create each one with `c11r promotions create -f <file>` (the same entry as YAML or JSON), then remove promotions: from store.yml.');
     const policies = (doc.policies ?? {});
     for (const [key, url] of Object.entries(policies)) {
         if (url && !/^https?:\/\//.test(String(url)))

package/dist/ucp/buy.js

@@ -68,6 +68,8 @@ export async function buy(origin, opts = {}) {
             const why = (checkout.messages ?? []).filter((m) => m.type === 'error').map((m) => `${m.code} at ${m.path}: ${m.content}`).join('; ');
             fail('checkout_not_ready', `The checkout is ${checkout.status}: ${why}`, 'Fix the store (markets, countries, prices) and run the command again.');
         }
+        // The checkout as it was before paying: its warnings (a code that applied nothing) and discounts.
+        const ready = checkout;
         const completeCall = await shopping.completeCheckout(store, checkout.id, { payment: { instruments: [sandboxInstrument(opts.decline)] }, signals: TEST_SIGNALS });
         checkout = note(steps, 'pay', completeCall, '');
         steps[steps.length - 1].result = checkout.status === 'completed' ? `completed, order ${checkout.order.id}` : `${checkout.status}: ${(checkout.messages ?? []).map((m) => m.code).join(', ')}`;
@@ -76,7 +78,7 @@ export async function buy(origin, opts = {}) {
             order = note(steps, 'order', await shopping.getOrder(store, checkout.order.id), '');
             steps[steps.length - 1].result = `${order.label}, ${order.line_items.length} line item(s), ${order.totals.at(-1).amount} ${order.currency}`;
         }
-        return { store, steps, checkout, order };
+        return { store, steps, checkout, ready, order };
     }
     catch (e) {
         if (e instanceof UcpError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [