@base44/app-plugin-commerce 0.1.15 → 0.1.16

package/skills/commerce/post-installation.md

@@ -1,39 +1,39 @@
 # Post-installation
 
-What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, build the storefront from the quick start below, and — **if and when the store needs online payments, a call you make deliberately (§2.2)** — wire a payment provider. Installed into the app at `.agents/skills/commerce/post-installation.md`.
+What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, build the storefront from the quick start below, seed the store's data, and — **if and when the store needs online payments, a call you make deliberately (§4)** — wire a payment provider. Installed into the app at `.agents/skills/commerce/post-installation.md`.
 
-> **This file is intentionally the whole job.** Unless the user has a special requirement (a non-Stripe payment provider, signature-verified webhooks, filters/reviews/accounts beyond the happy path), do **not** open the `references/` guides or the `docs/` API references — everything needed to ship a working store (admin mount, seeding, product list, product page, cart, checkout, order-received, and card payments for the stores that need them) is on this page, ending with the [Done when](#4-done-when) checklist. Reading more first just burns time.
+> **This file is intentionally the whole job.** Unless the user has a special requirement (a non-Stripe payment provider, signature-verified webhooks, filters/reviews/accounts beyond the happy path), do **not** open the `references/` guides or the `docs/` API references — everything needed to ship a working store (admin mount, the storefront — catalog pages, optional cart, checkout, order-received — seeding, and card payments for the stores that need them) is on this page, ending with the [Done when](#5-done-when) checklist. Reading more first just burns time.
 
 ## 0. Sequencing — build the UI while the slow work runs
 
-The sections below are ordered for **reading** — they are not a schedule. Executed strictly top-to-bottom, the install spends most of its wall-clock waiting on things that never needed to block: image generation (the slowest step of the whole install), the `commerce/seed-store` call (~20 seconds), and — for stores that take card payments — the user round-trip for the provider secret key. **None of these block writing the storefront**: every request/response shape §3 builds against is documented on this page, so the components are written from the docs, not from live data. Live data is only needed at the very end, to verify.
+The sections below are in work order — admin mount, storefront, then the data and payment calls — but the order is not a queue to wait in. The install's wall-clock is dominated by things that never needed to block: image generation (the slowest step of the whole install) and, for stores that take card payments, the user round-trip for the provider secret key. **Nothing about the storefront waits on live data**: every request/response shape §2 builds against is documented on this page, so the components are written from the docs, and live data only matters once at the end.
 
 So interleave — whenever a slow activity is in flight, write UI instead of waiting:
 
-1. **Start image generation first** — kick off every product image before anything else (§2.1 "Images"), because it takes the longest and nothing depends on it until seed time.
-2. **Mount the admin router (§1)** — minutes of work — and start writing storefront components (§3) while the images render.
-3. **The moment the image URLs are back, fire `commerce/seed-store` (§2) and keep writing UI while it runs.** Don't idle on the call; pick up its response (catalog report, slugs) when you next need it. If your tooling runs calls in the background, use that; if not, order the work so the call sits between two chunks of component-writing, never between you and an empty wait.
-4. **Payment wiring (§2.2), if the store takes card payments, runs in parallel too** — the file paste and webhook registration touch nothing the storefront depends on, and the ask for the secret key can be pending while you build.
-5. **Converge at the end**: with the seed done and pages written, verify the storefront against the live catalog and walk the [Done when](#4-done-when) checklist.
+1. **Start image generation first** — kick off every product image before anything else (§3.1 "Images"), because it takes the longest and nothing depends on it until seed time.
+2. **Mount the admin router (§1)** — minutes of work — and build the storefront (§2) while the images render.
+3. **The moment the image URLs are back, fire `commerce/seed-store` (§3).** Its writes run in parallel, so the call usually takes a few seconds — but don't idle on it either; pick up its response (catalog report, slugs) when you next need it.
+4. **Payment wiring (§4), if the store takes card payments, runs in parallel too** — the file paste and webhook registration touch nothing the storefront depends on, and the ask for the secret key can be pending while you build.
+5. **Converge at the end**: with the seed done and pages written, open the storefront against the live catalog and walk the [Done when](#5-done-when) checklist.
 
-The only real dependency edges are: image URLs → seed payload, and seed done → final verification. Everything else overlaps.
+The only real dependency edges are: image URLs → seed payload, and seed done → seeing real products on the finished pages. Everything else overlaps.
 
 ---
 
 ## 1. Embedding the admin pages
 
-The admin UI is a self-contained React app under `src/commerce/admin/`. Its only external touchpoints are `@/components/ui/*` (shadcn) and `@/api/base44Client` (your app's SDK client). `src/commerce/utils/` sits alongside it — framework-free storefront helpers (variant selection, free-shipping rules) with no dependencies, used by the customer-facing UI you build, not by the admin.
+The admin UI is a self-contained React app under `src/commerce/admin/`. Its only external touchpoints are `@/components/ui/*` (shadcn) and `@/api/base44Client` (your app's SDK client). Two storefront-logic folders sit alongside it, used by the customer-facing UI you build, not by the admin: `src/commerce/utils/` (framework-free helpers — API client, variant selection, free-shipping rules; no dependencies) and `src/commerce/storefront/` (the React layer — shared-cart provider, guided-checkout hook, headless shipping/payment pickers, order-received hook; needs React and nothing else).
 
 **Steps:**
 
-1. Copy `src/commerce/admin/` → `src/commerce/admin/` and `src/commerce/utils/` → `src/commerce/utils/` (already done if you ran `scripts/install.js`).
+1. Copy `src/commerce/admin/` → `src/commerce/admin/`, `src/commerce/utils/` → `src/commerce/utils/` and `src/commerce/storefront/` → `src/commerce/storefront/` (already done if you ran `scripts/install.js`).
 2. Check the app's `package.json` for `sonner`, `recharts` and `react-markdown` (the StoreAdmin bot uses the last one), and run `npm i` **only** for the ones actually absent — all three ship with the default Base44 template, so the normal outcome is no install at all. Do not re-install a package that is already a dependency. The template needs **no other dependency**. Verify the shadcn primitives listed in `src/commerce/admin/README.md` are present (`npx shadcn@latest add <name>` for any missing).
 3. Mount the router:
    ```jsx
    import AdminApp from "@/commerce/admin";
    <Route path="/store-admin/*" element={<AdminApp />} />
    ```
-   **You must also build a payment return page** (`/order-received` by default) — this is **mandatory for payment links to work at all**. If your route differs, set it in Settings → General → *Payment return path*, or payment links will send customers to a 404. Every link (checkout, the admin's payment link, emails) returns there; without the route a paying customer hits a 404, and since confirming is what marks an order paid, orders would stay unpaid. The page is a thin wrapper over one backend call — step 4 of the [storefront quick start](#3-storefront-quick-start--logic-only) below covers it completely.
+   **You must also build a payment return page** (`/order-received` by default) — this is **mandatory for payment links to work at all**. If your route differs, set it in Settings → General → *Payment return path*, or payment links will send customers to a 404. Every link (checkout, the admin's payment link, emails) returns there; without the route a paying customer hits a 404, and since confirming is what marks an order paid, orders would stay unpaid. The page is one shipped hook — `useOrderReturn` from `@/commerce/storefront` — plus your markup; step 4 of the [storefront quick start](#2-storefront-quick-start--logic-only) below covers it completely.
 
    **Give the app root something too.** A blank Base44 app has no `/` route, so after mounting only `/store-admin/*` the app's own URL still renders its "page not found" screen — which reads exactly like a broken install. Until a storefront exists, redirect: `<Route path="/" element={<Navigate to="/store-admin" replace />} />`.
 
@@ -58,9 +58,217 @@ Even if the client guard were bypassed, layers 2 and 3 keep the store data safe.
 
 ---
 
-## 2. Store data — seeding
+## 2. Storefront quick start — logic only
 
-A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. The call takes **~20 seconds** — never sit through it: fire it and write storefront components while it runs (§0); nothing in §3 needs its response, only the final verification does. It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices) and the `offline` and `card` payment gateways — and, depending on the payload, the catalog. A fallback "Rest of the world" **Shipping & Tax Location** (one free shipping rate, no tax) is seeded **only when the payload carries no `locations`** — locations you pass are the store's only shipping data, with no seeded fallback beside them. Pass **`currency`** (an ISO code, e.g. `"EUR"`) and/or **`weight_unit`**/**`dimension_unit`** to set the store's currency and measurement units instead of the defaults — explicit values always win, on a first seed and a re-run alike. (Prices are *formatted* with `Intl.NumberFormat` per the viewer's locale — the currency is a value; there are no format settings.)
+No visitor UI ships — and no visual component ships either: **every pixel of the shopfront stays yours to design**. What ships is the logic: the storefront **API**, the framework-free helpers in `@/commerce/utils`, and the React layer in `@/commerce/storefront` — hooks and headless pickers owning the contracts every store must get right. The catalog views (§2.1–2.2) are deliberately the thinnest, because that is where storefronts differ most; the cart and checkout (§2.3–2.4) are more guided, because shipping recalculation, payment methods and the place-order gate work the same in every store. **None of it waits on anything**: every shape you build against is documented right here, so seeding (§3) and payment wiring (§4) run in parallel with building these pages (§0 has the schedule) — kick off image generation, write the storefront while it renders, seed when the URLs are back, and pick up payments whenever the secret key arrives. Live data is only needed once, to see real products on the finished pages. The four chunks below are the whole happy path; open [`docs/api-storefront.md`](./docs/api-storefront.md) only for what's beyond them (attribute/price filters, reviews, customer accounts, refunds), and [`references/product-render.md`](./references/product-render.md) for which fields belong in which view.
+
+**Set up once** — mount the provider above every storefront route. It owns the shared API client, the store-info cache and ONE shared cart, so a header badge, a cart drawer and the checkout all render the same state:
+
+```jsx
+import { StorefrontProvider } from "@/commerce/storefront";
+import { base44 } from "@/api/base44Client";
+
+<StorefrontProvider base44={base44}>
+  {/* storefront routes */}
+</StorefrontProvider>
+```
+
+The provider owns the two things hand-rolled storefronts keep getting wrong, so **don't reimplement either — and never mount a second provider or create a second client**: the **`cart_token` lifecycle** (sent with every cart/checkout call, re-persisted from every response — a stale token silently starts a fresh cart; rolling 48 h expiry; cleared when checkout consumes the cart) and the **store-info cache** (`payment_gateways`, currency, countries live **only** on `get-store-info` — the cart view never carries them). Inside the tree, `useStorefront()` returns the shared client for catalog calls, and `store.inv(fn, payload)` on it is the raw escape hatch (it unwraps the `{ success, data }` envelope). If non-React code also needs the client, create it once in `src/lib/storefront.js` (`createStorefront(base44)` from `@/commerce/utils`) and pass that same instance via `<StorefrontProvider store={store}>`.
+
+**What each hook / client method resolves to** — every envelope is already unwrapped, so take these shapes at face value (no `.data`, and no `.categories` on a list result):
+
+| Source | Resolves to |
+|---|---|
+| `useStoreInfo()` | `{ info, settings, paymentGateways, countries, currencies, loading, error }` — cached; the **only** source of payment gateways |
+| `useFormatMoney()` | `(amount) => "€19.99"` — the store's currency, the viewer's locale |
+| `useCart()` | `{ cart, loading, itemCount, isEmpty, addItem, updateItem, removeItem, applyCoupon, removeCoupon, refresh }` — ONE cart shared by every consumer; `cart.items[n].attributes` is an **array** of `{ name, option }`, never a map |
+| `useCheckout()` / `CheckoutProvider` | the guided checkout — §2.4 |
+| `useOrderReturn()` | the `/order-received` page — §2.4 |
+| client `listProducts(params)` | `{ products, page, per_page, has_next }` — a page object; the array is `products` |
+| client `getProduct(slug \| { id })` | `{ product, variations, categories, ribbons, reviews }` |
+| client `listCategories()` | an **array** of root categories, subcategories nested under `children` |
+| client `listRibbons()` | an **array** of `{ id, name, count }` |
+
+Keep the UI in **small focused components** (~2–4K characters each — product card, gallery, cart panel, address step, payment step…), not monolithic page files: smaller files are faster to emit, review and fix.
+
+### 2.1 Product list
+
+The catalog is direct client calls plus your design — no premade structure to fight:
+
+```js
+const store = useStorefront();          // the shared client
+const formatMoney = useFormatMoney();   // store currency, viewer's locale — use for every price
+// useStoreInfo() → { settings, paymentGateways, countries, … } wherever store data is needed;
+//   it is the ONLY source of payment gateways (they are never on the cart view)
+
+const { products, page, per_page, has_next } = await store.listProducts({
+  page: 1, per_page: 12,           // optional: search, category_id, ribbon_id, featured, on_sale,
+  sort: "-created_date",           //   min_price, max_price, in_stock_only
+});                                // sort: -created_date | name | price | -price | popularity | rating
+```
+
+Each row is a full product record — for a card use `name`, `images[0]?.src` (**may be empty — render a placeholder, never a broken `<img>`**), `price`, `regular_price`, `on_sale` (sale badge), `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `store.listCategories()` — an **array** of root categories with subcategories nested under `children` (map over it directly; there is no `{ categories }` wrapper on the result). That is the whole card — no other call or reference needed for the list view.
+
+**Carry forward:** each card links to the product page by **`slug`**.
+
+### 2.2 Product page — variant selection included
+
+```js
+const { product, variations, categories, ribbons, reviews } =
+  await store.getProduct(slug);   // or store.getProduct({ id })
+
+// One selector PER product.attributes[] entry — never a flat list of variations.
+import { defaultSelection, selectOption, resolveSelection } from "@/commerce/utils";
+
+let selection = defaultSelection(product, variations);        // merchant defaults + single-option axes
+// on user pick: selection = selectOption(product, variations, selection, axisKey, option);
+
+const view = resolveSelection(product, variations, selection);
+// view.axes         → [{ key, name, options }] — render one control each
+// view.availability → { [axisKey]: { [option]: "available" | "out_of_stock" | "unavailable" } }
+// view.display      → { price, regular_price, on_sale, sku, stock_status, image, … } for the selection
+//                     ⚠ display.image is an OBJECT — { src, name, alt } | null. Render
+//                     <img src={view.display.image?.src} alt={view.display.image?.alt}>.
+//                     Passing the object itself as src fails the load and your fallback
+//                     shows a placeholder for every product — with the real image sitting
+//                     one `.src` away. Same shape everywhere: product.images[n].src too.
+// view.purchasable  → gate the Add-to-cart button on this
+// view.addToCart    → { product_id, variation_id } — null until the selection resolves
+```
+
+Add to cart — through the shared cart, so every badge and drawer in the tree updates at once (the cart bootstraps itself; a missing, stale or expired token starts a fresh one, and the provider does all the token bookkeeping):
+
+```js
+const { addItem } = useCart();
+await addItem(view.addToCart);        // quantity 1 — addItem(view.addToCart, 3) for more
+```
+
+A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call.
+
+**What the page renders — all from this one `get-product` call, no extra reads:** a gallery from `product.images` (`view.display.image` is the variant-selected one; placeholder **only** when the product truly has no images — every image is an `{ src, alt }` object, so render `img.src`/`img.alt`, never the object itself), name, price from `view.display` (`price`/`regular_price`/`on_sale` → sale badge), one selector per axis, stock state, `short_description` then `description` (**both HTML — render as rich text, don't escape or truncate away the markup**), SKU, `categories` as a breadcrumb, `ribbons` as light labels near the metadata, the `reviews` block (`{ items, has_next, average_rating, rating_count }`), and the `upsells`/`cross_sells` summaries. Descriptive properties (Material, Care…) live in `product.meta_data` — render them as a spec table; they are not attributes and not ribbons. That is the complete product page — [`references/storefront-product-page.md`](./references/storefront-product-page.md) and [`references/product-render.md`](./references/product-render.md) are only for edge cases and for adding fields to the *listing* call.
+
+**Carry forward:** nothing — the client keeps the `cart_token`.
+
+### 2.3 Cart
+
+**A cart page is optional — decide from what the store sells.** Under the hood a cart always exists (checkout consumes it, and `addItem` is still how anything gets bought), but the *UI step* — a cart page or drawer where customers review and edit line items — is a choice, not a requirement. A store selling one service, made-to-order pieces, or typically-single-item purchases reads better as **buy-now**: `addItem(view.addToCart)` and navigate straight to checkout, no cart view anywhere. Multi-item catalogs where customers accumulate a basket want the full cart step. Either way the checkout (§2.4) is unchanged — it reads the same shared cart whether the customer curated it on a cart page or a buy-now button filled it a second ago.
+
+When the store does want one, the cart is **shared state** — `useCart()` anywhere in the tree reads and mutates the same view, every action re-renders every consumer, and calls are serialized so rapid quantity clicks can never apply out of order:
+
+```jsx
+const { cart, loading, itemCount, isEmpty,
+        updateItem, removeItem, applyCoupon, removeCoupon } = useCart();
+// cart === null → no cart yet (an expired token self-clears) — render an empty state
+// cart.items  → [{ item_key, name, image, quantity, price, subtotal, total, attributes, purchasable }]
+//               item.attributes is an ARRAY of { name, option } — render "Size: 42" by
+//               mapping it (attributes.map(a => `${a.name}: ${a.option}`)); it is never a map
+// cart.totals → { subtotal, discount_total, shipping_total, cart_tax, total_tax, total, … }
+// cart.coupon_notices / cart.removed_items → tell the customer what auto-dropped and why
+//
+// NOT in the cart view: payment_gateways (useStoreInfo() ONLY — cart.payment_gateways
+// is always undefined), the product catalog (listProducts/getProduct), countries/currencies
+// (useStoreInfo). Never dot into the cart for any of those.
+
+await updateItem(item_key, quantity);        // ≤0 removes
+await removeItem(item_key);
+const res = await applyCoupon(code);         // { ok: true, cart } or { ok: false, code, message }
+if (!res.ok) setCouponError(res.message);    //   an invalid code is expected flow — render it inline
+```
+
+Shipping cost on the cart page: a store with exactly **one shipping location** shows its options (and, auto-selected, the cost) even before an address is known — render `cart.available_shipping_methods` and the totals as they come. Several locations report `shipping_status: "missing_address"` until an address resolves one; that address is collected in checkout, where `useCheckout` recalculates shipping and tax automatically the moment it is complete (§2.4) — **don't build a separate estimator or call `set-shipping-address` by hand on the cart page.**
+
+**Carry forward:** nothing — the provider keeps the `cart_token`, and the address and method choice live on the shared cart.
+
+### 2.4 Checkout & order-received
+
+`useCheckout()` is the guided checkout — it owns everything that is the same in every store, and your page is markup around it:
+
+- **address form state** (`billing`/`updateBilling`, an optional separate `shipping`/`updateShipping` behind `setShipToDifferent`), with `missingBillingFields` tracking what `place-order` would reject;
+- **automatic shipping/tax recalculation**: the moment the address is complete enough to price (default: country + city), the hook debounces and calls `set-shipping-address`, repricing every shipping option, its cost and the taxes — half-typed addresses are never sent, an unchanged address is never re-sent, and an address the store doesn't ship to surfaces as `addressError` to show **on the address fields**;
+- **the shipping choice** (`shippingStatus`, `shippingMethods`, `chosenShippingMethod`, `chooseShippingMethod`) and **the payment choice** (`paymentMethods` from store info — their only source; a store with exactly one enabled gateway gets it pre-selected);
+- **the gate**: `canPlaceOrder` + named `blockers`, and `placeOrder` with the online-payment redirect handled.
+
+Share one instance across the page's components with `CheckoutProvider` and build each step as your own markup:
+
+```jsx
+import { CheckoutProvider, useCheckoutContext, useCart, useStoreInfo,
+         ShippingMethodPicker, PaymentMethodPicker } from "@/commerce/storefront";
+
+<CheckoutProvider>          {/* one useCheckout shared by the whole page */}
+  <AddressFields />         {/* your components, your layout, your look */}
+  <ShippingStep />
+  <PaymentStep />
+  <OrderSummary />          {/* useCart().cart.totals re-renders as the address edits reprice it */}
+  <PlaceOrderButton />
+</CheckoutProvider>
+```
+
+The address form binds inputs to the hook — editing is all it takes to trigger the recalculation (`useStoreInfo().countries` is the country table for the selector):
+
+```jsx
+const { billing, updateBilling, missingBillingFields,
+        addressError, shippingSyncing } = useCheckoutContext();
+<input value={billing.city} onChange={(e) => updateBilling({ city: e.target.value })} />
+{addressError && <p role="alert">{addressError.message}</p>}   // "we don't ship there" lives HERE
+```
+
+The two store-data choices — **never hardcode either** — come pre-branched through the headless pickers (they render nothing themselves; the render prop is the whole UI):
+
+```jsx
+<ShippingMethodPicker>{({ status, methods, chosen, choose, mustChoose, syncing }) => (
+  // renders null for you on virtual carts (status "not_needed")
+  // status "missing_address" → say options appear once the address is entered
+  // mustChoose → render methods [{ id, title, cost }] as a picker → choose(m.id)
+  // otherwise  → display chosen.title + chosen.cost (never a raw id); dim while syncing
+)}</ShippingMethodPicker>
+
+<PaymentMethodPicker>{({ gateways, value, select, selected, single }) => (
+  // several → picker labeled with the admin's title/description → select(g.slug)
+  // single  → pre-selected; skip the picker but still show selected.title
+  // none    → checkout cannot complete — say so instead of rendering a dead button
+)}</PaymentMethodPicker>
+```
+
+While the store has no card provider implemented (§4 — one file, Stripe paste-in), picking the card gateway fails `place-order` with `503 no_card_payment_provider` — tell the customer card payment is temporarily unavailable and offer the other methods. `online: true` marks the card/redirect gateway; every other gateway is manual reconciliation.
+
+Placing the order — drive the button off the gate; the hook redirects to the provider's payment page when the gateway is online:
+
+```jsx
+const { canPlaceOrder, blockers, placing, placeOrder, orderError } = useCheckoutContext();
+
+<button disabled={!canPlaceOrder || placing} onClick={async () => {
+  const res = await placeOrder({ customer_note });
+  if (res.ok && !res.result.payment) showConfirmation(res.result);
+  // manual gateway → res.result.payment_instructions: { description, account_details } — render them
+  // online gateway → the hook already redirected to res.result.payment.checkout_url
+  // res.ok === false → res.error rendered below; the hook re-read the cart if it changed underneath
+}}>Place order</button>
+{orderError && <p role="alert">{orderError.message}</p>}
+```
+
+`blockers` names exactly what still stands in the way — drive inline hints from it instead of re-deriving: `empty_cart`, `billing_incomplete` (pair with `missingBillingFields`), `shipping_address_incomplete`, `shipping_recalculating`, `shipping_address_required`, `shipping_method_required`, `shipping_not_available`, `payment_method_required`.
+
+Every payment link returns to **`/order-received`** — the page from §1 step 3. One hook, idempotent, safe on every visit (it reads the URL params itself; `?payment=` is only a hint — the server verifies with the provider):
+
+```jsx
+const { status, order, paymentLink, paymentInstructions, error, reload } = useOrderReturn();
+// "loading"   → spinner
+// "paid"      → thank-you + order summary (the order is now marked paid)
+// "unpaid"    → card order: offer paymentLink.url to pay now;
+//               manual order: render paymentInstructions ({ description, account_details })
+// "cancelled" → payment was cancelled — offer paymentLink.url or support
+// "error"     → render error.message with a retry via reload()
+```
+
+Two shapes to get right when rendering: **`order` carries flat totals** — `order.total`, `order.shipping_total`, `order.total_tax` — there is **no `order.totals` object** (that nested shape belongs to the cart view and the place-order result's top-level `totals`); and `paymentLink` is `{ url, reference } | null` (card orders only).
+
+**Carry forward:** `order_id` + `order_key` are the guest's proof of ownership — `commerce/storefront-account` `get-order` with both returns the order for a tracking page (signed-in customers get `my-orders` with no key).
+
+---
+
+## 3. Store data — seeding
+
+A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. Its writes run in parallel, so the call usually takes a few seconds (large catalogs longer) — and nothing in §2 needs its response anyway, so fire it and keep building (§0). It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices) and the `offline` and `card` payment gateways — and, depending on the payload, the catalog. A fallback "Rest of the world" **Shipping & Tax Location** (one free shipping rate, no tax) is seeded **only when the payload carries no `locations`** — locations you pass are the store's only shipping data, with no seeded fallback beside them. Pass **`currency`** (an ISO code, e.g. `"EUR"`) and/or **`weight_unit`**/**`dimension_unit`** to set the store's currency and measurement units instead of the defaults — explicit values always win, on a first seed and a re-run alike. (Prices are *formatted* with `Intl.NumberFormat` per the viewer's locale — the currency is a value; there are no format settings.)
 
 Pass **`payment_methods`** (gateway slugs, e.g. `["card"]`) when the user restricts how they get paid: the listed gateways are enabled and **every other gateway row is disabled** — "card-only" or "offline-only" is part of the same seed call, with **no `commerce.PaymentGateway` reads or writes of your own**. Explicit values win on re-runs too. Unknown slugs fail as `400 invalid_payload` (the error lists the known ones). Should you ever need direct entity access, names are dotted — bracket syntax only: `base44.entities["commerce.PaymentGateway"]` (`commerce__PaymentGateway` / `PaymentGateway` don't exist).
 
@@ -76,57 +284,65 @@ Pass **`payment_methods`** (gateway slugs, e.g. `["card"]`) when the user restri
 
 The call runs a canary schema check first — on **422** `schema_incompatible` fix the reported entities before continuing. Bad catalog payloads fail as **400** `invalid_payload` with an `errors: [{ path, error }]` list before anything is written.
 
-### 2.1 The `products` payload
+### 3.1 The `products` payload
 
 **This is the store's real data, not template data.** The call writes the actual `commerce.*` records the admin and the storefront API read from that moment on — nothing is post-processed, substituted or "filled in by the platform" later. Whatever you pass is exactly what `list-products`/`get-product` return, so pass final values (real copy, real prices, permanently-resolvable image URLs) and build the storefront on what the API returns — never on client-side constants mirroring the seed (e.g. a slug→image map): the database is the single source of truth, and such a mirror silently diverges the first time a product is edited in the admin.
 
 Reference everything by **display name** — categories, ribbons, attributes and their options are get-or-created (slugs and codes derived, existing records matched case-insensitively and reused). Variants come from `attributes`: list each axis with the options the product comes in, and either pass explicit `variations` (only the combinations you stock, with per-variation overrides) or omit them to auto-generate **every combination**. Prices and the sale window are inherited from the product spec unless a variation overrides them; a variation with its own `stock_quantity` tracks it, one without draws on the parent's pooled `stock_quantity`.
 
+**Running this through a code-execution tool? Return only plain JSON.** The SDK's `invoke` resolves to the raw HTTP response, which carries circular request/response objects — `return result` (or stringifying a thrown error whole) fails with `Converting circular structure to JSON` *even when the seed itself succeeded*. Return `res.data` (the `{ success, data }` envelope) and, on error, `e.response?.data`:
+
 ```js
-await base44.functions.invoke("commerce/seed-store", {
-  store_name: "Aurora Threads",
-  currency: "EUR",                             // optional — defaults to USD
-  payment_methods: ["card"],                   // optional — enables ONLY these; omit to keep offline + card
-  products: [
-    { // simple product
-      name: "Classic T-Shirt",
-      sku: "TEE-CLASSIC",                      // optional, but makes re-runs idempotent
-      regular_price: 19.99,
-      stock_quantity: 50,                      // implies manage_stock: true
-      categories: ["Clothing"],                // get-or-create by name
-      ribbons: ["Best Seller"],
-      images: ["https://…/tee.jpg"],           // URLs or { src, alt }
-      short_description: "A soft, breathable everyday tee.",
-      description: "<p>Cut from combed cotton…</p><ul><li>100% combed cotton</li><li>Pre-shrunk</li></ul>",
-    },
-    { // variant product — attributes declare the axes, variations the stocked combos
-      name: "Runner Sneaker",
-      sku: "SNK-RUN",
-      regular_price: 89,                       // inherited by variations that don't override
-      categories: ["Shoes"],
-      images: [{ src: "https://…/sneaker.jpg", alt: "Runner Sneaker, side view" }],
-      attributes: [
-        { name: "Size", options: ["41", "42", "43"] },
-        { name: "Color", options: ["Black", "White"] },
-      ],
-      default_options: { Size: "42", Color: "Black" },   // pre-selected combination
-      variations: [                            // omit entirely → all 6 combos auto-generated
-        { options: { Size: "41", Color: "Black" }, stock_quantity: 4 },
-        { options: { Size: "42", Color: "Black" }, stock_quantity: 6 },
-        { options: { Size: "43", Color: "Black" }, stock_quantity: 2 },
-        { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
-          image: "https://…/sneaker-white.jpg" },        // give a visual axis per-variation images
-      ],
-    },
-  ],
-  coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],   // optional
-  locations: [{                              // optional — passing any makes these the store's ONLY locations (the free-shipping fallback is not seeded)
-    name: "Israel", countries: ["IL"],
-    shipping_rates: [{ name: "Standard", cost: 20, free_over: 150 }],
-    tax_groups: [{ name: "Products", rates: [{ name: "VAT", rate: 18 }] }],
-    shipping_tax: { type: "percent", value: 18 },   // or { type: "fixed", value: 5 }
-  }],
-});
+try {
+  const res = await base44.functions.invoke("commerce/seed-store", {
+    store_name: "Aurora Threads",
+    currency: "EUR",                             // optional — defaults to USD
+    payment_methods: ["card"],                   // optional — enables ONLY these; omit to keep offline + card
+    products: [
+      { // simple product
+        name: "Classic T-Shirt",
+        sku: "TEE-CLASSIC",                      // optional, but makes re-runs idempotent
+        regular_price: 19.99,
+        stock_quantity: 50,                      // implies manage_stock: true
+        categories: ["Clothing"],                // get-or-create by name
+        ribbons: ["Best Seller"],
+        images: ["https://…/tee.jpg"],           // URLs or { src, alt }
+        short_description: "A soft, breathable everyday tee.",
+        description: "<p>Cut from combed cotton…</p><ul><li>100% combed cotton</li><li>Pre-shrunk</li></ul>",
+      },
+      { // variant product — attributes declare the axes, variations the stocked combos
+        name: "Runner Sneaker",
+        sku: "SNK-RUN",
+        regular_price: 89,                       // inherited by variations that don't override
+        categories: ["Shoes"],
+        images: [{ src: "https://…/sneaker.jpg", alt: "Runner Sneaker, side view" }],
+        attributes: [
+          { name: "Size", options: ["41", "42", "43"] },
+          { name: "Color", options: ["Black", "White"] },
+        ],
+        default_options: { Size: "42", Color: "Black" },   // pre-selected combination
+        variations: [                            // omit entirely → all 6 combos auto-generated
+          { options: { Size: "41", Color: "Black" }, stock_quantity: 4 },
+          { options: { Size: "42", Color: "Black" }, stock_quantity: 6 },
+          { options: { Size: "43", Color: "Black" }, stock_quantity: 2 },
+          { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
+            image: "https://…/sneaker-white.jpg" },        // give a visual axis per-variation images
+        ],
+      },
+    ],
+    coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],   // optional
+    locations: [{                              // optional — passing any makes these the store's ONLY locations (the free-shipping fallback is not seeded)
+      name: "Israel", countries: ["IL"],
+      shipping_rates: [{ name: "Standard", cost: 20, free_over: 150 }],
+      tax_groups: [{ name: "Products", rates: [{ name: "VAT", rate: 18 }] }],
+      shipping_tax: { type: "percent", value: 18 },   // or { type: "fixed", value: 5 }
+    }],
+  });
+  return res.data;                 // the { success, data } envelope — plain JSON
+} catch (e) {
+  // e itself is circular (it wraps the HTTP request) — return only its payload
+  return { success: false, status: e.response?.status, ...(e.response?.data ?? { error: e.message }) };
+}
 ```
 
 What the seeder does per product: derives a unique slug, checks SKU uniqueness, prices variations (`sale_price` + optional `date_on_sale_from/to` supported at both levels), rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant (never set a variant parent's price yourself — it's derived), sets `stock_status`, and maintains category/ribbon counts. Products default to `status: "publish"`; pass `"draft"` to review first. Other `commerce.Product` fields (`weight`, `dimensions`, `virtual`, `downloadable`, `downloads`, `meta_data`, …) pass through; unknown keys are rejected so typos surface instead of vanishing.
@@ -151,21 +367,23 @@ The response reports everything:
   "payment_methods": { "enabled": ["card"], "disabled": ["offline"] } }   // null when not passed
 ```
 
-**Images**: every product needs at least one, and the URL you seed is the URL the store serves — there are no placeholders to swap later. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. **Final means permanent and resolving**, and both fail silently later rather than at seed time, so check them now: an image tool that returns a *temporary or signed* URL (expiry params in the query string are the tell) must be re-hosted — download and `UploadFile` it for a stable public URL — and before seeding, spot-check that the URLs actually resolve (fetch one or two: HTTP 200, image content type). A dead or expiring URL seeds fine and then renders as a broken image or an eternal placeholder in the store. Image generation is usually the **slowest step of the whole install** — this is dependency edge #1 of §0: kick all product images off first, do the rest (router mount, payment file, storefront pages) while they render, and seed the moment the URLs are back — then keep writing UI through the seed call too. If an image isn't ready at seed time you *may* seed without it and set it afterwards through the admin API (never seed a dead path and compensate in the frontend) — but that is **an open debt, not a resolution**: track every product seeded imageless and close it before handover. The [Done when](#4-done-when) checklist fails while any product shows a placeholder for lack of a real image.
+**Images**: every product needs at least one, and the URL you seed is the URL the store serves — there are no placeholders to swap later. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. **Final means permanent and resolving**, and both fail silently later rather than at seed time, so check them now: an image tool that returns a *temporary or signed* URL (expiry params in the query string are the tell) must be re-hosted — download and `UploadFile` it for a stable public URL — and before seeding, spot-check that the URLs actually resolve (fetch one or two: HTTP 200, image content type). A dead or expiring URL seeds fine and then renders as a broken image or an eternal placeholder in the store. Image generation is usually the **slowest step of the whole install** — this is dependency edge #1 of §0: kick all product images off first, do the rest (router mount, payment file, storefront pages) while they render, and seed the moment the URLs are back. If an image isn't ready at seed time you *may* seed without it and set it afterwards through the admin API (never seed a dead path and compensate in the frontend) — but that is **an open debt, not a resolution**: track every product seeded imageless and close it before handover.
 
 A successful response means the data is in — the catalog and settings are live exactly as reported. Write any remaining store-specific settings into `commerce.StoreSettings` (direct CRUD, one record per `group_id` — weight/dimension units are the usual ones; patch `values`, don't replace groups you weren't asked about).
 
-### 2.2 Payments — one file, any provider (Stripe as the reference)
+---
+
+## 4. Payments — one file, any provider (Stripe as the reference)
 
 The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions.
 
-**Whether the store needs online payments — and when in the install to wire them — is your decision, not a fixed step.** Nothing else on this page depends on this section: the admin, the seed and the entire storefront work with no provider wired (until then the card option answers `503 no_card_payment_provider` at checkout, and §3.4 shows the graceful fallback). Decide from what the user is actually building:
+**Whether the store needs online payments — and when in the install to wire them — is your decision, not a fixed step.** Nothing else on this page depends on this section: the admin, the seed and the entire storefront work with no provider wired (until then the card option answers `503 no_card_payment_provider` at checkout, and §2.4 shows the graceful fallback). Decide from what the user is actually building:
 
 - **The store doesn't take online payments** (cash on delivery, bank transfer, invoicing, pickup, quote-based…) → seed `payment_methods` without `"card"` and skip the rest of this section — the manual gateways are complete as shipped.
 - **The store does take online payments** → this section is the how-to (Stripe below is the reference), but *you* pick the point in the flow. The wiring is self-contained — the file paste and webhook registration touch nothing the storefront depends on, so it **runs in parallel with the storefront build** (§0) rather than before or after it. The one part that involves the user is the provider secret key: ask when it makes sense in the conversation, and keep building while the answer is pending — never stall the install on it. What's non-negotiable is only the end state: don't hand over a finished store with the card gateway enabled but no provider behind it (wire one, or disable the gateway).
 - **Unclear from the request** → build everything else first and raise payments with the user at the end, or ask.
 
-Which methods the store offers is **seed data**: pass `payment_methods` to `commerce/seed-store` (§2) — e.g. `["card"]` for a card-only store — instead of ever editing `commerce.PaymentGateway` records yourself.
+Which methods the store offers is **seed data**: pass `payment_methods` to `commerce/seed-store` (§3) — e.g. `["card"]` for a card-only store — instead of ever editing `commerce.PaymentGateway` records yourself.
 
 The **Credit card** option needs a payment provider — **any** provider works (Stripe, PayPal, Adyen, a local PSP…), and whichever one it is, wiring it touches exactly **one file**: `base44/shared/commerce/card-payment.ts` — four functions, each backing a premade flow. `commerce/payment-webhook` (the function) is **premade — do not edit it**: it calls this file's `parseWebhook` to validate each event and **never trusts an event body on its own** — an unverified event only *names* an order, and whether money arrived is asked of the provider itself through `checkCardPaymentPaid`, so a forged webhook call can never mark an order paid and **no signing secret is needed**. Until the file is implemented the card option answers `503 no_card_payment_provider` at checkout (or switch it off in Settings → Payments).
 
@@ -292,209 +510,15 @@ That's it — checkout redirect, `/order-received` confirmation, the webhook, th
 
 ---
 
-## 3. Storefront quick start — logic only
-
-No visitor UI ships; the storefront **API** is complete. The four chunks below are the whole happy path — product list → product page → cart → checkout — showing what to call, what comes back, and what to carry into the next step. **None of it waits on the seed**: every shape you build against is documented right here, so write these components while `seed-store` and image generation are still running (§0) — live data is only needed to verify the finished pages. Open [`docs/api-storefront.md`](./docs/api-storefront.md) only for what's beyond them (attribute/price filters, reviews, customer accounts, refunds), and [`references/product-render.md`](./references/product-render.md) for which fields belong in which view.
-
-Build on the **shipped API client** — create it once and import that instance everywhere (wrapping it in a React context is fine; never a second copy):
+## 5. Done when
 
-```js
-// src/lib/storefront.js
-import { createStorefront } from "@/commerce/utils";
-import { base44 } from "@/api/base44Client";
-export const store = createStorefront(base44);
-```
-
-The client owns the two things hand-rolled storefronts keep getting wrong, so **don't reimplement either**: the **`cart_token` lifecycle** (sent with every cart/checkout call, re-persisted from every response — a stale token silently starts a fresh cart; rolling 48 h expiry; cleared when checkout consumes the cart) and the **store-info cache** (`payment_gateways`, currency, countries live **only** on `get-store-info` — the cart view never carries them). For anything beyond its methods, `store.inv(fn, payload)` unwraps the `{ success, data }` envelope (`res.data.data`).
-
-**What each method resolves to** — the client already unwraps every envelope, so take these shapes at face value (no `.data`, and no `.categories` on a list result):
-
-| Method | Resolves to |
-|---|---|
-| `store.getStoreInfo()` | `{ settings, payment_gateways, countries, currencies }` — cached; the **only** source of `payment_gateways` |
-| `store.listProducts(params)` | `{ products, page, per_page, has_next }` — a page object; the array is `products` |
-| `store.getProduct(slug \| { id })` | `{ product, variations, categories, ribbons, reviews }` |
-| `store.listCategories()` | an **array** of root categories, subcategories nested under `children` |
-| `store.listRibbons()` | an **array** of `{ id, name, count }` |
-| `store.getCart()` and every cart mutation | the full cart view (`getCart()` alone may resolve to `null` — no cart yet); `cart.items[n].attributes` is an **array** of `{ name, option }`, never a map |
-| `store.placeOrder(details)` | `{ order_id, order_number, order_key, status, totals, order, payment_instructions, payment }` |
-| `store.completeReturn()` | `{ state, order, payment_link, payment_instructions }` |
-
-Keep the UI in **small focused components** (~2–4K characters each — product card, gallery, cart panel, address step, payment step…), not monolithic page files: smaller files are faster to emit, review and fix.
-
-### 3.1 Product list
-
-```js
-const info = await store.getStoreInfo();   // cached — call it wherever needed
-// info.settings → { store_name, currency, weight_unit, … } — format money with
-// Intl.NumberFormat(undefined, { style: "currency", currency: info.settings.currency })
-// info.payment_gateways → [{ slug, title, description, online }] — you'll need this at checkout;
-//   this call is its ONLY source (it is never on the cart view)
-// info.countries / info.currencies → static tables for address forms and money display
-
-const { products, page, per_page, has_next } = await store.listProducts({
-  page: 1, per_page: 12,           // optional: search, category_id, ribbon_id, featured, on_sale,
-  sort: "-created_date",           //   min_price, max_price, in_stock_only
-});                                // sort: -created_date | name | price | -price | popularity | rating
-```
-
-Each row is a full product record — for a card use `name`, `images[0]?.src` (**may be empty — render a placeholder, never a broken `<img>`**), `price`, `regular_price`, `on_sale` (sale badge), `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `store.listCategories()` — an **array** of root categories with subcategories nested under `children` (map over it directly; there is no `{ categories }` wrapper on the result). That is the whole card — no other call or reference needed for the list view.
-
-**Carry forward:** each card links to the product page by **`slug`**.
-
-### 3.2 Product page — variant selection included
-
-```js
-const { product, variations, categories, ribbons, reviews } =
-  await store.getProduct(slug);   // or store.getProduct({ id })
-
-// One selector PER product.attributes[] entry — never a flat list of variations.
-import { defaultSelection, selectOption, resolveSelection } from "@/commerce/utils";
-
-let selection = defaultSelection(product, variations);        // merchant defaults + single-option axes
-// on user pick: selection = selectOption(product, variations, selection, axisKey, option);
-
-const view = resolveSelection(product, variations, selection);
-// view.axes         → [{ key, name, options }] — render one control each
-// view.availability → { [axisKey]: { [option]: "available" | "out_of_stock" | "unavailable" } }
-// view.display      → { price, regular_price, on_sale, sku, stock_status, image, … } for the selection
-//                     ⚠ display.image is an OBJECT — { src, name, alt } | null. Render
-//                     <img src={view.display.image?.src} alt={view.display.image?.alt}>.
-//                     Passing the object itself as src fails the load and your fallback
-//                     shows a placeholder for every product — with the real image sitting
-//                     one `.src` away. Same shape everywhere: product.images[n].src too.
-// view.purchasable  → gate the Add-to-cart button on this
-// view.addToCart    → { product_id, variation_id } — null until the selection resolves
-```
-
-Add to cart — the cart bootstraps itself (a missing, stale or expired token starts a fresh one) and the client does all the token bookkeeping:
-
-```js
-const cart = await store.addItem({ ...view.addToCart, quantity: 1 });
-```
-
-A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call.
-
-**What the page renders — all from this one `get-product` call, no extra reads:** a gallery from `product.images` (`view.display.image` is the variant-selected one; placeholder **only** when the product truly has no images — every image is an `{ src, alt }` object, so render `img.src`/`img.alt`, never the object itself), name, price from `view.display` (`price`/`regular_price`/`on_sale` → sale badge), one selector per axis, stock state, `short_description` then `description` (**both HTML — render as rich text, don't escape or truncate away the markup**), SKU, `categories` as a breadcrumb, `ribbons` as light labels near the metadata, the `reviews` block (`{ items, has_next, average_rating, rating_count }`), and the `upsells`/`cross_sells` summaries. Descriptive properties (Material, Care…) live in `product.meta_data` — render them as a spec table; they are not attributes and not ribbons. That is the complete product page — [`references/storefront-product-page.md`](./references/storefront-product-page.md) and [`references/product-render.md`](./references/product-render.md) are only for edge cases and for adding fields to the *listing* call.
-
-**Carry forward:** nothing — the client keeps the `cart_token`.
-
-### 3.3 Cart
-
-**Every cart action returns the same full priced view**, so re-render from whatever the last call returned — no separate refresh:
-
-```js
-let cart = await store.getCart();   // null → no cart yet (an expired token self-clears)
-// cart.items  → [{ item_key, name, image, quantity, price, subtotal, total, attributes, purchasable }]
-//               item.attributes is an ARRAY of { name, option } — render "Size: 42" by
-//               mapping it (attributes.map(a => `${a.name}: ${a.option}`)); it is never a map
-// cart.totals → { subtotal, discount_total, shipping_total, cart_tax, total_tax, total, … }
-// cart.coupon_notices / cart.removed_items → tell the customer what auto-dropped and why
-//
-// NOT in the cart view: payment_gateways (store.getStoreInfo() ONLY — cart.payment_gateways
-// is always undefined), the product catalog (listProducts/getProduct), countries/currencies
-// (getStoreInfo). Never dot into the cart for any of those.
-
-cart = await store.updateItem(item_key, quantity);   // ≤0 removes
-cart = await store.removeItem(item_key);
-cart = await store.applyCoupon(code);
-```
-
-Shipping is chosen **on the cart, before place-order** — this is the step storefronts most often skip, and `place-order` refuses without it (`400 shipping_method_required`). **Call `set-shipping-address` the moment the customer provides an address** — every shipping option and cost is recalculated by that call (never reuse a list fetched earlier), and an address the store doesn't ship to **fails right there** with `400 shipping_not_available`, so the address form is where you surface it:
-
-```js
-// as soon as the address is entered — this is what (re)calculates shipping options + cost
-cart = await store.setShippingAddress({ country, state, postcode, city });
-// 400 shipping_not_available → show it on the address form
-// cart.chosen_shipping_method is the rate's ID (a string) — to display it, look
-// it up: cart.available_shipping_methods.find(m => m.id === cart.chosen_shipping_method)
-// and render that entry's title + cost. Never render the id itself.
-switch (cart.shipping_status) {
-  case "auto_selected": break;          // only ONE option existed — the backend already applied it;
-                                        // no picker needed, just display the looked-up title + cost
-  case "chosen": break;                 // customer's earlier choice still valid
-  case "choice_required":               // several options — MUST render cart.available_shipping_methods
-    // [{ id, title, cost }] as a picker, then send the customer's pick:
-    cart = await store.chooseShippingMethod(picked.id);   // the entry's id, not its method_id type
-    break;
-  case "missing_address": break;        // several zones, no address yet — shipping cost is NOT
-                                        // calculated; collect the address and call setShippingAddress
-  case "not_needed": break;             // fully virtual cart
-}
-```
-
-A store with exactly **one shipping zone** shows its options (and, auto-selected, the cost) on the cart even before an address is set — the options are the same everywhere. Several zones report `missing_address` until the address resolves one.
-
-**Carry forward:** the **`cart_token`** (address and method choice live on the cart).
-
-### 3.4 Checkout & order-received
-
-The checkout page renders **two sets of options that are store data, never hardcoded**: the shipping methods (already resolved on the cart in step 3 — `place-order` refuses with `400 shipping_method_required` until `shipping_status` is `chosen`/`auto_selected`/`not_needed`) and the payment methods — every gateway the admin has **enabled**:
-
-```js
-// card payments = ONE file to implement — §2.2 above has the complete
-// Stripe implementation to paste; no other reading needed
-const { payment_gateways: gateways } = await store.getStoreInfo();
-// ⚠ get-store-info is the ONLY source of payment_gateways — the cart view does
-// NOT include them (cart.payment_gateways is always undefined, which reads as
-// "no methods" and dead-disables the place-order button). If a context caches
-// store-info, read it from there — never from the cart object.
-// gateways → [{ slug, title, description, online }] — admin-owned data
-// several → render a picker using the admin's title/description as the labels
-// exactly ONE → no picker: use it directly, but still show its title so the customer knows how they'll pay
-// none → checkout cannot complete — say so instead of rendering a dead button
-const payment_method = gateways.length === 1 ? gateways[0].slug : picked.slug;  // never a hardcoded "card"
-```
-
-While the store has no card provider implemented, picking the card gateway fails `place-order` with `503 no_card_payment_provider` — tell the customer card payment is temporarily unavailable and offer the other methods.
-
-`online: true` marks the card/redirect gateway; every other gateway is manual reconciliation. Then one call places the order:
-
-```js
-const res = await store.placeOrder({
-  payment_method,                                     // the slug chosen above
-  billing: { first_name, last_name, address_1, city, country, email },   // the required set; phone, state, postcode optional
-  // shipping: { … } if it differs from billing; customer_note?
-});                                // token + return_url handled by the client; the cart is consumed
-// res → { order_id, order_number, order_key, status, totals, order,
-//         payment_instructions,   // manual gateways: { description, account_details } — render them
-//         payment }               // card: { status: "requires_payment", checkout_url, … } | null
-
-if (res.payment?.status === "requires_payment") window.location.href = res.payment.checkout_url;
-else showConfirmation(res);        // manual order placed — show payment_instructions
-```
-
-Every payment link returns to **`/order-received`** — the page from §1 step 3. It is one call, idempotent, safe on every visit:
-
-```js
-// GET /order-received?order_id=…&order_key=…&payment=success|cancel
-const { state, order, payment_link, payment_instructions } = await store.completeReturn();
-// (reads the URL params itself; ?payment= is only a hint — the server verifies with the provider)
-// state === "paid"      → thank-you + order summary (order is now marked paid)
-// state === "unpaid"    → card order: offer payment_link.url to pay now;
-//                         manual order: render payment_instructions ({ description, account_details })
-// state === "cancelled" → payment was cancelled — offer payment_link.url or support
-```
-
-Two shapes to get right when rendering: **`order` carries flat totals** — `order.total`, `order.shipping_total`, `order.total_tax` — there is **no `order.totals` object** (that nested shape belongs to the cart view and the place-order response's top-level `totals`); and `payment_link` is `{ url, reference } | null` (card orders only).
-
-**Carry forward:** `order_id` + `order_key` are the guest's proof of ownership — `commerce/storefront-account` `get-order` with both returns the order for a tracking page (signed-in customers get `my-orders` with no key).
-
----
-
-## 4. Done when
-
-Post-installation is complete when every line below holds — check against this list instead of re-reading docs. **Do not validate the admin part at all**: everything under `/store-admin` ships finished and already tested — there is nothing there for you to verify.
+Post-installation is complete when every line below holds. **Do not validate the admin part at all**: everything under `/store-admin` ships finished and already tested — there is nothing there for you to verify.
 
 - [ ] `/store-admin/*` mounted behind the shipped `AuthGuard`; `/` routes somewhere real (storefront or a redirect).
 - [ ] `commerce/seed-store` ran once and reported the catalog — real products, final image URLs; if the user restricted payment methods, `payment_methods` was passed in that same call.
-- [ ] Product list renders from `store.listProducts` (cards: image/placeholder, name, price or "From …", sale badge, stars, ribbons) and links by `slug`.
-- [ ] Product page renders from `store.getProduct` with one selector per attribute, resolving to `view.addToCart`.
-- [ ] **Real images actually render** — no placeholder anywhere except for a product genuinely without images: every image rendered via `.src` (`images[n].src`, `view.display.image?.src` — they are objects, not URL strings), every seeded URL permanent and resolving, and any product deliberately seeded imageless (§2.1) since given its image.
-- [ ] The storefront talks to the API through **one `createStorefront` instance** — no hand-rolled `cart_token` handling, and `payment_gateways` read from `getStoreInfo()` only, never off a cart.
-- [ ] `/order-received` calls `completeReturn` and renders `paid` / `unpaid` / `cancelled`.
-- [ ] Online payments **decided, not defaulted** (§2.2): if the store takes card payments, `card-payment.ts` implemented (Stripe: paste §2.2), `STRIPE_SECRET_KEY` secret set and webhook endpoint registered — wired at whatever point in the flow you judged right; if it doesn't (or not yet), the card gateway disabled (seed `payment_methods` without `"card"`). Either way, checkout never offers a card option with no provider behind it.
-
-## 5. Next
+- [ ] **Catalog pages and a checkout exist** — the catalog UI in whatever form fits the store (a product list, product pages, or both — one can be enough), a cart step only if the store wants one (§2.3), and the checkout built on `useCheckout` with `/order-received` rendering `useOrderReturn` (§2.4).
+- [ ] **One `<StorefrontProvider>`** above every storefront route — no second client, no hand-rolled `cart_token` handling, payment gateways read from `useStoreInfo()` only (never off a cart), and cart state everywhere through `useCart()`.
+
+## 6. Next
 
 Continue with the commerce skill — [`.agents/skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, deeper storefront features ([`references/product-render.md`](./references/product-render.md) for what to render per view, [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variant edge cases, [`references/reviews.md`](./references/reviews.md) for the ready-made reviews backend), payment provider wiring, scheduled maintenance, emails, webhooks, and operational limits.