@base44/app-plugin-commerce 0.2.4 → 0.2.6

package/skills/commerce/install/03-data.md

@@ -12,19 +12,17 @@ carry_forward:
 
 # 03 — Store data
 
-A fresh install has **no settings and no catalog**. One admin-only, idempotent call to `commerce/seed-store` creates both: the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`), the two gateway rows (`offline` enabled, `card` disabled), and — from the payload — the catalog, coupons and shipping locations. Nothing in [`./02-storefront.md`](./02-storefront.md) waits on it: fire it when the image URLs are back and pick the response up when you need the slugs.
+A fresh install has **no settings and no catalog**. One admin-only, idempotent call to `commerce/seed-store` creates both: the six settings groups, the two gateway rows (`offline` enabled, `card` disabled), and — from the payload — the catalog, coupons and shipping locations. Nothing in [`./02-storefront.md`](./02-storefront.md) waits on it: fire it when the image URLs are back.
 
-| Mode | Body | Products created |
-|---|---|---|
-| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) | yours — categories, ribbons, attributes, variants, all in this one call |
-| **Demo data** | `{ store_name, with_sample_data: true }` | 10 generic demo products (skipped if any product exists) |
-| **No products** | `{ store_name }` | none — defaults only |
-
-`with_sample_data` cannot be combined with `products` (**400** `invalid_payload`). Never calling the function leaves the operator the admin's first-run "Set up your store" screen.
+| Mode | Body |
+|---|---|
+| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) |
+| **Demo data** | `{ store_name, with_sample_data: true }` — 10 generic products; cannot combine with `products` (**400**) |
+| **No products** | `{ store_name }` — defaults only |
 
-**`store_name` is required on a first seed** (**400** `store_name_required`) — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). It becomes the email sender name and the public shop name. **`currency`** is an ISO code (`"EUR"`); prices are *formatted* per the viewer's locale, so there is nothing else to set. Explicit values always win, first seed and re-runs alike.
+**`store_name` is required on a first seed** — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). **`currency`** is an ISO code (`"EUR"`); formatting follows the viewer's locale, nothing else to set. Explicit values always win, first seed and re-runs alike.
 
-Full field contract — every payload key, every response field, all error codes: [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store). Here is the working call.
+The working call — `name` is the only required product key; give each product the keys its own catalog entry actually has and leave the rest out. The **full key list** (sale windows, downloads, tax, backorders, dimensions…) is in [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store) — open it only if the catalog needs one of those:
 
 ```js
 try {
@@ -32,75 +30,43 @@ try {
     store_name: "Aurora Threads",
     currency: "EUR",
     products: [
-      // ── 1. Minimal. `name` is the only required key; a real store wants a
-      //       price too, and everything else below is opt-in.
-      { name: "Linen Scarf", regular_price: 45 },
+      { name: "Linen Scarf", regular_price: 45 },     // minimal is complete
 
-      // ── 2. Every product key the seeder accepts, on one product. Take the
-      //       lines a product actually needs and drop the rest — there is no
-      //       "complete" product to fill in.
       { name: "Runner Sneaker",
         sku: "SNK-RUN",                            // optional; makes re-runs idempotent
-        slug: "runner-sneaker",                    // derived from name when omitted
-        status: "publish",                         // draft | pending | private | publish (seeder defaults to publish)
         featured: true,                            // → useProductList({ featured: true }) rails
-
-        regular_price: 89,                         // inherited by variations that don't override
-        sale_price: 79,                            // sets on_sale; the storefront strikes through regular_price
-        date_on_sale_from: "2026-03-01T00:00:00Z", // optional sale window (omit → sale is open-ended)
-        date_on_sale_to: "2026-03-31T23:59:59Z",
-
+        regular_price: 89,
+        sale_price: 79,                            // sets on_sale; storefront strikes regular_price
         stock_quantity: 12,                        // implies manage_stock: true
-        manage_stock: true,                        // only needed to force tracking with no quantity
-        low_stock_amount: 3,                       // overrides the store's threshold
-        backorders: "no",                          // no | notify | yes
-        sold_individually: false,                  // true → max 1 per order (kills the qty stepper)
-
+        sold_individually: false,                  // true → max 1 per order (no qty stepper)
         short_description: "Cushioned everyday runner.",
-        description: "<p>Cut from recycled knit…</p>",      // HTML, rendered as rich text
+        description: "<p>Cut from recycled knit…</p>",   // HTML, rendered as rich text
         images: ["https://…/sneaker.jpg"],         // URLs or { src, alt } — see Images below
-
         categories: ["Shoes"],                     // get-or-created by display name
         ribbons: ["Best Seller"],                  // flat labels, not a hierarchy
 
-        // Descriptive properties → the spec table (`productSpecs(product)`).
-        // NOT variant axes and NOT ribbons: they describe the product, they
-        // don't select anything. Values are strings; a leading `_` hides a row.
+        // Descriptive properties → the product page's spec rows (productSpecs
+        // types each one). NOT variant axes, NOT ribbons. Strings; `_` hides.
         meta_data: [
           { key: "Material", value: "Recycled knit upper" },
-          { key: "Care", value: "Machine wash cold" },
+          { key: "Weight", value: "248 g" },       // "<number> <unit>" → a numeric row
         ],
 
-        attributes: [                              // the axes → one selector each in the storefront
+        attributes: [                              // the axes → one selector each
           { name: "Size", options: ["41", "42"] },
           { name: "Color", options: ["Black", "White"] },
         ],
         default_options: { Size: "42", Color: "Black" },
-        variations: [                              // omit entirely → all 4 combos auto-generated
+        variations: [                              // omit entirely → all combos auto-generated
           { options: { Size: "41", Color: "Black" }, stock_quantity: 4 },
           { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
             image: "https://…/sneaker-white.jpg" }, // per-variation image for a visual axis
         ],
-
-        weight: 0.8,                               // store's weight/dimension units
-        dimensions: { length: 30, width: 20, height: 12 },
-        tax_status: "taxable",                     // taxable | none
-        tax_group: "Products",                     // a tax group from the matched location
-
-        virtual: false,                            // true → no shipping (a service, a booking)
-        downloadable: false,                       // ↓ the three download keys apply only when true
-        downloads: [{ name: "Care guide", file_url: "https://…/care.pdf" }],
-        download_limit: 3,                         // -1 / omit = unlimited
-        download_expiry: 30,                       // days after purchase
-
-        // Accepted, but they take Product *ids* — which only exist after this
-        // call. Cross-link in a later admin-products update, not here.
-        upsell_ids: [], cross_sell_ids: [],
       },
     ],
     coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],
     //   ONLY with a coupon field in the cart or checkout (see ./02-storefront.md)
-    // locations: [ … ],   // shipping — the next section; passing any makes them the store's ONLY ones
+    // locations: [ … ],   // shipping — next section; passing any makes them the store's ONLY ones
   });
   return res.data;                 // ← the { success, data } envelope: plain JSON
 } catch (e) {
@@ -108,29 +74,23 @@ try {
 }
 ```
 
-**Running this through a code-execution tool? Return `res.data`, never the raw response.** `invoke` resolves to the raw HTTP response, which carries circular request/response objects — `return res` (or stringifying a thrown error whole) fails with `Converting circular structure to JSON` *even when the seed succeeded*, and a thrown error needs `e.response?.data` for the same reason.
-
-**The two products above are the range, not a template.** `name` is the only required key: every other line is opt-in, and each product in the array picks its own set independently — a plain product stays two keys long next to a fully specified one, and the fields it omits simply don't apply to it (no attributes ⇒ it sells no variants; no `meta_data` ⇒ no spec table; no `downloads` ⇒ nothing to deliver). Seed each product with the keys its own catalog entry actually has, and leave the rest out rather than padding with empty values.
+**Running this through a code-execution tool? Return `res.data`, never the raw response** — the raw response carries circular objects and fails `Converting circular structure to JSON` *even when the seed succeeded*; a thrown error needs `e.response?.data` for the same reason.
 
-Reference taxonomy by **display name** (categories, ribbons, attributes, options) — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface instead of vanishing.
-
-**Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry after a timeout, or to seed into a store that already has products. **Limits:** ≤100 products, ≤500 variations per call, ≤50 per product, ≤50 locations. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]`, a modified schema **422** `schema_incompatible` — both before anything is written.
+Reference taxonomy by **display name** — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's price up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface. **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry. **Limits:** ≤100 products, ≤500 variations, ≤50 locations per call. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]` before anything is written.
 
 The response reports everything; these matter downstream:
 
 ```jsonc
-{ "catalog": { "products_created": 2, "variations_created": 2,
-    "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 2 }] },
-  "store_name": { "value": "Aurora Threads", "action": "created" },
+{ "catalog": { "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 2 }] },
   "payment_methods": null,          // null = the default (offline on, card off)
-  "warnings": [] }                  // always present; read it — see the shipping section
+  "warnings": [] }                  // always present; read it — see shipping
 ```
 
-Link pages by the **`slug`** from `catalog.products[]`; never mirror the seed in client-side constants (the database is the source of truth and a mirror diverges the first time the merchant edits a product).
+Link pages by the **`slug`** from `catalog.products[]`; never mirror the seed in client-side constants (the database is the source of truth and a mirror diverges on the first merchant edit).
 
 ## Shipping — declare it in the seed call
 
-**Seed-time `locations` is THE way to configure shipping.** Each location is a scope plus its rates and taxes, locations match in `order` ascending, and `order` defaults to the payload position — so the array reads as the priority. "€20 in Europe, €100 everywhere else" is two locations:
+Each location is a scope plus its rates and taxes; locations match in payload order. "€20 in Europe, €100 everywhere else" is two locations:
 
 ```js
 locations: [
@@ -139,63 +99,40 @@ locations: [
 ]
 ```
 
-- **`continents: ["EU"]`** spares you a 51-code country list. The seven codes are `AF` `AN` `AS` `EU` `NA` `OC` `SA`, and `EU` is the *continent* Europe, not the European Union. An unknown code fails `400 invalid_payload` with the known list.
-- **`rest_of_world: true`** is the catch-all — the location that matches every address no other location claims. It cannot also carry `countries`/`continents`/`regions`, and there is **no country code that means "everywhere"**: `countries: ["*"]`/`["ALL"]`/`["ROW"]`, and alpha-3 codes like `["USA"]`, are rejected **400** (every scope code is validated against the matcher's own country/continent/state data).
-- Other scopes: `countries: ["IL", "DE"]`, or explicit `regions: [{ type: "state", code: "US:CA" }]`. Matching is **country + state only** — no postcode or city rules exist.
-- One matched location supplies **both** the shipping rates and the tax groups: `shipping_rates: [{ name, cost, free_over? }]`, `tax_groups: [{ name, rates: [{ name, rate }] }]`, `shipping_tax: { type: "percent"|"fixed", value }`.
-
-**The catch-all trap.** Passing any `locations` suppresses the seeded "Rest of the world" fallback, so scoped locations with nothing behind them mean every other address gets `shipping_not_available` at checkout. That is plausibly intended, so it is not an error — it comes back in the response as `warnings: ["no_catchall_location: …"]`. Read `warnings` on every seed and either add a `rest_of_world` location or state the restriction to the user.
-
-Patching `commerce.ShippingTaxLocation` records afterwards is the **harder, day-2 route** — you must mint stable rate `id`s yourself, and there is no admin function for it. Do shipping in the seed payload. For continent codes in full, state-level regions, tax-group binding, free-over thresholds, VAT-on-shipping and day-2 edits: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
+- **`continents: ["EU"]`** spares you a 51-country list — and `EU` is the *continent* Europe, not the European Union.
+- **`rest_of_world: true`** is the catch-all. There is **no country code meaning "everywhere"** (`["*"]`, `["ALL"]`, alpha-3 like `["USA"]` all fail **400**); other scopes are `countries: ["IL", "DE"]` or `regions: [{ type: "state", code: "US:CA" }]`. Matching is country + state only.
+- A matched location supplies **both** shipping rates and tax groups (`tax_groups`, `shipping_tax`, `free_over` — see the reference below).
 
-**Tiered rates are worth one assertion**, because a wrong zone looks exactly like a right one until a customer in the wrong country pays. The cart prices from an address, so ask it directly — no UI needed:
+**The catch-all trap.** Passing any `locations` suppresses the seeded worldwide fallback, so scoped locations with nothing behind them mean every other address gets `shipping_not_available` at checkout. Plausibly intended, so it is a warning, not an error: **read `warnings` on every seed** and either add a `rest_of_world` location or state the restriction to the user. If the brief named tiered rates, assert them once by pricing a cart against one address per zone (`set-shipping-address` → `available_shipping_methods`; a `[]` means no location matched).
 
-```js
-// one item in the cart, then price it for each country the brief names
-for (const country of ["DE", "AU"]) {
-  const { data } = await base44.functions.invoke("commerce/storefront-cart", {
-    action: "set-shipping-address", cart_token, address: { country, city: "x" },
-  });
-  console.log(country, data.data.available_shipping_methods.map((m) => m.cost));
-}
-// DE → [20], AU → [100] for the payload above. A [] means no location matched
-// that address — the catch-all is missing.
-```
+Continent codes in full, state regions, tax binding, VAT-on-shipping, day-2 edits: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
 
 ## Images
 
-Every product needs at least one, and **the URL you seed is the URL the store serves** — there are no placeholders to swap later. Resolve each to its **final, permanent URL before seeding**: the app's image generation, `base44.integrations.Core.UploadFile({ file })` → public URL, or stable public stock URLs (`seed-store/sample-data.ts` shows a working pattern). Match the image to the product.
-
-Both failure modes are silent at seed time and visible only in the store, so check now: a **temporary or signed** URL (expiry params in the query string are the tell) must be re-hosted via `UploadFile`, and spot-check that one or two URLs resolve (200, image content type). Seeding without an image and setting it later through the admin API is allowed, but it is an open debt — track every imageless product and close it before handover.
+**The URL you seed is the URL the store serves.** Resolve each to its final, permanent URL before seeding: the app's image generation, or `base44.integrations.Core.UploadFile({ file })` → public URL. A temporary/**signed** URL (expiry params in the query string are the tell) must be re-hosted via `UploadFile` first — the failure is silent at seed time and visible only in the store. Seeding imageless and patching later is allowed but is open debt; close it before handover.
 
 ## Payments — the decision
 
-**The rule, in full.** Online card payments are **off by default**: `commerce/seed-store` enables the manual `offline` method and leaves the `card` gateway disabled. Offline-only is a complete, payable store — the order goes on-hold with the gateway's description rendered as payment instructions on `/order-received`, which needs no code and no credentials. **Enable `card` only if a payment provider is wired, or will be in the same stretch of work:** enabled means offered, and an enabled card option with nothing behind it answers **`503 no_card_payment_provider`** the moment a customer picks it. Enabling and wiring are two halves of one step; neither half is useful alone.
+Online card payments are **off by default**: the seeded store takes the manual `offline` method and is complete and payable — the order goes on-hold and `/order-received` renders the gateway's payment instructions, no code, no credentials. **Enable `card` only if a provider is wired in the same stretch of work**: an enabled card option with nothing behind it answers **`503 no_card_payment_provider`** the moment a customer picks it.
 
-**`payment_methods` is the on/off switch.** Pass gateway slugs and the listed gateways are enabled while **every other row is disabled** — `["offline"]`, `["card"]` (card-only) or both, with no `commerce.PaymentGateway` reads or writes of your own. Omit it and the store stays offline-only. It is idempotent and needs no catalog, so `{ payment_methods: ["offline", "card"] }` alone is the later on/off switch. Unknown slugs fail `400 invalid_payload` with the known list.
+`payment_methods` is the on/off switch — the listed slugs are enabled, every other row disabled; it is idempotent and needs no catalog, so `{ payment_methods: ["offline", "card"] }` alone is the later switch.
 
-| What the request says | Decision |
+| The request says | Decision |
 |---|---|
-| A provider is named ("use Stripe") | copy the provider file, enable `card` — whenever convenient; it blocks nothing |
-| Selling online implied, no provider named | cards are a reasonable read of *what* to offer, never of *when*: raise the provider **after** the store works |
-| Paid another way (transfer, COD, invoice, pickup, quotes) | nothing to do — the default already is exactly this |
-| Payments not mentioned at all | leave the default and **mention it at handover** |
-
-**Timing: late, never the opening move.** Payments have no dependency edge into anything — the admin, the seed and the entire buy path down to `place-order` work with no provider — so putting the provider connection before the store exists only stalls the build. Any instruction that treats a payment provider as a required install step is superseded by this section.
-
-**Say where payments landed** in your handover summary, including "offline only, cards off". A store's owner should never discover their payment configuration from a customer who couldn't pay.
+| A provider is named ("use Stripe") | copy the provider file, enable `card` — whenever convenient |
+| Selling online implied, no provider named | raise the provider **after** the store works |
+| Paid another way (transfer, COD, invoice, pickup) | nothing to do — the default is exactly this |
+| Payments not mentioned | leave the default, **state it at handover** |
 
-*Only for a store that opted into cards:* **if it is Stripe, the code is already written** — `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation, used **as-is**. Copy it over `base44/shared/commerce/card-payment.ts` (`fs.copyFileSync`, whole file — never a partial edit, which leaves duplicate exports and breaks every commerce function's deploy) and enable the gateway with `payment_methods: ["offline", "card"]`. Nothing in it needs filling in and no key belongs in the code; it reads the credential the app's Stripe connection publishes. Any other provider means implementing four functions in that one file — [`../references/online-payments.md`](../references/online-payments.md).
+*Cards only:* **if it is Stripe the code is already written** — copy `base44/shared/commerce/card-payment.stripe.ts` over `base44/shared/commerce/card-payment.ts` **whole** (`fs.copyFileSync`; a partial edit breaks every function's deploy), then enable via `payment_methods`. Nothing needs filling in. Any other provider: [`../references/online-payments.md`](../references/online-payments.md).
 
 ## Done — forget this file
 
-- [ ] `commerce/seed-store` returned success and reported the catalog — real products, final permanent image URLs.
-- [ ] `warnings` in the response is empty, or every warning is deliberate and stated to the user.
-- [ ] Shipping is expressed in `locations` (with a catch-all if the store ships worldwide), not patched into entities afterwards.
+- [ ] Seed returned success — real products, final permanent image URLs; slugs recorded and pages link by them.
+- [ ] `warnings` is empty, or every warning is deliberate and stated to the user.
+- [ ] Shipping expressed in `locations` (catch-all present if the store ships worldwide); named tiers asserted.
 - [ ] `coupons` seeded only if a coupon field exists ([`./02-storefront.md`](./02-storefront.md)).
-- [ ] Cards are either off, or on with the provider file copied whole and the `card` gateway enabled.
-- [ ] Product slugs from `catalog.products[]` recorded, and the storefront links by them.
-- [ ] If the brief named tiered rates, each named region prices to its rate (the `set-shipping-address` check above).
+- [ ] Cards off, or on with the provider file copied whole.
 
 Record these lines in your working notes; do not re-read this file.
 

package/skills/commerce/references/admin-product-form.md

@@ -67,3 +67,29 @@ Attribute and value *records* are shared between products, so the **Manage attri
 dialog saves them immediately, unlike the rest of the form which batches until Save. There
 are no Attributes or Ribbons pages in the side menu: attributes are reachable only from
 here, ribbons from the `TaxonomyPanel` card in the product sidebar.
+
+## Taxonomy cascade semantics (`save-term` / `delete-term`)
+
+What `commerce/admin-products` `save-term`/`delete-term` do beyond the plain upsert/delete
+(signatures and the per-taxonomy field table: [`../docs/api-admin.md`](../docs/api-admin.md#commerceadmin-products)).
+These rules apply whenever you build custom taxonomy tooling against those actions — the
+shipped dialogs already obey them.
+
+- Only a category has a slug, derived from its name and made unique; its `parent_id`
+  pointing at itself is coerced to `""` (`categoryWithDescendants` would loop). An
+  attribute's **`code`** is derived from the name and made unique — it is the key a
+  storefront filter URL should carry.
+- Creating a **ribbon** is get-or-create: a name that already exists case-insensitively
+  returns the existing record instead of splitting the ribbon in two.
+- Renaming an **attribute value** rewrites `attributes[].options` and `default_attributes`
+  on every product using it, and the matching `option` on their variations — products
+  store a value by name, so the rename would otherwise orphan them.
+- Deleting an **attribute** always deletes its terms (a term outliving its attribute is
+  unreachable); `detach: true` additionally strips the attribute from every product's
+  `attributes[]`. For a category or ribbon, products keep the id by default (the
+  storefront skips ids that no longer resolve); `detach: true` strips it from every
+  product first.
+- **For an attribute *value* `detach` is a no-op** — deleting a value leaves its name in
+  every product's `attributes[].options` and leaves the variations that use it in place,
+  so remove the value from the products first (or expect variants the storefront can no
+  longer resolve).

package/skills/commerce/references/catalog-rendering.md

@@ -31,7 +31,7 @@ A listing **row** is the product record itself (minus paywalled fields) plus res
 | `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`; every entry is an **object** — §2 |
 | `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
 | `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
-| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`productSpecs(product)` turns them into spec-table rows) |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`productSpecs(product)` turns them into typed spec rows) |
 | **`ribbons`** (resolved), `ribbon_ids`, `category_ids` | ✅ | ✅ | Rows carry `{id, name}` ribbons; `get-product` returns the full records |
 | **`categories`** (resolved) | ❌ *ids only* | ✅ | §6 to add them to rows |
 | **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | Why a product with variants can't be fully priced from a row |
@@ -50,21 +50,21 @@ There is **no product `type` field**. `attributes[]` tells the shapes apart:
 
 A product with attributes is **only** sellable through a variant: `add-item` without a `variation_id` is `400 variation_required`, with no fall-back to the parent. So one with attributes but no variations is unsellable by design, not by accident (§5 covers rendering that state).
 
-Three rules used to be prose here and are now enforced by exports — use them and they can't drift between views:
+Three rules are enforced by exports — use them and they can't drift between views:
 
-- **From-price.** `admin-products` (and the seeder) roll a parent's `regular_price`/`price`/`on_sale` up from the cheapest publishable variant on every save, so the parent price is real, sortable and filterable — but it is the **lowest** price, not *the* price. `productPrice(rowOrView, {formatMoney})` / `useProductPrice(rowOrView)` accept **either** a listing row or a `resolveSelection` view and return `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range on an unresolved page, the exact price once resolved.
-- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string, and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`), and an empty array is the *render your placeholder* signal — `useProductGallery` builds on them (`hasImages`). Passing the object itself to an `<img src>` fails the load and shows the placeholder for every product in the store.
-- **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is descriptive — never a selector, never a ribbon. How each modifier *renders* is a design decision (§3); what it can never become is a control.
+- **From-price.** A parent's `regular_price`/`price`/`on_sale` are rolled up from the cheapest publishable variant on every save (by `admin-products` and the seeder) — real, sortable, filterable, but the **lowest** price, not *the* price. `productPrice(rowOrView, {formatMoney})` / `useProductPrice(rowOrView)` take a listing row **or** a `resolveSelection` view and return `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range unresolved, the exact price resolved.
+- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string — passing the object itself to `<img src>` fails the load — and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`); an empty array means *render your placeholder* (`useProductGallery` builds on them, `hasImages`).
+- **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is descriptive — never a selector, never a ribbon; how it renders is a design decision (§3), a control is what it can never become.
 
 ## 3. What each view *can* render
 
-Both lists below are field inventories — what the data supports — **not a layout and not an order**. Read them for availability, then design the surface; a store that renders exactly these fields in exactly this sequence is the generic storefront every generated catalog produces.
+Both lists below are field inventories — what the data supports — **not a layout and not an order**; a store rendering exactly these fields in exactly this sequence is the generic storefront every generated catalog produces.
 
-**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `meta_data` via `productSpecs`) that says more about *this* catalog than a star average does. Link the whole card to the product page; the card, the grid's rhythm and whether every card is even the same size are yours.
+**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `meta_data` via `productSpecs`). Link the whole card to the product page; the layout is yours.
 
 **Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCartButton`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
 
-**Attributes and modifiers are individually designable.** `variantAxes` exposes `axis.key`/`axis.name` and `productSpecs` exposes `key`/`label` precisely so a page can branch on *which* one it is: colour as swatches, size as chips next to a size guide, "Composition" as bars, "Provenance" as a located line, "Certification" as a seal. One uniform chip row for every axis and one grey label/value table for every modifier is a default, not a requirement — pick the two or three that carry the product's meaning, give them real treatment, and let the remainder fall back to a plain row. The rules in §5 govern selector *behaviour* (one control per axis, unbuyable disabled), never its form, and they hold whatever the control looks like.
+**Attributes and modifiers are individually designable.** `productSpecs` rows carry `key`/`label`/`titleLabel` (display-cased) plus an inferred `type` (`numeric` with `number`/`unit` split out, `duration`, `location`, `list` with `items`, `text`); `useProductSpecs(product, { pick })` is the React wrapper, its get/pick case/underscore-insensitive. Branch on `type`/`key` instead of mapping everything into one uniform chip row per axis and one grey label/value table — the design guidance is [`../install/02-storefront.md`](../install/02-storefront.md)'s; §5's rules govern selector *behaviour*, never its form.
 
 ## 4. Ribbons — in **both** views
 

package/skills/commerce/references/online-payments.md

@@ -41,14 +41,9 @@ That is the whole of it. The file expects the app to be connected to Stripe and
 
 A kit update re-copies `shared/commerce/` and restores the stub — re-run the copy after updating. A different provider ships the same way (`card-payment.<provider>.ts` beside the stub); until one does, implement the four functions against its API per the rules below, with the Stripe file as the worked model.
 
-## How the premade flow works
+## The premade flow
 
-1. **Checkout** (`place-order` with the `card` gateway): the order is created `pending`, `createCardPayment` runs, the returned `reference` is stored on the order (`_payment_reference` meta), and the customer is redirected to `url`. The return URLs already carry `order_id`, `order_key` and `payment=success|cancel`.
-2. **Confirmation — two idempotent paths**, whichever runs second is a no-op: the **customer return** (`/order-received` calls `commerce/payments` `complete-return`, which runs `checkCardPaymentPaid` and on true moves the order to `processing`, firing the stock/email/webhook side-effects — `useOrderReturn` is that page in one hook), and the **webhook**, which covers the buyer who pays and closes the tab.
-3. **Payment links**: `commerce/payments` `create-link` mints a fresh page for any unpaid order through the same `createCardPayment` — the admin's payment-link button and order-received's "Pay now".
-4. **Refunds**: `commerce/admin-refunds` with `refund_payment: true` calls `refundCardPayment` **before** writing the local record (a failed provider refund writes nothing). While unimplemented it answers `501 card_refund_not_implemented` — record the refund without `refund_payment` and return the money from the provider's dashboard.
-
-With the gateway enabled and no provider behind it, picking Credit card answers `503 no_card_payment_provider` — implement the file, or switch the option off in Settings → Payments. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions and the operator moves it on when the money arrives. Those need no code, and the admin can add more of them.
+Checkout (`place-order`, `card` gateway) creates the order `pending`, runs `createCardPayment`, stores its `reference` on the order and redirects to `url`; return URLs carry `order_id`/`order_key`/`payment=`. Confirmation is **two idempotent paths** (the second a no-op): the customer return (`/order-received` → `commerce/payments` `complete-return` → `checkCardPaymentPaid` → `processing` with all side-effects; `useOrderReturn` is that page in one hook) and the webhook (covers the closed tab). `create-link` mints a fresh page for any unpaid order the same way; `admin-refunds` `refund_payment: true` calls `refundCardPayment` **before** writing locally (unimplemented → `501`; record without the flag instead). Gateway enabled with no provider behind it → `503 no_card_payment_provider`; every other payment option is **manual** (on-hold, the option's description as payment instructions) and needs no code.
 
 ## Implementation rules
 
@@ -62,12 +57,6 @@ For a **custom** provider (the shipped files already obey all of these):
 - **Amounts**: `order.total` is in display units (`12.34`) with `order.currency`; convert to the provider's minor units yourself, remembering the zero-decimal currencies.
 - The helpers in `shared/commerce/payments.ts` (return-URL building, `confirmCardPayment`, reference bookkeeping) are premade — don't duplicate or bypass them.
 
-## `parseWebhook` in depth
-
-`parseWebhook(req, payload)` lives in `card-payment.ts` with the other three; `commerce/payment-webhook` is premade and calls it with the raw request and the raw body — the exact bytes, so signature schemes work. It returns `CardWebhookEvent | null`:
-
-- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret: the premade flow verifies through `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction — a forged call can at worst trigger a re-check, and the `order_key` match stops an event being aimed at another order. This is what the shipped Stripe file does.
-- **The signature-verified fast path** (optional): verify the signature over the raw `payload` bytes (Stripe: `constructEventAsync` with a webhook signing secret) and return `paid: true` with the event's `reference`; the premade code then trusts it without the API round-trip. **`paid: true` from an unverified body is the one way to break this design.** Set `reference` only from a verified event; otherwise leave it unset and the flow uses the reference stored on the order at checkout.
-- Return **`null`** for events that aren't about one of this store's payments; the function answers 200 so the provider doesn't retry.
+## `parseWebhook`, briefly
 
-Everything after `parseWebhook` — order lookup, the `order_key` match, idempotent confirmation, order progression — is premade either way.
+Premade `commerce/payment-webhook` feeds `parseWebhook(req, payload)` the raw request and body (exact bytes, so signature schemes work); it returns `CardWebhookEvent | null` — `null` = not this store's payment, answered 200 (no retry). The secure default (what the shipped Stripe file does) is the **nudge**: read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }` — no signing secret, since payment is verified through `checkCardPaymentPaid` against the provider's API and the `order_key` match stops an event aimed at another order. Optionally verify the signature over the raw `payload` bytes and return `paid: true` + the event's `reference` to skip that round-trip — **`paid: true` (or a `reference`) from an unverified body is the one way to break this design.** Everything after `parseWebhook` — lookup, `order_key` match, idempotent confirmation, progression — is premade either way.

package/skills/commerce/references/operations.md

@@ -32,13 +32,31 @@ Every action above is guarded by `requireAdmin()`, so each workflow must run wit
 
 - **Pagination.** SDK `filter`/`list` cap at 5,000 records/page and there is **no total-count API**. Server-side scans use paged loops (`shared/commerce/scan.ts` `scanAll`, page size 500); admin lists and `useProductList` use limit+skip with a `limit+1` "has-next" probe — the UI shows *Page N ‹ ›*, never a total.
 - **Search** is server-side (`search` actions scan + JS-filter) because entity `filter` is exact-match only.
-- **Reports** scan on demand — fine to ~10k orders per range. `commerce/admin-reports` `summary`/`sales`/`top-sellers` scan `commerce.Order` (+ `commerce.OrderRefund`) filtered to counted orders (`date_paid` set, or status `processing`/`completed`); net sales = gross − refunds − tax − shipping. Beyond that, cache `summary` and materialize an `OrderStats` entity (one record per day per status, summed totals) updated on each order transition.
+- **Reports** scan on demand — fine to ~10k orders per range. `commerce/admin-reports` `summary`/`sales`/`top-sellers` scan `commerce.Order` (+ `commerce.OrderRefund`) filtered to counted orders (`date_paid` set, or status `processing`/`completed`); net sales = gross − refunds − tax − shipping. Beyond that, cache `summary` and materialize an `OrderStats` entity (one record per day per status, summed totals) updated on each order transition. The full action table is below.
 - **No transactions.** Four consequences, all documented in code:
   - `nextOrderNumber` is `max(order_number)+1` with a small retry; two concurrent checkouts could theoretically collide — acceptable for typical volume, or front it with a counter entity.
   - Stock decrement is last-write-wins; oversell is possible on simultaneous checkouts of the last unit. The hold mechanism (`hold_stock_minutes`) mitigates it; a stricter reserve step is yours to add.
   - Denormalized counters (`usage_count`, `total_sales`, `orders_count`, term `count`) can drift; the recount actions above repair them.
   - **Record size.** Orders embed their line/shipping/tax/fee/coupon lines, so orders with hundreds of distinct line items push against per-record size limits.
 
+### `commerce/admin-reports` actions
+
+The complete payload/return contract (invocation: [`../docs/api-admin.md`](../docs/api-admin.md#commerceadmin-reports)):
+
+| Action | Payload | Returns |
+|---|---|---|
+| `summary` | — | `{ sales_today, sales_month, orders_by_status, low_stock_count, out_of_stock_count, top_seller }` where `sales_*` = `{ gross_sales, net_sales, orders, items, tax, shipping, discount, refunds }` |
+| `sales` | `{ date_min?, date_max?, interval? }` (`day`\|`week`\|`month`) | `{ totals: <agg>, series: [{ period, ...agg }] }` (net = gross − refunds − tax − shipping) |
+| `top-sellers` | `{ date_min?, date_max?, limit? }` | `{ rows: [{ product_id, name, sku, quantity, net_revenue }] }` |
+| `stock` | — | `{ low_stock: [...], out_of_stock: [...] }` |
+| `orders-totals` | — | `{ [status]: count }` |
+| `products-totals` | — | `{ total, by: { [status]: count } }` |
+| `customers-totals` | — | `{ total, guests, registered, paying }` |
+| `coupons-totals` | — | `{ total, by: { [discount_type]: count } }` |
+| `reviews-totals` | — | `{ total, by: { [status]: count } }` |
+| `categories-totals` / `ribbons-totals` | — | `{ total, terms: [{ id, name, count }] }` |
+| `attributes-totals` | — | `{ total, attributes: [{ id, name, terms }] }` |
+
 ## Webhooks (outbound)
 
 Managed in the admin at **Settings → Webhooks** (`settings/webhooks`; the source still lives under `pages/status/`).

package/skills/commerce/references/storefront-verification.md

@@ -0,0 +1,47 @@
+---
+read_when: "You are about to drive the storefront from a browser script — adding to the cart, stepping quantities, filling the checkout, placing an order."
+skip_when: "You are not scripting the storefront."
+---
+
+# Driving the storefront from a browser script
+
+Whatever you choose to check and however you check it, these are what make a
+working storefront look broken under a script. The common cause is acting
+faster than the cart settles: the hooks are optimistic and debounced, so the
+DOM is briefly right about the *intent* and wrong about the *state*.
+
+- **Wait for the cart, then for each row.** Two waits, neither optional. Before
+  the first action, wait for the initial load to settle — `status` leaves
+  `"loading"` exactly once, so the signal is the loaded UI (a row, or the empty
+  state), never a fixed sleep. Then after every stepper click wait for **that
+  row**: the click starts a 250ms debounce before the request even leaves, so
+  reading the quantity or total straight after gives the optimistic number and
+  stale totals, and two quick clicks send **one** request for the final number.
+  Wait for the row's busy state to clear (`aria-busy`, re-enabled buttons)
+  before reading or clicking again.
+- **Scope actions to the visible drawer.** With a drawer, the page can hold two
+  "Remove" buttons for one line — drawer and cart page behind it. A drawer built
+  on `useCartUI` is inert while closed, so its copies can't be hit by mistake —
+  but still query inside the open drawer's container, not the document. A click
+  that seems to do nothing usually hit the hidden copy.
+- **Remove lines one at a time.** Clicking every "Remove" in one pass fails on
+  its own terms: cart calls are serialized, each removal re-renders the list,
+  and buttons collected up front are detached by the time the loop reaches
+  them. Remove one, wait for the row to disappear, then the next.
+- **Verify the checkout navigation before cleaning up.** Confirm you are on
+  `/checkout` — URL plus a field of the form on screen — before emptying the
+  cart or moving on. Tearing the cart down while still on the cart page, or
+  mid-navigation, produces an empty checkout that reads as a routing bug.
+- **Filling the checkout.** Every field is a controlled React input, so writing
+  `el.value` changes nothing React sees. Use the harness's own fill (it
+  dispatches `input` + `change`) — never lift the native setter off
+  `HTMLInputElement.prototype` and call `descriptor.set(v)`: detached from the
+  element it throws `Illegal invocation`, and the workaround it is reaching for
+  is what the fill helper already does.
+- **`placeOrder` ends the page.** It navigates with `window.location.assign`,
+  so a script that placed an order loses its page context and can land back at
+  `/` — while the order itself was created normally. That is the hard
+  navigation, not a broken redirect. The confirmation is reachable at any time
+  from a fresh navigation to `/order-received?order_id=…&order_key=…` (the ids
+  come back in `placeOrder`'s result, and `commerce/admin-orders` `search` has
+  the order either way).

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -19,14 +19,24 @@ import {
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
  *
  * Mount it once, above every storefront page (product list, product page,
- * cart, checkout, order-received) — it wraps <Routes>, it is NOT a <Route>:
+ * cart, checkout, order-received). It is NOT a <Route>. A store with shared
+ * chrome — nearly all of them — mounts it on a pathless layout route, wrapping
+ * the layout that renders <Outlet/>, which keeps the nav's cart badge and the
+ * page on one cart and leaves the admin outside:
  *
  *   import { base44 } from "@/api/base44Client";
+ *   <Route element={<StorefrontProvider base44={base44}><StoreLayout /></StorefrontProvider>}>
+ *     <Route path="/" element={<Home />} /> …
+ *   </Route>
+ *
+ * With no shared layout it can wrap <Routes> directly instead:
+ *
  *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
  *
- * Inside <Routes> it throws ("is not a <Route> component"), since React Router
- * allows only <Route>/<Fragment> children there. To cover just some routes,
- * use a pathless layout route: element={<StorefrontProvider …><Outlet/></…>}.
+ * As a child of <Routes> it throws ("is not a <Route> component"), since React
+ * Router allows only <Route>/<Fragment> children there. Never the other way
+ * round either: a layout that renders the provider inside itself puts the nav
+ * outside it, so the badge and the cart page read different carts.
  *
  * or, if other modules also need the raw client, create it once and share it:
  *
@@ -128,7 +138,7 @@ export function useStorefrontState() {
   const ctx = useContext(StorefrontContext);
   if (!ctx) {
     throw new Error(
-      "Storefront hooks need a <StorefrontProvider> above them — mount it once around your <Routes> (it wraps the router; it is not a <Route>, and inside <Routes> React Router rejects it).",
+      "Storefront hooks need a <StorefrontProvider> above them — mount it once on a pathless layout route, wrapping the layout component that renders <Outlet/> (or, with no shared layout, around your <Routes>). It is never a <Route> itself: as a child of <Routes>, React Router rejects it.",
     );
   }
   return ctx;
@@ -195,8 +205,10 @@ export function useFormatMoney() {
  * - `lines` are `cart.items` decorated with what a renderer needs and would
  *   otherwise re-derive: `attributesLabel` ("Size: 42 · Color: Ivory" — the raw
  *   `attributes` is an **array** of `{name, option}`, never a map),
- *   `image` normalized to `{src, alt}` or null, `purchasable` as a boolean with
- *   `unavailableReason` beside it, and the quantity bounds.
+ *   `image` normalized to `{src, alt}` or null, money pre-formatted
+ *   (`totalLabel`, `subtotalLabel`, `unitPriceLabel` — no `useFormatMoney`
+ *   needed in a row), `purchasable` as a boolean with `unavailableReason`
+ *   beside it, and the quantity bounds.
  * - `notices` normalizes `coupon_notices` + `removed_items` into one list —
  *   render it, or a line that auto-dropped vanishes with no explanation.
  * - `mutationError` is the last failed mutation (insufficient stock, an expired
@@ -204,6 +216,28 @@ export function useFormatMoney() {
  *   `useCartLine`/`useAddToCart` can handle failures locally.
  * - `applyCoupon(code)` resolves to `{ ok, cart }` or `{ ok: false, code,
  *   message }` — an invalid code is expected flow, not an exception.
+ *
+ * ## When `status` settles — and what it does not cover
+ *
+ * `status` is `"loading"` for exactly one thing: the **first** `getCart()` of
+ * the session has not resolved yet (internally, `cart === undefined`). It
+ * settles once, to `"empty"` or `"ready"`, and after that:
+ *
+ * - **A mutation never returns it to `"loading"`.** Adding, updating, removing
+ *   or couponing leaves `status` as it was, previous numbers on screen, until
+ *   the new view lands. There is no cart-wide busy flag by design: a page-wide
+ *   spinner for a 250ms quantity step is worse than the stale number, and the
+ *   right busy scope is the row (`useCartLine`'s `pending`) or the control that
+ *   started it.
+ * - `"empty"` therefore means *loaded, with no items* — including after
+ *   checkout consumes the cart — never "still arriving".
+ * - It flips `"empty"` → `"ready"` when the first line lands, so a header badge
+ *   and a drawer switch states off the same signal.
+ *
+ * So branch **`status`** for the page's loading/empty/ready shape, and watch
+ * **`useCartLine().pending`** (or your own flag around `addItem`) for "did that
+ * change land". Anything waiting on a mutation — a queued follow-up action, a
+ * script driving the page — waits on the second, never the first.
  */
 export function useCart() {
   const { client, cart, cartError, mutationError, runCart } = useStorefrontState();
@@ -254,6 +288,9 @@ export function useCart() {
           ...item,
           attributesLabel: attributesLabel(item.attributes),
           image: item.image ? { src: item.image, alt: item.name ?? "" } : null,
+          totalLabel: item.total != null ? formatMoney(item.total) : "",
+          subtotalLabel: item.subtotal != null ? formatMoney(item.subtotal) : "",
+          unitPriceLabel: item.price != null ? formatMoney(item.price) : "",
           maxQuantity,
           canIncrease: item.quantity < maxQuantity,
           canDecrease: item.quantity > 1,
@@ -261,7 +298,7 @@ export function useCart() {
           unavailableReason: purchasable ? null : (item.purchasable?.error ?? null),
         };
       }),
-    [items],
+    [items, formatMoney],
   );
 
   const notices = useMemo(