@base44/app-plugin-commerce 0.2.5 → 0.2.7

package/README.md

@@ -12,7 +12,7 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/reviews/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and price ranges; `price.js` encodes the from-price and price-range rules; `totals.js` projects a cart *or* an order into one summary shape; `address-spec.js` is the checkout address form as data; `images.js` normalizes catalog images; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" states a configured rule rather than an invented number.
-- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. What ships is every piece of logic that is the same in all stores, as hooks returning complete view-models: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useAddToCartButton`/`useProductPrice`/`useProductGallery` (+ the `variantAxes`/`productSpecs` render-model helpers), `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, `useOrderReturn`, and `useStorefrontSeo` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …). Needs React and nothing else.
+- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. What ships is every piece of logic that is the same in all stores, as hooks returning complete view-models: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useProductPrice`/`useProductGallery` (+ the `variantAxes`/`productSpecs` render-model helpers), `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, `useOrderReturn`, and `useStorefrontSeo` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …). Needs React and nothing else.
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/): [`SKILL.md`](./skills/commerce/SKILL.md) is the map every agent starts from (and the only path the platform needs to know); [`install/`](./skills/commerce/install/) holds the three stage files that are the whole install (`01-install` → `02-storefront` → `03-data`, each read at the moment its work starts and dropped when its checklist passes); [`references/`](./skills/commerce/references/) holds per-topic guides opened only on demand; [`docs/`](./skills/commerce/docs/) holds the data-model map ([`entities.md`](./skills/commerce/docs/entities.md)) and the two API references. The whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -10,77 +10,70 @@ Nothing else in this skill needs to be open right now.
 
 The kit ships, already written and tested: 20 `commerce.*` entities, the
 `commerce/*` backend functions (storefront API, admin API, payments, webhooks,
-emails), the shared commerce engine, a complete admin back office at
-`/store-admin`, the `commerce/StoreAdmin` copilot, and the storefront's entire
-logic layer (`@/commerce/storefront`, `@/commerce/utils`). None of that costs
-you generation — your work is the store's *UI and data*, not the plumbing.
-
-**Paths in this skill.** Every skill file named anywhere — in these docs, in a
-checklist, in a code comment — is written **relative to this skill's folder**
-(`.agents/skills/commerce/` in an installed app). So `references/online-payments.md`
-means `.agents/skills/commerce/references/online-payments.md`, and
-`install/03-data.md` means `.agents/skills/commerce/install/03-data.md`. Resolve
-them from the skill folder, never from the directory of the file that mentioned
-them — a comment in `src/…` naming `install/03-data.md` is not
-`src/install/03-data.md`. (Markdown links between skill files are ordinary
-relative links and resolve as written.)
+emails), the shared engine, a complete admin back office at `/store-admin`, the
+`commerce/StoreAdmin` copilot, and the storefront's entire logic layer
+(`@/commerce/storefront`). None of that costs you generation — your work is the
+store's *UI and data*, not the plumbing.
+
+**Paths in this skill** are relative to the skill's folder
+(`.agents/skills/commerce/` in an installed app), wherever they are named —
+docs, checklists, code comments. Resolve them from the skill folder, never from
+the file that mentioned them.
 
 ## Installing right now?
 
 Read **[`install/01-install.md`](./install/01-install.md)** and follow it. It
 routes you to `install/02-storefront.md` when you start the UI and
 `install/03-data.md` when you seed the catalog — in that order, at those
-moments. Read nothing else up front: those three files are the whole install,
-and each one says when a reference is genuinely needed.
+moments. Read nothing else up front.
 
 ## Four things to hold from the start
 
 - **Entity names are dotted; SDK access is bracket syntax only** —
   `base44.entities["commerce.Product"]`. `commerce__Product` and `Product` do
-  not exist. The full data-model map is [`docs/entities.md`](./docs/entities.md);
-  never scan `base44/entities/` to find a name.
-- **Store configuration is declared in one seed call**, not assembled by editing
-  records: catalog, shipping zones ("€20 in Europe, €100 worldwide" is a
-  six-line `locations` payload), currency, payment methods. See
-  [`install/03-data.md`](./install/03-data.md).
-- **Don't weaken the admin gating.** Three layers — the UI guard, entity RLS,
-  and `requireAdmin()` in every admin function — see
-  [`install/01-install.md`](./install/01-install.md). Keep all three when you
-  touch routes or schemas.
-- **Online card payments are optional and off by default.** A seeded store takes
-  manual (`offline`) payment and works end to end. Cards are a late, deliberate
-  step, and the decision plus the timing live in
-  [`install/03-data.md`](./install/03-data.md).
+  not exist. The map is [`docs/entities.md`](./docs/entities.md); never scan
+  `base44/entities/` for a name.
+- **Store configuration is declared in one seed call** — catalog, shipping
+  zones, currency, payment methods — never assembled by editing records
+  ([`install/03-data.md`](./install/03-data.md)).
+- **Don't weaken the admin gating** — three layers (UI guard, entity RLS,
+  `requireAdmin()`); keep all three when touching routes or schemas
+  ([`install/01-install.md`](./install/01-install.md)).
+- **Online card payments are optional and off by default.** A seeded store
+  takes manual (`offline`) payment and works end to end; cards are a late,
+  deliberate step ([`install/03-data.md`](./install/03-data.md)).
 
 ## The storefront: logic is premade, UI never is
 
-**The UI is yours, all of it** — every page, element, class and word of copy,
-from the home page to the checkout's place-order button. That is where a brief
-like "make it feel like <site>" lives, and the kit deliberately ships **no
-markup and no CSS anywhere**: there are no premade components to drop in or
-restyle. You design the storefront the way you would any app.
+**The UI is yours, all of it** — every page, element, class and word of copy.
+The kit deliberately ships **no markup and no CSS anywhere**; a brief like
+"make it feel like <site>" is your work, done as you would with no kit. Encode
+that identity **once** — design classes in `index.css`, spent across every
+page — not as decoration re-typed on every element;
+[`install/02-storefront.md`](./install/02-storefront.md) opens with the
+method.
 
 **The logic ships as headless hooks** (`@/commerce/storefront`) — checkout
-repricing from the address, variant resolution, cart state, coupon redemption,
-review policies, order-return verification. Every store's version of these is
-functionally identical and hand-writing them is where storefront bugs cluster,
-so **never re-implement what a hook does**. Each hook returns a complete
-view-model — a `status` to branch on, ready-to-map arrays, handlers, error
-objects — that your markup renders:
+repricing, variant resolution, cart state, coupons, reviews, order-return
+verification, cart-drawer state. Each returns a complete view-model as **plain
+states and handlers** (`status` to branch on, ready-to-map arrays, `label`s
+and `disabled` flags, callbacks) — you write every element and attribute from
+them. **Never re-implement what a hook does** — that is where storefront bugs
+cluster.
 
 ```jsx
-import { useCart, CartLine, useTotalsLines } from "@/commerce/storefront";
+import { useCart, CartLine } from "@/commerce/storefront";
 const { status, lines } = useCart();   // branch on status, map lines into YOUR rows
 ```
 
 The admin UI (`src/commerce/admin/`) is finished and **also yours to change** —
-restyle it, add pages, rework flows. To understand the backend it talks to, read
-[`docs/api-admin.md`](./docs/api-admin.md).
+restyle it, add pages, rework flows ([`docs/api-admin.md`](./docs/api-admin.md)
+is the backend it talks to).
 
 Four rules the API enforces — a storefront that skips them cannot complete a
-purchase. In a React app the hooks implement all four; your markup just has to
-render what they hand back. The API-level statements are in
-[`docs/api-storefront.md`](./docs/api-storefront.md) for non-React clients:
+purchase. In React the hooks implement all four; your markup renders what they
+hand back (API-level statements for non-React clients:
+[`docs/api-storefront.md`](./docs/api-storefront.md)):
 
 1. A product with variants needs **one selector per attribute**, resolved to a
    `variation_id` (`useProduct` + `variantAxes`).
@@ -88,8 +81,8 @@ render what they hand back. The API-level statements are in
    (`useCheckout` — automatic).
 3. **`/order-received` must exist** and render the return state, including a
    manual order's payment instructions (`useOrderReturn`).
-4. **Never advertise what isn't configured** — no free-shipping banner without a
-   real rate, no coupon codes without a field to redeem them in.
+4. **Never advertise what isn't configured** — no free-shipping banner without
+   a real rate, no coupon codes without a field to redeem them in.
 
 All backend functions return the envelope `{ success, data }`; with the SDK the
 payload is `res.data.data`:
@@ -101,32 +94,31 @@ const { products, has_next } = res.data.data;
 
 ## Where to look for what
 
-Open a file when its work starts — not while planning. The last column is there
-so you can answer "would that file help?" without paying for it.
-
-| Topic | Open when | Already covered without opening | Size |
-|---|---|---|---|
-| [`install/01-install.md`](./install/01-install.md) | installing — it routes you to 02 and 03 | — | 8K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages — cart-drawer behaviour and driving the storefront from a browser script are in here too, not in a separate reference | — | 38K |
-| [`install/03-data.md`](./install/03-data.md) | seeding the catalog, shipping, payments decision | — | 18K |
-| [`docs/entities.md`](./docs/entities.md) | any direct entity read/write, or "which entity holds X" | function-mediated flows never need it; the addressing rule is above | 11K |
-| [`references/catalog-rendering.md`](./references/catalog-rendering.md) | which fields each catalog call returns, variant edge cases | the install's product list/page chunks already render correct cards, prices and selectors | 13K |
-| [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond the standard recipe, taxes, editing locations later | "€X in a region, €Y worldwide" is inline in `install/03-data.md` | 8K |
-| [`references/online-payments.md`](./references/online-payments.md) | the store opted into cards and you are wiring the provider **now** | the decision and its timing are in `install/03-data.md`; wiring Stripe is a one-file copy, not code to write | 9K |
-| [`references/reviews.md`](./references/reviews.md) | moderation, or a policy beyond the `policy` prop | `useProductReviews` covers list + form + policies | 4K |
-| [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | the seeded defaults are right for a new store | 5K |
-| [`references/emails.md`](./references/emails.md) | order-email recipients, subjects, per-type overrides, the log | transactional emails already send | 5K |
-| [`references/admin-product-form.md`](./references/admin-product-form.md) | editing the shipped product editor | the editor works as shipped | 4K |
-| [`references/store-admin-agent.md`](./references/store-admin-agent.md) | changing the StoreAdmin copilot or its tools | it registers and works on install | 3K |
-| [`references/guest-access-security.md`](./references/guest-access-security.md) | **adding your own function or entity**, or questions about RLS/identity | the shipped functions already handle guest access | 5K |
-| [`references/operations.md`](./references/operations.md) | scheduled maintenance, scaling limits, outbound webhooks | nothing here is needed to ship a store | 5K |
-| [`docs/api-storefront.md`](./docs/api-storefront.md) | filters, customer accounts, refunds, a non-React client — anything past the happy path | the entire buy path | 40K |
-| [`docs/api-admin.md`](./docs/api-admin.md) | changing admin pages, automating against admin functions, the full seed contract | — | 28K |
+Open a file when its work starts — not while planning.
+
+| Topic | Open when | Size |
+|---|---|---|
+| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 27K |
+| [`install/03-data.md`](./install/03-data.md) | seeding catalog/shipping, payments decision | 11K |
+| [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
+| [`references/catalog-rendering.md`](./references/catalog-rendering.md) | which fields each catalog call returns, variant edge cases | 13K |
+| [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond 03's recipe, taxes, day-2 edits | 8K |
+| [`references/online-payments.md`](./references/online-payments.md) | the store opted into cards and you are wiring the provider **now** | 8K |
+| [`references/storefront-verification.md`](./references/storefront-verification.md) | driving the storefront from a browser script | 3K |
+| [`references/reviews.md`](./references/reviews.md) | moderation, or a policy beyond the `policy` prop | 4K |
+| [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | 5K |
+| [`references/emails.md`](./references/emails.md) | order-email recipients, subjects, the log | 5K |
+| [`references/admin-product-form.md`](./references/admin-product-form.md) | editing the shipped product editor | 6K |
+| [`references/store-admin-agent.md`](./references/store-admin-agent.md) | changing the StoreAdmin copilot | 3K |
+| [`references/guest-access-security.md`](./references/guest-access-security.md) | **adding your own function or entity**; RLS/identity questions | 5K |
+| [`references/operations.md`](./references/operations.md) | scheduled maintenance, scaling limits, outbound webhooks | 7K |
+| [`docs/api-storefront.md`](./docs/api-storefront.md) | filters, customer accounts, refunds, a non-React client | 32K |
+| [`docs/api-admin.md`](./docs/api-admin.md) | changing admin pages, automating admin functions, the full seed contract | 24K |
 
 **The read budget.** Content you pull into context is re-read on every later
-call, so a file opened while planning costs many times what the same file costs
-opened at the moment it is used. Open one reference when its task starts, take
-what you need, and when a stage's checklist passes, record that stage's
-carry-forward lines and treat the file as gone. If a reference and this map
-disagree, the reference wins — but if a *rule* appears in code (a hook's return
-value, its doc comment), the code wins over both.
+call, so a file opened while planning costs many times what it costs opened at
+the moment it is used. Open one reference when its task starts, take what you
+need, and when a stage's checklist passes, record its carry-forward lines and
+treat the file as gone. If a *rule* appears in code (a hook's JSDoc), the code
+wins over any doc.

package/skills/commerce/docs/api-admin.md

@@ -10,11 +10,7 @@ Two styles. **Reads are direct** entity SDK calls. **Mutations with side effects
 
 ## Invocation & envelope
 
-```js
-const res = await base44.functions.invoke("commerce/admin-products", { action: "search", q: "shirt", limit: 20 });
-const { rows, has_next } = res.data.data;   // res.data = { success, data }; .data = payload
-```
-Success: `{ success: true, data }`. Failure: `{ success: false, error, code }` with the HTTP status set. Auth: every `commerce/admin-*` function calls `requireAdmin()` → **401** if not signed in, **403** if signed in without the `admin` role, before any data access (via the service role).
+Standard invoke envelope — payload at `res.data.data` (SKILL.md owns it). Auth: every `commerce/admin-*` function calls `requireAdmin()` → **401** if not signed in, **403** if signed in without the `admin` role, before any data access (via the service role).
 
 ## Pagination & search
 
@@ -44,10 +40,10 @@ Actions: `save` · `delete` · `batch` · `duplicate` · `set-stock` · `search`
   | `attribute` | commerce.ProductAttribute | `id?, name, code?, order?` |
   | `attribute-term` | commerce.ProductAttributeTerm | `id?, attribute_id` (**required**, must exist)`, name, order?` |
 
-  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.
+  Cascade semantics — category slug/`parent_id` coercion, attribute `code` derivation, ribbon get-or-create, the attribute-value rename rewrite across products and variations: [`../references/admin-product-form.md`](../references/admin-product-form.md#taxonomy-cascade-semantics-save-term--delete-term).
 
   This is how a non-UI caller (notably the StoreAdmin agent) creates the records that `category_ids`/`ribbon_ids`/`attributes[].attribute_id` reference — assigning an id is useless if the record can't be created. **A product's `commerce.ProductAttribute` and its values must exist first**, so create those, then `save` the product with `attributes[]`/`variations[]`. (At install time, `commerce/seed-store` can do all of this in one call — it takes whole products by display name and get-or-creates the taxonomy internally; see below.)
-- **`delete-term`** — `{ taxonomy, id, detach? }` → `{ deleted, detached, terms_deleted }`. 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).
+- **`delete-term`** — `{ taxonomy, id, detach? }` → `{ deleted, detached, terms_deleted }`. What each taxonomy cascades and what `detach` does — including where it is a no-op: same reference as above.
 - **`list-terms`** — `{ taxonomy, q?, attribute_id?, limit?, skip? }` → `{ rows, has_next }`. Categories sort by `menu_order`, attributes and attribute values by `order`, ribbons by `name`; `attribute_id` filters values to one attribute. Use it to reuse an existing record instead of creating a duplicate.
 
 ## commerce/admin-orders
@@ -60,7 +56,7 @@ Actions: `create-draft` · `create` · `update` · `preview` · `update-status`
   - Any time: `billing`, `shipping`, `customer_id`, `customer_note`, `payment_method`, `meta_data`, `status`.
   - **Line edits require pending/on-hold** (else `409 order_locked`): `items` (specs `{ product_id, variation_id?, quantity, price_override? }`), `fees`, `coupon_codes`, `chosen_shipping_method`. Providing any of these — or changing addresses — triggers a full reprice.
   - A `status` in the patch is delegated to the transition engine last (fires the side effects below); otherwise an `order.updated` webhook fires.
-- **`preview`** — `{ order_id, patch }`. **Reads only — writes nothing, fires no webhooks.** Prices the same patch shape `update` takes and returns `{ fields }`: the Order fields `update` *would* have written (`line_items` with per-line tax, `shipping_lines`, `fee_lines`, `coupon_lines`, `tax_lines` and every total). Allowed on locked orders, since nothing is persisted. Only the pricing keys matter (`items`, `fees`, `shipping_lines`, `billing`, `shipping`); the rest are ignored. This is how the admin order editor shows live totals for **unsaved** edits — add a product and the tax, discount and grand total update before saving — without reimplementing tax and coupon rules on the client. Sharing `repriceOptsFromPatch()` with `update` is what guarantees the preview equals the saved result.
+- **`preview`** — `{ order_id, patch }`. **Reads only — writes nothing, fires no webhooks.** Prices the same patch shape `update` takes and returns `{ fields }`: the Order fields `update` *would* have written (`line_items` with per-line tax, `shipping_lines`, `fee_lines`, `coupon_lines`, `tax_lines` and every total). Allowed on locked orders, since nothing is persisted. Only the pricing keys matter (`items`, `fees`, `shipping_lines`, `billing`, `shipping`); the rest are ignored. This is how the admin order editor shows live totals for **unsaved** edits without reimplementing tax and coupon rules on the client; the preview always equals what saving would write.
 - **`update-status`** — `{ order_id, status, note? }` → runs the transition engine (side-effect matrix below).
 - **`bulk-status`** — `{ ids, status }` → `{ results: [{ id, success, error? }] }`.
 - **`status-counts`** — no payload → `{ all, pending, processing, "on-hold", completed, cancelled, refunded, failed }` (includes the `all` key). Powers the list tabs.
@@ -126,21 +122,8 @@ Actions: `test` · `redeliver` (webhook definitions themselves are direct `comme
 
 ## commerce/admin-reports
 
-All actions scan orders on demand (counted = `date_paid` set, or status `processing`/`completed`). Scaling: [`../references/operations.md`](../references/operations.md).
-
-| 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 }] }` |
+Actions: `summary` · `sales` · `top-sellers` · `stock` · a `*-totals` count action per resource (`orders` `products` `customers` `coupons` `reviews` `categories` `ribbons` `attributes`). All scan orders on demand (counted = `date_paid` set, or status `processing`/`completed`).
+The full payload/return table and scaling guidance: [`../references/operations.md`](../references/operations.md#commerceadmin-reports-actions).
 
 ## commerce/admin-tools
 
@@ -157,11 +140,8 @@ Actions: `status` · `admin-email-recipients` · `recount-terms` · `recount-cou
 
 ## commerce/payments
 
-Actions: `create-link` · `complete-return` · `verify` — the admin side of online payments (the same function serves customers, who authorize with `order_key` instead; see [`api-storefront.md`](./api-storefront.md)).
-
-- **`create-link`** — `{ order_id }` → `{ url, reference }`: a provider-hosted payment page for an unpaid order — the **payment link** to send a customer. Accepts an order on **any** payment method (including none, as admin-created orders start) and switches it onto the card gateway, logging the change: refunds key off `payment_method`, so this keeps the order honest about how it was paid. `409 already_paid`, `400 card_payments_disabled`, `503 no_card_payment_provider`.
-- **`verify`** — `{ order_id }` → `{ paid, already_confirmed, status, order }`: re-asks the provider and moves the order to `processing` when the money is there. Idempotent.
-- **`complete-return`** — what the storefront's mandatory `/order-received` page calls; full contract in [`api-storefront.md`](./api-storefront.md#commercepayments--online-payment-for-an-order).
+Actions: `create-link` · `complete-return` · `verify` — the admin side of online payments. [`api-storefront.md`](./api-storefront.md#commercepayments--online-payment-for-an-order) owns the action table (payloads, returns, error codes, the mandatory `/order-received` flow).
+An admin authorizes with the role and passes `{ order_id }` alone where a customer passes `order_key`; `create-link` mints the payment link for an unpaid order on **any** current method (it is switched onto the card gateway, logged).
 
 `commerce/payment-webhook` is the provider's server-to-server callback (raw body, no `action` envelope). The function is **premade** — it validates every event through `card-payment.ts`'s `parseWebhook` and never trusts an event body on its own: an unverified event only names an order, and payment is verified through `checkCardPaymentPaid` against the provider's API, so no signing secret is needed. Until `card-payment.ts` is implemented it answers `400 webhook_not_implemented`; events it can't tie to an order are acknowledged with `200 { ignored: true }` so providers don't retry. See [`../references/online-payments.md`](../references/online-payments.md).
 
@@ -197,7 +177,7 @@ The one-call catalog bootstrap. Entries reference categories/ribbons/attributes
 | `attributes` | `[{ name, options }]` or `{ <name>: [options] }` | declares the variant axes |
 | `variations` | `[{ options: { <name>: <option> }, ...overrides }]` | the stocked combinations. **Omit it to auto-generate all** combinations, each inheriting the product-level price/sale fields |
 | `default_options` | `{ <name>: <option> }` | the pre-selected combination |
-| everything else | `commerce.Product` fields | `name` (required), `slug`, `sku`, `status`, `regular_price`, `sale_price`, `images`, `featured`, `virtual`, `downloadable`, `downloads`, `tax_status`, `tax_group`, `stock_quantity`, `weight`, `dimensions`, `meta_data` |
+| everything else | `commerce.Product` fields | `name` (required), `slug`, `sku`, `status`, `regular_price`, `sale_price`, `date_on_sale_from`/`date_on_sale_to`, `short_description`, `description`, `images`, `featured`, `virtual`, `downloadable`, `downloads`, `download_limit`, `download_expiry`, `tax_status`, `tax_group`, `stock_quantity`, `manage_stock`, `low_stock_amount`, `backorders`, `sold_individually`, `weight`, `dimensions`, `meta_data` (`upsell_ids`/`cross_sell_ids` take Product *ids*, which exist only after this call — cross-link via `admin-products` later) |
 
 A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without one it draws on the parent's pooled stock (`"parent"`), and its SKU is synthesized from the parent's when absent. Parent price and `stock_status` are derived by the same helpers as `save` ([derived fields](./entities.md#derived-fields--never-write-these)), but **no `product.created` webhooks fire** — bootstrap precedes subscribers, so use `admin-products` for webhook-visible creates. **Re-runs converge**: a product whose `sku` (or, with none, derived slug) already exists is skipped and reported, so retries never duplicate; an explicit variation SKU already in use is **`409 duplicate_sku`**. `coupons` is a thin passthrough (code lowercased, skip-if-exists).
 
@@ -205,28 +185,9 @@ A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without on
 
 ### Payload — `locations`
 
-Seeding `locations` is **the** way to set shipping up. Each entry becomes a `commerce.ShippingTaxLocation`, skip-if-exists **by name**.
-
-| Key | Shape | Notes |
-|---|---|---|
-| `name` | string, required | the skip-if-exists match key |
-| `countries` | `["IL", "DE"]` | ISO country codes → `{ type: "country" }` regions |
-| `continents` | `["EU"]` | one of `AF` `AN` `AS` `EU` `NA` `OC` `SA`, sparing you a 51-code country list. `EU` is the **continent** Europe, not the European Union. An unknown code fails listing all seven |
-| `regions` | `[{ type, code }]` | raw escape hatch (`country`\|`state`\|`continent`; state codes are `US:CA`) |
-| `rest_of_world` | `true` | the **catch-all** every unmatched address falls to. It has no regions, so combining it with `countries`/`continents`/`regions` is a contradiction and fails validation |
-| `order` | integer | match priority, **ascending**. Defaults to the **payload position**, so the array reads as the priority; an explicit value wins |
-| `shipping_rates` | `[{ id?, name, cost, free_over? }]` | one checkout choice each. `id` is minted from the location + rate names when omitted, and must stay stable (carts and orders reference the chosen rate by it). `free_over` = discounted items subtotal at which it becomes free. Negative `cost` fails |
-| `tax_groups` | `[{ name, rates: [{ name, rate }] }]` | a `Products` group is prepended when missing (products pick one by name via `tax_group`). A `rate` outside 0–100 fails |
-| `shipping_tax` | `{ type: "percent"\|"fixed", value }` | tax on the shipping line |
-
-```js
-locations: [
-  { name: "Europe",    continents: ["EU"],    shipping_rates: [{ name: "Standard", cost: 20 }] },
-  { name: "Worldwide", rest_of_world: true,   shipping_rates: [{ name: "International", cost: 100 }] },
-]
-```
+Seeding `locations` is **the** way to set shipping up. Each entry becomes a `commerce.ShippingTaxLocation`, skip-if-exists **by name**: a scope (`countries: ["IL", "DE"]`, `continents: ["EU"]` — the **continent**, not the EU — raw `regions`, or `rest_of_world: true`, the catch-all, which contradicts the other scope keys), `order` (match priority ascending, defaults to payload position), `shipping_rates: [{ id?, name, cost, free_over? }]` (a minted `id` must stay stable — carts/orders reference it), `tax_groups` (a `Products` group prepended when missing) and `shipping_tax`. Unknown codes, negative `cost` or a tax `rate` outside 0–100 fail validation. Field-by-field semantics, matching and recipes: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
 
-**A payload carrying `locations` suppresses the seeded `Rest of the world` fallback** (free standard delivery, `order: 999`) — yours become the store's only shipping data, since a second no-region location beside them would be a fallback nobody asked for: shadowed today, live the moment theirs is reordered or deleted. The cost: **locations with no catch-all ship only to the listed regions**, every other address getting `shipping_not_available` at checkout. Plausibly intended, so not an error — it returns as `warnings: ["no_catchall_location: …"]`. Full model: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
+A payload carrying `locations` suppresses the seeded catch-all fallback — without your own, unlisted addresses get `shipping_not_available`, flagged as `warnings: ["no_catchall_location: …"]` (same reference; [`../install/03-data.md`](../install/03-data.md) also owns this).
 
 ### Response
 

package/skills/commerce/docs/api-storefront.md

@@ -2,65 +2,28 @@
 
 The raw HTTP/SDK surface behind a customer-facing shopfront. **A React storefront should not call most of it directly** — `src/commerce/storefront/` ships the logic layer, and this file is the reference for what lies beyond it, for non-React and headless clients, and for the exact payloads and error codes.
 
-**Logic is premade, UI never is.** In a React app, every surface here has a headless hook in `@/commerce/storefront` — `useProductList`, `useProduct` (+ `variantAxes`, `useAddToCartButton`), `useCart`/`useCartLine`/`useCoupon`, `useCheckout` (+ `useAddressForm`, the pickers), `useOrderReturn`, `useProductReviews`, `useStorefrontSeo`. The hooks own the API calls and the branching below and hand you a view-model; **all markup and styling are yours** — nothing in the kit renders UI. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
+**Logic is premade, UI never is.** In a React app, every surface here has a headless hook in `@/commerce/storefront` — `useProductList`, `useProduct` (+ `variantAxes`, `useAddToCart`, `useProductSpecs`, `useUpsell`), `useCart`/`useCartLine`/`useCoupon`/`useCartUI` (+ `CartUIProvider`), `useCheckout`/`usePlaceOrder` (+ `useAddressForm` and the pickers), `useOrderReturn`, `useProductReviews`, `useStorefrontSeo`. The hooks own the API calls and the branching below and hand you a view-model; **all markup and styling are yours** — nothing in the kit renders UI. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
 
-## Contents
-
-- [Required behaviors](#required-behaviors--a-storefront-that-skips-these-cannot-sell) (the four hard rules) · [capabilities](#what-the-api-already-gives-you-read-before-designing-the-ui) · [conventions](#conventions) (envelope, auth, money)
-- [`storefront-catalog`](#commercestorefront-catalog): [`get-store-info`](#get-store-info) · [`list-products`](#list-products) · [`get-product`](#get-product) · [`list-categories`](#list-categories) · [`list-ribbons`](#list-ribbons) · [`list-attributes`](#list-attributes) · [`submit-review`](#submit-review)
-- [`storefront-cart`](#commercestorefront-cart): [priced view](#the-priced-cart-view-returned-by-every-action) · [actions](#actions) · [`cart_token`](#cart_token--the-storefronts-one-job) · [**shipping rules**](#shipping-is-not-optional--read-this-before-building-checkout) · [never advertise unconfigured offers](#never-advertise-what-the-store-isnt-configured-to-do)
-- [`storefront-checkout`](#commercestorefront-checkout): [`place-order`](#place-order) · [`confirm-payment`](#confirm-payment) · [`cancel-order`](#cancel-order)
-- [`payments`](#commercepayments--online-payment-for-an-order): payment links, `complete-return` for `/order-received`
-- [`storefront-account`](#commercestorefront-account): orders, notes, downloads, addresses, my reviews
-- [Walkthrough A — guest checkout](#walkthrough-a--guest-checkout) · [B — member](#walkthrough-b--member-experience) (non-React clients)
-- Entities and direct CRUD → [`entities.md`](./entities.md) · admin surface → [`api-admin.md`](./api-admin.md)
+Entities and direct CRUD → [`entities.md`](./entities.md) · admin surface → [`api-admin.md`](./api-admin.md)
 
 ## Required behaviors — a storefront that skips these cannot sell
 
-The canonical statement. Each is enforced by the API, not a nicety:
-
-| # | Requirement | Enforced by |
-|---|---|---|
-| 1 | **Products with variants: one selector per attribute**, resolved to a `variation_id` before adding to the cart — never a flat list of combinations | `add-item` → `400 variation_required` ([product page](#get-product)) |
-| 2 | **Present shipping options and send a choice** — drive it off the cart's `shipping_status`; a single option is auto-applied, several mean you must ask | `place-order` → `400 shipping_method_required` ([shipping](#shipping-is-not-optional--read-this-before-building-checkout)) |
-| 3 | **Redirect to `payment.checkout_url`** when the customer pays by card | the order stays `pending` otherwise |
-| 4 | **Implement the return page** (`/order-received`, or your own route set in Settings → General → *Payment return path*) and call `commerce/payments` `complete-return` there | without it a paid order is never confirmed, and a wrong path is a 404 |
-| 5 | **Only advertise offers the store is configured for** (free-shipping thresholds come from a location's shipping rates) | nothing — this one is on you |
+Five hard rules — the first four API-enforced, the fifth on you:
 
-Four public functions — **`storefront-catalog`**, **`storefront-cart`**, **`storefront-checkout`**, **`storefront-account`** — all invoked the same way, all returning the same envelope.
+1. **Variants: one selector per attribute**, resolved to a `variation_id` before `add-item` (`400 variation_required`, [product page](#get-product)) — never a flat list of combinations.
+2. **Present shipping options and send a choice**, driven by the cart's `shipping_status` (`place-order` → `400 shipping_method_required`, [shipping](#shipping-is-not-optional--read-this-before-building-checkout)).
+3. **Redirect to `payment.checkout_url`** for card payments — the order stays `pending` otherwise.
+4. **Implement the return page** (`/order-received`, or the route set in Settings → General → *Payment return path*) and call `commerce/payments` `complete-return` there — otherwise a paid order is never confirmed, and a wrong path is a 404.
+5. **Only advertise offers the store is configured for** (free-shipping thresholds come from a location's rates) — nothing enforces this one.
 
-## What the API already gives you (read before designing the UI)
-
-**Build to this surface, not to the basics** — everything below already exists server-side, so leaving it out ships a storefront weaker than the store behind it.
-
-| Capability | Already supported | Where |
-|---|---|---|
-| **Product discovery** | full-text `search`; filters: category (incl. descendants), ribbon, attribute+term, price range, `featured`, `on_sale`, `in_stock_only`; sort by name / price / **newest** (default) / **popularity** / **rating**; paging | [`list-products`](#list-products) |
-| **Rich product pages** | galleries, per-variant price/stock/image, categories, ribbons, **upsells**, **cross-sells** | [`get-product`](#get-product) |
-| **Taxonomy navigation** | category tree, **ribbons with counts**, attributes + terms for filter UIs | [`list-categories`](#list-categories) · [`list-ribbons`](#list-ribbons) · [`list-attributes`](#list-attributes) |
-| **Customer reviews** | paginated per product with **average rating + count**, `verified` flag, **submission by anyone with an email** (no login), "my reviews" | [`submit-review`](#submit-review) |
-| **Cart** | guest carts via `cart_token`, add/update/remove, quantity merging, `sold_individually` caps, live re-pricing, stock revalidation | [`storefront-cart`](#commercestorefront-cart) |
-| **Coupons** | apply/remove by code, fully validated server-side (eligibility, limits, per-user usage). Codes are admin-only data, so a store with coupons needs a **code field** in the buy path or they can never be redeemed | [`apply-coupon`](#actions) |
-| **Shipping** | address → matched location → **selectable rates with live costs**, free-over thresholds | [`set-shipping-address`](#actions) |
-| **Tax** | inclusive/exclusive pricing, per-location tax groups, itemized display — resolved server-side | [`get-store-info`](#get-store-info) |
-| **Stock states** | in stock / out of stock / **on backorder**, low-stock signalling, out-of-stock hiding | [`list-products`](#list-products) |
-| **Checkout** | guest or authenticated, billing/shipping, per-gateway routing, **payment instructions** for manual methods, cancel, post-payment confirm | [`storefront-checkout`](#commercestorefront-checkout) |
-| **Accounts** | order history, saved addresses, **guest order tracking by `order_key`** with customer-visible notes | [`storefront-account`](#commercestorefront-account) |
-| **Digital products** | entitlement-checked downloads with remaining-count, expiry, signed URLs for private files | [`get-download`](#commercestorefront-account) |
-| **Store config** | currency, units, catalog/cart price display — honour it instead of hardcoding | [`get-store-info`](#get-store-info) |
-
-Not in the backend: the visitor UI (all of it is yours — the hooks above carry the logic), and the card-payment provider integration, which only a store that opts into cards needs — cards are off by default, the decision and its timing live in [`../install/03-data.md`](../install/03-data.md), the provider code in [`../references/online-payments.md`](../references/online-payments.md). Payment methods and the currency are admin-owned data — always render them from `get-store-info`, never a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
+Four public functions — **`storefront-catalog`**, **`storefront-cart`**, **`storefront-checkout`**, **`storefront-account`** — all invoked the same way, all returning the same envelope. Discovery filters and sorts, reviews, coupons, live shipping rates, tax, stock states, digital downloads and guest order tracking all already exist server-side — build to the sections below, not to a subset.
 
 ## Conventions
 
-- **Invoke:** `base44.functions.invoke("commerce/<function>", { action, ...payload })`. Response body is on `res.data`; the envelope is `{ success, data }` on success or `{ success, error, code }` on failure (HTTP status set accordingly).
-  ```js
-  const res = await base44.functions.invoke("commerce/storefront-catalog", { action: "get-store-info" });
-  const info = res.data.data;              // envelope → payload
-  ```
+- **Invoke:** `base44.functions.invoke("commerce/<function>", { action, ...payload })`; the `{ success, data }` / `{ success, error, code }` envelope and `res.data.data` unwrapping are covered in SKILL.md.
 - **Auth modes:** most actions are anonymous. Some require an authenticated Base44 session (marked **auth**). Two bearer credentials (HTTPS only): `order_key` for guest order access, `cart_token` for the cart — whose lifecycle rules are [in the cart section](#cart_token--the-storefronts-one-job).
 - **Identity is never a payload field.** Anything attributed to a person — a review's author, a saved profile — comes from the session. An email in the body does not make you that customer, and no request can assert that an order was paid. A feature built on client-supplied identity will be ignored.
-- **Money:** numbers, 2-dp. **Dates:** ISO strings.
+- **Money:** numbers, 2-dp — format with `Intl.NumberFormat(undefined, { style: "currency", currency })` using the `get-store-info` currency, never a hardcoded symbol. **Dates:** ISO strings.
 - **Errors:** every failure has a stable `code` (listed per action) plus a human `error` message.
 
 ---
@@ -131,15 +94,7 @@ await cat({ category_id, sort: "popularity", per_page: 4 });    // top in catego
 ```
 **Errors:** `404 not_found` (missing / not published / hidden).
 
-> **`variations[]` is not a list of choices to show.** Build **one control per `product.attributes[]` entry** (Size, Color, …) — every attribute is an axis — and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variant prices come from `variations[]`, never from `product.price` (the parent's price is a rolled-up from-price). A React page gets all of this from `useProduct` + `useAddToCartButton` (map `variantAxes(view, pick)` into your controls, gate on `view.purchasable`); a non-React client uses the framework-free resolver:
-> ```js
-> import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
-> const view = resolveSelection(product, variations, selection);  // selection from defaultSelection(), updated via selectOption()
-> // view.axes → one control per axis          view.display → image/price/sku/stock of the resolved variation
-> // view.availability[axis.key][option] → "available" | "out_of_stock" | "unavailable"  (disable, don't hide)
-> // view.purchasable + view.addToCart → { product_id, variation_id } for add-item
-> ```
-> Field availability per view, ribbons, from-price rules and the variant deep-dive (availability states, incomplete-selection pricing, URL round-trip): [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
+> **`variations[]` is not a list of choices to show** — variant rule 1 applies, and variant prices come from `variations[]`, never `product.price` (a rolled-up from-price). React: `useProduct` + `useAddToCart`. The non-React resolver sample (`resolveSelection` from `@/commerce/utils`) and the variant deep-dive: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
 
 ### `list-categories`
 No payload. Returns a nested tree: `{ "categories": [ { ...category, "children": [...] } ] }` sorted by `menu_order` then name.
@@ -157,7 +112,7 @@ This is the **only** way a storefront can enumerate ribbons (the entity is admin
 No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — each attribute (`id, name, code, order`) with its values (`id, attribute_id, name, order, count`), both sorted by `order`; for filter UIs. Filter with `list-products` `attribute_id` (id or attribute **name**) + `attribute_term` (the value name); `code` is the stable key for a URL.
 
 ### `submit-review`
-**Payload:** `{ product_id, reviewer?, review, rating }`.
+**Payload:** `{ product_id, email?, reviewer?, review, rating? }` — `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
 
 > A React storefront gets the whole reviews surface — this call, the paginated list from `get-product`, refresh, and the store's moderation policy — from **`useProductReviews`**; don't hand-roll it. Read on for the raw contract.
 
@@ -239,15 +194,9 @@ rather than assuming:
 | `missing_address` | options undeterminable until an address is set (several locations, none matchable yet) | collect the address, call `set-shipping-address`; cost is not calculated yet |
 | `none_available` | nothing ships to this address | say so and block checkout (`set-shipping-address` already failed `shipping_not_available`) |
 
-Rules the cart enforces on every price, so you get them for free:
-
-- **A single available method is auto-selected.** One option is not a choice, and requiring a round trip for it is how a storefront ends up never sending a method at all.
-- **A single location answers before the address.** A store with exactly **one** location gets its rates (and, via auto-select, a cost) with no address set — the options are the same everywhere. With several, the cart reports `missing_address` until `set-shipping-address` resolves one.
-- **An unsupported address fails on entry**, with `400 shipping_not_available` — surface it on the address form instead of letting the customer reach payment.
-- **A stale choice is dropped.** If the address or cart changes so the chosen method is no longer offered, it is cleared (and re-auto-selected when one remains) rather than silently pricing zero shipping.
-- **Costs change with the cart** — free-shipping thresholds and coupon-gated methods appear and disappear, so **call `set-shipping-address` as soon as an address exists and re-read the cart after every mutation**; never carry an options list you fetched earlier.
+Rates re-resolve on every cart change (a stale choice is dropped, re-auto-selected when one remains) — call `set-shipping-address` as soon as an address exists and re-read the cart after every mutation; never cache an options list. A store with exactly one location answers before any address is set.
 
-What `place-order` does with all this: a single offered method is applied for you; several offered with none chosen is `400 shipping_method_required` (with `available_shipping_methods` in the error body); a `chosen_shipping_method` not offered for the address is `400 invalid_shipping_method`, never silently swapped; nothing offered is `400 no_shipping_available`. No order is created in any of those cases, and the order that is created prices the resolved method, so its `shipping_total` always matches what the customer was shown.
+`place-order` errors: none chosen of several → `400 shipping_method_required`; `chosen_shipping_method` no longer offered → `400 invalid_shipping_method` (never silently swapped); nothing offered → `400 no_shipping_available`; an unsupported address already failed `set-shipping-address` with `400 shipping_not_available`. Each error body carries `available_shipping_methods`, no order is created, and a created order's `shipping_total` matches what was shown.
 
 **In React this is `useCheckout`**: address state debounces into `set-shipping-address`, `ShippingMethodPicker` renders the options, and `canPlaceOrder` blocks with a named blocker until a method resolves — the whole table above is the hook's behavior, not code you write. Location/zone/tax configuration: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
 
@@ -255,19 +204,7 @@ What `place-order` does with all this: a single offered method is applied for yo
 
 Copy like *"Free shipping on orders over €150"* is a **claim about store configuration**, and checkout honours only what is configured. Don't write such a line unless a matching rule exists — configure it (with the operator's agreement) or leave the copy out. The same goes for a discount claim (it needs a real `commerce.Coupon`, and only a code the operator gave you) and for delivery-time or returns promises the template cannot enforce.
 
-**Locations are admin-only data** like every entity, so a visitor cannot list them — do not try. Two honest sources:
-
-1. **The cart** — the live answer for a real address: after `set-shipping-address`, `available_shipping_methods` reflects every rule checkout will honour, free shipping included. Prefer this.
-2. **A projection you add**, for a threshold banner *before* an address exists: widen `get-store-info` (or add an action) to return the free-shipping rules, then normalize them:
-
-```js
-import { freeShippingRules, freeShippingThreshold, freeShippingProgress } from "@/commerce/utils";
-// locations come from your own storefront action — NOT a client entity read
-const threshold = freeShippingThreshold(freeShippingRules(locations));  // null → no rule: no banner
-const progress = freeShippingProgress(threshold, cart.totals.subtotal - cart.totals.discount_total);
-```
-
-A free-shipping rule is a rate that is free (`cost: 0`) or carries a `free_over` threshold. Thresholds are **per location** — a rule in one location must not become a site-wide banner.
+**Locations are admin-only data**, so a visitor cannot list them. Two honest sources: the cart's `available_shipping_methods` after `set-shipping-address` (prefer this — it reflects every rule checkout will honour), or a server projection you add (widen `get-store-info` or add an action — never a client entity read) normalized with `freeShippingRules` / `freeShippingThreshold` / `freeShippingProgress` from `@/commerce/utils` (a `null` threshold means no rule: no banner). Thresholds are **per location** — a rule in one location must not become a site-wide banner.
 
 ---
 
@@ -352,68 +289,38 @@ Two access modes: **auth** (Base44 session) or **`order_key` bearer** (guest tra
 
 ---
 
-## Walkthrough A — guest checkout
+## Walkthrough — guest checkout
 
-Raw-call sequence for a non-React client (a React app gets this from `useCart` + `useCheckout`).
+Raw-call spine for a non-React client (a React app gets this from `useCart` + `useCheckout`).
 
 ```js
 const inv = (fn, payload) => base44.functions.invoke(fn, payload).then(r => r.data.data);
 
-// 1. Browse, then 2. open a cart with one item
 const { products } = await inv("commerce/storefront-catalog", { action: "list-products", per_page: 12 });
-let cart = await inv("commerce/storefront-cart", { action: "create",
-  items: [{ product_id: products[0].id, quantity: 1 }] });
-const token = cart.cart_token;   // re-read it from every response
+let cart = await inv("commerce/storefront-cart", { action: "create", items: [{ product_id: products[0].id, quantity: 1 }] });
+const token = cart.cart_token;                                         // re-read it from every response
 
-// 3. (variants) fetch the options, then add the chosen variation
 const detail = await inv("commerce/storefront-catalog", { action: "get-product", id: products[0].id });
-if ((detail.product.attributes ?? []).length) {
+if ((detail.product.attributes ?? []).length)                          // variants: add the resolved variation
   cart = await inv("commerce/storefront-cart", { action: "add-item",
     cart_token: token, product_id: detail.product.id, variation_id: detail.variations[0].id });
-}
 
-// 4. Coupon (optional)
 cart = await inv("commerce/storefront-cart", { action: "apply-coupon", cart_token: token, code: "welcome10" });
 
-// 5. Shipping: address as soon as it's known, then a method if asked for one
 cart = await inv("commerce/storefront-cart", { action: "set-shipping-address",
   cart_token: token, address: { country: "US", state: "CA", postcode: "90210", city: "Los Angeles" } });
 if (cart.shipping_status === "choice_required") {
   const picked = await askCustomer(cart.available_shipping_methods);   // your UI
-  cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method",
-    cart_token: token, method_id: picked.id });
+  cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method", cart_token: token, method_id: picked.id });
 }
 
-// 6. Place it (offline → on-hold; no money has arrived yet)
-const order = await inv("commerce/storefront-checkout", { action: "place-order",
+const order = await inv("commerce/storefront-checkout", { action: "place-order",   // offline → on-hold
   cart_token: token, payment_method: "offline",
   billing: { first_name: "Ada", last_name: "Lovelace", address_1: "1 St",
              city: "Los Angeles", state: "CA", postcode: "90210", country: "US", email: "ada@example.com" } });
 
-// 7. Track it later without an account, using order_key from step 6
-const tracked = await inv("commerce/storefront-account", { action: "get-order",
+const tracked = await inv("commerce/storefront-account", { action: "get-order",    // guest tracking
   order_id: order.order_id, order_key: order.order_key });
 ```
 
-## Walkthrough B — member experience
-
-Same, for an authenticated caller (the SDK sends the session automatically).
-
-```js
-// Carts made while logged out merge into this one automatically on `get`/`create`.
-let cart = await inv("commerce/storefront-cart", { action: "create", items: [{ product_id, quantity: 2 }] });
-
-// Saved addresses speed up checkout
-await inv("commerce/storefront-account", { action: "update-my-addresses",
-  billing: { first_name: "Ada", last_name: "Lovelace", address_1: "1 St", city: "LA",
-             state: "CA", postcode: "90210", country: "US", email: "ada@example.com" } });
-
-const order = await inv("commerce/storefront-checkout", { action: "place-order",
-  cart_token: cart.cart_token, payment_method: "offline", billing: { /* ... */ } });
-// offline → on-hold; show order.payment_instructions.account_details
-
-// Order history, downloads, reviews — all auth, no order_key needed
-const { orders } = await inv("commerce/storefront-account", { action: "my-orders", per_page: 10 });
-const { downloads } = await inv("commerce/storefront-account", { action: "my-downloads" });
-const file = await inv("commerce/storefront-account", { action: "get-download", permission_id: downloads[0]?.permission_id });
-```
+**Authenticated caller:** same sequence — the SDK sends the session automatically, carts made while logged out merge in on `create`/`get`, and `update-my-addresses` lets checkout prefill saved addresses. The account actions (`my-orders`, `my-downloads`, `my-reviews`, `get-download`) then need no `order_key`.