@base44/app-plugin-commerce 0.1.20 → 0.2.2

package/skills/commerce/references/reviews.md

@@ -1,26 +1,41 @@
+---
+stage: reference
+read_when: "You need review behaviour beyond useProductReviews — moderation, auto-approval, a customer's own reviews, or a policy the three built-in ones don't cover."
+skip_when: "useProductReviews is on the product page — that is list + submit + policy + the right confirmation copy already."
+forget_when: "A review submits, appears (or is held) as the store's auto-approve setting dictates, and the aggregate rating renders."
+carry_forward:
+  - "Reviews are part of the happy path: one hook. The confirmation copy must come from the submit response, never hardcoded."
+---
+
 # 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.
+Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and the whole UI contract is one hook. Unless the store explicitly doesn't want them, put them on the product page: `useProductReviews(product, { policy, user, requireRating, perPage })` — the list with paging (`items`, `hasNext`/`loadMore`), the aggregates (`averageRating`, `ratingCount`), the whole form contract (`form`/`setField`/`fieldErrors`/`valid`/`submit`/`message`) and the policy gate (`canReview`, `reviewBlockedReason`, `requiresEmail`); exact shapes in its JSDoc. The markup around it — stars, rows, the form — is yours, like all storefront UI.
+
+## What ships
+
+- `get-product` returns **paginated `reviews`** plus `average_rating`, `rating_count` and a `verified` flag per review; `list-products` rows carry the aggregates, so **stars on cards cost no extra call**;
+- `submit-review` accepts `{ product_id, email, reviewer?, review, rating? }` from **anyone — no login**. A signed-in caller's session email always wins (the payload cannot impersonate); a guest supplies `email`; `verified` comes from that email's order history. The three error codes (`400 email_required | review_incomplete | invalid_rating`) land on their fields via `fieldErrors` instead of rejecting into nothing;
+- `storefront-account` `my-reviews` lists a signed-in customer's own — what a "My reviews" account tab renders from;
+- moderation is in the admin (Products → Reviews); `commerce/admin-reviews` recalculates the product's rating on every status change.
+
+## The `policy` prop
 
-What ships, with nothing to write on the backend:
+`policy` is the store's review rule as one option, replacing the patterns a storefront used to implement by hand. Pass your app's current user alongside it (`useProductReviews(product, { policy: "login", user })`) — the stricter policies need 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, email, reviewer?, review, rating? }` from **anyone — no login**. For a signed-in caller the session email always wins (the payload cannot impersonate); a guest supplies `email`. `verified` is derived from that email's order history;
-- `commerce/storefront-account` `my-reviews` lists a signed-in customer's own;
-- moderation is already in the admin (Products → Reviews), and `commerce/admin-reviews` recalculates the product's rating on every status change.
+| `policy` | Who may submit | Blocked as |
+|---|---|---|
+| `"open"` (default) | anyone with a valid email — the server's own rule | — |
+| `"login"` | a signed-in visitor only | `reviewBlockedReason: "login_required"` |
+| `"verified_buyers"` | someone whose own orders include a `processing`/`completed` order for this product (checked via `my-orders`) | `"not_a_buyer"` |
 
-**The one server-side switch is auto-approval** (`products.auto_approve_reviews`, the toggle on the admin's Reviews screen): off (the default) holds every new review as `hold` for moderation; on publishes immediately. Tell the submitter their review is awaiting approval rather than showing it as live.
+Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate. `requireRating: true` makes the stars mandatory; `requiresEmail` is `false` for a signed-in visitor, so the field is hidden (the session's email wins server-side anyway). A policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
 
-## Policies are yours to enforce in the UI
+## Auto-approval and moderation
 
-The server deliberately ships the **most open default — anyone can review by email**. Anything stricter is storefront policy, implemented where you build the form:
+`products.auto_approve_reviews` ([`store-settings.md`](./store-settings.md), toggle on the admin's Reviews screen) is the **only** server-side switch: off (the default) holds every review as `hold` for moderation; on publishes immediately.
 
-- **Login-gated reviews** — render the form only for a signed-in session (`base44.auth.me()`), and omit `email` from the payload: the session email is used automatically.
-- **Verified buyers only** — before showing the form to a signed-in customer, check their history: `commerce/storefront-account` `my-orders` and look for a `processing`/`completed` order containing the product. (For guests there is nothing to check against — pair this policy with login-gating.) The `verified` flag on every stored review tells moderators and readers which reviews came from buyers either way — an honest middle ground is to accept all reviews and render a "Verified purchase" badge from it.
-- **Required rating** — `rating` is optional server-side (0–5 when present); make the stars mandatory in the form before submitting if the store wants no unrated reviews.
-- **Disabling reviews store-wide** — simply build no review UI. There is no server switch to keep in sync.
+So **the confirmation copy must come from the response**: `submit()` resolves `{ ok, status, verified }` with `status` `"approved"` or `"hold"`, and `message` follows it. A hardcoded "awaiting approval" lies to every store with auto-approval on — and after an approved submission the hook refreshes the list so the review actually appears.
 
-If a policy must hold even against handcrafted API calls (not just your UI), enforce it in a backend function of your own that wraps `submit-review` — the same pattern as any custom storefront action.
+Disabling reviews store-wide is simply building no review UI; there is no server switch to keep in sync.
 
-Shapes and error codes (`400 email_required|review_incomplete|invalid_rating`): [`docs/api-storefront.md`](../docs/api-storefront.md#submit-review). Where ratings belong per view: [`references/product-render.md`](./product-render.md).
+Shapes and error details: [`../docs/api-storefront.md`](../docs/api-storefront.md#submit-review). Where ratings belong per view: [`catalog-rendering.md`](./catalog-rendering.md).

package/skills/commerce/references/shipping-and-tax.md

@@ -0,0 +1,110 @@
+---
+stage: reference
+read_when: "You need shipping or tax beyond the one recipe inline in ../install/03-data.md — several priced tiers, VAT, tax on shipping, or editing locations after the seed."
+skip_when: "One flat rate is enough, or the '€X region / €Y worldwide' recipe in ../install/03-data.md already expresses the requirement."
+forget_when: "The seed response came back with no `no_catchall_location` warning and checkout prices shipping for both a domestic and a foreign test address."
+carry_forward:
+  - "One matched commerce.ShippingTaxLocation supplies BOTH the shipping rates and the tax for an address."
+  - "Locations match by `order` ascending; one with no regions (`rest_of_world: true`) is the catch-all — without it every unlisted address gets `shipping_not_available`."
+  - "Matching is country / state / continent only — no postcode or city rules exist."
+---
+
+# Shipping & tax locations
+
+One entity does both jobs. A **`commerce.ShippingTaxLocation`** is *a set of regions plus everything charged there*: the shipping options offered and the tax applied. There is no zone/method/class model and no separate tax-rate table.
+
+Declaring `locations` in the `commerce/seed-store` call is **the** way to set shipping up ([`../install/03-data.md`](../install/03-data.md)); editing the entity afterwards is the day-2 route (last section).
+
+## The model
+
+| Field | Meaning |
+|---|---|
+| `name` | Required; also the identity used for skip-if-exists when seeding. |
+| `order` | Match priority, **ascending**. Defaults to the payload position (0, 1, 2…) at seed time, so the array reads as the priority; the seeded fallback sits at `999`. |
+| `regions[]` | `{ type: "country" \| "state" \| "continent", code }` — `"US"`, `"US:CA"`, `"EU"`. **Empty = the catch-all.** |
+| `shipping_rates[]` | `{ id, name, cost, free_over }` — each one a checkout choice. |
+| `tax_groups[]` | `[{ name, rates: [{ name, rate }] }]`, `rate` a percentage (`18` = 18%). `Products` is the group every product uses unless its `tax_group` names another. |
+| `shipping_tax` | `{ type: "percent" \| "fixed", value }`, or `null` for untaxed shipping. |
+
+**The 7 continent codes** (`shared/commerce/data/continents.ts`): `AF` Africa, `AN` Antarctica, `AS` Asia, `EU` Europe, `NA` North America, `OC` Oceania, `SA` South America. `EU` is the **continent** — 51 countries including GB, CH, NO, RU, UA — *not* the European Union. Unknown codes are rejected at seed time with the known list.
+
+## Matching an address
+
+`shared/commerce/shipping.ts` `matchLocation()`: sort by `order` ascending → the first location with non-empty `regions` where **any** region matches wins (regions OR together) → else the first location with **no** regions → else nothing, and the storefront gets `400 shipping_not_available` from `set-address`.
+
+**Country and state only.** A `state` region matches as `COUNTRY:STATE` (`US:CA`) — which is why the address form must collect `state`. **No postcode or city matching exists**; the address carries them, nothing reads them. Per-postcode pricing means a rate per state, or your own logic.
+
+One convenience: with no address yet, a store with exactly **one** location prices from it, so the cart can show shipping before the customer types anything. With two or more the cart reports `missing_address` until an address is set.
+
+## One location, both charges
+
+Totals resolve the location **once** (`tax.tax_based_on` — `shipping` by default, or `billing` — picks which address), then its `tax_groups` tax the items, its `shipping_rates` are the options offered, and its `shipping_tax` taxes the chosen rate (`fixed` charged once per order). A product's `tax_group` picks the group **by name** (case-insensitive, default `Products`); a group's tax is the **sum of its rates** — no priorities, no compounding. So tax follows shipping coverage: a location with no matching group charges nothing, and a region you don't ship to is untaxed unless you give it a location with no rates.
+
+**Rate ids are stable and referenced** — carts and orders store the chosen `id`, derived at seed time as `<location-slug>-<rate-slug>` (`europe-standard`) unless you pass one. `free_over` zeroes a rate once the **discounted items subtotal** reaches it (`null` = never); a free-shipping coupon zeroes every offered rate.
+
+## Recipes
+
+Copy-pasteable `locations` values for `commerce/seed-store`.
+
+**1. One country, flat rate**
+
+```js
+locations: [{ name: "United States", countries: ["US"],
+              shipping_rates: [{ name: "Standard", cost: 6.95 }] }]
+```
+
+**2. €20 in Europe, €100 worldwide** — a whole continent without a 51-code list:
+
+```js
+locations: [
+  { name: "Europe",    continents: ["EU"],  shipping_rates: [{ name: "Standard", cost: 20 }] },
+  { name: "Worldwide", rest_of_world: true, shipping_rates: [{ name: "International", cost: 100 }] },
+]
+```
+
+**3. Domestic, then priced international tiers** — explicit `order` when the payload order isn't the priority you want:
+
+```js
+locations: [
+  { name: "Germany", countries: ["DE"], order: 0,
+    shipping_rates: [{ name: "DHL Paket", cost: 4.9 }, { name: "Express", cost: 12.9 }] },
+  { name: "EU", continents: ["EU"], order: 1, shipping_rates: [{ name: "Standard", cost: 9.9 }] },
+  { name: "Rest of the world", rest_of_world: true, order: 2,
+    shipping_rates: [{ name: "International", cost: 24.9 }] },
+]
+```
+
+Two rates at one location = a real choice at checkout; a single rate is auto-selected (`resolveShippingSelection`).
+
+**4. Free over a threshold** — one rate, not two:
+
+```js
+locations: [{ name: "United Kingdom", countries: ["GB"],
+              shipping_rates: [{ id: "uk-standard", name: "Standard (free over £50)",
+                                 cost: 3.95, free_over: 50 }] }]
+```
+
+**5. VAT, with tax on shipping too**
+
+```js
+locations: [{
+  name: "Israel", countries: ["IL"],
+  shipping_rates: [{ name: "Standard", cost: 20, free_over: 150 }],
+  tax_groups: [{ name: "Products", rates: [{ name: "VAT", rate: 18 }] }, { name: "Books", rates: [] }],
+  shipping_tax: { type: "percent", value: 18 },
+}]
+```
+
+Products join the `Books` group by carrying `tax_group: "Books"`. Set `tax.prices_include_tax` if the prices you seed are **gross** — tax is then extracted from them rather than added ([`store-settings.md`](./store-settings.md)).
+
+## The catch-all trap
+
+A payload carrying `locations` **suppresses** the seeded "Rest of the world" fallback: your list becomes the store's entire shipping story. Seed `{ name: "Europe", continents: ["EU"] }` alone and the store ships to Europe and **nowhere else** — every other address fails `set-address` with `400 shipping_not_available`, deliberately loudly rather than dead-ending at place-order. Ship worldwide ⇒ include a `rest_of_world: true` location; the seeder flags the omission in its response `warnings` as `no_catchall_location`.
+
+`rest_of_world: true` is the catch-all *instead of* a scope — combining it with `countries`/`continents`/`regions` is a payload error, not a merge. (An empty `regions: []` still works and means the same.)
+
+## Day-2 edits
+
+No admin function owns locations, so there are two routes: **direct CRUD** on `commerce.ShippingTaxLocation` (admin-only RLS, bracket syntax — [`../docs/entities.md`](../docs/entities.md)), where `shipping_rates` is written whole so you must **mint stable `id`s yourself and never renumber existing ones** (orders reference them); or **the merchant's screen**, admin → Settings → Shipping & Tax (`settings/shipping-tax`), which edits regions, rates, groups and shipping tax directly.
+
+Re-seeding is **skip-if-exists by name**: a location of the same name is left untouched, never duplicated and never updated — to change one, edit the record. Limit **≤ 50 locations** per seed call. At runtime the storefront never picks a location: `set-address` prices the cart, the totals view carries `matched_location_id` and `available_shipping_methods`, and `useCheckout` surfaces failure as the `shipping_not_available` blocker.

package/skills/commerce/references/store-admin-agent.md

@@ -0,0 +1,21 @@
+---
+stage: reference
+read_when: "You are changing the StoreAdmin copilot — its tools, its instructions, the chat panel — or debugging why it fails at message time."
+skip_when: "You are not touching the agent; it registers itself when its file lands and needs no wiring."
+forget_when: "The agent answers in the admin's chat panel and its tool calls succeed for an admin user."
+carry_forward:
+  - "Never add entity tools or service-role calls to StoreAdmin: its only authorization layer is requireAdmin() inside the admin functions it calls."
+---
+
+# The StoreAdmin agent (admin copilot)
+
+The kit ships an AI copilot for store operators.
+
+- **Agent definition** — `base44/agents/commerce/StoreAdmin.jsonc`, registered as **`commerce/StoreAdmin`** (the folder namespaces the agent, exactly like functions). The hosted runtime registers it when the file lands; on the CLI path run `npx base44 agents push`.
+- **Tools** — the `commerce/*` backend functions attached directly (`commerce/admin-products`, `commerce/admin-orders`, …, `commerce/seed-store`, plus read-only `commerce/storefront-catalog` for enumerating product variations). Tool calls run **with the chatting user's credentials**, so `requireAdmin()` in every admin function still authorizes the actual user — the agent has no entity tools and no service-role shortcut; a non-admin chatting with it gets `401/403` from every admin operation.
+- **No `model` field, on purpose.** The platform's default-model path accepts slash-namespaced tool names; explicitly setting a `model` currently rejects them (LLM tool names must match `^[a-zA-Z0-9_-]{1,128}$`). If you set a model, the bot fails at message time with a `tools.0.custom.name` error.
+- **Variant safety** — the agent is instructed to never auto-pick a variation: for a product carrying attributes it fetches `{product, variations}` via `commerce/storefront-catalog get-product`, presents the variants as a table, and asks the operator which `variation_id` to use before touching an order, stock, or download grant.
+- **Bot UI** — `src/commerce/admin/bot/` (chat panel; "StoreAdmin bot" launcher at the bottom of the admin sidebar). Responses render as markdown via `react-markdown`, with the agent's GFM tables (`| col |` with `|---|` separators) rendered by the kit's own `bot/pipe-tables.js` — no markdown plugin dependency. The panel lives behind the same `AuthGuard` as the rest of the admin.
+- **Config it can't change, it links to.** Store settings, Shipping & Tax Locations, gateways and webhook definitions have no function tool, so the agent is instructed to name the screen and emit an `admin:`-scheme link (`[Settings → Shipping & Tax](admin:settings/shipping-tax)`) rather than telling the operator to "do it manually". `bot/Markdown.jsx` resolves `admin:` through `useAdminHref()`, so links follow your actual mount point (`basePath`) and navigate in-app instead of opening a tab. If you add screens, add the path to the table in the agent's instructions.
+
+**Do not weaken the tool set.** The agent's power comes only from the admin functions' own `requireAdmin()` layer — don't add entity tools or service-role calls to the agent config, and keep `commerce/storefront-*` tools limited to the read-only catalog.

package/skills/commerce/references/store-settings.md

@@ -0,0 +1,49 @@
+---
+stage: reference
+read_when: "You need to change store behaviour through a settings key — stock holds, review auto-approval, tax display, the payment return path, the store name."
+skip_when: "The seeded defaults are fine (they are, for a new store) — or the value is set by the seed call's own arguments (store_name, currency, weight_unit, dimension_unit)."
+forget_when: "The setting is written and the behaviour it drives is observed once."
+carry_forward:
+  - "commerce.StoreSettings is one record per group_id with a `values` object; `update` replaces `values` whole — read, spread, write back."
+---
+
+# Store settings
+
+Six records, one per group: `general`, `products`, `inventory`, `tax`, `shipping`, `emails`. Defaults are seeded by `commerce/seed-store` (`seed-store/defaults.ts` is the literal source). Backend reads: `getSettings(sr, ...groups)` / `getSetting(groups, group, key, fallback)` in `shared/commerce/settings.ts`. Admin: `useSettings().get(group, key, fallback)`. The storefront sees only the `storefrontSafeSettings()` projection on `get-store-info`.
+
+| Key | Default | Effect / read by |
+|---|---|---|
+| **`general`** | | |
+| `order_received_path` | `"/order-received"` | The route a paying customer returns to; `shared/commerce/payments.ts` builds the provider's success/cancel URLs from it. A value that doesn't match your route is a 404 after payment and an order never confirmed. |
+| `currency` | `"USD"` | ISO code, **a value not a format**. Stamped on orders by `storefront-checkout`; published on `get-store-info` for `useMoney`/`useFormatMoney`. |
+| `weight_unit` / `dimension_unit` | `"kg"` / `"cm"` | Labels only — nothing converts. Admin product form, `get-store-info`. |
+| **`products`** | | |
+| `auto_approve_reviews` | `false` | The **only** server-enforced review rule: `submit-review` returns `status: "hold"` or `"approved"`. Confirmation copy comes from that response ([`reviews.md`](./reviews.md)). |
+| **`inventory`** | | |
+| `manage_stock` | `true` | Stock-tracking default for new products. |
+| `hold_stock_minutes` | `60` | How long an unpaid order holds stock: `place-order` sets `hold_expires_at`; `admin-orders release-expired-holds` frees it ([`operations.md`](./operations.md)). `0` disables holds. |
+| `low_stock_threshold` / `out_of_stock_threshold` | `2` / `0` | Stock status and the low/out-of-stock emails (`shared/commerce/stock.ts`, `admin-products`, `admin-reports`); a product's own `low_stock_amount` wins. |
+| `hide_out_of_stock` | `false` | `storefront-catalog` drops out-of-stock products from `list-products` **and** `get-product` — the catalog, not just the UI. |
+| **`tax`** | | |
+| `prices_include_tax` | `false` | `true` = stored prices are **gross** and `totals.ts` extracts tax instead of adding it. Flipping it after orders exist re-prices everything. |
+| `tax_based_on` | `"shipping"` | Which address resolves the location — `shipping` or `billing` ([`shipping-and-tax.md`](./shipping-and-tax.md)). |
+| `display_prices_shop` / `display_prices_cart` | `"excl"` | `incl` \| `excl`. **Nothing in the engine enforces these** — they ride on `get-store-info` as a hint for the storefront you build. Honour them or ignore them; no price changes by itself. |
+| **`shipping`** | | |
+| `enable_shipping` | `true` | `false` = no shipping line, no rates, no address requirement anywhere. The digital-only-store switch. |
+| **`emails`** | | |
+| `store_name` | `""` (set from the seed call) | Subject/heading `{store_name}`, the `SendEmail` sender name, **and** the public shop name on `get-store-info`. Blank = Base44 sends as the app's name; semantics in [`emails.md`](./emails.md). Required on a first seed ([`../install/03-data.md`](../install/03-data.md)). |
+| `admin_recipients` | `[]` | Fallback notification addresses; empty falls back to the app's `admin`-role users. |
+| `<type>.enabled` / `.subject` / `.heading` / `.recipient` | enabled, blanks | Per-type overrides at the **top level** of the group (`emails.new_order.enabled`) — [`emails.md`](./emails.md). |
+
+## Writing a setting
+
+`values` is written **whole**: `update(id, { values })` replaces the object, so patch by spreading what is already there.
+
+```js
+const [rec] = await base44.entities["commerce.StoreSettings"].filter({ group_id: "inventory" });
+await base44.entities["commerce.StoreSettings"].update(rec.id, {
+  values: { ...rec.values, hold_stock_minutes: 30 },
+});
+```
+
+No admin function owns settings — it is direct CRUD (admin-only RLS) or the merchant's own Settings screens, where each group is one page. `commerce/seed-store` re-runs never clobber a group that exists, except for the arguments it is given explicitly (`store_name`, `currency`, `weight_unit`, `dimension_unit`), which always win.

package/src/commerce/admin/README.md

@@ -4,8 +4,11 @@ React admin UI for the Base44 commerce template. Copy this
 folder into a Base44 app built on the default template (Vite + React +
 Tailwind + shadcn/ui + React Router) to get a full store back office.
 
-> Install docs: [`.agents/skills/commerce/installation-guidelines.md`](../../../.agents/skills/commerce/installation-guidelines.md) · mounting & role setup: [`.agents/skills/commerce/post-installation.md`](../../../.agents/skills/commerce/post-installation.md) · architecture & operations: the commerce skill, [`.agents/skills/commerce/SKILL.md`](../../../.agents/skills/commerce/SKILL.md)
-> API references: [`.agents/skills/commerce/docs/api-admin.md`](../../../.agents/skills/commerce/docs/api-admin.md), [`.agents/skills/commerce/docs/api-storefront.md`](../../../.agents/skills/commerce/docs/api-storefront.md)
+> Docs live in the commerce skill, and every path below is **relative to that
+> skill folder** (`.agents/skills/commerce/` once installed): install, mounting
+> and role setup are `install/01-install.md`; the map for everything else is
+> `SKILL.md`; the API references are `docs/api-admin.md` and
+> `docs/api-storefront.md`.
 
 ## Mounting
 
@@ -39,7 +42,7 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    sample data when the store has no products yet. If `commerce/seed-store` was
    already run during installation — including when an agent generated a real
    catalog — the store counts as ready and this screen never shows; see
-   `.agents/skills/commerce/post-installation.md` §2.
+   the commerce skill's install/03-data.md.
 
 ## External touchpoints
 

package/src/commerce/admin/layout/AuthGuard.jsx

@@ -24,7 +24,7 @@ const AUTH_CHECK_TIMEOUT_MS = 8000;
 
 /**
  * Blocks the admin UI unless the caller is an authenticated user with
- * role === "admin". Do NOT weaken this check — see .agents/skills/commerce/post-installation.md.
+ * role === "admin". Do NOT weaken this check — see the commerce skill's install/01-install.md.
  * (Server-side RLS + requireAdmin() in functions enforce this independently.)
  *
  * Timing out resolves to **no user**, i.e. the sign-in screen — it never grants

package/src/commerce/admin/pages/products/Reviews.jsx

@@ -263,7 +263,7 @@ export default function Reviews() {
 /**
  * The one server-enforced review setting: everything else (login-gating,
  * verified-buyers-only, required ratings) is storefront policy — see
- * .agents/skills/commerce/references/reviews.md.
+ * the commerce skill's references/reviews.md.
  */
 function AutoApproveToggle() {
   const settings = useSettings();

package/src/commerce/admin/pages/settings/InventorySettings.jsx

@@ -51,7 +51,7 @@ export default function InventorySettings() {
             <p className="text-xs text-muted-foreground">
               Hold stock for unpaid orders for this many minutes. When the limit is reached, the
               pending order is cancelled and its stock released. Release runs opportunistically —
-              see .agents/skills/commerce/references/scheduled-work.md.
+              see the commerce skill's references/operations.md.
             </p>
           </div>
 

package/src/commerce/admin/pages/settings/PaymentsSettings.jsx

@@ -209,7 +209,7 @@ export default function PaymentsSettings() {
                   wiring one means implementing the four functions in
                   shared/commerce/card-payment.ts (rules, and a Stripe
                   implementation to paste, in
-                  .agents/skills/commerce/references/online-payments.md; the
+                  the commerce skill's references/online-payments.md; the
                   payment webhook is premade). Enabled without that, picking it
                   at checkout answers 503 no_card_payment_provider.
                   Deliberately not shown to the store operator — it's developer

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -7,7 +7,13 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { createStorefront, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import {
+  attributesLabel,
+  cartTotalsLines,
+  createStorefront,
+  storefrontErrorCode,
+  storefrontErrorMessage,
+} from "@/commerce/utils";
 
 /**
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
@@ -67,21 +73,37 @@ export function StorefrontProvider({ base44, store, children }) {
   // undefined = still loading, null = no cart yet, object = the priced view.
   const [cart, setCart] = useState(undefined);
   const [cartError, setCartError] = useState(null);
+  const [mutationError, setMutationError] = useState(null);
   const queue = useRef(Promise.resolve());
 
   /**
    * Run one cart call at a time, in order, and publish its returned view.
    * Serializing is what keeps rapid quantity clicks (or an address sync racing
    * an add-to-cart) from applying responses out of order.
+   *
+   * A failure is recorded in `mutationError` *and* re-thrown: the caller still
+   * gets its rejection, and a component that renders no error handling of its
+   * own (a bare quantity stepper) still has somewhere the message can show,
+   * instead of the failure vanishing into an unhandled rejection.
    */
   const runCart = useCallback((fn) => {
     const next = queue.current.catch(() => {}).then(fn);
     queue.current = next;
-    return next.then((view) => {
-      setCart(view ?? null);
-      setCartError(null);
-      return view ?? null;
-    });
+    return next.then(
+      (view) => {
+        setCart(view ?? null);
+        setCartError(null);
+        setMutationError(null);
+        return view ?? null;
+      },
+      (e) => {
+        setMutationError({
+          code: storefrontErrorCode(e) ?? "error",
+          message: storefrontErrorMessage(e),
+        });
+        throw e;
+      },
+    );
   }, []);
 
   /** Forget the cart locally (used after checkout consumes it). */
@@ -95,8 +117,8 @@ export function StorefrontProvider({ base44, store, children }) {
   }, [client, runCart]);
 
   const value = useMemo(
-    () => ({ client, info, infoError, cart, cartError, runCart, clearCart }),
-    [client, info, infoError, cart, cartError, runCart, clearCart],
+    () => ({ client, info, infoError, cart, cartError, mutationError, runCart, clearCart }),
+    [client, info, infoError, cart, cartError, mutationError, runCart, clearCart],
   );
   return <StorefrontContext.Provider value={value}>{children}</StorefrontContext.Provider>;
 }
@@ -157,23 +179,34 @@ export function useFormatMoney() {
 }
 
 /**
- * The shared cart — state plus every cart mutation. All consumers see the
- * same view; every action resolves to the fresh priced cart it published.
+ * The shared cart — state, decorated lines, and every cart mutation. All
+ * consumers see the same view; every action resolves to the fresh priced cart.
+ *
+ *   const { status, lines, totalsLines, notices, updateItem, removeItem } = useCart();
+ *   if (status === "loading") return <Skeleton />;
+ *   if (status === "empty")   return <EmptyBag />;
+ *   lines.map(line => …)   // line.attributesLabel, line.image, line.canIncrease
  *
- *   const { cart, loading, itemCount, addItem, updateItem, removeItem,
- *           applyCoupon, removeCoupon, refresh } = useCart();
+ * **Branch on `status`, not on `isEmpty`.** `isEmpty` is true while the cart is
+ * still loading (there are no items *yet*), so a page that renders its empty
+ * state from it flashes "your bag is empty" on every visit before the cart
+ * arrives. `status` separates the two: `"loading"` → `"empty"` | `"ready"`.
  *
- * - `cart` is `null` until something is added (render an empty state).
- * - `addItem(view.addToCart, quantity)` — pass the resolved `addToCart` from
- *   `resolveSelection`; a product with attributes is rejected without its
- *   `variation_id` (`400 variation_required`).
+ * - `lines` are `cart.items` decorated with what a renderer needs and would
+ *   otherwise re-derive: `attributesLabel` ("Size: 42 · Color: Ivory" — the raw
+ *   `attributes` is an **array** of `{name, option}`, never a map),
+ *   `image` normalized to `{src, alt}` or null, `purchasable` as a boolean with
+ *   `unavailableReason` beside it, and the quantity bounds.
+ * - `notices` normalizes `coupon_notices` + `removed_items` into one list —
+ *   render it, or a line that auto-dropped vanishes with no explanation.
+ * - `mutationError` is the last failed mutation (insufficient stock, an expired
+ *   cart), cleared on the next success. Mutations still reject, so
+ *   `useCartLine`/`useAddToCart` can handle failures locally.
  * - `applyCoupon(code)` resolves to `{ ok, cart }` or `{ ok: false, code,
  *   message }` — an invalid code is expected flow, not an exception.
- * - Render `cart.coupon_notices` / `cart.removed_items` when present: they
- *   say what auto-dropped and why.
  */
 export function useCart() {
-  const { client, cart, cartError, runCart } = useStorefrontState();
+  const { client, cart, cartError, mutationError, runCart } = useStorefrontState();
 
   const refresh = useCallback(() => runCart(() => client.getCart()), [client, runCart]);
   const addItem = useCallback(
@@ -203,13 +236,66 @@ export function useCart() {
     [client, runCart],
   );
 
+  const formatMoney = useFormatMoney();
   const items = cart?.items ?? [];
+  const loading = cart === undefined;
+
+  const lines = useMemo(
+    () =>
+      items.map((item) => {
+        // A cart line's `purchasable` is a RESULT object ({ ok, code, error }),
+        // not a boolean — truthiness alone would call every line purchasable.
+        const purchasable = item.purchasable?.ok ?? Boolean(item.purchasable);
+        // `sold_individually` is the only per-line ceiling the cart view
+        // carries; real stock limits surface as `insufficient_stock` from the
+        // server when a customer tries to exceed them.
+        const maxQuantity = item.sold_individually ? 1 : Infinity;
+        return {
+          ...item,
+          attributesLabel: attributesLabel(item.attributes),
+          image: item.image ? { src: item.image, alt: item.name ?? "" } : null,
+          maxQuantity,
+          canIncrease: item.quantity < maxQuantity,
+          canDecrease: item.quantity > 1,
+          purchasable,
+          unavailableReason: purchasable ? null : (item.purchasable?.error ?? null),
+        };
+      }),
+    [items],
+  );
+
+  const notices = useMemo(
+    () => [
+      ...(cart?.coupon_notices ?? []).map((n) => ({
+        kind: "coupon",
+        code: n.error_code ?? n.code ?? "coupon_invalid",
+        message: n.error ?? `Coupon ${n.code} is no longer valid.`,
+      })),
+      ...(cart?.removed_items ?? []).map((r) => ({
+        kind: "removed_item",
+        code: r.code ?? "unavailable",
+        message: r.reason ?? "An item is no longer available and was removed.",
+      })),
+    ],
+    [cart],
+  );
+
+  const totalsLines = useMemo(
+    () => (cart ? cartTotalsLines(cart, { formatMoney }) : []),
+    [cart, formatMoney],
+  );
+
   return {
     cart: cart ?? null,
-    loading: cart === undefined,
+    loading,
     error: cartError,
+    mutationError,
     itemCount: items.reduce((n, i) => n + (i.quantity || 0), 0),
     isEmpty: !items.length,
+    status: loading ? "loading" : items.length ? "ready" : "empty",
+    lines,
+    notices,
+    totalsLines,
     refresh,
     addItem,
     updateItem,