@base44/app-plugin-commerce 0.1.4 → 0.1.5

package/skills/commerce/post-installation.md

@@ -1,6 +1,6 @@
 # Post-installation
 
-What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, decide with the user how the store's data gets created, and register the template + skill in `AGENTS.md`. Installed into the app at `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, seed the store's data, and build the storefront from the quick start below. Installed into the app at `skills/commerce/post-installation.md`.
 
 ---
 
@@ -17,7 +17,7 @@ The admin UI is a self-contained React app under `src/commerce/admin/`. Its only
    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, `commerce/payments` `complete-return`, which confirms the payment and returns `{ state, order, payment_link }` for the paid / unpaid / cancelled cases — the contract and rules are in [`references/online-payments.md`](./references/online-payments.md).
+   **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.
 
    **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 />} />`.
 
@@ -42,113 +42,237 @@ Even if the client guard were bypassed, layers 2 and 3 keep the store data safe.
 
 ---
 
-## 2. Store data — ask the user before seeding anything
+## 2. Store data — seeding
 
-A fresh install has **no settings and no catalog**. Don't decide this silently and don't default to the demo catalog: **ask the user which of these three they want**, then do exactly that.
+A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices), the `offline` and `stripe` payment gateways, three tax classes and a free "Rest of the world" fallback shipping zone — and, depending on the payload, the catalog:
 
-> Suggested wording: *"Before you open the admin — should I generate a starter catalog for your store (products, descriptions, prices, images, categories, variants) based on what you're selling, seed the template's generic demo catalog so you can click around, or leave the store empty and set it up yourself? Generating one costs tokens — I write every product's copy and generate an image each — while the demo catalog is static and effectively free."*
+| Mode | Body | Products created |
+|---|---|---|
+| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `tax_rates`) | Yours — categories, attributes, variants and all, in this one call |
+| **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 |
 
-| Option | What you do | Result | Cost |
-|---|---|---|---|
-| **A — Generate the store's data** (best when you know the app's niche) | `commerce/seed-store` with `{ store_name, with_sample_data: false }`, then create real categories, attributes, products and images through the admin API (§2.1) | Store is **ready** — the admin opens straight onto a populated dashboard, no first-run screen | **Spends tokens**: you author every name, description and price, and image generation is billed per image |
-| **B — Default demo data** | `commerce/seed-store` with `{ store_name, with_sample_data: true }` | Store is **ready**, populated with the template's 10 generic demo products | **Near-zero**: one function call, static content and stock image URLs |
-| **C — Nothing** | don't call `seed-store` at all | The admin shows its first-run **"Set up your store"** screen; the operator initializes defaults themselves | none |
+`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.
 
-Say the cost part out loud when you ask — it's the main trade-off between A and B, and the user is the one paying for it. A generated catalog of a dozen products with images is a real chunk of generation (text for every product plus one image call each); the static demo seed is a single backend call with no generation at all. If the user wants a populated store only to click around the admin, B is the better deal; A is worth it when the catalog is meant to survive into the real store.
+**`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" }`.
 
-**Both A and B must pass `store_name`** — the app's name as the platform shows it. It is required on a first seed (**400** `store_name_required` without it), because nothing server-side can read the app's name and an unnamed store sends subjects like `[]: New order #1002`. It lands in `emails.store_name` — that is the only place it lives, and it drives email subjects, headings and the sender name. It is also published to storefronts as `settings.store_name` by `get-store-info`, so it is the public shop name too. On an already-seeded store the call fills a blank name and never overwrites one the merchant chose; the response reports which happened as `store_name: { value, action }` (`created` · `filled` · `unchanged` · `kept_existing`). It is the sender name too — there is no separate from-name; leave `store_name` blank and Base44 sends as the app's name.
+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.
 
-Both A and B call `seed-store`, which creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`), payment gateways, tax classes and a fallback shipping zone. **Creating the `general` settings group is what marks the business as ready:** the admin's `SettingsProvider` (`src/commerce/admin/context/SettingsContext.jsx`) renders the first-run setup screen only while that group is missing. So under A and B the modal never appears — do **not** add a separate "ready" flag or suppress the screen in code; leave it working for option C, which is the only case it's meant for.
+### 2.1 The `products` payload
 
-Confirm afterwards:
+Reference everything by **display name** — categories, tags, 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`.
 
 ```js
-const { data } = (await base44.functions.invoke("commerce/admin-tools", { action: "status" })).data;
-// → seeded: true (i.e. settings_groups includes "general"),
-//   settings_groups: ["general", "products", ...], counts: { "commerce.Product": n, ... }
+await base44.functions.invoke("commerce/seed-store", {
+  store_name: "Aurora Threads",
+  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
+      tags: ["bestseller"],
+      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
+});
 ```
 
-### 2.1 Generating the store's data (option A)
-
-The goal is a catalog that looks like **this** business, not a demo. Order of operations:
-
-1. **Defaults first** — `commerce/seed-store` with `{ with_sample_data: false, store_name: "<the app's name>" }`. `store_name` is **required** on a first seed (else **400** `store_name_required`) — use the app's name as the platform shows it (ask the user if unsure — `base44/config.jsonc` → `name` can be stale, e.g. `New App` for an app called `Canvas`), since the function cannot read it. It lands in `emails.store_name`, which is both the name in email subjects and the sender name. It's idempotent and runs a canary schema check; on `422 schema_incompatible` fix the reported entities before continuing. Never follow it with `with_sample_data: true` — you'd mix demo products into a real catalog (the sample seeder is skipped once any product exists, so this usually silently does nothing, which is worse).
-2. **Business settings** — ask for, or infer from the app, the store name (in the `emails` group), currency and units, and write them into the relevant `commerce.StoreSettings` groups (direct CRUD, one record per `group_id`; patch `values`, don't replace groups you weren't asked about).
-3. **Taxonomy** — create these through `commerce/admin-products` **`save-term`** (`taxonomy: "category" | "tag" | "attribute" | "attribute-term"`), not direct entity CRUD: `save-term` is what derives a category's unique slug and an attribute's unique `code` (the key a storefront filter URL carries), makes tag creation get-or-create by name, and initializes `count`. A direct create leaves an attribute with a blank `code`. Nest categories via `parent_id`; for variants create the attribute (`{name, code, order}`) then its values (`{attribute_id, name, order}`) for e.g. Size and Color. Attributes are shared: create Size once and reuse it across shoes and shirts, picking per product which of its values apply.
-4. **Products** — `commerce/admin-products` `save` (or `batch`, ≤100 items) per product. Write real merchandising copy: a distinct `name`, a one-line `short_description`, an HTML `description` (paragraph + `<ul>` of specifics), plus `sku`, `regular_price`, optional `sale_price`, `manage_stock: true` + `stock_quantity` where stock is tracked, `category_ids` and `images[]`. **On a product that will carry attributes, price the variations and leave the parent's price alone** — `regular_price`, `price` and `on_sale` are rolled up from the cheapest publishable variant on every save, so anything you set there is discarded. (`manage_stock` is a boolean on Product but `"yes"|"no"|"parent"` on ProductVariation.)
-5. **Variants — an attribute in the attributes list does NOTHING on its own.** This is the step agents get wrong: they create a shared `Size` attribute with values, and every product stays a single item. There is **no product type and no per-attribute flag** — a product sells variants because it carries attributes — so listing the attribute **on the product**, with the values that product comes in, is what declares it. Two things must be true, and both happen in the *same* `commerce/admin-products` `save` call:
-   1. the attribute is listed **on the product** with its `options` — not just in `commerce.ProductAttribute`;
-   2. a `variations` array is sent with one entry per combination you actually stock (plus `default_attributes` for the combination to pre-select).
-
-   ```js
-   await call("admin-products", "save", {
-     product: {
-       name: "Runner Sneaker", status: "publish", sku: "SNK",
-       category_ids: [shoesId], images: [{ src: "…" }],
-       attributes: [{ attribute_id: sizeAttrId, name: "Size", position: 0,
-                      options: ["41", "42", "43"] }],
-       default_attributes: [{ attribute_id: sizeAttrId, name: "Size", option: "42" }],
-     },
-     variations: [
-       { attributes: [{ attribute_id: sizeAttrId, name: "Size", option: "41" }],
-         sku: "SNK-41", regular_price: 89, manage_stock: "yes", stock_quantity: 4, status: "publish" },
-       { attributes: [{ attribute_id: sizeAttrId, name: "Size", option: "42" }],
-         sku: "SNK-42", regular_price: 89, manage_stock: "yes", stock_quantity: 6, status: "publish" },
-       { attributes: [{ attribute_id: sizeAttrId, name: "Size", option: "43" }],
-         sku: "SNK-43", regular_price: 89, manage_stock: "yes", stock_quantity: 2, status: "publish" },
-     ],
-   });
-   ```
+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/tag 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.
+
+**Re-runs converge instead of duplicating**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported — safe for retries after a timeout, and for seeding into a store that already has products. Limits: ≤100 products and ≤500 variations per call, ≤50 variations per product (an auto-generated cartesian above that is rejected — pass explicit `variations`).
+
+The response reports everything:
+
+```jsonc
+{ "seeded": { "settings_groups": 6, "gateways": 2, ... },
+  "catalog": {
+    "categories": { "created": 2, "reused": 0 }, "tags": { ... }, "attributes": { ... }, "terms": { ... },
+    "products_created": 2, "products_skipped": 0, "variations_created": 4,
+    "coupons": { "created": 1, "skipped": 0 }, "tax_rates": { "created": 0, "skipped": 0 },
+    "products": [
+      { "name": "Classic T-Shirt", "id": "…", "slug": "classic-t-shirt", "sku": "TEE-CLASSIC", "variation_count": 0 },
+      { "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "sku": "SNK-RUN", "variation_count": 4 }
+    ]
+  },
+  "store_name": { "value": "Aurora Threads", "action": "created" } }
+```
 
-   Give a visual axis (Color) a per-variation `image`. `manage_stock` is `"yes"|"no"|"parent"` on a variation but a boolean on the product. **Then check your work**: re-read the product and assert `variations.length > 0` — a product with attributes and no variations cannot be added to a cart at all (`400 variation_required`), and the storefront has nothing to show. Descriptive properties (Material, Care) are **not** attributes: put them in `meta_data`, which the admin surfaces as *modifiers*.
-6. **Images** — every product needs at least one. 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 the `{ src, name, alt }` shape and a working Unsplash pattern). Match the image to the product — a generated catalog with mismatched or missing images reads as broken.
-7. **Optional extras** — a launch coupon via `commerce/admin-coupons` `save`; tax rates via `commerce.TaxRate` direct CRUD if the user sells into taxed regions.
-8. **Payments — once the store has something to sell.** Leave this until the catalog, shipping and settings are in place: connecting a payment provider is a step the *user* has to take in the platform dashboard, so asking for it first interrupts setup and leaves nothing to test the payment against. When the store is otherwise ready, raise it — don't wait to be asked. Card payments are **already implemented** (hosted payment page, payment links, refunds); they only need a provider connected. The other gateway (`offline`) is **manual** — nobody pays online and someone reconciles by hand. So tell the user card payments are ready and ask them to set up the platform's **Stripe integration** for the app (app dashboard → Integrations → Stripe — *not* an OAuth connector; there is no Stripe connector in Base44's catalog), then **redeploy the backend functions** — the platform injects `STRIPE_SECRET_KEY` at deploy time, so a provider connected after the last deploy is invisible to already-deployed functions and the store still reports *no payment provider connected*. On a hosted app, edit any file under `base44/shared/commerce/` (bump the deploy marker at the top of `payments.ts`) to redeploy every `commerce/*` function; on the CLI, `npx base44 functions deploy`. Then confirm with `commerce/admin-tools` → `payment-connector-status`. Nothing to code. The card gateway is enabled by default and stays hidden from customers until a provider is connected, so enabling it early is safe. Declining is a legitimate choice — then switch that gateway off and make the manual flow explicit in the checkout copy. Details: [`references/online-payments.md`](./references/online-payments.md).
-9. **Report back** — tell the user what you created (counts by category, currency, enabled gateways) and that the store is ready at `/store-admin`.
+**Images**: every product needs at least one. 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.
 
-Keep the generated catalog small unless asked — roughly 8–15 products across 3–5 categories, with at least one variable product if the business plausibly has options. Cost scales with the catalog: every product is generated copy plus at least one generated image, so confirm before going past that range rather than quietly producing a 50-product store. Products are created as `status: "publish"` only if you set it; leave them `draft` if the user wants to review before going live.
+A successful response means the data is in — the catalog and settings are live exactly as reported. Write any store-specific settings into `commerce.StoreSettings` (direct CRUD, one record per `group_id` — currency and units are the usual ones; patch `values`, don't replace groups you weren't asked about).
+
+### 2.2 Payments
+
+Card payments are **already implemented** (hosted payment page, payment links, refunds) — make sure a payment provider (i.e. the platform's **Stripe** integration) is configured for the app, and the store takes cards; the `offline` gateway (manual reconciliation) works with nothing to configure. Provider internals, webhooks and refunds are day-2 material: [`references/online-payments.md`](./references/online-payments.md).
 
 ---
 
-## 3. Register the template and skill in `AGENTS.md`
+## 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. 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.
 
-So future agent sessions know the store exists and read the skill before touching it, **edit the app's existing `AGENTS.md` in place** — add the template to an **Installed templates** section and point at the skill from a **My Skills** section. Do **not** replace or overwrite the file: keep everything already in it and only append these two entries, creating either section only if it doesn't already exist (if a section is already there, add to it rather than duplicating it). The snippet below shows the entries to merge in, not a full-file replacement:
+Every function returns the envelope `{ success, data }`; with the SDK the payload is `res.data.data`, so define one helper and use it everywhere:
 
-```md
-## Installed templates
+```js
+const inv = (fn, payload) => base44.functions.invoke(fn, payload).then((r) => r.data.data);
+```
 
-- commerce
+The cart is identified by a **`cart_token`** the backend mints — persist it in `localStorage` and send it with every cart/checkout call. Rolling 48 h expiry, refreshed on every touch.
 
-## My Skills
+### 3.1 Product list
 
-- `skills/commerce/SKILL.md` — Base44 Commerce template: 24 `commerce.*` entities, 16 `commerce/*` backend functions (storefront + admin APIs + online payments), the shared commerce engine under `base44/shared/commerce/`, the Store Management UI mounted at `/store-admin`, and the `commerce/StoreAdmin` agent (admin copilot bot in the admin sidebar). Read before working on store features — catalog, cart, checkout, orders, payments, emails, webhooks, or the admin UI.
+```js
+const info = await inv("commerce/storefront-catalog", { action: "get-store-info" });
+// info.settings → { store_name, currency, currency_position, num_decimals, … } — format money with these
+// info.payment_gateways → [{ slug, title, description, online }] — you'll need this at checkout
+// info.countries / info.currencies → static tables for address forms and money display
+
+const { products, page, per_page, has_next } = await inv("commerce/storefront-catalog", {
+  action: "list-products",
+  page: 1, per_page: 12,           // optional: search, category_id, tag_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`, `price`, `regular_price`, `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `tags` (`[{ id, name }]`, may be absent). **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 `{ action: "list-categories" }` (a tree via `parent_id`).
+
+**Carry forward:** each card links to the product page by **`slug`**.
+
+### 3.2 Product page — variant selection included
+
+```js
+const { product, variations, categories, tags, reviews } =
+  await inv("commerce/storefront-catalog", { action: "get-product", slug });   // or { id }
+
+// One selector PER product.attributes[] entry — never a flat list of variations.
+import { defaultSelection, selectOption, resolveSelection } from "@/commerce/utils";
 
-## 4. Reviews — build them unless the user rules it out
+let selection = defaultSelection(product, variations);        // merchant defaults + single-option axes
+// on user pick: selection = selectOption(product, variations, selection, axisKey, option);
 
-**Unless you are sure the store doesn't want reviews, implement them: the backend already exists.** Skipping them is the common miss, and it costs the store the social proof most shoppers look for before buying.
+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
+// view.purchasable  → gate the Add-to-cart button on this
+// view.addToCart    → { product_id, variation_id } — null until the selection resolves
+```
 
-What ships, with nothing to write on the backend:
+Add to cart — **create** mints the `cart_token` on first add; every later call reuses it:
 
-- `commerce/storefront-catalog` `get-product` returns **paginated `reviews`** plus `average_rating` and `rating_count`, and a `verified` flag per review;
-- `list-products` rows carry `average_rating`/`rating_count`, so **stars on cards cost no extra call**;
-- `commerce/storefront-catalog` `submit-review` accepts `{ product_id, reviewer?, review, rating }` from a **signed-in** customer — the email comes from the session, never the payload;
-- `commerce/storefront-account` `my-reviews` lists a customer's own;
-- moderation is already in the admin (Products → Reviews), and `commerce/admin-reviews` recalculates the product's rating on every status change.
+```js
+let cart_token = localStorage.getItem("cart_token");
+if (!cart_token) {
+  const cart = await inv("commerce/storefront-cart", { action: "create" });
+  cart_token = cart.cart_token;
+  localStorage.setItem("cart_token", cart_token);
+}
+await inv("commerce/storefront-cart", { action: "add-item", cart_token, ...view.addToCart, quantity: 1 });
+```
 
-So the work is UI: stars on cards and the product page, a reviews list, and a submit form. Behaviors to respect rather than fight:
+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. Show `reviews` (`{ items, has_next, average_rating, rating_count }`) and the `upsells`/`cross_sells` summaries the same response carries.
 
-- anonymous callers get **`401 login_required`** — put the form behind a login prompt instead of hiding reviews from guests;
-- a new review is **`hold`** unless `auto_approve_reviews`, so tell the submitter it's awaiting approval rather than showing it as live;
-- `only_verified_reviews` requires the customer to have a `processing`/`completed` order with that product (**`403 verified_only`**), and `review_rating_required` makes the rating mandatory (**`400 rating_required`**);
-- the store can switch reviews off store-wide (`products.enable_reviews`) — read it and hide the UI when false.
+**Carry forward:** 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 inv("commerce/storefront-cart", { action: "get", cart_token });
+// cart.items  → [{ item_key, name, image, quantity, price, subtotal, total, attributes, purchasable }]
+// 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
+
+cart = await inv("commerce/storefront-cart", { action: "update-item", cart_token, item_key, quantity }); // ≤0 removes
+cart = await inv("commerce/storefront-cart", { action: "remove-item", cart_token, item_key });
+cart = await inv("commerce/storefront-cart", { action: "apply-coupon", cart_token, 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`):
+
+```js
+cart = await inv("commerce/storefront-cart", { action: "set-shipping-address", cart_token,
+  address: { country, state, postcode, city } });
+switch (cart.shipping_status) {
+  case "auto_selected":                 // one option — already applied, nothing to do
+  case "chosen": break;                 // customer's earlier choice still valid
+  case "choice_required":               // MUST render cart.available_shipping_methods [{ id, title, cost }]
+    cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method", cart_token,
+      method_id: picked.id });          // the entry's id, not its method_id type
+    break;
+  case "none_available": /* the store doesn't ship there — say so, don't place the order */ break;
+  case "not_needed": break;             // fully virtual cart
+}
+```
+
+**Carry forward:** the **`cart_token`** (address and method choice live on the cart).
+
+### 3.4 Checkout & order-received
+
+Payment methods are `info.payment_gateways` from step 1 — render them as they come (`online: true` marks the card/redirect gateway; `offline` is manual reconciliation). Make sure a payment provider (i.e. Stripe) is configured for the app. Then one call places the order:
+
+```js
+// card payments ride the app's Stripe integration — setup & provider details:
+// skills/commerce/references/online-payments.md
+const res = await inv("commerce/storefront-checkout", {
+  action: "place-order", cart_token,
+  payment_method: gateway.slug,                       // from info.payment_gateways
+  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?; return_url: window.location.origin
+});
+// res → { order_id, order_number, order_key, status, totals, order,
+//         payment_instructions,   // offline: { description, account_details } — render them
+//         payment }               // online: { status: "requires_payment", checkout_url, … } | null
+
+if (res.payment?.status === "requires_payment") window.location.href = res.payment.checkout_url;
+else showConfirmation(res);        // offline 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 params = new URLSearchParams(window.location.search);
+const { state, order, payment_link } = await inv("commerce/payments", {
+  action: "complete-return",
+  order_id: params.get("order_id"), order_key: params.get("order_key"),
+  payment: params.get("payment"),        // only a hint — the server verifies with the provider
+  return_url: window.location.origin,
+});
+// state === "paid"      → thank-you + order summary (order is now marked paid)
+// state === "unpaid"    → offer payment_link.url to try again
+// state === "cancelled" → payment was cancelled — offer payment_link.url or support
+```
 
-Shapes and error codes: [`docs/api-storefront.md`](./docs/api-storefront.md#submit-review--auth). Where ratings belong per view: [`references/product-render.md`](./references/product-render.md).
+**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).
 
 ---
 
-## 5. Next
+## 4. Next
 
-Continue with the commerce skill — [`skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, storefront building (start with [`references/product-render.md`](./references/product-render.md) for what to render, then [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variants), Stripe wiring, scheduled maintenance, emails, webhooks, and operational limits.
+Continue with the commerce skill — [`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), Stripe wiring, scheduled maintenance, emails, webhooks, and operational limits.

package/skills/commerce/references/reviews.md

@@ -0,0 +1,20 @@
+# Reviews
+
+**Unless you are sure the store doesn't want reviews, implement them: the backend already exists.** Skipping them is the common miss, and it costs the store the social proof most shoppers look for before buying.
+
+What ships, with nothing to write on the backend:
+
+- `commerce/storefront-catalog` `get-product` returns **paginated `reviews`** plus `average_rating` and `rating_count`, and a `verified` flag per review;
+- `list-products` rows carry `average_rating`/`rating_count`, so **stars on cards cost no extra call**;
+- `commerce/storefront-catalog` `submit-review` accepts `{ product_id, reviewer?, review, rating }` from a **signed-in** customer — the email comes from the session, never the payload;
+- `commerce/storefront-account` `my-reviews` lists a customer's own;
+- moderation is already in the admin (Products → Reviews), and `commerce/admin-reviews` recalculates the product's rating on every status change.
+
+So the work is UI: stars on cards and the product page, a reviews list, and a submit form. Behaviors to respect rather than fight:
+
+- anonymous callers get **`401 login_required`** — put the form behind a login prompt instead of hiding reviews from guests;
+- a new review is **`hold`** unless `auto_approve_reviews`, so tell the submitter it's awaiting approval rather than showing it as live;
+- `only_verified_reviews` requires the customer to have a `processing`/`completed` order with that product (**`403 verified_only`**), and `review_rating_required` makes the rating mandatory (**`400 rating_required`**);
+- the store can switch reviews off store-wide (`products.enable_reviews`) — read it and hide the UI when false.
+
+Shapes and error codes: [`docs/api-storefront.md`](../docs/api-storefront.md#submit-review--auth). Where ratings belong per view: [`references/product-render.md`](./product-render.md).