@base44/app-plugin-commerce 0.1.5 → 0.1.7

package/skills/commerce/post-installation.md

@@ -1,6 +1,6 @@
 # Post-installation
 
-What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, and build the storefront from the quick start below. Installed into the app at `skills/commerce/post-installation.md`.
+What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, and build the storefront from the quick start below. Installed into the app at `.agents/skills/commerce/post-installation.md`.
 
 ---
 
@@ -44,11 +44,11 @@ Even if the client guard were bypassed, layers 2 and 3 keep the store data safe.
 
 ## 2. Store data — seeding
 
-A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices), the `offline` and `stripe` payment gateways, three tax classes and a free "Rest of the world" fallback shipping zone — and, depending on the payload, the catalog:
+A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices) and the `offline` and `card` payment gateways — and, depending on the payload, the catalog. A fallback "Rest of the world" **Shipping & Tax Location** (one free shipping rate, no tax) is seeded **only when the payload carries no `locations`** — locations you pass are the store's only shipping data, with no seeded fallback beside them. Pass **`currency`** (an ISO code, e.g. `"EUR"`) and/or **`weight_unit`**/**`dimension_unit`** to set the store's currency and measurement units instead of the defaults — explicit values always win, on a first seed and a re-run alike. (Prices are *formatted* with `Intl.NumberFormat` per the viewer's locale — the currency is a value; there are no format settings.)
 
 | Mode | Body | Products created |
 |---|---|---|
-| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `tax_rates`) | Yours — categories, attributes, variants and all, in this one call |
+| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) | Yours — categories, ribbons, attributes, variants and all, in this one call |
 | **Demo data** | `{ store_name, with_sample_data: true }` | The template's 10 generic demo products (skipped if any product exists) |
 | **No products** | `{ store_name }` | None — defaults only |
 
@@ -60,11 +60,14 @@ The call runs a canary schema check first — on **422** `schema_incompatible` f
 
 ### 2.1 The `products` payload
 
-Reference everything by **display name** — categories, tags, attributes and their options are get-or-created (slugs and codes derived, existing records matched case-insensitively and reused). Variants come from `attributes`: list each axis with the options the product comes in, and either pass explicit `variations` (only the combinations you stock, with per-variation overrides) or omit them to auto-generate **every combination**. Prices and the sale window are inherited from the product spec unless a variation overrides them; a variation with its own `stock_quantity` tracks it, one without draws on the parent's pooled `stock_quantity`.
+**This is the store's real data, not template data.** The call writes the actual `commerce.*` records the admin and the storefront API read from that moment on — nothing is post-processed, substituted or "filled in by the platform" later. Whatever you pass is exactly what `list-products`/`get-product` return, so pass final values (real copy, real prices, permanently-resolvable image URLs) and build the storefront on what the API returns — never on client-side constants mirroring the seed (e.g. a slug→image map): the database is the single source of truth, and such a mirror silently diverges the first time a product is edited in the admin.
+
+Reference everything by **display name** — categories, ribbons, attributes and their options are get-or-created (slugs and codes derived, existing records matched case-insensitively and reused). Variants come from `attributes`: list each axis with the options the product comes in, and either pass explicit `variations` (only the combinations you stock, with per-variation overrides) or omit them to auto-generate **every combination**. Prices and the sale window are inherited from the product spec unless a variation overrides them; a variation with its own `stock_quantity` tracks it, one without draws on the parent's pooled `stock_quantity`.
 
 ```js
 await base44.functions.invoke("commerce/seed-store", {
   store_name: "Aurora Threads",
+  currency: "EUR",                             // optional — defaults to USD
   products: [
     { // simple product
       name: "Classic T-Shirt",
@@ -72,7 +75,7 @@ await base44.functions.invoke("commerce/seed-store", {
       regular_price: 19.99,
       stock_quantity: 50,                      // implies manage_stock: true
       categories: ["Clothing"],                // get-or-create by name
-      tags: ["bestseller"],
+      ribbons: ["Best Seller"],
       images: ["https://…/tee.jpg"],           // URLs or { src, alt }
       short_description: "A soft, breathable everyday tee.",
       description: "<p>Cut from combed cotton…</p><ul><li>100% combed cotton</li><li>Pre-shrunk</li></ul>",
@@ -98,10 +101,16 @@ await base44.functions.invoke("commerce/seed-store", {
     },
   ],
   coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],   // optional
+  locations: [{                              // optional — passing any makes these the store's ONLY locations (the free-shipping fallback is not seeded)
+    name: "Israel", countries: ["IL"],
+    shipping_rates: [{ name: "Standard", cost: 20, free_over: 150 }],
+    tax_groups: [{ name: "Products", rates: [{ name: "VAT", rate: 18 }] }],
+    shipping_tax: { type: "percent", value: 18 },   // or { type: "fixed", value: 5 }
+  }],
 });
 ```
 
-What the seeder does per product: derives a unique slug, checks SKU uniqueness, prices variations (`sale_price` + optional `date_on_sale_from/to` supported at both levels), rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant (never set a variant parent's price yourself — it's derived), sets `stock_status`, and maintains category/tag counts. Products default to `status: "publish"`; pass `"draft"` to review first. Other `commerce.Product` fields (`weight`, `dimensions`, `virtual`, `downloadable`, `downloads`, `meta_data`, …) pass through; unknown keys are rejected so typos surface instead of vanishing.
+What the seeder does per product: derives a unique slug, checks SKU uniqueness, prices variations (`sale_price` + optional `date_on_sale_from/to` supported at both levels), rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant (never set a variant parent's price yourself — it's derived), sets `stock_status`, and maintains category/ribbon counts. Products default to `status: "publish"`; pass `"draft"` to review first. Other `commerce.Product` fields (`weight`, `dimensions`, `virtual`, `downloadable`, `downloads`, `meta_data`, …) pass through; unknown keys are rejected so typos surface instead of vanishing.
 
 **Re-runs converge instead of duplicating**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported — safe for retries after a timeout, and for seeding into a store that already has products. Limits: ≤100 products and ≤500 variations per call, ≤50 variations per product (an auto-generated cartesian above that is rejected — pass explicit `variations`).
 
@@ -110,24 +119,25 @@ The response reports everything:
 ```jsonc
 { "seeded": { "settings_groups": 6, "gateways": 2, ... },
   "catalog": {
-    "categories": { "created": 2, "reused": 0 }, "tags": { ... }, "attributes": { ... }, "terms": { ... },
+    "categories": { "created": 2, "reused": 0 }, "ribbons": { ... }, "attributes": { ... }, "terms": { ... },
     "products_created": 2, "products_skipped": 0, "variations_created": 4,
-    "coupons": { "created": 1, "skipped": 0 }, "tax_rates": { "created": 0, "skipped": 0 },
+    "coupons": { "created": 1, "skipped": 0 }, "locations": { "created": 1, "skipped": 0 },
     "products": [
       { "name": "Classic T-Shirt", "id": "…", "slug": "classic-t-shirt", "sku": "TEE-CLASSIC", "variation_count": 0 },
       { "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "sku": "SNK-RUN", "variation_count": 4 }
     ]
   },
-  "store_name": { "value": "Aurora Threads", "action": "created" } }
+  "store_name": { "value": "Aurora Threads", "action": "created" },
+  "currency": { "value": "EUR", "action": "created" } }   // "updated" | "unchanged" on re-runs; null when not passed
 ```
 
-**Images**: every product needs at least one. Use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product.
+**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. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. If an image isn't ready at seed time, seed without it and set it afterwards through the admin API — don't seed a dead path and compensate in the frontend.
 
-A successful response means the data is in — the catalog and settings are live exactly as reported. Write any store-specific settings into `commerce.StoreSettings` (direct CRUD, one record per `group_id` — currency and units are the usual ones; patch `values`, don't replace groups you weren't asked about).
+A successful response means the data is in — the catalog and settings are live exactly as reported. Write any remaining store-specific settings into `commerce.StoreSettings` (direct CRUD, one record per `group_id` — weight/dimension units are the usual ones; patch `values`, don't replace groups you weren't asked about).
 
 ### 2.2 Payments
 
-Card payments are **already implemented** (hosted payment page, payment links, refunds) — make sure a payment provider (i.e. the platform's **Stripe** integration) is configured for the app, and the store takes cards; the `offline` gateway (manual reconciliation) works with nothing to configure. Provider internals, webhooks and refunds are day-2 material: [`references/online-payments.md`](./references/online-payments.md).
+The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions. The **Credit card** option needs a payment provider, which means implementing exactly two files (`shared/commerce/card-payment.ts` + the payment webhook); until then it answers `503 no_card_payment_provider` at checkout, or can simply be switched off. Details: [`references/online-payments.md`](./references/online-payments.md).
 
 ---
 
@@ -147,25 +157,26 @@ The cart is identified by a **`cart_token`** the backend mints — persist it in
 
 ```js
 const info = await inv("commerce/storefront-catalog", { action: "get-store-info" });
-// info.settings → { store_name, currency, currency_position, num_decimals, … } — format money with these
+// info.settings → { store_name, currency, weight_unit, … } — format money with
+// Intl.NumberFormat(undefined, { style: "currency", currency: info.settings.currency })
 // info.payment_gateways → [{ slug, title, description, online }] — you'll need this at checkout
 // info.countries / info.currencies → static tables for address forms and money display
 
 const { products, page, per_page, has_next } = await inv("commerce/storefront-catalog", {
   action: "list-products",
-  page: 1, per_page: 12,           // optional: search, category_id, tag_id, featured, on_sale,
+  page: 1, per_page: 12,           // optional: search, category_id, ribbon_id, featured, on_sale,
   sort: "-created_date",           //   min_price, max_price, in_stock_only
 });                                // sort: -created_date | name | price | -price | popularity | rating
 ```
 
-Each row is a full product record — for a card use `name`, `images[0]?.src`, `price`, `regular_price`, `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `tags` (`[{ id, name }]`, may be absent). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `{ action: "list-categories" }` (a tree via `parent_id`).
+Each row is a full product record — for a card use `name`, `images[0]?.src`, `price`, `regular_price`, `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `{ action: "list-categories" }` (a tree via `parent_id`).
 
 **Carry forward:** each card links to the product page by **`slug`**.
 
 ### 3.2 Product page — variant selection included
 
 ```js
-const { product, variations, categories, tags, reviews } =
+const { product, variations, categories, ribbons, reviews } =
   await inv("commerce/storefront-catalog", { action: "get-product", slug });   // or { id }
 
 // One selector PER product.attributes[] entry — never a flat list of variations.
@@ -182,21 +193,21 @@ const view = resolveSelection(product, variations, selection);
 // view.addToCart    → { product_id, variation_id } — null until the selection resolves
 ```
 
-Add to cart — **create** mints the `cart_token` on first add; every later call reuses it:
+Add to cart — `add-item` bootstraps the cart itself: a missing, stale or expired token starts a fresh cart, so the one rule is to **re-persist the `cart_token` from every response** (your cached token may have expired — 48h TTL — or been consumed by a checkout):
 
 ```js
-let cart_token = localStorage.getItem("cart_token");
-if (!cart_token) {
-  const cart = await inv("commerce/storefront-cart", { action: "create" });
-  cart_token = cart.cart_token;
-  localStorage.setItem("cart_token", cart_token);
-}
-await inv("commerce/storefront-cart", { action: "add-item", cart_token, ...view.addToCart, quantity: 1 });
+const cart = await inv("commerce/storefront-cart", {
+  action: "add-item",
+  cart_token: localStorage.getItem("cart_token") || undefined,   // fine if absent/stale
+  ...view.addToCart,
+  quantity: 1,
+});
+localStorage.setItem("cart_token", cart.cart_token);   // ALWAYS — the token may be a new cart's
 ```
 
-A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call. Show `reviews` (`{ items, has_next, average_rating, rating_count }`) and the `upsells`/`cross_sells` summaries the same response carries.
+A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call. Show `reviews` (`{ items, has_next, average_rating, rating_count }`) and the `upsells`/`cross_sells` summaries the same response carries. On the other cart actions a `404 cart_not_found|cart_expired` means the cached token went stale — clear it and treat the cart as empty.
 
-**Carry forward:** the **`cart_token`**.
+**Carry forward:** the **`cart_token`** — from the response, every time.
 
 ### 3.3 Cart
 
@@ -213,44 +224,65 @@ cart = await inv("commerce/storefront-cart", { action: "remove-item", cart_token
 cart = await inv("commerce/storefront-cart", { action: "apply-coupon", cart_token, code });
 ```
 
-Shipping is chosen **on the cart, before place-order** — this is the step storefronts most often skip, and `place-order` refuses without it (`400 shipping_method_required`):
+Shipping is chosen **on the cart, before place-order** — this is the step storefronts most often skip, and `place-order` refuses without it (`400 shipping_method_required`). **Call `set-shipping-address` the moment the customer provides an address** — every shipping option and cost is recalculated by that call (never reuse a list fetched earlier), and an address the store doesn't ship to **fails right there** with `400 shipping_not_available`, so the address form is where you surface it:
 
 ```js
+// as soon as the address is entered — this is what (re)calculates shipping options + cost
 cart = await inv("commerce/storefront-cart", { action: "set-shipping-address", cart_token,
-  address: { country, state, postcode, city } });
+  address: { country, state, postcode, city } });   // 400 shipping_not_available → show it on the address form
+// cart.chosen_shipping_method is the rate's ID (a string) — to display it, look
+// it up: cart.available_shipping_methods.find(m => m.id === cart.chosen_shipping_method)
+// and render that entry's title + cost. Never render the id itself.
 switch (cart.shipping_status) {
-  case "auto_selected":                 // one option — already applied, nothing to do
+  case "auto_selected": break;          // only ONE option existed — the backend already applied it;
+                                        // no picker needed, just display the looked-up title + cost
   case "chosen": break;                 // customer's earlier choice still valid
-  case "choice_required":               // MUST render cart.available_shipping_methods [{ id, title, cost }]
+  case "choice_required":               // several options — MUST render cart.available_shipping_methods
+    // [{ id, title, cost }] as a picker, then send the customer's pick:
     cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method", cart_token,
       method_id: picked.id });          // the entry's id, not its method_id type
     break;
-  case "none_available": /* the store doesn't ship there — say so, don't place the order */ break;
+  case "missing_address": break;        // several zones, no address yet — shipping cost is NOT
+                                        // calculated; collect the address and call set-shipping-address
   case "not_needed": break;             // fully virtual cart
 }
 ```
 
+A store with exactly **one shipping zone** shows its options (and, auto-selected, the cost) on the cart even before an address is set — the options are the same everywhere. Several zones report `missing_address` until the address resolves one.
+
 **Carry forward:** the **`cart_token`** (address and method choice live on the cart).
 
 ### 3.4 Checkout & order-received
 
-Payment methods are `info.payment_gateways` from step 1 — render them as they come (`online: true` marks the card/redirect gateway; `offline` is manual reconciliation). Make sure a payment provider (i.e. Stripe) is configured for the app. Then one call places the order:
+The checkout page renders **two sets of options that are store data, never hardcoded**: the shipping methods (already resolved on the cart in step 3 — `place-order` refuses with `400 shipping_method_required` until `shipping_status` is `chosen`/`auto_selected`/`not_needed`) and the payment methods, which come from `info.payment_gateways` (step 1) — every gateway the admin has **enabled**:
+
+```js
+// wiring a card provider = implementing two files — details:
+// .agents/skills/commerce/references/online-payments.md
+const gateways = info.payment_gateways;   // [{ slug, title, description, online }] — admin-owned data
+// several → render a picker using the admin's title/description as the labels
+// exactly ONE → no picker: use it directly, but still show its title so the customer knows how they'll pay
+// none → checkout cannot complete — say so instead of rendering a dead button
+const payment_method = gateways.length === 1 ? gateways[0].slug : picked.slug;  // never a hardcoded "card"
+```
+
+While the store has no card provider implemented, picking the card gateway fails `place-order` with `503 no_card_payment_provider` — tell the customer card payment is temporarily unavailable and offer the other methods.
+
+`online: true` marks the card/redirect gateway; every other gateway is manual reconciliation. Then one call places the order:
 
 ```js
-// card payments ride the app's Stripe integration — setup & provider details:
-// skills/commerce/references/online-payments.md
 const res = await inv("commerce/storefront-checkout", {
   action: "place-order", cart_token,
-  payment_method: gateway.slug,                       // from info.payment_gateways
+  payment_method,                                     // the slug chosen above
   billing: { first_name, last_name, address_1, city, country, email },   // the required set; phone, state, postcode optional
   // shipping: { … } if it differs from billing; customer_note?; return_url: window.location.origin
 });
 // res → { order_id, order_number, order_key, status, totals, order,
-//         payment_instructions,   // offline: { description, account_details } — render them
-//         payment }               // online: { status: "requires_payment", checkout_url, … } | null
+//         payment_instructions,   // manual gateways: { description, account_details } — render them
+//         payment }               // card: { status: "requires_payment", checkout_url, … } | null
 
 if (res.payment?.status === "requires_payment") window.location.href = res.payment.checkout_url;
-else showConfirmation(res);        // offline order placed — show payment_instructions
+else showConfirmation(res);        // manual order placed — show payment_instructions
 ```
 
 Every payment link returns to **`/order-received`** — the page from §1 step 3. It is one call, idempotent, safe on every visit:
@@ -258,21 +290,24 @@ Every payment link returns to **`/order-received`** — the page from §1 step 3
 ```js
 // GET /order-received?order_id=…&order_key=…&payment=success|cancel
 const params = new URLSearchParams(window.location.search);
-const { state, order, payment_link } = await inv("commerce/payments", {
+const { state, order, payment_link, payment_instructions } = await inv("commerce/payments", {
   action: "complete-return",
   order_id: params.get("order_id"), order_key: params.get("order_key"),
   payment: params.get("payment"),        // only a hint — the server verifies with the provider
   return_url: window.location.origin,
 });
 // state === "paid"      → thank-you + order summary (order is now marked paid)
-// state === "unpaid"    → offer payment_link.url to try again
+// state === "unpaid"    → card order: offer payment_link.url to pay now;
+//                         manual order: render payment_instructions ({ description, account_details })
 // state === "cancelled" → payment was cancelled — offer payment_link.url or support
 ```
 
+Two shapes to get right when rendering: **`order` carries flat totals** — `order.total`, `order.shipping_total`, `order.total_tax` — there is **no `order.totals` object** (that nested shape belongs to the cart view and the place-order response's top-level `totals`); and `payment_link` is `{ url, reference } | null` (card orders only).
+
 **Carry forward:** `order_id` + `order_key` are the guest's proof of ownership — `commerce/storefront-account` `get-order` with both returns the order for a tracking page (signed-in customers get `my-orders` with no key).
 
 ---
 
 ## 4. Next
 
-Continue with the commerce skill — [`skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, deeper storefront features ([`references/product-render.md`](./references/product-render.md) for what to render per view, [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variant edge cases, [`references/reviews.md`](./references/reviews.md) for the ready-made reviews backend), Stripe wiring, scheduled maintenance, emails, webhooks, and operational limits.
+Continue with the commerce skill — [`.agents/skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, deeper storefront features ([`references/product-render.md`](./references/product-render.md) for what to render per view, [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variant edge cases, [`references/reviews.md`](./references/reviews.md) for the ready-made reviews backend), payment provider wiring, scheduled maintenance, emails, webhooks, and operational limits.

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

@@ -4,20 +4,23 @@ Where to change what, in `src/commerce/admin/pages/products/`. The shape follows
 rule: **a product sells variants because it carries attributes** — there is no product
 type — so everything a customer actually buys is edited in one place.
 
-## Tabs
+## Sections
 
-`components/ProductDataPanel.jsx` builds the list. There are four, and two are conditional:
+`components/ProductDataPanel.jsx` stacks the sections one below the other — no side menu.
+There are four, and one is conditional:
 
-| Tab | File | Holds |
+| Section | File | Holds |
 |---|---|---|
-| **Price & Inventory** | `components/tabs/PriceInventoryTab.jsx` | Tax status/class and *limit to 1 per order* (product-wide) → the **Attributes** section → a row per purchasable thing |
+| **Price & Inventory** | `components/tabs/PriceInventoryTab.jsx` | Tax status/group and *limit to 1 per order* (product-wide) → the **Attributes** section → a row per purchasable thing |
 | **Modifiers** | `components/tabs/ModifiersTab.jsx` | `meta_data` key/value pairs — descriptive properties (Material, Care, GTIN). They never affect price, stock or variants |
 | **Downloads** | `components/tabs/DownloadsTab.jsx` | Only when `downloadable` |
 | **Linked products** | `components/tabs/LinkedTab.jsx` | Upsells and cross-sells |
 
-`Virtual` and `Downloadable` are checkboxes in the panel header, not tabs. There is no
-General, Inventory, Variations, Attributes, Shipping, Advanced or External tab — all of
-those were removed, and `scripts/install.js` retires the files on upgrade.
+`Virtual` and `Downloadable` are checkboxes in the panel header. The main column reads
+Name → Description → Short description → Product data; the sidebar's **Publish** box has a
+single **Visible** toggle driving `status` (publish/draft) — there is no catalog-visibility
+field. The product's **Tax group** names a group defined per Shipping & Tax Location
+(default `Products`).
 
 ## Price & Inventory
 
@@ -25,9 +28,9 @@ those were removed, and `scripts/install.js` retires the files on upgrade.
   edits the product's own fields. A product with attributes shows a row per variant.
   Both go through the same `PriceFields` / inventory / `ShippingFields` / `DownloadsFields`
   components, so there is one definition to change, not two.
-- **Shipping is per row.** Weight, dimensions and shipping class live on each variant (a
-  large mug weighs more than a small one); the Base price row edits the product's own.
-  Hidden when the product is virtual.
+- **Shipping is per row.** Weight and dimensions live on each variant (a large mug weighs
+  more than a small one); the Base price row edits the product's own. Hidden when the
+  product is virtual.
 - **The parent price is not editable** when variants exist — `commerce/admin-products`
   derives `regular_price`, `price` and `on_sale` from the cheapest publishable variant on
   save, and the seeder does the same. Don't add an input for it.
@@ -52,5 +55,5 @@ merchant touches anything. Keep that guard if you touch the effect.
 
 Attribute and value *records* are shared between products, so the **Manage attributes**
 dialog saves them immediately, unlike the rest of the form which batches until Save. There
-are no Attributes or Tags pages in the side menu: attributes are reachable only from here,
-tags from the `TaxonomyPanel` card in the product sidebar.
+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.

package/skills/commerce/references/emails.md

@@ -1,10 +1,10 @@
 # Emails
 
-Transactional email is sent via `base44.integrations.Core.SendEmail` from the shared `emails.ts`. Ten order emails are wired to the lifecycle (see the side-effect matrix in [`skills/commerce/docs/api-admin.md`](../docs/api-admin.md)): `new_order`, `cancelled_order`, `failed_order`, `on_hold_order`, `processing_order`, `completed_order`, `refunded_order`, `partial_refund`, `customer_invoice`, `customer_note`. `reset_password` and `new_account` are handled by **Base44 auth**, not this template.
+Transactional email is sent via `base44.integrations.Core.SendEmail` from the shared `emails.ts`. Ten order emails are wired to the lifecycle (see the side-effect matrix in [`.agents/skills/commerce/docs/api-admin.md`](../docs/api-admin.md)): `new_order`, `cancelled_order`, `failed_order`, `on_hold_order`, `processing_order`, `completed_order`, `refunded_order`, `partial_refund`, `customer_invoice`, `customer_note`. `reset_password` and `new_account` are handled by **Base44 auth**, not this template.
 
 - Per-type enable/subject/heading/recipient/additional_content overrides live at the **top level** of the `emails` StoreSettings group, keyed by type id (`emails.new_order.enabled`) — that is the path `shared/commerce/emails.ts` reads. Editable in Settings → Emails; blank = built-in default. Don't nest them under a sub-object: the backend won't see them.
 - Admin notifications (`new_order`, `cancelled_order`, `failed_order`) resolve in three steps: the per-type `recipient` if it holds an address, else `emails.admin_recipients`, else — at send time — **the app's users with `role: "admin"`** (`sr.entities.User.filter({role:"admin"})`, memoized per isolate). Both settings accept a comma-separated list and drop blank entries, so a cleared per-type override falls back rather than sending to an empty address. Nothing is seeded: a fresh store notifies its admin users until someone sets explicit recipients, and promoting an admin is enough to add them. Only when there is also no admin user does the email go nowhere, logged in `commerce.EmailLog` with `success: false` and an `error` naming what was empty. Settings → Emails shows the addresses actually in effect (via `commerce/admin-tools` `admin-email-recipients`).
-- Stock notifications follow the same chain: `inventory.notification_recipient`, else the first `emails.admin_recipients` entry, else the first admin user.
+- Stock notifications (`low_stock`, `out_of_stock`) sit in the same Settings → Emails list and are configured per type like the rest (`emails.low_stock.enabled`, `emails.low_stock.recipient`). Recipients resolve exactly like the admin order emails: per-type `recipient`, else `emails.admin_recipients`, else the app's admin users — comma-separated lists reach every address. Subject and body are generated (product name, SKU, remaining stock), so there are no subject/heading overrides for these two.
 - The **store name** is `emails.store_name` — one setting, used for both the `{store_name}` in subjects/headings and the sender name. It lives nowhere else, but it is not email-only: `storefrontSafeSettings()` publishes it as `settings.store_name` on `get-store-info`, so it is also the public shop name. `commerce/seed-store` fills it from the `store_name` it is passed, and Settings → Emails is where a merchant changes it.
 - It seeds **blank on purpose**: a blank name means `SendEmail` is called without `from_name`, in which case **Base44 sends as the app's name** (verified: an app named *Canvas* with it blank delivered mail from "Canvas"). So the sender is the app name unless the store overrides it — one place to rename, and no hardcoded default.
 - That fallback does **not** reach subjects or headings: those are rendered by this template, which has no access to the app name, so a store with no `emails.store_name` sends `New order #1002` rather than `[Canvas]: New order #1002`. Set the store name if you want it in the subject line.

package/skills/commerce/references/guest-access-security.md

@@ -12,7 +12,7 @@
 The storefront functions run as the service role, so RLS is not protecting the caller from itself — these guards are. Keep them when you extend a function, and follow them in a new one.
 
 - **Identity comes from the session, never from the body.** An email in the payload is a claim, not a credential. Use `getCallerUser(base44)` and `requireUser(user)` from `shared/commerce/auth.ts`, and `ownsEmail(user, email)` before writing to anything keyed on someone's address. This is why `submit-review` requires a signed-in customer (a `reviewer_email` field is ignored) and why a guest checkout attaches to an existing `commerce.Customer` without rewriting its saved name and addresses — otherwise knowing a customer's email would be enough to redirect where their next order ships, or to post a review in their name.
-- **Anything a person owns needs authentication, not just an email.** If you add reviews, wishlists, loyalty, saved payment details, subscriptions or support tickets, gate the write on `requireUser` and derive the owner from `user.email` / `user.id`. Guest access is only ever by bearer token (`cart_token`, `order_key`) for the *one* record that token names.
-- **Only the payment provider can say an order is paid.** Never transition an order to `processing` because a request said so — no `paid: true` flag, no `transaction_id` from a client, no `?payment=success` in a return URL. Go through `confirmOnlinePayment()`, which asks the provider and checks the session was opened for that order. Adding a gateway means writing an adapter (see [`online-payments.md`](./online-payments.md)), not a new "confirm" endpoint.
+- **Anything a person owns needs authentication, not just an email.** If you add wishlists, loyalty, saved payment details, subscriptions or support tickets, gate the write on `requireUser` and derive the owner from `user.email` / `user.id`. Guest access is only ever by bearer token (`cart_token`, `order_key`) for the *one* record that token names. (Reviews are the deliberate exception — public by email, moderated instead of authenticated; a session email still always beats the payload.)
+- **Only the payment provider can say an order is paid.** Never transition an order to `processing` because a request said so — no `paid: true` flag, no `transaction_id` from a client, no `?payment=success` in a return URL. Go through `confirmCardPayment()`, which asks the provider about the payment reference stored on the order. Wiring a provider means implementing the two payment files (see [`online-payments.md`](./online-payments.md)), never a new "confirm" endpoint.
 - **A bearer token authorizes one record.** `order_key` gets you *that* order; it is not a licence to name someone else's ids in the same request. Match every id in the payload back to the record the token opened.
 - **Don't return more than the caller asked about.** Serialize customer-facing orders through `serializeOrderForCustomer()`, and don't let a response reveal whether another person's email exists, bought something, or has an account — a boolean in an error body is an enumeration oracle.