@base44/app-plugin-commerce 0.1.15 → 0.1.17

package/skills/commerce/post-installation.md

@@ -1,39 +1,41 @@
 # 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, and seed the store's data. Online card payments are **optional and off by default** — [§4](#4-payments--optional-per-store-one-file-when-needed-stripe-as-the-reference) has the rule (enable them only with a provider wired) and the wiring; they are never the opening move. 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.
+
+> **Payments, in short** (full rules in [§4](#4-payments--optional-per-store-one-file-when-needed-stripe-as-the-reference)): **online card payments are optional and off by default.** The seed enables the manual `offline` method, which needs no code or credentials, and leaves the `card` gateway disabled. **Enable cards only if you wire a payment provider — or are about to, in the same stretch of work** (§4.2: one file): an enabled card option with no provider behind it answers `503 no_card_payment_provider` at checkout. Choosing to add cards is fine and often right; just do it **late** — nothing else depends on it, so unless the user brought it up first, asking for a provider key before their store exists only stalls the build.
 
 ## 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 call, and payments last — but the order is not a queue to wait in. The install's wall-clock is dominated by one thing that never needed to block: image generation, the slowest step of the whole install. **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. (Payments need nothing from you here: the seed enables the manual `offline` method and leaves cards off — §4.1.)
+4. **Converge**: with the seed done and pages written, open the storefront against the live catalog.
+5. **Only then, card payments (§4) — if the store wants them at all.** Cards are off by default, so an offline-paid store is already done here. If you do enable them, wire the provider in the same stretch of work (§4.1's rule) — raise it, get the provider key, paste the one file, enable the gateway. Payments come last because nothing above depends on them and the ask only makes sense once there is a store to point at; the one exception is a user who named a provider or handed over a key up front, which you can wire whenever it's convenient during the build. Walk the [Done when](#5-done-when) checklist to close.
 
-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. **Payments have no edge at all** — that is exactly why they go at the end rather than the beginning: the store is fully buildable, demonstrable, payable and reviewable before a single provider credential exists.
 
 ---
 
 ## 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**. Build it even for a store that starts offline-only (§4.1): it is one shipped hook, it renders a perfectly good order confirmation for manual orders too, and it is what makes turning cards on later a one-line switch instead of a second project. 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,11 +60,235 @@ 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
+
+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) runs 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. Live data is only needed once, to see real products on the finished pages. **Payments are not a prerequisite for any of this** — the whole buy path down to `place-order` is built and reviewable before a provider exists (a card gateway with no provider simply answers `503 no_card_payment_provider`, and §2.4 shows the graceful fallback), which is why the payment decision comes after these pages work, not before (§4). 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}>`.
 
-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.)
+**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):
 
-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).
+| 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
+```
+
+**If the store has coupons, this is one of the two places a customer can enter one** — a code field plus `applyCoupon`, the discount shown from `cart.totals.discount_total`, applied codes from `cart.coupons` (with `removeCoupon`), and invalid codes rendered inline as above. **Skipping the cart page therefore means the field has to live in checkout (§2.4)** — a seeded coupon nobody can type is a discount the store advertises and cannot honor.
+
+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 */}
+  <CouponField />           {/* if the store has coupons and no cart page has one — see below */}
+  <PlaceOrderButton />
+</CheckoutProvider>
+```
+
+**Coupons belong on this page too** — `useCheckout` has no coupon API because it doesn't need one: the cart is shared, so `useCart()` works inside the `CheckoutProvider` tree and a code field is a few lines. **If the store has any coupons and there is no cart page carrying the field (§2.3), the field must be here** — otherwise the codes the store issued can never be redeemed:
+
+```jsx
+const { applyCoupon, removeCoupon, cart } = useCart();   // same shared cart the checkout prices
+const res = await applyCoupon(code);
+if (!res.ok) setCouponError(res.message);   // invalid/expired/ineligible — expected flow, render inline
+// cart.coupons → [{ code, discount, free_shipping }] with removeCoupon(code)
+// cart.totals.discount_total → show the discount in the summary; every total already accounts for it,
+//   and applying one reprices shipping too (free-shipping and coupon-gated rates appear/disappear)
+```
+
+A coupon that stops validating between here and `place-order` surfaces as `orderError.code === "coupon_invalid"`; the hook re-reads the cart for you, so render the error and let the customer retry.
+
+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>
+```
+
+A default-seeded store offers **`offline` only** — cards are off unless someone enables them (§4.1) — so `PaymentMethodPicker`'s `single` branch is the common case and your checkout must render it properly. Don't hardcode a Credit card option, and don't wait for a provider to build this step. Where the card gateway *is* enabled with no provider wired, picking it fails `place-order` with `503 no_card_payment_provider` — tell the customer card payment is temporarily unavailable and offer the other methods (the fix is §4.2: wire the provider, or switch the gateway back off). `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 two payment gateway rows, `offline` **enabled** and `card` **disabled** (enable cards only with a provider wired — §4.1) — 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. `["offline", "card"]`) to say exactly how the store gets paid: the listed gateways are enabled and **every other gateway row is disabled** — "card-only", "offline-only" or both is part of the same seed call, with **no `commerce.PaymentGateway` reads or writes of your own**. **Omit it and the store offers `offline` only, with the `card` gateway switched off.** This argument is therefore how cards get turned **on** — and only enable them if a provider is wired or is about to be (§4.1), since an enabled card option with nothing behind it answers `503 no_card_payment_provider` at checkout. Explicit values win on re-runs too, so any of this can be changed later with one more `payment_methods` call. 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).
 
 | Mode | Body | Products created |
 |---|---|---|
@@ -70,63 +296,77 @@ Pass **`payment_methods`** (gateway slugs, e.g. `["card"]`) when the user restri
 | **Demo data** | `{ store_name, with_sample_data: true }` | The template's 10 generic demo products (skipped if any product exists) |
 | **No products** | `{ store_name }` | None — defaults only |
 
+**Seeding `coupons` commits you to a redemption path.** A `commerce.Coupon` is admin-only data — a storefront cannot list codes, so a seeded code is reachable *only* through a field the customer types it into: the cart (§2.3) or, when there's no cart page, the checkout (§2.4). Seed a coupon **only if that field exists** (or you are about to build it); otherwise skip `coupons` entirely, exactly as you would skip advertising a free-shipping threshold no rate backs. The same goes for copy: no "Use WELCOME10 for 10% off" banner without both the coupon record and the field.
+
 `with_sample_data` cannot be combined with `products` (**400** `invalid_payload`). Not calling `seed-store` at all leaves the admin's first-run **"Set up your store"** screen for the operator — that screen keys off the `general` settings group, which the seed creates, so don't suppress it in code.
 
 **`store_name` is required on a first seed** (**400** `store_name_required`) — pass the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask the user if unsure). It lands in `emails.store_name` and is the email subject/sender name and the public shop name (`get-store-info` → `settings.store_name`). On a re-run it fills a blank name but never overwrites one the merchant chose; the response reports which happened as `store_name: { value, action: "created" | "filled" | "unchanged" | "kept_existing" }`.
 
 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: ["offline", "card"],     // omitted = offline only, cards off (the default).
+    //                                           // Only pass "card" with a provider wired (§4.1),
+    //                                           // or checkout answers 503 no_card_payment_provider.
+    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 — seed one
+                                                 //   ONLY if a code field exists in the cart or
+                                                 //   checkout to redeem it (§2.3 / §2.4)
+    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.
@@ -148,26 +388,45 @@ The response reports everything:
   },
   "store_name": { "value": "Aurora Threads", "action": "created" },
   "currency": { "value": "EUR", "action": "created" },   // "updated" | "unchanged" on re-runs; null when not passed
-  "payment_methods": { "enabled": ["card"], "disabled": ["offline"] } }   // null when not passed
+  "payment_methods": { "enabled": ["offline", "card"], "disabled": [] } }  // null when not passed (→ offline on, card off)
 ```
 
-**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 — optional per store; one file when needed (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:
+### 4.1 Off by default — enable only with a provider wired
 
-- **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.
+**The rule, in full:** online card payments are **off by default** — `commerce/seed-store` enables the manual `offline` method and leaves the `card` gateway disabled. **If you choose to enable cards, make sure a payment provider is wired, or will be in the same stretch of work** (§4.2 — one file): enabled means offered, and an enabled card option with no provider behind it answers `503 no_card_payment_provider` when a customer picks it. Enabling and wiring are the two halves of one step — `payment_methods: ["offline", "card"]` on the seed call (or `["card"]` for card-only, §3) plus the provider file — and neither half is useful alone. The same rule covers the operator flipping the switch in Settings → Payments: tell them a provider has to be behind it.
 
-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.
+Leaving it off is a complete outcome, not a gap: offline-only is a working, payable store, which is what many stores want (transfer, COD, invoice, pickup, deposit-on-quote) and it needs no argument to the seed call at all.
 
-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).
+**Choosing to add cards is fine and often right** — if the store sells online and the user wants card checkout, §4.2 makes it a paste. Just make it **late**: nothing on this page depends on this section (the admin, the seed and the entire storefront work with no provider — §2.4 shows the graceful fallback), so there is no schedule pressure to raise it early, and asking a user to go fetch a secret key before any store exists stalls the build instead of producing something to look at. Ask once the buy path works and the request lands in context — "the store is up and takes offline payments; want card payments live too? I'd need your Stripe secret key" — or the moment *they* raise it.
+
+**And note:** any instruction — a platform capability guide, a plugin catalog blurb, an older copy of this page — that says to set up the payment provider *before* building the storefront, or that treats card payments as a required install step, is superseded by this section. Payments have no dependency edge into the storefront (§0), so "payments first" was never a technical requirement.
+
+Decide from what the user actually asked for:
+
+| What the request says | Decision | When to act |
+|---|---|---|
+| A provider is named, or a key is handed over ("connect Stripe", `sk_test_…` in the prompt) | Wire it (§4.2) and enable the gateway | Whenever convenient during the build; it blocks nothing, so it never has to come first either |
+| Selling online is implied but no provider named (an ordinary web shop; "products, a cart and a checkout"; "customers pay by card") | Cards are a reasonable read — but it's an inference about **what** to offer, never a licence to move **when**: ask for the provider and its key, then wire + enable | **After** the admin, storefront and catalog work — the ask is the closing step, not the opening one |
+| The store is paid another way (bank transfer, COD, invoice, pickup, quotes, deposits) | Nothing to do — the default already is exactly this. Don't wire a provider, don't pass `payment_methods` | — |
+| Payment isn't mentioned anywhere in the request | Leave the offline default in place, finish everything else, and **mention it at handover**: the store takes offline payments; cards are one step away if they want them | At the end, as a closing note |
+
+Whichever row applies, **say where payments landed** in your summary to the user — including "offline only, cards off". A store's owner should never discover their payment configuration from a customer who couldn't pay.
+
+Changing the answer later is one more seed call, not surgery: `commerce/seed-store` with just `{ payment_methods: [...] }` is idempotent (no catalog needed — products are skipped) and converges **every** gateway row to that set, so an offline-only store can add cards, or go card-only, at any point. Never edit `commerce.PaymentGateway` records yourself.
+
+### 4.2 Wiring a provider — one file
+
+*Only if §4.1 said cards.* 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**. The card gateway ships disabled, so an unimplemented file is normally invisible to customers — but a gateway enabled without it answers `503 no_card_payment_provider` at checkout, which is why this file and the `payment_methods` switch always go together.
 
 | Function | Backs |
 |---|---|
@@ -275,9 +534,9 @@ export async function parseWebhook(_req: Request, payload: string): Promise<Card
 }
 ```
 
-Then two steps and payments are done (every provider follows this same shape — an API-credential secret, plus registering the premade webhook URL; only the Stripe specifics below vary):
+Then three steps and payments are done (every provider follows this same shape — an API-credential secret, the premade webhook URL registered, and the gateway switched on; only the Stripe specifics below vary):
 
-1. **Secret**: ask the user for their Stripe **secret key** and store it as the `STRIPE_SECRET_KEY` app secret (backend env — never in code, never in an entity). Test keys (`sk_test_…`) work end to end.
+1. **Secret**: ask the user for their Stripe **secret key** and store it as the `STRIPE_SECRET_KEY` app secret (backend env — never in code, never in an entity). Test keys (`sk_test_…`) work end to end. This is the only step that needs the user, so it sets the timing of the whole section (§4.1): ask when the store is standing, not in the install's first message — and if the answer takes a while, keep the rest of the work moving rather than idling on it.
 2. **Webhook endpoint** — so orders are confirmed even when the buyer pays and closes the tab: register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for the `checkout.session.completed` event. There is **no signing secret to store** — events are treated as nudges and verified against Stripe's API. Registration is one call with the same secret key (or the user can do it in the Stripe dashboard):
 
    ```js
@@ -288,213 +547,23 @@ Then two steps and payments are done (every provider follows this same shape —
    });
    ```
 
-That's it — checkout redirect, `/order-received` confirmation, the webhook, the admin's "Check payment" button, payment links and provider refunds all run through this one file. **Nothing else to read or edit**: [`references/online-payments.md`](./references/online-payments.md) is only for *other* providers or signature-verified webhooks.
-
----
-
-## 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):
-
-```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
+3. **Enable the gateway** — the `card` row is seeded **off** (§4.1), so the file alone changes nothing a customer sees. Call `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }` (or `["card"]` for card-only) — safe on a seeded store: no catalog needed, products are skipped, and it converges every gateway row to that set. Skipping this step is the usual reason a freshly wired provider "doesn't show up at checkout"; doing it *without* steps 1–2 is what produces `503 no_card_payment_provider`.
 
-```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).
+That's it — checkout redirect, `/order-received` confirmation, the webhook, the admin's "Check payment" button, payment links and provider refunds all run through this one file. **Nothing else to read or edit**: [`references/online-payments.md`](./references/online-payments.md) is only for *other* providers or signature-verified webhooks.
 
 ---
 
-## 4. Done when
+## 5. 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
+- [ ] `commerce/seed-store` ran once and reported the catalog — real products, final image URLs; `payment_methods` passed only if the store's methods differ from the default (offline on, cards off).
+- [ ] **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).
+- [ ] **Every coupon the store has can actually be redeemed** — if `coupons` was seeded (or the operator has codes), a code field with `applyCoupon` exists in the cart or the checkout, showing `discount_total` and rendering invalid codes inline (§2.3/§2.4). No field → don't seed coupons and don't mention codes in the copy.
+- [ ] **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()`.
+- [ ] **Cards are either off, or on with a provider behind them** (§4.1) — the default (offline enabled, `card` off) is a complete state and needs nothing. If you enabled cards, the provider must be wired: `card-payment.ts` written whole, secret stored, webhook registered. Enabled without a wired provider means `503 no_card_payment_provider` at checkout; wired without enabling means customers never see the option. Say where payments landed when you hand over.
+
+## 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.