@base44/app-plugin-commerce 0.2.7 → 0.3.2

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`/`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. **It ships no customer-facing copy either**: where a state needs words you get the *state* — `buy.state`, a picker's `hint.code`, the checkout's `blockers`, a review's `status` — and write the sentence. What ships is every piece of logic that is the same in all stores: `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine` (+ `useCartUI`/`CartUIProvider` for a drawer), `useCheckout`/`CheckoutProvider`/`useCheckoutContext`, `useOrderReturn`/`orderReceivedUrl` — 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), and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`). 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.
 
@@ -32,8 +32,8 @@ base44-commerce-template/
 │   └── commerce/
 │       ├── admin/      React admin UI (copy into your app's src/commerce/)
 │       ├── utils/      storefront helpers — API client, variants, price/totals rules
-│       └── storefront/ storefront React layer — headless hooks (cart, checkout,
-│                       catalog, reviews, SEO); no markup or CSS ships
+│       └── storefront/ storefront React layer — headless hooks (catalog, cart,
+│                       checkout, receipt); no markup, CSS or copy ships
 ├── scripts/
 │   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
 ├── skills/
@@ -104,7 +104,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 
 ## What's NOT included
 
-- **No storefront *design*.** The parts of a shopfront that carry a brand — the home page, the collection grid, the product card, the product page's layout, the theme — ship as nothing at all, on purpose: that is the work a build should spend its effort on. Everything under those surfaces does ship: the storefront API, the hooks, and default markup for the commodity UI (checkout, cart, totals, coupon field, reviews, order-received, and the product page's internals), all restylable and replaceable — see [`skills/commerce/install/02-storefront.md`](./skills/commerce/install/02-storefront.md) for how the two tiers fit together, [`skills/commerce/references/catalog-rendering.md`](./skills/commerce/references/catalog-rendering.md) for what each catalog call returns, and [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md) for the raw API.
+- **No storefront *design*.** The parts of a shopfront that carry a brand — the home page, the collection grid, the product card, the product page's layout, the theme — ship as nothing at all, on purpose: that is the work a build should spend its effort on. Everything under those surfaces does ship: the storefront API and the hooks that own the logic of every surface (catalog, product, cart, checkout, order-received, reviews) — the markup, styling and copy on top of them stay yours, including the commodity screens — see [`skills/commerce/install/02-storefront.md`](./skills/commerce/install/02-storefront.md) for how the two tiers fit together, [`skills/commerce/references/catalog-rendering.md`](./skills/commerce/references/catalog-rendering.md) for what each catalog call returns, and [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md) for the raw API.
 - **No payment provider — and cards are off by default.** The order side of card payments is premade (see above), but charging a card needs a provider, so `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code, no credentials) and leaves the **`card`** gateway **switched off**. **Enable cards only if a provider is wired, or is about to be** — implement the four functions in `base44/shared/commerce/card-payment.ts`, or for Stripe copy the shipped `card-payment.stripe.ts` over it and use it as-is (`skills/commerce/references/online-payments.md`), then enable the gateway via the seed's `payment_methods: ["offline", "card"]`; enabled with nothing behind it, checkout answers `503 no_card_payment_provider`. The rule and why it belongs at the end of a build rather than its start: `skills/commerce/install/03-data.md`.
 - **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see [`skills/commerce/references/operations.md`](./skills/commerce/references/operations.md).
 

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -1,7 +1,7 @@
 {
   "name": "commerce.PaymentGateway",
   "type": "object",
-  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and card (processed by commerce/payments + commerce/payment-webhook via shared/commerce/card-payment.ts). Secrets are never stored here; use Base44 secrets.",
+  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and card (processed by commerce/payments + commerce/payment-webhook via shared/commerce/card-payment.ts). Enable or disable a gateway with commerce/seed-store payment_methods — e.g. { payment_methods: [\"offline\", \"card\"] }, valid at any time and the whole payload — never by writing enabled on this row: the seeder owns the on/off state and the next call overwrites a hand edit. Secrets are never stored here; use Base44 secrets.",
   "properties": {
     "slug": {
       "type": "string",

package/base44/functions/commerce/seed-store/entry.ts

@@ -47,6 +47,14 @@
  * the one call covers "card-only" stores with no entity editing. Explicit
  * values always win, on first seed and re-runs alike (like `currency`).
  *
+ * **Every key is independent, and the call is the day-2 tool as much as the
+ * install one.** A later call carries only the slice being changed — enabling
+ * cards on a live store is `{ payment_methods: ["offline", "card"] }` and
+ * nothing else. Omitted keys are not reset: no `products` means no catalog work
+ * at all, and no `locations` leaves the store's shipping untouched. This is the
+ * supported way to change store configuration; editing `commerce.PaymentGateway`
+ * (or the settings rows) by hand is not.
+ *
  * `store_name` is required on a first seed: a function's env is only
  * BASE44_APP_ID, so it cannot read the app's name, and subjects need one.
  * `currency` is an ISO code and `weight_unit`/`dimension_unit` are the
@@ -249,9 +257,15 @@ Deno.serve(async (req) => {
     if (catalogSpec?.locations?.length && !catalogSpec.locations.some((l: any) => !l.regions?.length)) {
       warnings.push("no_catchall_location: addresses outside your locations will get shipping_not_available — add a location with rest_of_world: true if you ship worldwide");
     }
+    // The same reasoning applies to a later call that simply doesn't mention
+    // shipping — flipping `payment_methods` on a live store, say. The merchant's
+    // locations are still the shipping story, so the test is whether the store
+    // has ANY location, not whether one carries this default's name: matching by
+    // name would drop a free worldwide rate behind a catch-all called anything
+    // else, which is the exact record the paragraph above refuses to create.
     if (!catalogSpec?.locations?.length) {
-      const fallback = ((await sr.entities["commerce.ShippingTaxLocation"].filter({ name: REST_OF_WORLD_LOCATION.name }, undefined, 1)) ?? [])[0];
-      if (!fallback) {
+      const existing = (await sr.entities["commerce.ShippingTaxLocation"].list(undefined, 1)) ?? [];
+      if (!existing.length) {
         await sr.entities["commerce.ShippingTaxLocation"].create(REST_OF_WORLD_LOCATION);
         seeded.locations++;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.2.7",
+  "version": "0.3.2",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",
@@ -21,7 +21,7 @@
   },
   "files": [
     "base44",
-    "scripts",
+    "scripts/install.js",
     "skills",
     "src",
     "README.md",

package/scripts/install.js

@@ -142,6 +142,21 @@
     [".agents", "skills", "commerce", "references", "limits-and-performance.md"],   // → references/operations.md
     [".agents", "skills", "commerce", "references", "webhooks.md"],                 // → references/operations.md
     [".agents", "skills", "commerce", "references", "media-and-downloads.md"],      // → docs/api-storefront.md + install/03-data.md
+    // The storefront layer went back to a small surface: these hooks are gone,
+    // their guards live in @/commerce/utils, and the rest is a doc recipe in
+    // install/02-storefront.md. They must not linger — each one carries
+    // kit-authored customer copy ("Add to bag", blocker messages) in its JSDoc,
+    // which is exactly what stores must write themselves. `index.js` stops
+    // exporting them either way, so a page that imported one from the barrel
+    // needs updating whether or not the file is here.
+    ["src", "commerce", "storefront", "useAddressForm.js"],      // → addressFieldSpec + a recipe
+    ["src", "commerce", "storefront", "usePlaceOrder.js"],       // → useCheckout's own gate
+    ["src", "commerce", "storefront", "useProductPrice.js"],     // → productPrice
+    ["src", "commerce", "storefront", "useProductGallery.js"],   // → productImages + your index state
+    ["src", "commerce", "storefront", "useProductReviews.js"],   // → client methods + references/reviews.md
+    ["src", "commerce", "storefront", "useStorefrontSeo.js"],    // → your own head handling
+    ["src", "commerce", "storefront", "useTotalsLines.js"],      // → cartTotalsLines / orderTotalsLines
+    ["src", "commerce", "storefront", "useUpsell.js"],           // → p.upsells + addItem
   ];
   let retiredRemoved = 0;
   for (const parts of RETIRED) {

package/skills/commerce/SKILL.md

@@ -33,8 +33,11 @@ moments. Read nothing else up front.
   `base44.entities["commerce.Product"]`. `commerce__Product` and `Product` do
   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
+- **Store configuration is declared through `commerce/seed-store`** — catalog,
+  shipping zones, currency, payment methods — never assembled by editing
+  records. It is idempotent and every key is independent, so it is the day-2
+  tool as much as the install one: a later call carries only the slice it
+  changes — enabling cards is `{ payment_methods: ["offline", "card"] }`, whole
   ([`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
@@ -54,16 +57,19 @@ page — not as decoration re-typed on every element;
 method.
 
 **The logic ships as headless hooks** (`@/commerce/storefront`) — checkout
-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.
+repricing, variant resolution, cart state, coupon redemption, order-return
+verification, cart-drawer state. Each returns **plain states and handlers**
+(`status` to branch on, arrays to map, callbacks) — you write every element and
+attribute from them. **Never re-implement what a hook does** — that is where
+storefront bugs cluster.
+
+It ships **no copy**, either: where a state needs words you get the state
+(`buy.state`, `hint.code`, `blockers`) and write the words in the store's voice.
+A kit sentence rendered into every store is how storefronts end up alike.
 
 ```jsx
 import { useCart, CartLine } from "@/commerce/storefront";
-const { status, lines } = useCart();   // branch on status, map lines into YOUR rows
+const { status, cart } = useCart();   // branch on status, map cart.items into YOUR rows
 ```
 
 The admin UI (`src/commerce/admin/`) is finished and **also yours to change** —
@@ -84,6 +90,10 @@ hand back (API-level statements for non-React clients:
 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.
 
+A fifth that breaks nothing but flattens the catalog, and is skipped most often:
+**ribbons belong in both the grid and the product page**, each linking to its
+filtered listing. They are the merchant's own merchandising.
+
 All backend functions return the envelope `{ success, data }`; with the SDK the
 payload is `res.data.data`:
 
@@ -98,27 +108,34 @@ 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 |
+| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 5K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 33K |
+| [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 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/online-payments.md`](./references/online-payments.md) | enabling card payments, or wiring the provider — at install or any time later | 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/reviews.md`](./references/reviews.md) | review policies (login-gated, verified buyers), moderation | 5K |
 | [`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-storefront.md`](./docs/api-storefront.md) | filters, customer accounts, refunds, a non-React client | 31K |
 | [`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 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.
+treat the file as gone.
+
+**The install stages are self-contained.** Every request and response shape they
+build against is written out in them — `install/02-storefront.md` carries a table
+of exactly what each storefront hook resolves to. You should not need to open a
+file under `src/commerce/` while building, and doing it mid-build is the most
+expensive way to answer a question the stage already answers. (The source is
+still the final authority if a doc and the code ever disagree — report that
+rather than working around it.)

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

@@ -155,7 +155,7 @@ Not action-routed — the body **is** the payload. Requires admin. This is the *
 
 | Key | Type | Effect |
 |---|---|---|
-| `store_name` | string | **Required on a first seed** (the `emails` group doesn't exist yet) — otherwise **`400 store_name_required`**. Lands in `emails.store_name`: both the name in email subjects and the sender name, so a nameless store renders `[]: New order #1002`. On an already-seeded store it **fills a blank** name and never overwrites one the merchant chose. |
+| `store_name` | string | **Required on a first seed** (the `emails` group doesn't exist yet) — otherwise **`400 store_name_required`**. Lands in `emails.store_name`: both the name in email subjects and the sender name, so a nameless store sends `New order #1002` — substitution drops the empty brackets and collapses the gap, never `[]: New order #1002` ([`../references/emails.md`](../references/emails.md)) — it just never names the shop. On an already-seeded store it **fills a blank** name and never overwrites one the merchant chose. |
 | `currency` | ISO code | Sets `general.currency`, validated against the shared currencies table. Prices are formatted with `Intl.NumberFormat` — there are no format settings. |
 | `weight_unit` | `kg`\|`g`\|`lbs`\|`oz` | Sets `general.weight_unit`. |
 | `dimension_unit` | `cm`\|`m`\|`mm`\|`in`\|`yd` | Sets `general.dimension_unit`. |

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

@@ -2,7 +2,7 @@
 
 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`, `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/`.
+**Logic is premade, UI never is.** In a React app every surface here — listing, product page, cart, checkout, the receipt, reviews — has a headless hook in `@/commerce/storefront` ([`../install/02-storefront.md`](../install/02-storefront.md) is the surface, one line per export). The hooks own the API calls and the branching below and hand you a view-model; **all markup, styling and copy are yours** — nothing in the kit renders UI or ships a word of customer-facing text. 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/`.
 
 Entities and direct CRUD → [`entities.md`](./entities.md) · admin surface → [`api-admin.md`](./api-admin.md)
 
@@ -50,7 +50,7 @@ Bootstrap data for a storefront. No payload.
 ```
 `settings` is a safe projection — display/behavior keys only, never admin config.
 
-`payment_gateways` is **every gateway the admin has enabled** (sorted by `order`) and this call is its **only** source — `cart.payment_gateways` does not exist, and a hardcoded list is a broken checkout. A **default-seeded store reports `offline` alone** (cards are off by default — [`../install/03-data.md`](../install/03-data.md)), so expect the one-method case. `online: true` marks the card option (`place-order` answers with a payment page; `503 no_card_payment_provider` if it was enabled with no provider behind it); everything else settles manually. In React: `useStoreInfo()` + `PaymentMethodPicker`.
+`payment_gateways` is **every gateway the admin has enabled** (sorted by `order`) and this call is its **only** source — `cart.payment_gateways` does not exist, and a hardcoded list is a broken checkout. A **default-seeded store reports `offline` alone** (cards are off by default — [`../install/03-data.md`](../install/03-data.md)), so expect the one-method case. `online: true` marks the card option (`place-order` answers with a payment page; `503 no_card_payment_provider` if it was enabled with no provider behind it); everything else settles manually. In React the list arrives with the cached store info from `@/commerce/storefront`, which also ships the picker for it.
 
 ### `list-products`
 **Payload** (all optional): `search`, `category_id` (includes descendants), `ribbon_id`, `attribute_id` + `attribute_term`, `min_price`, `max_price`, `featured` (bool), `on_sale` (bool), `in_stock_only` (bool), `sort` (`-created_date`|`name`|`price`|`-price`|`popularity`|`rating`, default `-created_date`), `page` (default 1), `per_page` (default 12, max 100).
@@ -73,7 +73,7 @@ await cat({ on_sale: true, in_stock_only: true, per_page: 4 }); // deals
 await cat({ category_id, sort: "popularity", per_page: 4 });    // top in category
 ```
 
-`featured` is the admin's per-product flag (`commerce/seed-store` accepts `featured: true`), so a featured strip is store data, not slugs pinned in the UI. **A filter may legitimately match nothing** (nothing starred, nothing discounted) — drive the block off the returned array's length, hiding it or falling back to another slice, rather than assuming rows came back; `has_next` says whether a "see all" has more behind it. In React this is `useProductList`.
+`featured` is the admin's per-product flag (`commerce/seed-store` accepts `featured: true`), so a featured strip is store data, not slugs pinned in the UI. **A filter may legitimately match nothing** (nothing starred, nothing discounted) — drive the block off the returned array's length, hiding it or falling back to another slice, rather than assuming rows came back; `has_next` says whether a "see all" has more behind it. In React this call is one hook in `@/commerce/storefront`, paging and filters included.
 
 ### `get-product`
 **Payload:** `{ id }` **or** `{ slug }`; optional `reviews_page` (1), `reviews_per_page` (10, max 50).
@@ -94,7 +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** — 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).
+> **`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). In React the product page's hooks in `@/commerce/storefront` resolve this for you. 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.
@@ -106,7 +106,7 @@ Returns `{ "ribbons": [ { id, name, count } ] }` sorted by name. By default it o
 
 `count` is tallied from the products this API would actually list (published, honoring `inventory.hide_out_of_stock`) — **not** from `ProductRibbon.count`, which also counts drafts and drifts until `admin-tools` `recount-terms` runs. So `Gift (12)` and the ribbon's listing agree.
 
-This is the **only** way a storefront can enumerate ribbons (the entity is admin-only) and what makes `list-products` `ribbon_id` usable, since that filter needs an id. Ribbons are flat, cross-cutting labels; categories are the hierarchical spine — show both ([`../references/catalog-rendering.md`](../references/catalog-rendering.md)). In React: `useRibbons` / `useCategories`.
+This is the **only** way a storefront can enumerate ribbons (the entity is admin-only) and what makes `list-products` `ribbon_id` usable, since that filter needs an id. Ribbons are flat, cross-cutting labels; categories are the hierarchical spine — show both ([`../references/catalog-rendering.md`](../references/catalog-rendering.md)). In React both taxonomies are cached hooks in `@/commerce/storefront`.
 
 ### `list-attributes`
 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.
@@ -114,9 +114,9 @@ No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] }
 ### `submit-review`
 **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.
+> A React storefront reaches this call as `submitReview` (and the paginated list as `getProductReviews`) on the client from `@/commerce/storefront`'s `useStorefront()`, with the list itself already riding along on the product; policies and moderation are [`../references/reviews.md`](../references/reviews.md). Read on for the raw contract.
 
-**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are a `policy` option on the hook, not code you write: [`../references/reviews.md`](../references/reviews.md).
+**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
 
 **Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
 **Errors:** `404 not_found`, `400 email_required|review_incomplete|invalid_rating`.
@@ -153,7 +153,7 @@ Token-scoped cart (guest + member). Every action **except `create`** takes `cart
   "expires_at": "2025-..."
 }
 ```
-Coupons that stop validating are **auto-removed** and reported in `coupon_notices`; items whose product vanished or was unpublished appear in `removed_items`. In React `useCart` exposes this view as `lines` + `notices`.
+Coupons that stop validating are **auto-removed** and reported in `coupon_notices`; items whose product vanished or was unpublished appear in `removed_items`. In React the cart hook in `@/commerce/storefront` publishes this exact view — you render `items` and both notice arrays yourself.
 
 ### Actions
 | Action | Payload | Notes / errors |
@@ -176,7 +176,7 @@ Common: `400 cart_token_required`, `404 cart_not_found`, `404 cart_expired` —
 
 The token is the cart's bearer credential (treat it as a secret) and the **only** cart state a client keeps. Tokens expire (48h rolling TTL) and carts are consumed at checkout, so one cached in `localStorage` can go stale. `add-item` heals that by starting a fresh cart — but only if the client **reads `cart_token` from every cart response and re-persists it** instead of assuming the stored one survived. Do that after every cart call, and treat `404 cart_not_found|cart_expired` from the other actions as "clear the cached token and start over", not as an error to show.
 
-**In React none of this is yours:** `StorefrontProvider` owns the token and `useCart` exposes the priced view — never read, store or send the token yourself.
+**In React none of this is yours:** the provider in `@/commerce/storefront` owns the token and publishes the priced view — never read, store or send the token yourself.
 
 ### Shipping is not optional — read this before building checkout
 <a id="shipping-is-not-optional--read-this-before-building-checkout"></a>
@@ -198,7 +198,7 @@ Rates re-resolve on every cart change (a stale choice is dropped, re-auto-select
 
 `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).
+**In React this is the checkout hook in `@/commerce/storefront`**: address state debounces into `set-shipping-address`, a render-prop picker renders the options, and a `canPlaceOrder` gate 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).
 
 ### Never advertise what the store isn't configured to do
 
@@ -255,7 +255,7 @@ Separate function, same guest-bearer rule: `order_id` + `order_key` (an admin ma
 | `complete-return` | `{ order_id, order_key, payment?, return_url? }` | `{ state: "paid"\|"cancelled"\|"unpaid", paid, already_confirmed, status, order, payment_link, payment_instructions }` — the whole return flow in one call: confirms with the provider, progresses the order, adds a fresh `payment_link: { url, reference }` while a card order is unpaid, and re-supplies `payment_instructions: { type, description, account_details }` for unpaid **manual** orders so bank details render on every visit. `payment` is only a hint — a hand-edited `?payment=success` can never yield `paid`. **`order` carries flat totals** (`order.total`, `order.shipping_total`); there is no `order.totals` — that shape belongs to the cart view |
 | `verify` | `{ order_id, order_key }` | `{ paid, already_confirmed, status, order }` — the same confirmation without the render-ready extras. **Idempotent**; money is asked of the provider about the reference stored on the order |
 
-> **The `/order-received` route is mandatory** (requirement 4): without it a paying customer lands on a 404 *and* the order is never marked paid. It only has to call `complete-return` and render its three states — `useOrderReturn` does exactly that (your markup renders the states, including `paymentInstructions`).
+> **The `/order-received` route is mandatory** (requirement 4): without it a paying customer lands on a 404 *and* the order is never marked paid. It only has to call `complete-return` and render its three states — the receipt hook in `@/commerce/storefront` does exactly that (your markup renders the states, including `paymentInstructions`).
 
 Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab; whichever path runs second is a no-op. That function is premade (it verifies through the provider's API, so no signing secret). Wiring a provider: [`../references/online-payments.md`](../references/online-payments.md).
 
@@ -291,7 +291,7 @@ Two access modes: **auth** (Base44 session) or **`order_key` bearer** (guest tra
 
 ## Walkthrough — guest checkout
 
-Raw-call spine 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 all of it from `@/commerce/storefront`).
 
 ```js
 const inv = (fn, payload) => base44.functions.invoke(fn, payload).then(r => r.data.data);

package/skills/commerce/install/01-install.md

@@ -23,8 +23,11 @@ carry_forward:
 Image generation is the slowest step and nothing depends on it until seed time; the storefront doesn't wait on live data either.
 
 1. **Start image generation first** — every product image, before anything else.
-2. **Mount the admin (below) and build the storefront** while images render.
-3. **Seed the moment the image URLs are back** — one `commerce/seed-store` call ([`./03-data.md`](./03-data.md)).
+2. **Mount the admin (below) and build the storefront** while images render. Every
+   request and response shape the pages build against is written out in
+   [`./02-storefront.md`](./02-storefront.md), so they are written from the docs,
+   not from live data.
+3. **Seed the moment the image URLs are back** — one `commerce/seed-store` call ([`./03-data.md`](./03-data.md)). Its writes run in parallel, so the call usually takes a few seconds — but don't idle on it either.
 4. **Converge**: open the finished pages against the live catalog.
 5. **Payments last, if at all** — cards are off by default; [`./03-data.md`](./03-data.md) decides it.
 
@@ -64,9 +67,4 @@ Storefront functions are public on purpose (per-action verification, above). To
 
 Then continue: **[`./02-storefront.md`](./02-storefront.md) when you start building UI**, **[`./03-data.md`](./03-data.md) when you start the seed payload**. Do **not** read them now, and open no `references/` or `docs/` file during an install — a file read early costs its size on every later call.
 
-Record these lines in your working notes; do not re-read this file.
-
-- Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them.
-- `/order-received` must exist as a route: every payment link returns there, and confirming is what marks an order paid.
-- Interleave: start image generation first → mount admin + build the storefront while images render → seed when the URLs are back → payments last.
-- Entities are dotted + bracket-syntax only (`base44.entities["commerce.X"]`); the map is [`../docs/entities.md`](../docs/entities.md) — never scan `base44/entities/`.
+Then copy this file's `carry_forward` lines (in its front matter) into your working notes, and do not re-read this file.