@base44/app-plugin-commerce 0.2.7 → 0.3.2

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

@@ -22,7 +22,7 @@ A fresh install has **no settings and no catalog**. One admin-only, idempotent c
 
 **`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.
 
-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:
+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…) lives in `api-admin.md` — open it only if the catalog needs one:
 
 ```js
 try {
@@ -45,11 +45,10 @@ try {
         categories: ["Shoes"],                     // get-or-created by display name
         ribbons: ["Best Seller"],                  // flat labels, not a hierarchy
 
-        // Descriptive properties → the product page's spec rows (productSpecs
-        // types each one). NOT variant axes, NOT ribbons. Strings; `_` hides.
+        // Descriptive spec rows (productSpecs). NOT axes, NOT ribbons; `_` hides.
         meta_data: [
           { key: "Material", value: "Recycled knit upper" },
-          { key: "Weight", value: "248 g" },       // "<number> <unit>" → a numeric row
+          { key: "Weight",   value: "248 g" },
         ],
 
         attributes: [                              // the axes → one selector each
@@ -76,7 +75,7 @@ try {
 
 **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** — 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.
+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. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]` before anything is written; per-call limits (≤100 products, ≤500 variations, ≤50 locations) and the full key list are in [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store).
 
 The response reports everything; these matter downstream:
 
@@ -94,28 +93,31 @@ Each location is a scope plus its rates and taxes; locations match in payload or
 
 ```js
 locations: [
-  { name: "Europe",    continents: ["EU"],    shipping_rates: [{ name: "Standard",      cost: 20 }] },
+  { name: "Europe",    continents: ["EU"],    shipping_rates: [{ name: "Standard", cost: 20 },
+                                                               { name: "Express",  cost: 35 }] },
   { name: "Worldwide", rest_of_world: true,   shipping_rates: [{ name: "International", cost: 100 }] },
 ]
 ```
 
+⚑ **Speeds go in one location's `shipping_rates`; zones are separate locations.** Exactly one location matches an address, so several rates in it become the customer's pick at checkout (`shipping_status: "choice_required"`), while a second location with the same scope is simply dead — never matched, its rates never offered.
+
 - **`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).
+- **`rest_of_world: true`** is the catch-all — there is **no country code meaning "everywhere"**, and improvised ones (`["*"]`, `["ALL"]`, alpha-3 `["USA"]`) fail **400**. The narrower scope is `countries: ["IL", "DE"]`; matching is country + state only.
+- The matched location supplies the taxes too (`tax_groups`, `shipping_tax`) and `free_over` zeroes a rate above a subtotal — reference below.
 
-**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).
+**The catch-all trap.** Passing any `locations` suppresses the seeded worldwide fallback, so scoped locations with nothing behind them answer `shipping_not_available` to every other address. Plausibly intended, so it warns rather than fails: **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, price a cart against one address per zone to check them (`set-shipping-address` → `available_shipping_methods`; `[]` means no location matched).
 
 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
 
-**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.
+**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. Cheap insurance before seeding: fetch one or two of the URLs and check they answer 200 with an image content type. Seeding imageless and patching later is allowed but is open debt; close it before handover.
 
 ## Payments — the decision
 
 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 — 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.
+`payment_methods` is the on/off switch — the listed slugs are enabled, every other row disabled. ⚑ **Never write `enabled` on the `commerce.PaymentGateway` row instead.** **Seeding need not happen all at once:** every key is independent, so re-call `commerce/seed-store` whenever one slice of configuration changes, carrying only that slice — `{ payment_methods: ["offline", "card"] }` is a complete standalone call, as valid on a live store weeks later as during the install (`store_name` is required only on a store's first seed).
 
 | The request says | Decision |
 |---|---|

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

@@ -5,7 +5,7 @@ skip_when: "The listing and product page render correctly from useProductList /
 forget_when: "Cards and the product page render the fields you intended, variant selection resolves to a variation, and add-to-cart succeeds."
 carry_forward:
   - "There is no product `type` field: a non-empty `attributes[]` is what makes a product sell variants, and such a product is only sellable via a `variation_id`."
-  - "A variant parent's `price` is a FROM price — render it through productPrice/useProductPrice, never as the price."
+  - "A variant parent's `price` is a FROM price — render it through productPrice(row, { formatMoney }), never as the price."
   - "Product images are objects `{src, name, alt}` and the array can be empty — go through productImages/normalizeImage and render a placeholder."
 ---
 
@@ -13,16 +13,16 @@ carry_forward:
 
 Both storefront surfaces render the same catalog record from a different call:
 
-| View | Call | Hook | Returns |
+| View | `commerce/storefront-catalog` action | Hook | Returns |
 |---|---|---|---|
-| Listing / grid / search / ribbon & category pages | `commerce/storefront-catalog` `list-products` | `useProductList` | `{ products: [row…], page, per_page, has_next }` |
-| Product page | `commerce/storefront-catalog` `get-product` | `useProduct` | `{ product, variations, categories, ribbons, reviews, upsells, cross_sells }` |
+| Listing / grid / search / ribbon & category pages | `list-products` | `useProductList` | `{ products: [row…], page, per_page, has_next }` |
+| Product page | `get-product` | `useProduct` | `{ product, variations, categories, ribbons, reviews, upsells, cross_sells }` |
 
-Request/response shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). You choose what belongs in each view — but you can only render what the call returns, and §1 is that boundary.
+Shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). What belongs in each view is yours — you can only render what the call returns, and §1 is that boundary.
 
 ## 1. Field availability
 
-A listing **row** is the product record itself (minus paywalled fields) plus resolved `ribbons`. `get-product` adds everything that needs a second read.
+A listing **row** is the product record (minus paywalled fields) plus resolved `ribbons`; `get-product` adds everything that needs a second read.
 
 | Data | `list-products` row | `get-product` | Notes |
 |---|---|---|---|
@@ -30,85 +30,79 @@ A listing **row** is the product record itself (minus paywalled fields) plus res
 | `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | With variants the parent `price` is a *from* price — §2 |
 | `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 typed spec rows) |
+| `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves aren't |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` the descriptive **modifiers** (`productSpecs(product)` → 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 |
 | **`reviews`** (paged items + aggregates) | ❌ | ✅ | Rows still carry the aggregate numbers |
 | **`upsells`, `cross_sells`** (summaries) | ❌ | ✅ | `{id, name, slug, price, on_sale, image}` |
-| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** public — reached only through `commerce/storefront-account` `get-download` |
+| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** public — only via `commerce/storefront-account` `get-download` |
 
-## 2. Two shapes, and the three rules the code now owns
+## 2. Two shapes, and three rules the exports own
 
 There is **no product `type` field**. `attributes[]` tells the shapes apart:
 
-| Shape | Test | Card | Product page |
-|---|---|---|---|
-| **Single item** | `attributes` is empty | price, and Add to cart straight from the card if you want one | one Add to cart — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
-| **Sells variants** | `attributes` is non-empty | price **range or "From €19"**, never selectors — link through | one control per axis — §5 |
+| Shape | Test | Renders as |
+|---|---|---|
+| **Single item** | `attributes` empty | one price; one Add to cart, from the card too if you want (`resolveSelection` gives no axes, `complete: true`, a ready `addToCart`) |
+| **Sells variants** | `attributes` non-empty | card: price **range or "From €19"**, never selectors — link through. Page: one control per axis (§5) |
 
-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).
+A product with attributes is **only** sellable through a variant — `add-item` with no `variation_id` is `400 variation_required`, no parent fall-back — so attributes with no variations is unsellable by design, not by accident (§5 renders it).
 
-Three rules are enforced by exports — use them and they can't drift between views:
+Three rules the exports enforce, so two views can't drift apart:
 
-- **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.
+- **From-price.** A parent's `regular_price`/`price`/`on_sale` are rolled up from the cheapest publishable variant on every save (`admin-products`, the seeder) — real, sortable, filterable, but the **lowest** price, not *the* price. `productPrice(rowOrView, { formatMoney })` (`formatMoney` from `useFormatMoney()`) takes a listing row **or** a `resolveSelection` view → `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range unresolved, the exact price once resolved.
+- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string — passing the object to an `<img src>` fails the load, on every product at once — and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean, de-duplicated entries (non-empty `src`, defaulted `alt`); `[]` means *render your placeholder*. Same trap one level in: `view.display.image` is that normalized object or **`null`** — render `display.image?.src`/`?.alt`, and `null` (no variation *or* parent image) is the one placeholder case.
+- **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 be.
 
 ## 3. What each view *can* render
 
-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.
+Both lists are inventories of what the data supports — **not a layout and not an order**: rendering exactly these fields in this sequence is the generic storefront.
 
-**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.
+**Card:** image, name, `price.label`, a sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `productSpecs`). Link the whole card through; 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)`, `useAddToCart`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, upsells/cross-sells. All but the markup is handed to you: `productImages(product)` + your own active index, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `p.reviews` (+ `submitReview` off `useStorefront()`), and `p.upsells`/`p.crossSells` — added with `useCart().addItem`, matching "already in cart" by product id.
 
-**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.
+**Attributes and modifiers are individually designable.** `productSpecs(product)` rows are `{key, label, titleLabel, value}` and nothing more. ⚑ **Look a row up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`: meta keys are free text typed per product (`care`, `Care`, `Care Instructions`), so an equality test on `label` — or on one spelling of `key` — silently never fires and the feature renders its fallback forever; `titleLabel` is the display-cased form, for a heading. What a row *looks* like is a per-catalog design decision — not one uniform chip row per axis and one grey label/value table ([`../install/02-storefront.md`](../install/02-storefront.md)); §5's rules govern selector *behaviour*, never its form.
 
 ## 4. Ribbons — in **both** views
 
 Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categories are the hierarchical spine. Generated storefronts routinely omit ribbons entirely. Don't.
 
-- **Listing rows carry resolved `ribbons`**, so a card renders them with no extra call; the product page renders the top-level `ribbons` near the metadata, lighter than the breadcrumb. One or two per card is useful, more is noise, and an empty array means render nothing — never a dangling "Ribbons:" label.
-- **Every ribbon links to a filtered listing** — `list-products` with `ribbon_id`, never a dead label. A ribbon has no slug, so key the URL on its id (`/shop?ribbon=<id>`) to keep the page shareable across reloads.
+- **Listing rows carry resolved `ribbons`** — a card renders them with no extra call; the product page renders its top-level `ribbons` near the metadata, lighter than the breadcrumb. One or two per card is useful, more is noise, and `[]` means render nothing — never a dangling "Ribbons:" label.
+- **Every ribbon links to a filtered listing** — `list-products` with `ribbon_id`, never a dead label. A ribbon has no slug, so key the URL on its id (`/shop?ribbon=<id>`) to stay shareable across reloads.
 - **Offer ribbons as a filter** from `useRibbons()` / `list-ribbons`, which hides ribbons no published product carries and gives a `count` for labels like "Gift (12)". `ribbon_id` stacks with `category_id`, price, `on_sale`, `featured`, `in_stock_only`.
 - Ribbons are not breadcrumbs and never variant options — a size or colour is an `attribute`.
 
 ## 5. Variant selection
 
-The one interaction agents reliably get wrong. `variantAxes(view, pick)` hands you the render-ready model that encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise that hides the product's structure), and an option that isn't buyable renders **disabled, not removed** (`o.disabled`; `o.outOfStock` stays visible, just marked). Map it to any control — buttons, swatches, dropdowns — and call `o.pick()` on select.
+The one interaction agents reliably get wrong. `variantAxes(view, pick)` is the render-ready model, and it encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise hiding the product's structure); an unbuyable option renders **disabled, not removed** (`o.disabled`; `o.outOfStock` stays visible, just marked). Map it to any control — buttons, swatches, dropdowns — and call `o.pick()` on select.
 
-Underneath, `useProduct` composes the framework-free helpers in `src/commerce/utils/variants.js` — `defaultSelection` → `selectOption` on a click → `resolveSelection` for the view. Every `product.attributes[]` entry is an **axis** in `position` order; every `variations[]` record is one combination. Bind the UI to `view`, not to `product.*`, or a selection changes nothing:
+Underneath, `useProduct` composes the framework-free helpers in `src/commerce/utils/variants.js`: `defaultSelection` → `selectOption` per click → `resolveSelection`. That middle step keeps dead ends out — it holds the just-picked option and clears **only** conflicting axes (Red/L → click Blue → `{Color: Blue}`, size re-opens), never parking the customer on a combination that resolves to nothing. Every `product.attributes[]` entry is an **axis** in `position` order, every `variations[]` record one combination. Bind the UI to `view`, not `product.*`, or a selection changes nothing:
 
 | `view` field | Binds to |
 |---|---|
 | `axes` | the controls: `[{ key, name, attribute_id, options[] }]`, dead options already dropped |
 | `availability[axisKey][option]` | `"available"` / `"out_of_stock"` / `"unavailable"` (constants `OPTION_*`) |
-| `display` | image, price, `regular_price`, `on_sale`, SKU, stock, weight/dimensions, description — variation-first with parent fallback; `display.image` is normalized or `null` |
-| `priceRange` | `{min, max, on_sale, count}` while the selection is incomplete — render via `useProductPrice(view)` |
+| `display` | image, price, `regular_price`, `on_sale`, SKU, stock, weight/dimensions, description — variation-first with parent fallback; `display.image` per §2 |
+| `priceRange` | `{min, max, on_sale, count}` while the selection is incomplete — render via `productPrice(view, { formatMoney })` |
 | `complete` / `missingAxes` | the button label: `Select a ${view.missingAxes[0]?.name}` |
 | `purchasable` / `addToCart` | gate **Add to cart** on `purchasable`, send `addToCart` (`{product_id, variation_id}`, or `null`) |
-| `variation` / `candidates` / `isVariable` / `selection` | the record itself, the variations still reachable, and the state the selector renders from |
+| `variation` / `candidates` / `isVariable` / `selection` | the record itself, the variations still reachable, the state the selector renders from |
 
 Three decisions the helpers can't make for you:
 
-- **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → visible and labelled. `onbackorder` counts as available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
-- **Incomplete selection.** Show the range from `useProductPrice(view)` — never `€0`, never the bare parent price — and keep Add to cart disabled with a hint at what's missing.
-- **Linkability.** `useProduct` mirrors the selection into the URL (`?color=Ivory`) and hydrates from it, so a variant is shareable and survives a reload; `selectionToParams`/`selectionFromParams` do a custom round-trip, and `selectionForVariation` hydrates controls from a cart line or an `?variation=` link.
+- **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → visible, labelled. `onbackorder` is available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
+- **Incomplete selection.** Show the range from `productPrice(view, { formatMoney })` — never `€0`, never the bare parent price — and keep Add to cart disabled with a hint at what's missing.
+- **Linkability.** `useProduct` mirrors the selection into the URL (`?color=Ivory`) and hydrates from it, so a variant is shareable and survives a reload; `selectionToParams`/`selectionFromParams` are that round-trip by hand, `selectionForVariation` hydrates controls from a cart line or an `?variation=` link.
 
-**Attributes but no usable variations** — what attaching an attribute and stopping leaves behind — deliberately gets no parent fallback, because `add-item` would reject it: empty `axes[].options`, `purchasable: false`, `addToCart: null`. Render it as unavailable rather than painting empty selector groups, and guard the label (with no attributes at all `missingAxes[0]?.name` is `undefined` → "Select a undefined").
+**Attributes but no usable variations** — attaching an attribute and stopping — gets no parent fallback by design, since `add-item` would reject it: empty `axes[].options`, `purchasable: false`, `addToCart: null`. Render it as unavailable rather than painting empty selector groups, and guard the label: with no attributes at all `missingAxes[0]?.name` is `undefined` → "Select a undefined".
 
-**Add to cart** goes through `useAddToCart(product)`, whose `addToCart()` never throws and maps the codes: `variation_required` (a page bug — empty `variation_id` on a product with attributes), `out_of_stock` / `insufficient_stock`, and `variation_not_found` (the catalog changed under the page → the hook reloads the product itself). `product.sold_individually` caps quantity at 1, already reflected in `useProduct().maxQuantity`. Two behaviors that matter only if you hand-roll the view model: non-publishable variations never leak an option into the UI, and an empty `option` on a variation axis means **"any"**.
+**Add to cart** goes through `useAddToCart(product)`: `addToCart()` never throws and maps the codes — `variation_required` (a page bug: empty `variation_id` on a product with attributes), `out_of_stock`/`insufficient_stock`, `variation_not_found` (the catalog changed under the page → the hook reloads it). `product.sold_individually` caps quantity at 1, reflected in `useProduct().maxQuantity`. Two behaviors only a hand-rolled view model gets wrong: non-publishable variations never leak an option into the UI, and an empty `option` on an axis means **"any"**.
 
 ## 6. Adding a `get-product`-only field to the listing
 
-If the store needs something a row doesn't carry — resolved categories are the common one — resolve it **in the listing call**, never with `get-product` per card (N requests for one grid). `list-products` resolves its page slice through a helper in `base44/functions/commerce/storefront-catalog/entry.ts`:
-
-```ts
-const pageItems = await withRibbons(sr, products.slice(start, start + perPage).map(publicProduct));
-```
-
-`withRibbons` reads the taxonomy **once per request** and maps ids onto the rows — not once per row. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to fields the UI renders; a listing payload is served on every browse.
+Something a row doesn't carry (resolved categories, typically) gets resolved **in the listing call**, never `get-product` per card (N requests for one grid). `list-products` resolves its page slice through one helper in `base44/functions/commerce/storefront-catalog/entry.ts` — `await withRibbons(sr, pageRows.map(publicProduct))` — which reads the taxonomy **once per request**, not once per row, and maps ids onto the rows. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to fields the UI renders — a listing payload is served on every browse.
 
-Don't add `variations` to every row — the heaviest read in the catalog, and a grid doesn't need it; if cards must show true ranges, precompute `price_min`/`price_max`. And don't relax entity RLS to read the catalog from the client — it is admin-only by design ([`guest-access-security.md`](./guest-access-security.md)); widen the function's response instead.
+Don't add `variations` to every row — the heaviest read in the catalog, and a grid doesn't need it; if cards must show true ranges, precompute `price_min`/`price_max`. And don't relax entity RLS to read the catalog client-side — it is admin-only by design ([`guest-access-security.md`](./guest-access-security.md)); widen the function's response instead.

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

@@ -17,6 +17,16 @@ What it does **not** ship is a live provider. Wiring one means **one file** —
 
 Card payments are **off by default** and are the last thing to add, never the first — the rule, the timing and the decision table live in [`../install/03-data.md`](../install/03-data.md). Everything below assumes that decision is made.
 
+## Enabling the gateway — one seed call, at any time
+
+⚑ **Turning `card` on is a `commerce/seed-store` call, never an edit to `commerce.PaymentGateway`.** The gateway row is derived data: the seeder enables every slug you list and disables every one you don't, so writing `enabled` on the record by hand is undone by the next seed and skips the checks the seeder makes.
+
+```js
+await base44.functions.invoke("commerce/seed-store", { payment_methods: ["offline", "card"] });
+```
+
+That is the **whole payload**. `seed-store` is idempotent and every key is independent, so this is as valid on a live store months later as it is during the install: no `products` key means no catalog work, no `locations` key leaves shipping exactly as it is, and `store_name` is only required on a store's very first seed. Drop `"offline"` from the array for a card-only store — the list is the complete set of enabled methods, not an addition to it.
+
 | Function | Backs |
 |---|---|
 | `createCardPayment(sr, order, {successUrl, cancelUrl, customerEmail})` | checkout + payment links: a hosted page for `order.total`, returning `{ url, reference }`, with `order.id`/`order.order_key` on the payment's metadata |

package/skills/commerce/references/reviews.md

@@ -1,41 +1,48 @@
 ---
 stage: reference
-read_when: "You need review behaviour beyond useProductReviews — moderation, auto-approval, a customer's own reviews, or a policy the three built-in ones don't cover."
-skip_when: "useProductReviews is on the product page — that is list + submit + policy + the right confirmation copy already."
+read_when: "You are building the review surface — the list, the form, a policy (login-gated, verified buyers) — or need moderation, auto-approval, or a customer's own reviews."
+skip_when: "The product page already renders `p.reviews` and submits through `submitReview`, with the confirmation copy following the response's `status`."
 forget_when: "A review submits, appears (or is held) as the store's auto-approve setting dictates, and the aggregate rating renders."
 carry_forward:
-  - "Reviews are part of the happy path: one hook. The confirmation copy must come from the submit response, never hardcoded."
+  - "Reviews are part of the happy path: the list arrives with the product, submitting is one client call. The confirmation copy must come from the submit response's `status`, never hardcoded."
 ---
 
 # Reviews
 
-Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and the whole UI contract is one hook. Unless the store explicitly doesn't want them, put them on the product page: `useProductReviews(product, { policy, user, requireRating, perPage })` — the list with paging (`items`, `hasNext`/`loadMore`), the aggregates (`averageRating`, `ratingCount`), the whole form contract (`form`/`setField`/`fieldErrors`/`valid`/`submit`/`message`) and the policy gate (`canReview`, `reviewBlockedReason`, `requiresEmail`); exact shapes in its JSDoc. The markup around it — stars, rows, the form — is yours, like all storefront UI.
+Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and the storefront's half is two calls. Unless the store explicitly doesn't want them, put them on the product page — `useProduct(slug)` already hands you `p.reviews` (the first page of approved reviews plus the aggregates, fetched with the product), and submitting is one method. There is no reviews hook and no review markup: the stars, the rows, the form and every word around them are yours, like all storefront UI.
+
+## The two client calls
+
+Both live on the storefront client in `@/commerce/utils` — in React, `useStorefront()` is that client:
+
+- **`getProductReviews(slugOrRef, { page, per_page })`** → `{ items, page, per_page, has_next, average_rating, rating_count }`. The same reviews `get-product` returns — page or refresh the list without re-fetching the page; `useProduct(slug, { reviewsPerPage })` sizes the first one.
+- **`submitReview({ product_id, review, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. `review` is the body text and is required; `rating` is optional, **0–5**; `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
 
 ## What ships
 
 - `get-product` returns **paginated `reviews`** plus `average_rating`, `rating_count` and a `verified` flag per review; `list-products` rows carry the aggregates, so **stars on cards cost no extra call**;
-- `submit-review` accepts `{ product_id, email, reviewer?, review, rating? }` from **anyone — no login**. A signed-in caller's session email always wins (the payload cannot impersonate); a guest supplies `email`; `verified` comes from that email's order history. The three error codes (`400 email_required | review_incomplete | invalid_rating`) land on their fields via `fieldErrors` instead of rejecting into nothing;
+- `submit-review` accepts `{ product_id, email, reviewer?, review, rating? }` from **anyone — no login**. A signed-in caller's session email always wins (the payload cannot impersonate); a guest supplies `email`; `verified` comes from that email's order history;
 - `storefront-account` `my-reviews` lists a signed-in customer's own — what a "My reviews" account tab renders from;
 - moderation is in the admin (Products → Reviews); `commerce/admin-reviews` recalculates the product's rating on every status change.
 
-## The `policy` prop
+## The policy is the store's
 
-`policy` is the store's review rule as one option, replacing the patterns a storefront used to implement by hand. Pass your app's current user alongside it (`useProductReviews(product, { policy: "login", user })`) — the stricter policies need it:
+Which visitors may submit is a gate **you** render, in your own words. The three patterns worth knowing:
 
-| `policy` | Who may submit | Blocked as |
+| Policy | Who may submit | How you implement it |
 |---|---|---|
-| `"open"` (default) | anyone with a valid email — the server's own rule | — |
-| `"login"` | a signed-in visitor only | `reviewBlockedReason: "login_required"` |
-| `"verified_buyers"` | someone whose own orders include a `processing`/`completed` order for this product (checked via `my-orders`) | `"not_a_buyer"` |
+| **Open** (the server's own rule) | anyone with a valid email | render the form for everyone; the email field is required for guests |
+| **Login-gated** | a signed-in visitor only | render the form only when your app has a user; otherwise your "sign in to review" line |
+| **Verified buyers** | someone whose own orders include a `processing`/`completed` order for this product | check `storefront-account` `my-orders` for the product, gate on the result |
 
-Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate. `requireRating: true` makes the stars mandatory; `requiresEmail` is `false` for a signed-in visitor, so the field is hidden (the session's email wins server-side anyway). A policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
+Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side), and make the stars mandatory by validating before you call. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
 
 ## Auto-approval and moderation
 
 `products.auto_approve_reviews` ([`store-settings.md`](./store-settings.md), toggle on the admin's Reviews screen) is the **only** server-side switch: off (the default) holds every review as `hold` for moderation; on publishes immediately.
 
-So **the confirmation copy must come from the response**: `submit()` resolves `{ ok, status, verified }` with `status` `"approved"` or `"hold"`, and `message` follows it. A hardcoded "awaiting approval" lies to every store with auto-approval on — and after an approved submission the hook refreshes the list so the review actually appears.
+So **the confirmation copy must come from the response**: `submitReview` resolves `{ review_id, status, verified }` with `status` `"approved"` or `"hold"`, and your message follows it. A hardcoded "awaiting approval" lies to every store with auto-approval on — and only the approved case is worth refreshing the list for.
 
-Disabling reviews store-wide is simply building no review UI; there is no server switch to keep in sync.
+Disabling reviews store-wide is simply building no review UI; there is no server switch to keep in sync (and then no star ratings on cards either — an average of nothing is `0`).
 
 Shapes and error details: [`../docs/api-storefront.md`](../docs/api-storefront.md#submit-review). Where ratings belong per view: [`catalog-rendering.md`](./catalog-rendering.md).

package/skills/commerce/references/store-settings.md

@@ -15,7 +15,7 @@ Six records, one per group: `general`, `products`, `inventory`, `tax`, `shipping
 |---|---|---|
 | **`general`** | | |
 | `order_received_path` | `"/order-received"` | The route a paying customer returns to; `shared/commerce/payments.ts` builds the provider's success/cancel URLs from it. A value that doesn't match your route is a 404 after payment and an order never confirmed. |
-| `currency` | `"USD"` | ISO code, **a value not a format**. Stamped on orders by `storefront-checkout`; published on `get-store-info` for `useMoney`/`useFormatMoney`. |
+| `currency` | `"USD"` | ISO code, **a value not a format**. Stamped on orders by `storefront-checkout`; published on `get-store-info` for `useFormatMoney`. |
 | `weight_unit` / `dimension_unit` | `"kg"` / `"cm"` | Labels only — nothing converts. Admin product form, `get-store-info`. |
 | **`products`** | | |
 | `auto_approve_reviews` | `false` | The **only** server-enforced review rule: `submit-review` returns `status: "hold"` or `"approved"`. Confirmation copy comes from that response ([`reviews.md`](./reviews.md)). |

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

@@ -11,19 +11,24 @@ 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.
+  the first action, wait for the initial load to settle — `useCart().status`
+  leaves `"loading"` exactly once and never returns there for a mutation, 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**: `useCartLine` 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. The row's `pending` is the
+  only mutation-settled signal there is (`pending === false` with no `error`
+  means the row, the totals and any badge have all landed) — wait for the busy
+  state the page renders from it (`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 unmounted 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 a hidden copy.
+  "Remove" buttons for one line — drawer and cart page behind it. `useCartUI`
+  only hands the page an `open` flag: whether the closed drawer is unmounted
+  (`{ui.open && …}`) or merely translated off-screen is the store's choice, so
+  assume the duplicates exist and query inside the open drawer's container,
+  never the document. A click that seems to do nothing usually hit a 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
@@ -42,6 +47,7 @@ DOM is briefly right about the *intent* and wrong about the *state*.
   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).
+  from a fresh navigation to `orderReceivedUrl(result)`
+  (`/order-received?order_id=…&order_key=…` — the ids come back in
+  `placeOrder`'s result, and `commerce/admin-orders` `search` has the order
+  either way).