@base44/app-plugin-commerce 0.1.20 → 0.2.2

package/skills/commerce/references/catalog-rendering.md

@@ -0,0 +1,110 @@
+---
+stage: reference
+read_when: "You are asking which fields a card or a product page can actually show, or hit a variant edge case (unavailable combinations, attributes with no variations, price ranges, linkable selections)."
+skip_when: "The listing and product page render correctly from useProductList / useProduct and the render-model helpers — the quick start in ../install/02-storefront.md covers the happy path."
+forget_when: "Cards and the product page render the fields you intended, variant selection resolves to a variation, and add-to-cart succeeds."
+carry_forward:
+  - "There is no product `type` field: a non-empty `attributes[]` is what makes a product sell variants, and such a product is only sellable via a `variation_id`."
+  - "A variant parent's `price` is a FROM price — render it through productPrice/useProductPrice, never as the price."
+  - "Product images are objects `{src, name, alt}` and the array can be empty — go through productImages/normalizeImage and render a placeholder."
+---
+
+# Rendering the catalog: listing and product page
+
+Both storefront surfaces render the same catalog record from a different call:
+
+| View | Call | Hook | Returns |
+|---|---|---|---|
+| Listing / grid / search / ribbon & category pages | `commerce/storefront-catalog` `list-products` | `useProductList` | `{ products: [row…], page, per_page, has_next }` |
+| Product page | `commerce/storefront-catalog` `get-product` | `useProduct` | `{ product, variations, categories, ribbons, reviews, upsells, cross_sells }` |
+
+Request/response shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). You choose what belongs in each view — but you can only render what the call returns, and §1 is that boundary.
+
+## 1. Field availability
+
+A listing **row** is the product record itself (minus paywalled fields) plus resolved `ribbons`. `get-product` adds everything that needs a second read.
+
+| Data | `list-products` row | `get-product` | Notes |
+|---|---|---|---|
+| `id`, `name`, `slug`, `status` | ✅ | ✅ | No `type` field — see §2 |
+| `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | With variants the parent `price` is a *from* price — §2 |
+| `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`; every entry is an **object** — §2 |
+| `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
+| `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`productSpecs(product)` turns them into spec-table rows) |
+| **`ribbons`** (resolved), `ribbon_ids`, `category_ids` | ✅ | ✅ | Rows carry `{id, name}` ribbons; `get-product` returns the full records |
+| **`categories`** (resolved) | ❌ *ids only* | ✅ | §6 to add them to rows |
+| **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | Why a product with variants can't be fully priced from a row |
+| **`reviews`** (paged items + aggregates) | ❌ | ✅ | Rows still carry the aggregate numbers |
+| **`upsells`, `cross_sells`** (summaries) | ❌ | ✅ | `{id, name, slug, price, on_sale, image}` |
+| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** public — reached only through `commerce/storefront-account` `get-download` |
+
+## 2. Two shapes, and the three rules the code now owns
+
+There is **no product `type` field**. `attributes[]` tells the shapes apart:
+
+| Shape | Test | Card | Product page |
+|---|---|---|---|
+| **Single item** | `attributes` is empty | price, and Add to cart straight from the card if you want one | one Add to cart — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
+| **Sells variants** | `attributes` is non-empty | price **range or "From €19"**, never selectors — link through | one control per axis — §5 |
+
+A product with attributes is **only** sellable through a variant: `add-item` without a `variation_id` is `400 variation_required`, with no fall-back to the parent. So one with attributes but no variations is unsellable by design, not by accident (§5 covers rendering that state).
+
+Three rules used to be prose here and are now enforced by exports — use them and they can't drift between views:
+
+- **From-price.** `admin-products` (and the seeder) roll a parent's `regular_price`/`price`/`on_sale` up from the cheapest publishable variant on every save, so the parent price is real, sortable and filterable — but it is the **lowest** price, not *the* price. `productPrice(rowOrView, {formatMoney})` / `useProductPrice(rowOrView)` accept **either** a listing row or a `resolveSelection` view and return `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range on an unresolved page, the exact price once resolved.
+- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string, and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`), and an empty array is the *render your placeholder* signal — `useProductGallery` builds on them (`hasImages`). Passing the object itself to an `<img src>` fails the load and shows the placeholder for every product in the store.
+- **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is a spec table — never a selector, never a ribbon.
+
+## 3. What each view renders
+
+**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page — like every other piece of storefront UI, the card is entirely yours to design.
+
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCartButton`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
+
+## 4. Ribbons — in **both** views
+
+Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categories are the hierarchical spine. Generated storefronts routinely omit ribbons entirely. Don't.
+
+- **Listing rows carry resolved `ribbons`**, so a card renders them with no extra call; the product page renders the top-level `ribbons` near the metadata, lighter than the breadcrumb. One or two per card is useful, more is noise, and an empty array means render nothing — never a dangling "Ribbons:" label.
+- **Every ribbon links to a filtered listing** — `list-products` with `ribbon_id`, never a dead label. A ribbon has no slug, so key the URL on its id (`/shop?ribbon=<id>`) to keep the page shareable across reloads.
+- **Offer ribbons as a filter** from `useRibbons()` / `list-ribbons`, which hides ribbons no published product carries and gives a `count` for labels like "Gift (12)". `ribbon_id` stacks with `category_id`, price, `on_sale`, `featured`, `in_stock_only`.
+- Ribbons are not breadcrumbs and never variant options — a size or colour is an `attribute`.
+
+## 5. Variant selection
+
+The one interaction agents reliably get wrong. `variantAxes(view, pick)` hands you the render-ready model that encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise that hides the product's structure), and an option that isn't buyable renders **disabled, not removed** (`o.disabled`; `o.outOfStock` stays visible, just marked). Map it to any control — buttons, swatches, dropdowns — and call `o.pick()` on select.
+
+Underneath, `useProduct` composes the framework-free helpers in `src/commerce/utils/variants.js` — `defaultSelection` → `selectOption` on a click → `resolveSelection` for the view. Every `product.attributes[]` entry is an **axis** in `position` order; every `variations[]` record is one combination. Bind the UI to `view`, not to `product.*`, or a selection changes nothing:
+
+| `view` field | Binds to |
+|---|---|
+| `axes` | the controls: `[{ key, name, attribute_id, options[] }]`, dead options already dropped |
+| `availability[axisKey][option]` | `"available"` / `"out_of_stock"` / `"unavailable"` (constants `OPTION_*`) |
+| `display` | image, price, `regular_price`, `on_sale`, SKU, stock, weight/dimensions, description — variation-first with parent fallback; `display.image` is normalized or `null` |
+| `priceRange` | `{min, max, on_sale, count}` while the selection is incomplete — render via `useProductPrice(view)` |
+| `complete` / `missingAxes` | the button label: `Select a ${view.missingAxes[0]?.name}` |
+| `purchasable` / `addToCart` | gate **Add to cart** on `purchasable`, send `addToCart` (`{product_id, variation_id}`, or `null`) |
+| `variation` / `candidates` / `isVariable` / `selection` | the record itself, the variations still reachable, and the state the selector renders from |
+
+Three decisions the helpers can't make for you:
+
+- **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → visible and labelled. `onbackorder` counts as available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
+- **Incomplete selection.** Show the range from `useProductPrice(view)` — never `€0`, never the bare parent price — and keep Add to cart disabled with a hint at what's missing.
+- **Linkability.** `useProduct` mirrors the selection into the URL (`?color=Ivory`) and hydrates from it, so a variant is shareable and survives a reload; `selectionToParams`/`selectionFromParams` do a custom round-trip, and `selectionForVariation` hydrates controls from a cart line or an `?variation=` link.
+
+**Attributes but no usable variations** — what attaching an attribute and stopping leaves behind — deliberately gets no parent fallback, because `add-item` would reject it: empty `axes[].options`, `purchasable: false`, `addToCart: null`. Render it as unavailable rather than painting empty selector groups, and guard the label (with no attributes at all `missingAxes[0]?.name` is `undefined` → "Select a undefined").
+
+**Add to cart** goes through `useAddToCart()`, which never throws and maps the codes: `variation_required` (a page bug — empty `variation_id` on a product with attributes), `out_of_stock` / `insufficient_stock`, and `variation_not_found` (the catalog changed under the page → `shouldReload: true`, refetch). `product.sold_individually` caps quantity at 1, already reflected in `useProduct().maxQuantity`. Two behaviors that matter only if you hand-roll the view model: non-publishable variations never leak an option into the UI, and an empty `option` on a variation axis means **"any"**.
+
+## 6. Adding a `get-product`-only field to the listing
+
+If the store needs something a row doesn't carry — resolved categories are the common one — resolve it **in the listing call**, never with `get-product` per card (N requests for one grid). `list-products` resolves its page slice through a helper in `base44/functions/commerce/storefront-catalog/entry.ts`:
+
+```ts
+const pageItems = await withRibbons(sr, products.slice(start, start + perPage).map(publicProduct));
+```
+
+`withRibbons` reads the taxonomy **once per request** and maps ids onto the rows — not once per row. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to fields the UI renders; a listing payload is served on every browse.
+
+Don't add `variations` to every row — the heaviest read in the catalog, and a grid doesn't need it; if cards must show true ranges, precompute `price_min`/`price_max`. And don't relax entity RLS to read the catalog from the client — it is admin-only by design ([`guest-access-security.md`](./guest-access-security.md)); widen the function's response instead.

package/skills/commerce/references/emails.md

@@ -1,14 +1,51 @@
+---
+stage: reference
+read_when: "You are changing which transactional emails go out, their copy, who receives them, or investigating a mail that didn't arrive."
+skip_when: "The store's default emails are fine — all ten order emails are wired and enabled out of the box."
+forget_when: "The email in question sends to the intended recipient, or its EmailLog row explains why it didn't."
+carry_forward:
+  - "Per-type email overrides live at the TOP level of the emails settings group, keyed by type id (emails.new_order.enabled) — never nested."
+  - "emails.store_name is both the {store_name} in subjects and the sender name, and it is the public shop name on get-store-info."
+---
+
 # Emails
 
-Transactional email is sent via `base44.integrations.Core.SendEmail` from the shared `emails.ts`. Ten order emails are wired to the lifecycle (see the side-effect matrix in [`.agents/skills/commerce/docs/api-admin.md`](../docs/api-admin.md)): `new_order`, `cancelled_order`, `failed_order`, `on_hold_order`, `processing_order`, `completed_order`, `refunded_order`, `partial_refund`, `customer_invoice`, `customer_note`. `reset_password` and `new_account` are handled by **Base44 auth**, not this template.
-
-- Per-type enable/subject/heading/recipient/additional_content overrides live at the **top level** of the `emails` StoreSettings group, keyed by type id (`emails.new_order.enabled`) — that is the path `shared/commerce/emails.ts` reads. Editable in Settings → Emails; blank = built-in default. Don't nest them under a sub-object: the backend won't see them.
-- Admin notifications (`new_order`, `cancelled_order`, `failed_order`) resolve in three steps: the per-type `recipient` if it holds an address, else `emails.admin_recipients`, else — at send time — **the app's users with `role: "admin"`** (`sr.entities.User.filter({role:"admin"})`, memoized per isolate). Both settings accept a comma-separated list and drop blank entries, so a cleared per-type override falls back rather than sending to an empty address. Nothing is seeded: a fresh store notifies its admin users until someone sets explicit recipients, and promoting an admin is enough to add them. Only when there is also no admin user does the email go nowhere, logged in `commerce.EmailLog` with `success: false` and an `error` naming what was empty. Settings → Emails shows the addresses actually in effect (via `commerce/admin-tools` `admin-email-recipients`).
-- Stock notifications (`low_stock`, `out_of_stock`) sit in the same Settings → Emails list and are configured per type like the rest (`emails.low_stock.enabled`, `emails.low_stock.recipient`). Recipients resolve exactly like the admin order emails: per-type `recipient`, else `emails.admin_recipients`, else the app's admin users — comma-separated lists reach every address. Subject and body are generated (product name, SKU, remaining stock), so there are no subject/heading overrides for these two.
-- The **store name** is `emails.store_name` — one setting, used for both the `{store_name}` in subjects/headings and the sender name. It lives nowhere else, but it is not email-only: `storefrontSafeSettings()` publishes it as `settings.store_name` on `get-store-info`, so it is also the public shop name. `commerce/seed-store` fills it from the `store_name` it is passed, and Settings → Emails is where a merchant changes it.
-- It seeds **blank on purpose**: a blank name means `SendEmail` is called without `from_name`, in which case **Base44 sends as the app's name** (verified: an app named *Canvas* with it blank delivered mail from "Canvas"). So the sender is the app name unless the store overrides it — one place to rename, and no hardcoded default.
-- That fallback does **not** reach subjects or headings: those are rendered by this template, which has no access to the app name, so a store with no `emails.store_name` sends `New order #1002` rather than `[Canvas]: New order #1002`. Set the store name if you want it in the subject line.
-- Subjects and headings tolerate a **blank** store name: `{store_name}` substitution drops empty brackets and collapses the gap, so an unnamed store sends `New order #1002`, never `[]: New order #1002`.
-- `emails_sent[]` on each order dedupes lifecycle emails so a re-entered status won't re-send.
-- Deliverability (SPF/DKIM) and the sending address depend on your Base44 email configuration — the store only sets the sender *name*. Every send is recorded in the `commerce.EmailLog` entity.
-- **Reading `commerce.EmailLog`:** one row per address per attempt. `target` is `admin` or `customer` — the same split the Recipient column shows in Settings → Emails (stock notifications count as `admin`). `order_id` is the id **users are shown**: the `order_number` from the admin Orders list and every email subject (`#1023` → `1023`). The internal Order record id is in `order_record_id`, which is what the admin routes on. Rows written before these fields existed still carry the record id in `order_id` and have no `target`; they are not backfilled.
+Transactional email is sent via `base44.integrations.Core.SendEmail` from the shared `emails.ts`.
+
+## Email types
+
+Ten order emails are wired to the lifecycle (see the side-effect matrix in [`../docs/api-admin.md`](../docs/api-admin.md)): `new_order`, `cancelled_order`, `failed_order`, `on_hold_order`, `processing_order`, `completed_order`, `refunded_order`, `partial_refund`, `customer_invoice`, `customer_note`. `reset_password` and `new_account` are handled by **Base44 auth**, not this kit.
+
+Two stock notifications — `low_stock`, `out_of_stock` — sit in the same Settings → Emails list. Their subject and body are generated (product name, SKU, remaining stock), so they have no subject/heading overrides.
+
+`emails_sent[]` on each order dedupes lifecycle emails, so a re-entered status won't re-send.
+
+## Per-type overrides
+
+Enable/subject/heading/recipient/additional_content overrides live at the **top level** of the `emails` StoreSettings group, keyed by type id (`emails.new_order.enabled`) — that is the path `shared/commerce/emails.ts` reads. Editable in Settings → Emails; blank = built-in default. **Don't nest them under a sub-object: the backend won't see them.** The stock types take `enabled` and `recipient` only.
+
+## Recipients
+
+- **Admin notifications** (`new_order`, `cancelled_order`, `failed_order`) resolve in three steps: the per-type `recipient` if it holds an address, else `emails.admin_recipients`, else — at send time — **the app's users with `role: "admin"`** (`sr.entities.User.filter({role:"admin"})`, memoized per isolate). Both settings accept a comma-separated list and drop blank entries, so a cleared per-type override falls back rather than sending to an empty address.
+- Nothing is seeded: a fresh store notifies its admin users until someone sets explicit recipients, and promoting an admin is enough to add them. Only when there is also no admin user does the email go nowhere — logged with `success: false` and an `error` naming what was empty. Settings → Emails shows the addresses actually in effect (via `commerce/admin-tools` `admin-email-recipients`).
+- **Stock notifications** resolve identically: per-type `recipient`, else `emails.admin_recipients`, else the app's admin users.
+
+## The store name
+
+`emails.store_name` is one setting doing three jobs: the `{store_name}` in subjects/headings, the `SendEmail` sender name, and — via `storefrontSafeSettings()` — the public shop name published as `settings.store_name` on `get-store-info`. `commerce/seed-store` fills it from the `store_name` it is passed; Settings → Emails is where a merchant changes it.
+
+It seeds **blank on purpose**: a blank name means `SendEmail` is called without `from_name`, in which case **Base44 sends as the app's name** (verified: an app named *Canvas* with it blank delivered mail from "Canvas"). So the sender is the app name unless the store overrides it — one place to rename, and no hardcoded default.
+
+That fallback does **not** reach subjects or headings: those are rendered by this kit, which has no access to the app name. Subjects and headings tolerate a blank store name — `{store_name}` substitution drops empty brackets and collapses the gap — so an unnamed store sends `New order #1002` rather than `[Canvas]: New order #1002`, and never `[]: New order #1002`. Set the store name if you want it in the subject line.
+
+## Deliverability
+
+SPF/DKIM and the sending **address** depend on your Base44 email configuration — the store only sets the sender *name*.
+
+## The email log
+
+Every send is recorded in `commerce.EmailLog`: one row per address per attempt.
+
+- `target` is `admin` or `customer` — the same split the Recipient column shows in Settings → Emails (stock notifications count as `admin`).
+- `order_id` is the id **users are shown**: the `order_number` from the admin Orders list and every email subject (`#1023` → `1023`). The internal Order record id is in `order_record_id`, which is what the admin routes on.
+- Rows written before these fields existed still carry the record id in `order_id` and have no `target`; they are not backfilled.

package/skills/commerce/references/guest-access-security.md

@@ -1,18 +1,31 @@
+---
+stage: reference
+read_when: "You are adding anything to a storefront function, writing a new one, or deciding what a guest may reach — wishlists, loyalty, saved details, subscriptions, tickets."
+skip_when: "You are only calling the shipped functions from UI you build; they already enforce their own guards."
+forget_when: "The code you added derives identity from the session, gates owned data on requireUser, and returns nothing about anyone else."
+carry_forward:
+  - "Identity comes from the session, never the request body: getCallerUser/requireUser/ownsEmail in shared/commerce/auth.ts."
+  - "All entities are admin-only RLS; storefronts read through commerce/storefront-* functions (service role) — never relax a catalog entity's read rule."
+  - "cart_token and order_key are bearer credentials for ONE record each."
+---
+
 # Guest access & security
 
-- Storefront functions are **public** (anonymous invocation); confirm your app allows unauthenticated function calls. Checkout accepts guests unconditionally — there is no store setting that forces login. A login-required store has to enforce that in the shopfront you build (and, if it must not be bypassable, by adding the check to `commerce/storefront-checkout` `place-order`).
+## The identity model
+
+- Storefront functions are **public** (anonymous invocation); confirm your app allows unauthenticated function calls. Checkout accepts guests unconditionally — there is no store setting that forces login. A login-required store enforces that in the shopfront you build, and, if it must not be bypassable, by adding the check to `commerce/storefront-checkout` `place-order`.
 - **All entities are admin-only RLS**, including the catalog (Product, ProductVariation, categories, tax/shipping config, payment gateways). Storefronts read the catalog through `commerce/storefront-catalog` (service role), never by querying entities directly with the client SDK — a direct read from a non-admin is rejected by the backend. This is deliberate: a world-readable catalog row exposes more than a shopper should see (`downloads[].file_url`, draft/hidden products, stock and sales internals, gateway `settings` such as the offline gateway's bank details). Do **not** relax any catalog entity's read RLS to `true`; if a shopfront needs a field, surface it through the storefront function instead.
 - The storefront catalog function strips the paywalled fields (`downloads`, `download_limit`, `download_expiry`) from every product/variation it returns. Downloadable files are reached only through `commerce/storefront-account` `get-download`, which enforces ownership, download limits, expiry and short-lived signed URLs — keep that the only path to a `file_url`.
 - `cart_token` and `order_key` are **bearer credentials** — possession grants access to that cart/order. Always serve over HTTPS; don't log them; treat them like secrets.
 - Carts and orders have admin-only RLS; customers never touch those entities directly — all access is mediated by `commerce/storefront-*` functions using the service role after verifying the caller.
-- The admin side has three enforcement layers (UI guard, entity RLS, `requireAdmin()` function guard) — see [`post-installation.md`](../post-installation.md); never weaken them.
+- The admin side has three enforcement layers; never weaken them ([`../install/01-install.md`](../install/01-install.md)).
 
 ## Rules for anything you add
 
 The storefront functions run as the service role, so RLS is not protecting the caller from itself — these guards are. Keep them when you extend a function, and follow them in a new one.
 
-- **Identity comes from the session, never from the body.** An email in the payload is a claim, not a credential. Use `getCallerUser(base44)` and `requireUser(user)` from `shared/commerce/auth.ts`, and `ownsEmail(user, email)` before writing to anything keyed on someone's address. This is why `submit-review` requires a signed-in customer (a `reviewer_email` field is ignored) and why a guest checkout attaches to an existing `commerce.Customer` without rewriting its saved name and addresses — otherwise knowing a customer's email would be enough to redirect where their next order ships, or to post a review in their name.
-- **Anything a person owns needs authentication, not just an email.** If you add wishlists, loyalty, saved payment details, subscriptions or support tickets, gate the write on `requireUser` and derive the owner from `user.email` / `user.id`. Guest access is only ever by bearer token (`cart_token`, `order_key`) for the *one* record that token names. (Reviews are the deliberate exception — public by email, moderated instead of authenticated; a session email still always beats the payload.)
-- **Only the payment provider can say an order is paid.** Never transition an order to `processing` because a request said so — no `paid: true` flag, no `transaction_id` from a client, no `?payment=success` in a return URL. Go through `confirmCardPayment()`, which asks the provider about the payment reference stored on the order. Wiring a provider means implementing the four functions in `shared/commerce/card-payment.ts` (see [`online-payments.md`](./online-payments.md)), never a new "confirm" endpoint.
+- **Identity comes from the session, never from the body.** An email in the payload is a claim, not a credential. Use `getCallerUser(base44)` and `requireUser(user)` from `shared/commerce/auth.ts`, and `ownsEmail(user, email)` before writing to anything keyed on someone's address. This is why a signed-in caller's session email always beats a `reviewer_email` in the payload, and why a guest checkout attaches to an existing `commerce.Customer` without rewriting its saved name and addresses — otherwise knowing a customer's email would be enough to redirect where their next order ships, or to post a review in their name.
+- **Anything a person owns needs authentication, not just an email.** If you add wishlists, loyalty, saved payment details, subscriptions or support tickets, gate the write on `requireUser` and derive the owner from `user.email` / `user.id`. Guest access is only ever by bearer token (`cart_token`, `order_key`) for the *one* record that token names. (Reviews are the deliberate exception — public by email, moderated instead of authenticated; a session email still always wins.)
 - **A bearer token authorizes one record.** `order_key` gets you *that* order; it is not a licence to name someone else's ids in the same request. Match every id in the payload back to the record the token opened.
 - **Don't return more than the caller asked about.** Serialize customer-facing orders through `serializeOrderForCustomer()`, and don't let a response reveal whether another person's email exists, bought something, or has an account — a boolean in an error body is an enumeration oracle.
+- **Never mark an order paid from a request.** Only the payment provider can say so, through `confirmCardPayment()`/`checkCardPaymentPaid` — no `paid: true` flag, no client `transaction_id`, no `?payment=success`, and never a new "confirm" endpoint ([`online-payments.md`](./online-payments.md)).

package/skills/commerce/references/online-payments.md

@@ -1,172 +1,72 @@
+---
+stage: reference
+read_when: "The store opted into card payments and you are wiring the provider NOW."
+skip_when: "The store takes offline payments (the default) — nothing here applies; the decision itself lives in ../install/03-data.md."
+forget_when: "A test payment reaches /order-received as paid, or the provider file is copied and the `card` gateway is enabled."
+carry_forward:
+  - "Wiring a provider = replace shared/commerce/card-payment.ts WHOLE (copy the shipped card-payment.<provider>.ts over it) — a partial edit breaks every commerce function's deploy with duplicate exports."
+  - "Stripe: the shipped card-payment.stripe.ts is used as-is once the app is connected to Stripe — connecting is outside the kit. Enabling the `card` gateway is the seed call."
+  - "Only the provider can say an order is paid: confirmation always goes through checkCardPaymentPaid against the provider's API."
+---
+
 # Online (card) payments
 
-The store ships with a **Credit card** checkout option (`commerce.PaymentGateway` slug `card`) and everything around it already built — order creation, totals, stock holds, the two idempotent confirmation paths (customer return + provider webhook), payment links for unpaid orders, refund records, emails, and the admin's payment panel.
+The kit ships a **Credit card** checkout option (`commerce.PaymentGateway` slug `card`) with everything around it built — order creation, totals, stock holds, the two idempotent confirmation paths (customer return + provider webhook), payment links for unpaid orders, refund records, emails, and the admin's payment panel.
 
-What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal, Adyen, a local PSP…) means implementing **one file** — `base44/shared/commerce/card-payment.ts`, four functions — and nothing else: no entity is touched, no caller or UI needs editing, and the payment webhook *function* is premade (it calls this file's `parseWebhook`).
+What it does **not** ship is a live provider. Wiring one means **one file** — `base44/shared/commerce/card-payment.ts`, four functions — and nothing else: no entity is touched, no caller or UI needs editing, and the payment webhook *function* is premade (it calls this file's `parseWebhook`).
 
-**Does this store even need a provider?** Card payments are **optional and off by default**: `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code at all) and leaves the **`card`** gateway disabled. **Enable cards only if this file is implemented, or is about to be in the same stretch of work** — an enabled card option with no provider behind it answers `503 no_card_payment_provider` at checkout, so the gateway switch (seed `payment_methods`) and this file always move together. [`post-installation.md` §4.1](../post-installation.md#41-off-by-default--enable-only-with-a-provider-wired) has the rule and the timing (short version: a fine thing to add, but at the end of a build, not the start — nothing depends on it).
+Card payments are **off by default** and are the last thing to add, never the first — the rule, the timing and the decision table live in [`../install/03-data.md`](../install/03-data.md). Everything below assumes that decision is made.
 
 | Function | Backs |
 |---|---|
-| `createCardPayment` | checkout + payment links: make a hosted payment page for `order.total`, return `{ url, reference }`, and attach `order.id`/`order.order_key` to the payment's metadata |
-| `checkCardPaymentPaid` | confirmation: ask the provider whether `reference` was paid **and is the payment for this order** — used by the return page, the webhook and the admin's "Check payment" |
-| `refundCardPayment` | admin refunds through the provider (optional — leave the stub to keep refunds manual) |
-| `parseWebhook` | webhook validation: name the order a provider event is about (from the echoed metadata), and vouch `paid: true` **only** after verifying the request signature over the raw body bytes |
-
-**Wiring a payment provider?** Whichever one the store chose, the job is the same: implement those four functions against its API, following the rules on this page. As a worked example, [a complete Stripe implementation](#reference-implementation--stripe) sits at the bottom of the page — with its secret and webhook-endpoint steps — usable as-is if Stripe happens to be the provider, and as a model of the four contracts if it isn't. It is a reference for one common choice, **not a bundled provider**: no provider ships with the template.
+| `createCardPayment(sr, order, {successUrl, cancelUrl, customerEmail})` | checkout + payment links: a hosted page for `order.total`, returning `{ url, reference }`, with `order.id`/`order.order_key` on the payment's metadata |
+| `checkCardPaymentPaid(sr, order, reference)` | confirmation: ask the provider whether `reference` was paid **and is the payment for this order** — the return page, the webhook and the admin's "Check payment" |
+| `refundCardPayment(sr, order, {reference, amount, currency, reason})` | admin refunds through the provider (optional — leave the stub, refunds stay manual) |
+| `parseWebhook(req, payload)` | name the order a provider event is about; vouch `paid: true` **only** after verifying the signature over the raw body |
 
-The card option ships **disabled**, so on a default store none of this is customer-visible. Where the gateway has been enabled without the file, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods) — implement the file, or switch the option back off in Settings → Payments. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
+## Stripe: copy the shipped file
 
-## How the premade flow works
+The kit ships a complete, ready-to-use Stripe implementation at **`base44/shared/commerce/card-payment.stripe.ts`**. There is nothing to transcribe and nothing to fill in — wire it by copying it over the stub:
 
-1. **Checkout** (`commerce/storefront-checkout` `place-order` with the `card` gateway): the order is created `pending`, `createCardPayment(sr, order, {successUrl, cancelUrl, customerEmail})` is called, the returned `reference` is stored on the order (`_payment_reference` meta), and the customer is redirected to `url`. The return URLs already carry `order_id`, `order_key` and `payment=success|cancel`.
-2. **Confirmation — two idempotent paths**, whichever runs second is a no-op:
-   - **Customer return**: the `/order-received` page calls `commerce/payments` `complete-return`, which runs `checkCardPaymentPaid(sr, order, reference)` and, when true, moves the order to `processing` (stock/email/webhook side-effects fire from the transition).
-   - **Webhook**: register `commerce/payment-webhook`'s URL with the provider — it covers the buyer who pays and closes the tab. The function is **premade** and never trusts an event body on its own: it hands the raw request to your `parseWebhook`, which names the order from the `order_id`/`order_key` metadata `createCardPayment` attached. A `paid: false` event is an unverified *nudge* — payment is then verified through `checkCardPaymentPaid` against the provider's API, which is why **no signing secret is needed**: a forged event can at worst trigger a re-check, never mark an order paid, and the `order_key` match stops an event being pointed at another order. `paid: true` is trusted directly and is therefore only allowed after real signature verification.
-3. **Payment links**: `commerce/payments` `create-link` mints a fresh page for any unpaid order via the same `createCardPayment` — used by the admin's payment-link button and the order-received page's "Pay now".
-4. **Refunds**: `commerce/admin-refunds` with `refund_payment: true` calls `refundCardPayment` **before** writing the local record (a failed provider refund writes nothing). While unimplemented it answers `501 card_refund_not_implemented` — record the refund without `refund_payment` and return the money from the provider's own dashboard.
+```js
+fs.copyFileSync(
+  "base44/shared/commerce/card-payment.stripe.ts",
+  "base44/shared/commerce/card-payment.ts",
+);
+```
 
-## Implementation rules
+…and **enable the gateway**: `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }`. The `card` row is seeded off, so that call is what makes card payment visible at checkout — the usual reason a wired provider "doesn't show up".
 
-- **Replace `card-payment.ts` whole** — one write of the full new file, never a `find_replace` into the shipped stub: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors ("Multiple exports with the same name …"); the fix is always to rewrite the file whole.
-- **Credentials** come from backend secrets/env (`Deno.env.get(...)`) — never from an entity, never from the client. On Base44, env vars are injected at deploy time; after adding a secret, redeploy the backend functions so they can see it.
-- **Which methods the store offers is seed data** — `commerce/seed-store`'s `payment_methods` (e.g. `["offline", "card"]`) enables the listed gateways and disables the rest; don't edit `commerce.PaymentGateway` records to turn methods on or off. Omitting it means offline-only, cards off — so **enabling the card gateway is part of wiring a provider**, not a separate concern: a correct `card-payment.ts` is invisible at checkout until that call runs, and that call without the file gives customers a `503`.
-- **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference`; never return true because a request claimed it. It should also check the payment **names this order** (compare the payment's metadata `order_id` to `order.id`) — that stops a reference to some other, genuinely paid payment being replayed against a different order.
-- **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` + `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against.
-- **`parseWebhook` never trusts a raw body.** Return `paid: false` (the verify-via-API nudge) unless you verified the provider's signature over the raw payload bytes; set `reference` only from a verified event, otherwise leave it unset so the premade flow uses the reference stored on the order at checkout.
-- **Amounts**: `order.total` is in display units (e.g. `12.34`) with `order.currency`; convert to the provider's minor units yourself if it needs them.
-- The shared helpers in `base44/shared/commerce/payments.ts` (return-URL building, `confirmCardPayment`, reference bookkeeping) are premade — don't duplicate or bypass them.
+That is the whole of it. The file expects the app to be connected to Stripe and reads the secret key that connection publishes; **connecting the app is outside this kit and not described here.** Nothing in the file needs filling in, and no key belongs in the code. A missing key is not silent — checkout answers `503 no_card_payment_provider`.
 
-## `parseWebhook` in depth
+A kit update re-copies `shared/commerce/` and restores the stub — re-run the copy after updating. A different provider ships the same way (`card-payment.<provider>.ts` beside the stub); until one does, implement the four functions against its API per the rules below, with the Stripe file as the worked model.
 
-`parseWebhook(req, payload)` lives in `card-payment.ts` with the other three; `commerce/payment-webhook` (the function file) is premade and calls it with the raw request and the raw body — the exact bytes, so signature schemes work. It returns `CardWebhookEvent | null`:
+## How the premade flow works
 
-- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret; the premade flow verifies via `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction. This is what the Stripe implementation below does.
-- **The signature-verified fast path** (optional): verify the provider's signature over the raw `payload` bytes (Stripe: `constructEventAsync` with a webhook signing secret) and return `paid: true` with the event's `reference` for a verified successful payment; the premade code then trusts it without the API round-trip. `paid: true` from an unverified body is the one way to break this design — never do it.
-- Return **`null`** for events that aren't about a payment for one of this store's orders; the function answers 200 so the provider doesn't retry.
+1. **Checkout** (`place-order` with the `card` gateway): the order is created `pending`, `createCardPayment` runs, the returned `reference` is stored on the order (`_payment_reference` meta), and the customer is redirected to `url`. The return URLs already carry `order_id`, `order_key` and `payment=success|cancel`.
+2. **Confirmation — two idempotent paths**, whichever runs second is a no-op: the **customer return** (`/order-received` calls `commerce/payments` `complete-return`, which runs `checkCardPaymentPaid` and on true moves the order to `processing`, firing the stock/email/webhook side-effects — `useOrderReturn` is that page in one hook), and the **webhook**, which covers the buyer who pays and closes the tab.
+3. **Payment links**: `commerce/payments` `create-link` mints a fresh page for any unpaid order through the same `createCardPayment` — the admin's payment-link button and order-received's "Pay now".
+4. **Refunds**: `commerce/admin-refunds` with `refund_payment: true` calls `refundCardPayment` **before** writing the local record (a failed provider refund writes nothing). While unimplemented it answers `501 card_refund_not_implemented` — record the refund without `refund_payment` and return the money from the provider's dashboard.
 
-Everything after `parseWebhook` — order lookup, the `order_key` match, idempotent confirmation, order progression — is premade either way.
+With the gateway enabled and no provider behind it, picking Credit card answers `503 no_card_payment_provider` — implement the file, or switch the option off in Settings → Payments. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions and the operator moves it on when the money arrives. Those need no code, and the admin can add more of them.
 
-## Reference implementation — Stripe
-
-**A worked example, not a bundled provider**: the template ships with no provider at all, and Stripe is one option among many (PayPal, Adyen, a local PSP — the four functions are the same shape against any API). Paste this in when Stripe is the provider the store actually chose; read it as a model of the four contracts when the provider is something else. Either way, only once §4.1's rule says cards are wanted at all.
-
-Overwrite `base44/shared/commerce/card-payment.ts` with this **as one whole-file write** (never `find_replace` into the stubs — see *Implementation rules* above):
-
-```ts
-// base44/shared/commerce/card-payment.ts — Stripe implementation
-import Stripe from "npm:stripe@18";
-import { HttpError } from "./auth.ts";
-
-export interface CardPaymentPage {
-  url: string;        // where the customer goes to pay
-  reference: string;  // the provider's id for this payment, stored on the order
-}
-
-const stripe = () => {
-  const key = Deno.env.get("STRIPE_SECRET_KEY");
-  if (!key) {
-    throw new HttpError(503, "Card payments are not configured — the STRIPE_SECRET_KEY secret is missing.", "no_card_payment_provider");
-  }
-  return new Stripe(key);
-};
-
-// Stripe amounts are in minor units; these currencies have none.
-const ZERO_DECIMAL = new Set(["BIF","CLP","DJF","GNF","JPY","KMF","KRW","MGA","PYG","RWF","UGX","VND","VUV","XAF","XOF","XPF"]);
-const minorUnits = (amount: number, currency: string) =>
-  Math.round(Number(amount) * (ZERO_DECIMAL.has(String(currency).toUpperCase()) ? 1 : 100));
-
-export async function createCardPayment(
-  _sr: any,
-  order: any,
-  opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
-): Promise<CardPaymentPage> {
-  // order_id + order_key in the metadata is how the premade payment-webhook
-  // names the order when Stripe's event arrives — keep it on both objects.
-  const metadata = { order_id: String(order.id), order_key: String(order.order_key) };
-  const session = await stripe().checkout.sessions.create({
-    mode: "payment",
-    line_items: [{
-      quantity: 1,
-      price_data: {
-        currency: String(order.currency || "USD").toLowerCase(),
-        product_data: { name: `Order #${order.order_number}` },
-        unit_amount: minorUnits(order.total, order.currency),
-      },
-    }],
-    customer_email: opts.customerEmail || undefined,
-    metadata,
-    payment_intent_data: { metadata },
-    success_url: opts.successUrl,
-    cancel_url: opts.cancelUrl,
-  });
-  if (!session.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
-  return { url: session.url, reference: session.id };
-}
-
-export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
-  const session = await stripe().checkout.sessions.retrieve(reference);
-  // The payment must be for THIS order — stops a reference to some other
-  // (paid) session being replayed against a different order.
-  return session.payment_status === "paid" && session.metadata?.order_id === String(order.id);
-}
-
-export async function refundCardPayment(_sr: any, _order: any, opts: {
-  reference: string; amount: number; currency: string; reason?: string;
-}): Promise<{ refund_id: string }> {
-  const session = await stripe().checkout.sessions.retrieve(opts.reference);
-  if (!session.payment_intent) {
-    throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
-  }
-  const refund = await stripe().refunds.create({
-    payment_intent: String(session.payment_intent),
-    amount: minorUnits(opts.amount, opts.currency),
-  });
-  return { refund_id: refund.id };
-}
-
-/** What parseWebhook distills an event into — the premade webhook's contract. */
-export interface CardWebhookEvent {
-  order_id: string;
-  order_key: string;
-  paid: boolean;       // true only after signature verification — never from a raw body
-  reference?: string;  // only if signature-verified; otherwise the order's stored reference is used
-}
-
-/**
- * Stripe webhook events. The event body is never trusted: this only names
- * the order (from the metadata createCardPayment attached) and returns
- * paid: false, so the premade webhook verifies against Stripe's API through
- * checkCardPaymentPaid — a forged call can never mark an order paid, and no
- * signing secret is needed. (Optional fast path that skips the API
- * round-trip: verify the signature instead — references/online-payments.md.)
- */
-export async function parseWebhook(_req: Request, payload: string): Promise<CardWebhookEvent | null> {
-  let event: any;
-  try { event = JSON.parse(payload); } catch { return null; }
-  const metadata = event?.data?.object?.metadata;
-  if (!metadata?.order_id || !metadata?.order_key) return null;
-  return { order_id: String(metadata.order_id), order_key: String(metadata.order_key), paid: false };
-}
-```
+## Implementation rules
 
-Then the credential and the webhook endpoint:
+For a **custom** provider (the shipped files already obey all of these):
 
-1. **Secret**: the user's Stripe **secret key**, stored as the `STRIPE_SECRET_KEY` app secret (backend env — never in code, never in an entity). Test keys (`sk_test_…`) work end to end.
-2. **Webhook endpoint**: register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for `checkout.session.completed`. There is **no signing secret to store** — events are nudges, verified against Stripe's API. One call with the same secret key (or the user does it in the Stripe dashboard):
+- **Write `card-payment.ts` whole** — one write of the complete file, never a `find_replace` into the stub: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors ("Multiple exports with the same name …"). The fix is always the whole-file write — which is also why the shipped provider files exist.
+- **Credentials come from backend env** (`Deno.env.get(...)`) — never an entity, never the client — and are read **lazily inside the call**, so a store with the file but no credential yet answers a clean 503 instead of failing to boot every function that imports it.
+- **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference` **and** check the payment names this order (its metadata `order_id` vs `order.id`) — that stops a reference to some other, genuinely paid payment being replayed against a different order.
+- **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` **and** `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against.
+- **Amounts**: `order.total` is in display units (`12.34`) with `order.currency`; convert to the provider's minor units yourself, remembering the zero-decimal currencies.
+- The helpers in `shared/commerce/payments.ts` (return-URL building, `confirmCardPayment`, reference bookkeeping) are premade — don't duplicate or bypass them.
 
-   ```js
-   await fetch("https://api.stripe.com/v1/webhook_endpoints", {
-     method: "POST",
-     headers: { Authorization: `Bearer ${Deno.env.get("STRIPE_SECRET_KEY")}`, "Content-Type": "application/x-www-form-urlencoded" },
-     body: new URLSearchParams({ url: "https://<app-domain>/functions/commerce/payment-webhook", "enabled_events[]": "checkout.session.completed" }),
-   });
-   ```
+## `parseWebhook` in depth
 
-Finally **enable the `card` gateway** — it is seeded off, so none of the above is visible at checkout until `commerce/seed-store` runs with `{ payment_methods: ["offline", "card"] }` ([`post-installation.md` §4.2](../post-installation.md#42-wiring-a-provider--one-file)).
+`parseWebhook(req, payload)` lives in `card-payment.ts` with the other three; `commerce/payment-webhook` is premade and calls it with the raw request and the raw body — the exact bytes, so signature schemes work. It returns `CardWebhookEvent | null`:
 
-## Storefront requirements (unchanged by any of this)
+- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret: the premade flow verifies through `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction — a forged call can at worst trigger a re-check, and the `order_key` match stops an event being aimed at another order. This is what the shipped Stripe file does.
+- **The signature-verified fast path** (optional): verify the signature over the raw `payload` bytes (Stripe: `constructEventAsync` with a webhook signing secret) and return `paid: true` with the event's `reference`; the premade code then trusts it without the API round-trip. **`paid: true` from an unverified body is the one way to break this design.** Set `reference` only from a verified event; otherwise leave it unset and the flow uses the reference stored on the order at checkout.
+- Return **`null`** for events that aren't about one of this store's payments; the function answers 200 so the provider doesn't retry.
 
-- Redirect to `payment.checkout_url` when `place-order` returns `payment.status === "requires_payment"`.
-- **Build the `/order-received` page** (or set your route in Settings → General → *Payment return path*): call `commerce/payments` `complete-return` with the return query params and render its `state` (`paid | cancelled | unpaid`, with `payment_link` for "Pay now" while unpaid). Without this page a paying customer lands on a 404 and the order is never marked paid.
-- Handle `503 no_card_payment_provider` from `place-order` by telling the customer card payment is unavailable and offering the other methods.
+Everything after `parseWebhook` — order lookup, the `order_key` match, idempotent confirmation, order progression — is premade either way.

package/skills/commerce/references/operations.md

@@ -0,0 +1,52 @@
+---
+stage: reference
+read_when: "You are setting up recurring maintenance, sizing the store against SDK/entity limits, or wiring outbound webhooks to another system."
+skip_when: "You are building the store itself — every maintenance job also runs opportunistically, so nothing here blocks a launch."
+forget_when: "The workflows you decided to create exist, or you have confirmed the store's volume is inside the limits below."
+carry_forward:
+  - "No workflow/schedule files ship — recurring jobs are workflows you create in the app, running with admin privileges."
+  - "There is no total-count API and no transactions: lists are limit+1 probes, counters can drift, and admin-tools recount actions repair them."
+---
+
+# Operations: schedules, limits, webhooks
+
+## Scheduled work (workflows)
+
+**The kit ships no workflow or schedule files, on purpose** — don't look for them under `base44/` and don't add them there. Base44 *has* a scheduler: you (or the Base44 agent) create the workflows **in the app**, one per row below, each invoking one function action on a cadence:
+
+```js
+await base44.functions.invoke("commerce/admin-tools", { action: "clear-abandoned-carts", older_than_days: 2 });
+```
+
+| Workflow to create | What it does | Action to invoke | Payload | Cadence |
+|---|---|---|---|---|
+| Release expired stock holds | Frees stock held by unpaid orders past `hold_stock_minutes`. `storefront-checkout place-order` already runs this at the start of every checkout, so the schedule mainly covers quiet periods. | `commerce/admin-orders` `release-expired-holds` | — | every 5–15 min |
+| Abandoned cart cleanup | Marks carts past the 48 h TTL as `abandoned`. Also happens lazily on next cart access. | `commerce/admin-tools` `clear-abandoned-carts` | `{ older_than_days: 2 }` | hourly–daily |
+| Prune webhook delivery log | Deletes old `commerce.WebhookDelivery` rows so the log doesn't grow unbounded. **No opportunistic fallback — this one genuinely needs a schedule.** | `commerce/admin-tools` `prune-webhook-deliveries` | `{ keep_days: 30 }` | daily–weekly |
+
+**Optional — drift repair.** For self-healing counters (see *Limits*), add a nightly/weekly workflow calling the `commerce/admin-tools` recount actions: `recount-terms`, `recount-coupon-usage`, `recalculate-customer-stats-all`, `regenerate-download-permissions`.
+
+Every action above is guarded by `requireAdmin()`, so each workflow must run with **admin privileges** (an admin identity / service context), never as an anonymous caller.
+
+## Limits, concurrency & reports
+
+- **Pagination.** SDK `filter`/`list` cap at 5,000 records/page and there is **no total-count API**. Server-side scans use paged loops (`shared/commerce/scan.ts` `scanAll`, page size 500); admin lists and `useProductList` use limit+skip with a `limit+1` "has-next" probe — the UI shows *Page N ‹ ›*, never a total.
+- **Search** is server-side (`search` actions scan + JS-filter) because entity `filter` is exact-match only.
+- **Reports** scan on demand — fine to ~10k orders per range. `commerce/admin-reports` `summary`/`sales`/`top-sellers` scan `commerce.Order` (+ `commerce.OrderRefund`) filtered to counted orders (`date_paid` set, or status `processing`/`completed`); net sales = gross − refunds − tax − shipping. Beyond that, cache `summary` and materialize an `OrderStats` entity (one record per day per status, summed totals) updated on each order transition.
+- **No transactions.** Four consequences, all documented in code:
+  - `nextOrderNumber` is `max(order_number)+1` with a small retry; two concurrent checkouts could theoretically collide — acceptable for typical volume, or front it with a counter entity.
+  - Stock decrement is last-write-wins; oversell is possible on simultaneous checkouts of the last unit. The hold mechanism (`hold_stock_minutes`) mitigates it; a stricter reserve step is yours to add.
+  - Denormalized counters (`usage_count`, `total_sales`, `orders_count`, term `count`) can drift; the recount actions above repair them.
+  - **Record size.** Orders embed their line/shipping/tax/fee/coupon lines, so orders with hundreds of distinct line items push against per-record size limits.
+
+## Webhooks (outbound)
+
+Managed in the admin at **Settings → Webhooks** (`settings/webhooks`; the source still lives under `pages/status/`).
+
+`shared/commerce/webhooks.ts` `dispatch()` fires on `order.*`, `product.*`, `customer.*`, `coupon.*` (created/updated/deleted — `restored` is selectable on a webhook but **never emitted**). Each active `commerce.Webhook` matching the topic gets an HTTP POST with headers `X-Commerce-Webhook-Topic/-Resource/-Event/-ID/-Delivery-ID/-Signature`; the signature is **base64 HMAC-SHA256** of the body keyed by the webhook's `secret` (Web Crypto) — verify by recomputing it over the **raw** body.
+
+- Every attempt is logged as a `commerce.WebhookDelivery` (request/response bodies truncated to 32 KB). Prune it on a schedule (above).
+- `failure_count` increments on non-2xx/timeout and resets on success; a webhook **auto-disables after 5 consecutive failures**.
+- The `secret` lives on the (admin-only-RLS) `commerce.Webhook` entity. For higher assurance, move it to Base44 secrets and read it in `dispatch()`.
+
+Inbound payment webhooks are a different mechanism entirely — [`online-payments.md`](./online-payments.md).