@base44/app-plugin-commerce 0.1.20 → 0.2.2

package/skills/commerce/install/02-storefront.md

@@ -0,0 +1,444 @@
+---
+stage: install/02
+read_when: "You are about to build storefront pages (product list/page, cart, checkout, order-received)."
+skip_when: "The storefront pages already render against live data and pass the checklist at the bottom of this file."
+forget_when: "The checklist at the bottom passes — every page renders against the seeded catalog and an offline order completes."
+carry_forward:
+  - "Payment gateways, currency and countries come from useStoreInfo() only — never off a cart (cart.payment_gateways is always undefined)."
+  - "A store with any coupons must have a coupon field (useCoupon) in the cart or the checkout, or its codes can never be redeemed."
+  - "/order-received is mandatory and renders useOrderReturn's states, including paymentInstructions — how a normal (offline) customer learns how to pay."
+  - "Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design."
+  - "Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations."
+---
+
+# 02 — Storefront
+
+One split decides everything here: **the logic is premade, the UI never is.**
+
+- **Logic — hooks, shipped.** Checkout repricing from the address, variant
+  resolution, cart state, coupon redemption, review policies, order-return
+  verification. Every store's version of these is functionally identical, and
+  hand-writing them is where storefront bugs cluster: **never re-implement what
+  a hook does.**
+- **UI — yours, always.** Every element, class, layout and word of copy on
+  every page. Nothing in `@/commerce/storefront` renders markup or carries CSS,
+  and this file deliberately doesn't hand you page bodies either — the design
+  is the part of the storefront only you can do, and it should be designed,
+  not assembled.
+
+Each hook returns a complete view-model — a `status` to branch on,
+ready-to-map arrays, handlers, error objects — and its **doc comment (JSDoc) is
+the API reference**: open the hook's file when you need exact shapes; don't
+guess fields. This file gives you the routing, each surface's hook, and the
+render rules that keep a store correct (marked ⚑ — these must survive whatever
+design you build).
+
+Where you get a **reference implementation** and where you get only the hook is
+deliberate: **cart, checkout and order-received** have reference code below —
+their wiring is dense enough that reading it is cheaper than deriving it, and
+they are conventions (a form, a receipt) where familiarity beats invention.
+The **identity surfaces** — home, collection, the card, the product page's
+layout — get hooks only, on purpose: reference markup there would make every
+store look the same, and their design is the work only you can do. Either way
+the hooks are high-level enough that a page is a handful of calls plus your
+markup — writing more code than the budgets at the bottom allow means you are
+re-deriving logic a hook already owns. Everything imports from
+`@/commerce/storefront`.
+
+## Setup — once
+
+```jsx
+import { StorefrontProvider } from "@/commerce/storefront";
+import { base44 } from "@/api/base44Client";
+
+<BrowserRouter>
+  <StorefrontProvider base44={base44}>     {/* wraps <Routes> — never a child of it */}
+    <Routes>                               {/* ONE <Routes> — merge new pages into the app's */}
+      <Route path="/" element={<Home />} />
+      <Route path="/product/:slug" element={<ProductPage />} />
+      <Route path="/bag" element={<Bag />} />
+      <Route path="/checkout" element={<Checkout />} />
+      <Route path="/order-received" element={<OrderReceived />} />
+      <Route path="/store-admin/*" element={<AdminApp />} />
+    </Routes>
+  </StorefrontProvider>
+</BrowserRouter>
+```
+
+The provider owns the shared client, the store-info cache and **one** shared
+cart, so a header badge, a drawer and the checkout render the same state. Never
+mount a second provider, and never touch the `cart_token` — the provider owns
+its whole lifecycle.
+
+> ⚠ **`<Routes>` accepts only `<Route>` children.** Nesting the provider inside
+> it — the natural reading of "wrap the storefront routes" — throws at render:
+> `Error: [StorefrontProvider] is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>`.
+> To scope the provider to storefront routes only, use a pathless **layout
+> route**, the one place a wrapper is legal:
+> ```jsx
+> <Route element={<StorefrontProvider base44={base44}><Outlet /></StorefrontProvider>}>
+>   <Route path="/" element={<Home />} />
+>   <Route path="/checkout" element={<Checkout />} />
+> </Route>
+> <Route path="/store-admin/*" element={<AdminApp />} />   {/* outside the provider */}
+> ```
+
+## Product list / collection
+
+`useProductList(params)` → `{ status, products, hasNext, next, refreshing,
+setParams, reload }`. ⚑ `status` is `"loading" | "ready" | "empty" | "error"`
+— branch on it, so a failed request renders as a failure instead of an empty
+grid. `setParams({ category_id, search, on_sale, min_price, in_stock_only })`
+resets to page 1 and keeps the current rows on screen (`refreshing`) while the
+page loads. `useCategories()` / `useRibbons()` → `{ items }` (arrays, children
+nested).
+
+Your card renders `name`, `images[0]?.src` (⚑ **images are `{src,name,alt}`
+objects and the array may be empty — render a placeholder, never a broken
+`<img>`**), `useProductPrice(row).label` (already "From €19.99" when the
+product sells variants — there is no product `type` flag), `on_sale`,
+`short_description`, `stock_status`, `average_rating`/`rating_count`,
+`ribbons`. Full field matrix:
+[`../references/catalog-rendering.md`](../references/catalog-rendering.md).
+
+**Rails** (featured row, "new in") are the same hook with a filter
+(`{ featured: true, per_page: 4 }`). ⚑ Any filter may legitimately match
+nothing — render *nothing* then, never a heading over an empty row. Upsells
+beside a product need no query: `p.upsells` / `p.crossSells` from `useProduct`.
+
+## Product page
+
+`useProduct(slug)` (or `{ id }`) owns fetch + variant selection + quantity +
+price, race-safe, selection mirrored to the URL. ⚑ `status: "not_found"` is a
+404 page, not a spinner. Destructure `{ product, view, price, categories }`
+and build your layout from:
+
+- **Price** — `price.label`, plus `price.compareAtLabel` (struck through) when
+  on sale. Never read `product.price` directly — the parent's price is a
+  rolled-up from-price.
+- **Gallery** — `useProductGallery(product, view)` → `{ hasImages, images,
+  active, activeIndex, setActiveIndex, next, prev }`. The active image already
+  follows the variant selection; `hasImages: false` means render your
+  placeholder.
+- **Variant selector** — `variantAxes(view, p.pick)` → one entry per axis:
+  `{ key, name, selectedOption, options: [{ value, selected, disabled,
+  outOfStock, pick }] }`. Map it to any control — buttons, swatches, a dropdown.
+  ⚑ **One control per axis, never a list of variations** (`Red / S`, `Red / M`,
+  … is n × m noise), and ⚑ **an unbuyable option renders `disabled`, never
+  hidden** (`outOfStock` stays visible, just marked) — a customer who can't see
+  that a size exists assumes the store doesn't carry it. `view.missingAxes`
+  names what's still unpicked. The shape of the map (the one interaction agents
+  reliably get wrong — the control itself is yours):
+
+  ```jsx
+  {variantAxes(view, p.pick).map((axis) => (
+    <fieldset key={axis.key}>{/* label from axis.name / axis.selectedOption */}
+      {axis.options.map((o) => (
+        <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}>
+          {o.value}{/* o.outOfStock → mark visibly, keep clickable-looking off */}
+        </button>
+      ))}
+    </fieldset>
+  ))}
+  ```
+- **Buy box** — `useAddToCartButton(p, { onAdded })` → `{ add, adding, error,
+  disabled, soldOut, needsSelection, quantity, increase, decrease, canIncrease,
+  canDecrease, showQuantity }`. It gates on purchasability, recovers from every
+  add failure and clamps quantity to stock and `sold_individually`. ⚑ Render
+  `error.message` inline; ⚑ `showQuantity: false` means no stepper (only 1 can
+  be bought); the button label should reflect `adding`/`soldOut`/
+  `needsSelection` — the words are yours.
+- **Description** — `product.description` is HTML; render as rich text
+  (`dangerouslySetInnerHTML`), `short_description` above it.
+- **Specs** — `productSpecs(product)` → `[{ key, label, value }]` from
+  `meta_data` (Material, Care). `[]` means no section at all.
+- **Breadcrumbs** — build from `categories`
+  (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons are
+  labels, not breadcrumbs.
+
+All optional — include what this store's products actually have.
+
+### Reviews — optional
+
+**Build reviews only if the store wants them** — because the brief asks, or the
+products are the kind customers rate. No review UI means no reviews, and that
+is a complete outcome. (If you skip them, don't put star ratings on cards
+either — an average of nothing is `0`.)
+
+`useProductReviews(product, { policy, user })` is the whole surface: `items`,
+paging (`hasNext`/`loadMore`), `averageRating`/`ratingCount`, and the submit
+form — `form`/`setField`/`fieldErrors` (matching the server's error codes),
+`valid`, `submit`, `requiresEmail` (false for a signed-in visitor),
+`reviewBlockedReason` (`"login_required"` / `"not_a_buyer"` under the stricter
+policies). ⚑ The confirmation copy is `message`, **taken from the server's
+response** — a store with auto-approval on says "published", not "awaiting
+approval", so render `message`, never your own text. `policy` is
+`"open" | "login" | "verified_buyers"`. Details beyond this:
+[`../references/reviews.md`](../references/reviews.md).
+
+## Cart / bag
+
+A cart *page* is optional: a store selling one made-to-order piece reads better
+as buy-now straight to checkout. The surface is four hooks: `useCart()`
+(`status`, `lines`, `notices`), `CartLine` (headless render-prop binding
+`useCartLine` per row — quantity stepping that clamps, coalesces and recovers),
+`useTotalsLines()`, `useCoupon()`.
+
+⚑ Rules: branch on `status`, never on emptiness while loading. Render
+`notices` — they say what auto-dropped from the cart and why. Render every
+non-`hidden` totals line rather than hardcoding subtotal/total — a hand-written
+summary omits discount and tax, then stops adding up the day a coupon or a tax
+rate exists. **A store with any coupons must have a coupon field** (here or in
+the checkout): coupons are admin-only data, redeemable only through a field the
+customer types into — if no field exists anywhere, don't seed coupons and don't
+write "use WELCOME10" in the copy.
+
+**Reference implementation** — read once for the wiring, then write your own
+page: the structure below is correct, the presentation is deliberately absent.
+Restyle, rearrange, split into your own components; the ⚑ rules are the part
+that must survive.
+
+```jsx
+function Bag() {
+  const { status, lines, notices } = useCart();
+  const totals = useTotalsLines();
+  const formatMoney = useFormatMoney();
+  if (status === "loading") return /* your loading state */;
+  if (status === "empty")   return /* your empty-bag state, linking back to the catalog */;
+  return (
+    <>
+      {notices.map((n, i) => <p key={i} role="status">{n.message}</p>)}
+      {lines.map((line) => (
+        <CartLine key={line.item_key} line={line}>
+          {(l) => (   /* line: name, attributesLabel, image, total — l: the controls */
+            <li>
+              {line.name} {line.attributesLabel}
+              <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+              {l.quantity}
+              <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
+              <button onClick={l.remove}>Remove</button>
+              {formatMoney(line.total)}
+              {l.error && <p role="alert">{l.error.message}</p>}
+            </li>
+          )}
+        </CartLine>
+      ))}
+      <CouponField />   {/* useCoupon: code/setCode, apply, applying, error, applied[] + remove */}
+      {totals.filter((l) => !l.hidden).map((l) => (
+        <div key={l.key}>{l.label} {l.formatted}</div>   /* l.emphasis → the total row */
+      ))}
+      <Link to="/checkout">Checkout</Link>
+    </>
+  );
+}
+```
+
+No shipping estimator here — checkout reprices shipping and tax from the
+address.
+
+## Checkout
+
+The state machine is `useCheckout`, shared across the page's regions by
+`CheckoutProvider` + `useCheckoutContext()`. It reprices shipping/tax from the
+address automatically (debounced, never on a half-typed address), derives the
+shipping and payment choices, gates the button (`canPlaceOrder` +
+`useCheckoutBlockers()` in words), and `placeOrder()` handles **both**
+navigations — online gateway → provider redirect, everything else →
+`/order-received`. The address form comes from `useAddressForm(which)` as a
+field spec (`state` collected, country options never null); the two
+store-data choices come through the headless `ShippingMethodPicker` /
+`PaymentMethodPicker`, whose render props enumerate every branch.
+
+⚑ Rules: handle every picker branch (they exist because every one occurs in a
+normal store); a single shipping or payment option still *shows* what it is —
+never a picker of one, never "nothing selected"; zero gateways → say checkout
+is unavailable instead of a dead button; keep each field's `autoComplete` (the
+spec provides it) and render `f.error` — "we don't ship there" arrives on the
+country field; show `orderError.message` and the blockers so the gate explains
+itself. ⚑ Payment methods, currency and countries come from `useStoreInfo()`
+only — `cart.payment_gateways` is always `undefined`, and a default store
+offers `offline` only ([`./03-data.md`](./03-data.md)).
+
+**Reference implementation** — the densest wiring in the storefront; read it,
+then build yours around it. Structure correct, presentation absent.
+
+```jsx
+function Checkout() {   // hooks read the context BELOW the provider
+  return <CheckoutProvider><CheckoutForm /></CheckoutProvider>;
+}
+
+function CheckoutForm() {
+  const { status } = useCart();
+  const checkout = useCheckoutContext();
+  const blockers = useCheckoutBlockers();
+  const formatMoney = useFormatMoney();
+  if (status === "loading") return /* loading */;
+  if (status === "empty")   return /* "your bag is empty" — a checkout with nothing says so */;
+  return (
+    <>
+      <AddressFields which="billing" />
+      <label>
+        <input type="checkbox" checked={checkout.shipToDifferent}
+               onChange={(e) => checkout.setShipToDifferent(e.target.checked)} />
+        Deliver to a different address
+      </label>
+      {checkout.shipToDifferent && <AddressFields which="shipping" />}
+
+      <ShippingMethodPicker>
+        {({ status, methods, chosen, choose, mustChoose, syncing }) => (
+          <fieldset>{/* syncing → subtle busy state; renders null for a virtual cart */}
+            {status === "missing_address" && <p>Delivery options appear once your address is entered.</p>}
+            {status === "none_available"  && <p role="alert">We don't deliver to that address yet.</p>}
+            {mustChoose && methods.map((m) => (
+              <label key={m.id}>
+                <input type="radio" checked={chosen?.id === m.id} onChange={() => choose(m.id)} />
+                {m.title} {formatMoney(m.cost)}
+              </label>
+            ))}
+            {!mustChoose && chosen && <p>{chosen.title} {formatMoney(chosen.cost)}</p>}
+          </fieldset>
+        )}
+      </ShippingMethodPicker>
+
+      <PaymentMethodPicker>
+        {({ gateways, value, select, selected, single }) => (
+          <fieldset>
+            {gateways.length === 0 && <p role="alert">No payment method is available right now.</p>}
+            {!single && gateways.map((g) => (
+              <label key={g.slug}>
+                <input type="radio" checked={value === g.slug} onChange={() => select(g.slug)} />
+                {g.title} {g.description}
+              </label>
+            ))}
+            {single && selected && <p>{selected.title}</p>}
+          </fieldset>
+        )}
+      </PaymentMethodPicker>
+
+      {/* summary: coupon field (if not in the cart) + useTotalsLines(), as in the cart page */}
+
+      <button disabled={!checkout.canPlaceOrder || checkout.placing} onClick={() => checkout.placeOrder()}>
+        {checkout.placing ? "Placing your order…" : "Place order"}
+      </button>
+      {checkout.orderError && <p role="alert">{checkout.orderError.message}</p>}
+      {!checkout.canPlaceOrder && blockers.map((b) => <p key={b.code}>{b.message}</p>)}
+    </>
+  );
+}
+
+function AddressFields({ which }) {
+  const { fields, set, countriesLoading } = useAddressForm(which);
+  return fields.map((f) => (
+    <label key={f.key}>
+      {f.label}{f.required && " *"}
+      {f.type === "select" ? (
+        <select value={f.value} onChange={(e) => set(f.key, e.target.value)} autoComplete={f.autoComplete}>
+          <option value="">{f.key === "country" && countriesLoading ? "Loading…" : `Select ${f.label}`}</option>
+          {f.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+        </select>
+      ) : (
+        <input type={f.type} value={f.value} required={f.required}
+               onChange={(e) => set(f.key, e.target.value)} autoComplete={f.autoComplete} />
+      )}
+      {f.error && <span role="alert">{f.error}</span>}
+    </label>
+  ));
+}
+```
+
+## Order received
+
+**Mandatory route** — every payment link returns here, and confirming is what
+marks a card order paid. `useOrderReturn()` is the whole page's logic: it reads
+`order_id`/`order_key` from the URL, verifies with the provider (idempotent),
+and marks the page noindex itself.
+
+⚑ Rules: render all five states — never a blank page while `"loading"`, and a
+retry via `reload()` on `"error"`. ⚑ **Never drop `paymentInstructions`**: a
+manual/offline order settles outside the store, so these ARE how the store's
+default customer learns how to pay — render them whenever present, on any
+state. ⚑ An order's totals are **flat** — `order.total`; there is no
+`order.totals` (use `useTotalsLines(order)`).
+
+**Reference implementation** — a receipt is a convention, not an identity
+surface: take this structure, restyle it to the store, keep every branch.
+
+```jsx
+function OrderReceived() {
+  const { status, order, lines, paymentLink, paymentInstructions, error, reload } = useOrderReturn();
+  const totals = useTotalsLines(order);
+  const formatMoney = useFormatMoney();
+  if (status === "loading") return /* confirming copy */;
+  if (status === "error")   return <><p role="alert">{error.message}</p>
+                                     <button onClick={() => reload()}>Try again</button></>;
+  return (
+    <>
+      {status === "paid"      && /* thank-you heading */}
+      {status === "unpaid"    && <>{/* awaiting-payment heading */}
+                                   {paymentLink?.url && <a href={paymentLink.url}>Pay now</a>}</>}
+      {status === "cancelled" && <>{/* payment-cancelled heading */}
+                                   {paymentLink?.url && <a href={paymentLink.url}>Try payment again</a>}</>}
+      {order?.order_number && <p>Order {order.order_number}</p>}
+      {paymentInstructions && (
+        <section>{/* "How to pay" — the offline customer's next step */}
+          {paymentInstructions.description && <p>{paymentInstructions.description}</p>}
+          {paymentInstructions.account_details && Object.entries(paymentInstructions.account_details)
+            .map(([k, v]) => <p key={k}>{k.replace(/_/g, " ")}: {String(v)}</p>)}
+        </section>
+      )}
+      {lines.map((l, i) => <p key={i}>{l.name} {l.attributesLabel} × {l.quantity} — {formatMoney(l.total)}</p>)}
+      {totals.filter((t) => !t.hidden).map((t) => <p key={t.key}>{t.label} {t.formatted}</p>)}
+    </>
+  );
+}
+```
+
+## SEO — one line per page type
+
+```jsx
+useStorefrontSeo(productSeo(p.product, p.view, { storeName, currency }));  // product page
+useStorefrontSeo(collectionSeo({ title, products: list.products }));      // collection / home
+// order-received is already noindex via useOrderReturn
+```
+
+It is a hook — call it above the page's early returns (the builders tolerate a
+null product).
+
+## Per-page output budgets
+
+| Page | budget (chars) | rationale |
+|---|---|---|
+| Checkout | ≤ 5K | your markup over the reference above — the logic is all hook calls |
+| Cart / bag | ≤ 3K | `useCart` + `CartLine` rows + totals + coupon + empty state |
+| Order-received | ≤ 2.5K | five states + payment instructions + summary |
+| Product page | ≤ 5K | your layout and type around `useProduct`, `variantAxes`, `useAddToCartButton`, the gallery |
+| Collection | ≤ 3K | `useProductList` + custom card + pagination controls |
+| Home | ≤ 5K | pure identity — hero/editorial earn their chars |
+| Any single component file | ≤ 4K, hard ceiling 8K | Base1 evidence: decode is 34% of wall; a 12K file is a 45s write batch |
+
+These budgets assume the hooks carry the logic and your markup carries only the
+design. Over budget ⇒ you are re-implementing something a hook does — an
+address spec, a quantity clamp, totals math, variant resolution, add-to-cart
+error recovery. Go back to the hook and delete your version.
+
+## Done — forget this file
+
+- [ ] Catalog UI exists in whatever form fits the store (list, product pages, or both), plus a checkout, plus `/order-received`.
+- [ ] **One** `<StorefrontProvider>` above every storefront route, wrapping `<Routes>` (or a layout route's `<Outlet/>`); one client, no hand-rolled `cart_token`.
+- [ ] Pages branch on `status`; no page maps a possibly-null list or shows an empty state while loading.
+- [ ] Gateways/currency/countries read from `useStoreInfo()` only.
+- [ ] If the store has coupons, a coupon field (`useCoupon`) exists in the cart or the checkout.
+- [ ] `/order-received` renders `useOrderReturn`'s states **including `paymentInstructions`**.
+- [ ] Variant options render one control per axis; unbuyable options are disabled, not hidden.
+- [ ] No hook logic was re-implemented by hand (address fields, quantity clamps, totals rows, shipping/payment branching).
+- [ ] The storefront looks designed — the reference implementations above were adapted into this store's design, not shipped bare.
+- [ ] Every page is within its budget above.
+- [ ] A real purchase completes in the preview — pick a variant, add it, check out, place an offline order, land on `/order-received`.
+
+Record these lines in your working notes; do not re-read this file.
+
+- Payment gateways, currency and countries come from `useStoreInfo()` only — never off a cart (`cart.payment_gateways` is always undefined).
+- A store with any coupons must have a coupon field (`useCoupon`) in the cart or the checkout, or its codes can never be redeemed.
+- `/order-received` is mandatory and renders `useOrderReturn`'s states, including `paymentInstructions` — how a normal (offline) customer learns how to pay.
+- Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design.
+- Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations.

package/skills/commerce/install/03-data.md

@@ -0,0 +1,162 @@
+---
+stage: install/03
+read_when: "You are about to build the seed payload — the store's catalog, shipping, coupons, currency — or deciding about payments."
+skip_when: "commerce/seed-store has already returned success for this store and payments are decided."
+forget_when: "The seed response is received and recorded (slugs + warnings), and the checklist at the bottom passes."
+carry_forward:
+  - "Product slugs come from the seed response's catalog.products[] — link pages by slug, never by a client-side map."
+  - "Payments: report at handover where they landed (default = offline on, card off) — the owner must never learn it from a customer."
+  - "Turning card payments on or off later is one more seed call: { payment_methods: [\"offline\", \"card\"] }."
+  - "Seed-time `locations` is THE shipping path; patching commerce.ShippingTaxLocation is the day-2 route."
+---
+
+# 03 — Store data
+
+A fresh install has **no settings and no catalog**. One admin-only, idempotent call to `commerce/seed-store` creates both: the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`), the two gateway rows (`offline` enabled, `card` disabled), and — from the payload — the catalog, coupons and shipping locations. Nothing in [`./02-storefront.md`](./02-storefront.md) waits on it: fire it when the image URLs are back and pick the response up when you need the slugs.
+
+| Mode | Body | Products created |
+|---|---|---|
+| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) | yours — categories, ribbons, attributes, variants, all in this one call |
+| **Demo data** | `{ store_name, with_sample_data: true }` | 10 generic demo products (skipped if any product exists) |
+| **No products** | `{ store_name }` | none — defaults only |
+
+`with_sample_data` cannot be combined with `products` (**400** `invalid_payload`). Never calling the function leaves the operator the admin's first-run "Set up your store" screen.
+
+**`store_name` is required on a first seed** (**400** `store_name_required`) — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). It becomes the email sender name and the public shop name. **`currency`** is an ISO code (`"EUR"`); prices are *formatted* per the viewer's locale, so there is nothing else to set. Explicit values always win, first seed and re-runs alike.
+
+Full field contract — every payload key, every response field, all error codes: [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store). Here is the working call.
+
+```js
+try {
+  const res = await base44.functions.invoke("commerce/seed-store", {
+    store_name: "Aurora Threads",
+    currency: "EUR",
+    products: [
+      { name: "Classic T-Shirt",
+        sku: "TEE-CLASSIC",                        // optional; makes re-runs idempotent
+        regular_price: 19.99,
+        stock_quantity: 50,                        // implies manage_stock
+        categories: ["Clothing"],                  // get-or-created by display name
+        ribbons: ["Best Seller"],
+        images: ["https://…/tee.jpg"],             // URLs or { src, alt } — see Images below
+        short_description: "A soft, breathable everyday tee.",
+        description: "<p>Cut from combed cotton…</p>",     // HTML, rendered as rich text
+      },
+      { name: "Runner Sneaker",
+        sku: "SNK-RUN",
+        regular_price: 89,                         // inherited by variations that don't override
+        attributes: [                              // the axes → one selector each in the storefront
+          { name: "Size", options: ["41", "42"] },
+          { name: "Color", options: ["Black", "White"] },
+        ],
+        default_options: { Size: "42", Color: "Black" },
+        variations: [                              // omit entirely → all 4 combos auto-generated
+          { options: { Size: "41", Color: "Black" }, stock_quantity: 4 },
+          { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
+            image: "https://…/sneaker-white.jpg" }, // per-variation image for a visual axis
+        ],
+      },
+    ],
+    coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],
+    //   ONLY with a coupon field in the cart or checkout (see ./02-storefront.md)
+    // locations: [ … ],   // shipping — the next section; passing any makes them the store's ONLY ones
+  });
+  return res.data;                 // ← the { success, data } envelope: plain JSON
+} catch (e) {
+  return { success: false, status: e.response?.status, ...(e.response?.data ?? { error: e.message }) };
+}
+```
+
+**Running this through a code-execution tool? Return `res.data`, never the raw response.** `invoke` resolves to the raw HTTP response, which carries circular request/response objects — `return res` (or stringifying a thrown error whole) fails with `Converting circular structure to JSON` *even when the seed succeeded*, and a thrown error needs `e.response?.data` for the same reason.
+
+Reference taxonomy by **display name** (categories, ribbons, attributes, options) — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface instead of vanishing.
+
+**Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry after a timeout, or to seed into a store that already has products. **Limits:** ≤100 products, ≤500 variations per call, ≤50 per product, ≤50 locations. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]`, a modified schema **422** `schema_incompatible` — both before anything is written.
+
+The response reports everything; these matter downstream:
+
+```jsonc
+{ "catalog": { "products_created": 2, "variations_created": 3,
+    "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 3 }] },
+  "store_name": { "value": "Aurora Threads", "action": "created" },
+  "payment_methods": null,          // null = the default (offline on, card off)
+  "warnings": [] }                  // always present; read it — see the shipping section
+```
+
+Link pages by the **`slug`** from `catalog.products[]`; never mirror the seed in client-side constants (the database is the source of truth and a mirror diverges the first time the merchant edits a product).
+
+## Shipping — declare it in the seed call
+
+**Seed-time `locations` is THE way to configure shipping.** Each location is a scope plus its rates and taxes, locations match in `order` ascending, and `order` defaults to the payload position — so the array reads as the priority. "€20 in Europe, €100 everywhere else" is two locations:
+
+```js
+locations: [
+  { name: "Europe",    continents: ["EU"],    shipping_rates: [{ name: "Standard",      cost: 20 }] },
+  { name: "Worldwide", rest_of_world: true,   shipping_rates: [{ name: "International", cost: 100 }] },
+]
+```
+
+- **`continents: ["EU"]`** spares you a 51-code country list. The seven codes are `AF` `AN` `AS` `EU` `NA` `OC` `SA`, and `EU` is the *continent* Europe, not the European Union. An unknown code fails `400 invalid_payload` with the known list.
+- **`rest_of_world: true`** is the catch-all — the location that matches every address no other location claims. It cannot also carry `countries`/`continents`/`regions`.
+- Other scopes: `countries: ["IL", "DE"]`, or explicit `regions: [{ type: "state", code: "US:CA" }]`. Matching is **country + state only** — no postcode or city rules exist.
+- One matched location supplies **both** the shipping rates and the tax groups: `shipping_rates: [{ name, cost, free_over? }]`, `tax_groups: [{ name, rates: [{ name, rate }] }]`, `shipping_tax: { type: "percent"|"fixed", value }`.
+
+**The catch-all trap.** Passing any `locations` suppresses the seeded "Rest of the world" fallback, so scoped locations with nothing behind them mean every other address gets `shipping_not_available` at checkout. That is plausibly intended, so it is not an error — it comes back in the response as `warnings: ["no_catchall_location: …"]`. Read `warnings` on every seed and either add a `rest_of_world` location or state the restriction to the user.
+
+Patching `commerce.ShippingTaxLocation` records afterwards is the **harder, day-2 route** — you must mint stable rate `id`s yourself, and there is no admin function for it. Do shipping in the seed payload. For continent codes in full, state-level regions, tax-group binding, free-over thresholds, VAT-on-shipping and day-2 edits: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
+
+**Tiered rates are worth one assertion**, because a wrong zone looks exactly like a right one until a customer in the wrong country pays. The cart prices from an address, so ask it directly — no UI needed:
+
+```js
+// one item in the cart, then price it for each country the brief names
+for (const country of ["DE", "AU"]) {
+  const { data } = await base44.functions.invoke("commerce/storefront-cart", {
+    action: "set-shipping-address", cart_token, address: { country, city: "x" },
+  });
+  console.log(country, data.data.available_shipping_methods.map((m) => m.cost));
+}
+// DE → [20], AU → [100] for the payload above. A [] means no location matched
+// that address — the catch-all is missing.
+```
+
+## 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. Resolve each to its **final, permanent URL before seeding**: the app's image generation, `base44.integrations.Core.UploadFile({ file })` → public URL, or stable public stock URLs (`seed-store/sample-data.ts` shows a working pattern). Match the image to the product.
+
+Both failure modes are silent at seed time and visible only in the store, so check now: a **temporary or signed** URL (expiry params in the query string are the tell) must be re-hosted via `UploadFile`, and spot-check that one or two URLs resolve (200, image content type). Seeding without an image and setting it later through the admin API is allowed, but it is an open debt — track every imageless product and close it before handover.
+
+## Payments — the decision
+
+**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. Offline-only is a complete, payable store — the order goes on-hold with the gateway's description rendered as payment instructions on `/order-received`, which needs no code and no credentials. **Enable `card` only if a payment provider is wired, or will be in the same stretch of work:** enabled means offered, and an enabled card option with nothing behind it answers **`503 no_card_payment_provider`** the moment a customer picks it. Enabling and wiring are two halves of one step; neither half is useful alone.
+
+**`payment_methods` is the on/off switch.** Pass gateway slugs and the listed gateways are enabled while **every other row is disabled** — `["offline"]`, `["card"]` (card-only) or both, with no `commerce.PaymentGateway` reads or writes of your own. Omit it and the store stays offline-only. It is idempotent and needs no catalog, so `{ payment_methods: ["offline", "card"] }` alone is the later on/off switch. Unknown slugs fail `400 invalid_payload` with the known list.
+
+| What the request says | Decision |
+|---|---|
+| A provider is named ("use Stripe") | copy the provider file, enable `card` — whenever convenient; it blocks nothing |
+| Selling online implied, no provider named | cards are a reasonable read of *what* to offer, never of *when*: raise the provider **after** the store works |
+| Paid another way (transfer, COD, invoice, pickup, quotes) | nothing to do — the default already is exactly this |
+| Payments not mentioned at all | leave the default and **mention it at handover** |
+
+**Timing: late, never the opening move.** Payments have no dependency edge into anything — the admin, the seed and the entire buy path down to `place-order` work with no provider — so putting the provider connection before the store exists only stalls the build. Any instruction that treats a payment provider as a required install step is superseded by this section.
+
+**Say where payments landed** in your handover summary, including "offline only, cards off". A store's owner should never discover their payment configuration from a customer who couldn't pay.
+
+*Only for a store that opted into cards:* **if it is Stripe, the code is already written** — `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation, used **as-is**. Copy it over `base44/shared/commerce/card-payment.ts` (`fs.copyFileSync`, whole file — never a partial edit, which leaves duplicate exports and breaks every commerce function's deploy) and enable the gateway with `payment_methods: ["offline", "card"]`. Nothing in it needs filling in and no key belongs in the code; it reads the credential the app's Stripe connection publishes. Any other provider means implementing four functions in that one file — [`../references/online-payments.md`](../references/online-payments.md).
+
+## Done — forget this file
+
+- [ ] `commerce/seed-store` returned success and reported the catalog — real products, final permanent image URLs.
+- [ ] `warnings` in the response is empty, or every warning is deliberate and stated to the user.
+- [ ] Shipping is expressed in `locations` (with a catch-all if the store ships worldwide), not patched into entities afterwards.
+- [ ] `coupons` seeded only if a coupon field exists ([`./02-storefront.md`](./02-storefront.md)).
+- [ ] Cards are either off, or on with the provider file copied whole and the `card` gateway enabled.
+- [ ] Product slugs from `catalog.products[]` recorded, and the storefront links by them.
+- [ ] If the brief named tiered rates, each named region prices to its rate (the `set-shipping-address` check above).
+
+Record these lines in your working notes; do not re-read this file.
+
+- Product slugs come from the seed response's `catalog.products[]` — link pages by slug, never by a client-side map.
+- Payments: report at handover where they landed (default = offline on, card off) — the owner must never learn it from a customer.
+- Turning card payments on or off later is one more seed call: `{ payment_methods: ["offline", "card"] }`.
+- Seed-time `locations` is THE shipping path; patching `commerce.ShippingTaxLocation` is the day-2 route.

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

@@ -1,3 +1,13 @@
+---
+stage: reference
+read_when: "You are changing the admin's product editing screens — sections, price/inventory rows, attribute or variant behaviour."
+skip_when: "You are not editing the admin product form; the shipped form already covers every product shape."
+forget_when: "The form change saves correctly for both a simple product and one with attributes."
+carry_forward:
+  - "A product sells variants because it carries attributes — the attributes ARE the variant control; there is no product type and no generate-variants button."
+  - "A variant parent's price is derived from the cheapest publishable variant on save — never add an input for it."
+---
+
 # The admin product form
 
 Where to change what, in `src/commerce/admin/pages/products/`. The shape follows one