@base44/app-plugin-commerce 0.1.20 → 0.2.2

package/base44/shared/commerce/payments.ts

@@ -7,8 +7,8 @@
  * event). No provider ships with the template and the `card` gateway is
  * seeded disabled, so this half is dormant until a store opts into online
  * cards. Any provider works; the rules — and a complete Stripe
- * implementation, for that one common choice — are in
- * `.agents/skills/commerce/references/online-payments.md`.
+ * implementation, for that one common choice — are in the commerce skill's
+ * references/online-payments.md.
  *
  * Everything here — return URLs, storing the payment reference on the order,
  * idempotent confirmation that moves the order to processing, refund routing —

package/base44/shared/commerce/scan.ts

@@ -2,7 +2,7 @@
  * Full-collection scan helper. Base44's filter() is exact-match with a 5k page
  * cap and no total count, so server-side search/aggregation loops pages of 500.
  * Keep `cap` sane — reports over very large stores should move to a
- * materialized stats entity (see .agents/skills/commerce/references/limits-and-performance.md).
+ * materialized stats entity (see the commerce skill's references/operations.md).
  */
 
 export interface ScanOpts {

package/base44/shared/commerce/sequence.ts

@@ -3,8 +3,8 @@
  *
  * NOTE ON CONCURRENCY: Base44 has no transactions, so nextOrderNumber() is a
  * read-max-then-increment and two simultaneous checkouts could race. The window
- * is tiny and order ids (not numbers) are the primary key; see
- * .agents/skills/commerce/references/limits-and-performance.md for mitigations.
+ * is tiny and order ids (not numbers) are the primary key; see the commerce
+ * skill's references/operations.md for mitigations.
  */
 
 const ORDER_NUMBER_START = 1001;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.20",
+  "version": "0.2.2",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/scripts/install.js

@@ -25,12 +25,11 @@
  * overwritten (so re-running after a template update is safe), everything
  * else in the app is left untouched.
  *
- * This is only the static part of the install. The remaining steps live in
- * ../skills/commerce/installation-guidelines.md (deps, deploy, seeding) and
- * ../skills/commerce/post-installation.md (mounting the /store-admin route, admin
- * role, seeding, the storefront quick start); day-2 guidance starts at
- * ../skills/commerce/SKILL.md. The skill folder carries all of this
- * documentation into the app.
+ * This is only the static part of the install. Everything after it lives in
+ * ../skills/commerce/install/01-install.md (deps, the /store-admin mount, the
+ * admin-role gating), which routes on to 02-storefront.md and 03-data.md at the
+ * right moments; ../skills/commerce/SKILL.md is the map for all later work. The
+ * skill folder carries all of that documentation into the app.
  *
  * Written with dynamic import() and process.argv[1] (instead of require/
  * __dirname) so it runs unchanged whether the host app's package.json is
@@ -132,6 +131,17 @@
     ["src", "commerce", "admin", "pages", "settings", "TaxRatesTable.jsx"],
     ["src", "commerce", "admin", "pages", "settings", "ShippingSettings.jsx"],
     ["src", "commerce", "admin", "pages", "settings", "ShippingZoneEditor.jsx"],
+    // The skill's docs were restructured into stage files (install/01..03) plus a
+    // smaller reference set. Stale guidance is worse than none — agents read
+    // whatever is in .agents/skills/ — so every retired doc goes, by name.
+    [".agents", "skills", "commerce", "post-installation.md"],        // → install/01..03
+    [".agents", "skills", "commerce", "installation-guidelines.md"],  // → install/01-install.md + references/store-admin-agent.md
+    [".agents", "skills", "commerce", "references", "product-render.md"],           // → references/catalog-rendering.md
+    [".agents", "skills", "commerce", "references", "storefront-product-page.md"],  // → references/catalog-rendering.md
+    [".agents", "skills", "commerce", "references", "scheduled-work.md"],           // → references/operations.md
+    [".agents", "skills", "commerce", "references", "limits-and-performance.md"],   // → references/operations.md
+    [".agents", "skills", "commerce", "references", "webhooks.md"],                 // → references/operations.md
+    [".agents", "skills", "commerce", "references", "media-and-downloads.md"],      // → docs/api-storefront.md + install/03-data.md
   ];
   let retiredRemoved = 0;
   for (const parts of RETIRED) {
@@ -186,16 +196,16 @@
     (retiredRemoved ? ` (${retiredRemoved} retired file${retiredRemoved === 1 ? "" : "s"} removed)` : ""),
   );
   console.log(
-    "\nNext steps (see .agents/skills/commerce/installation-guidelines.md + post-installation.md):\n" +
+    "\nNext: read .agents/skills/commerce/install/01-install.md and follow it.\n" +
+    "It is the whole install, and it says when to open 02-storefront.md and\n" +
+    "03-data.md — read nothing else up front.\n" +
+    "\n" +
     "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
-    "     Base44 template — check package.json and npm i only what is truly missing;\n" +
-    "     do not re-install packages already listed as dependencies\n" +
+    "     Base44 template — check package.json and npm i only what is truly missing\n" +
     '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
-    "     and implement the payment return page /order-received — one hook,\n" +
-    "     useOrderReturn from @/commerce/storefront (post-installation.md)\n" +
-    "  3. Grant your user the admin role, then seed the store's data — one commerce/seed-store\n" +
-    "     call (store_name required) takes the whole catalog via products, or the demo data\n" +
-    "     via with_sample_data, or defaults only (post-installation.md §3)\n" +
+    "     plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
+    "  3. Seed the store — one commerce/seed-store call (store_name required) takes the\n" +
+    "     catalog, currency, shipping locations and payment methods\n" +
     "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"
   );
 })();

package/skills/commerce/SKILL.md

@@ -1,66 +1,132 @@
 ---
 name: commerce
-description: Base44 Commerce template — 20 commerce.* entities, 16 commerce/* backend functions (storefront + admin APIs + online payments), the shared commerce engine under base44/shared/commerce/, the Store Management UI mounted at /store-admin, and the commerce/StoreAdmin agent (admin copilot). Read before working on store features — the admin UI, storefront building, payment provider wiring, scheduled maintenance, emails, webhooks, downloads, or scaling limits.
+description: Base44 Commerce — commerce.* entities, commerce/* backend functions (storefront + admin APIs, payments, webhooks), the shared engine under base44/shared/commerce/, the Store Management UI at /store-admin, and the headless storefront hooks under src/commerce/. Read before working on store features: installing, building a storefront, seeding a catalog, shipping zones, payments, or the admin.
 ---
 
 # Commerce
 
-Operational guidance for extending, operating and building on the Base44 Commerce Template. This file is the map: it stays short, and each topic links to a focused reference under [`.agents/skills/commerce/references/`](./references/) — open one only when your task touches that area. The API references live in [`.agents/skills/commerce/docs/`](./docs/).
-
-> **If you are a Base44 agent working inside the runtime, read this first:**
-> - **Don't read the whole codebase up front.** Start with this file, then open only the files your current task touches plus the matching reference below, pulling in more as you go. Reading everything first just burns context.
-> - **Don't weaken the admin gating.** The UI guard, entity RLS and function guards form three enforcement layers — see [`.agents/skills/commerce/post-installation.md`](./post-installation.md) — keep all of them intact when changing routes or schemas.
-> - **Entity names are dotted — SDK access is bracket syntax only:** `base44.entities["commerce.PaymentGateway"]` (schema file: `base44/entities/commerce.PaymentGateway.jsonc`). `commerce__PaymentGateway` / `PaymentGateway` don't exist. Gateway on/off is seed data anyway: `commerce/seed-store` `payment_methods`.
-> - **Online card payments are optional and off by default.** The seed enables the manual `offline` method and leaves the `card` gateway disabled. **Enable cards only if a payment provider is wired — or will be, in the same stretch of work** (one file): enabled with nothing behind it answers `503 no_card_payment_provider` at checkout. Choosing to add them is fine, but it belongs at the *end* of an install, once there's a working store to point at — nothing else depends on it, so never open a build by asking a user for a provider key. [`post-installation.md` §4.1](./post-installation.md#41-off-by-default--enable-only-with-a-provider-wired) has the rule and the timing.
-
-## IMPORTANT — first-time installation
-
-If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else — and, unless the user has a special requirement, read nothing else**: it alone covers embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §3) — **card payments as an optional, late step** (§4.1: off by default — the seed enables offline payment and leaves cards off; **no payment provider ships with the kit**, so cards mean deliberately wiring one, raised at the end of the install and never at its start; §4.2 is the four-step how-to, and the provider code itself lives in [`references/online-payments.md`](./references/online-payments.md) — read it only if the store opts in), and the **storefront quick start** (§2): logic-only chunks for product list → product page → optional cart → checkout. Its §0 schedules the whole install: **storefront components are written while image generation and the seed call (parallel writes — usually a few seconds) run — never after them, and never behind a payment-provider round-trip**. The references below and the API docs are for requests that go beyond that happy path, not for the install. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
-
-## Working on the UI
-
-- **Admin UI** (`src/commerce/admin/`) — a complete store back office ships with the template, and it is **yours to change**: restyle it, add or remove pages, rework flows, extend it however the app needs. To understand the backend it talks to, read [`.agents/skills/commerce/docs/api-admin.md`](./docs/api-admin.md) — every admin function/action plus the direct-entity-CRUD contract. The only invariant is the admin-role gating (see above).
-- **Storefront** — **no visitor UI ships** (no visual components at all — the shopfront's look is the app's to design); the storefront *API* is complete (token-based cart), and the storefront *logic* ships on two levels: framework-free helpers in [`src/commerce/utils/`](../../src/commerce/utils/) (`storefront.js` client, `variants.js`, `shipping-promos.js` — import from `@/commerce/utils`) and the React layer in [`src/commerce/storefront/`](../../src/commerce/storefront/) (import from `@/commerce/storefront`): `StorefrontProvider` (one client, one store-info cache, ONE shared cart), `useCart`, `useCheckout` (guided checkout — automatic shipping/tax recalculation when the address is complete, shipping/payment choice, a gated `placeOrder`), headless `ShippingMethodPicker`/`PaymentMethodPicker`, and `useOrderReturn` for the mandatory `/order-received` page. **In a React app, build cart/checkout on these hooks — don't hand-roll their logic.** Catalog views stay thin by design (client calls + variant helpers — the design freedom lives there). Start from the logic-only quick start in [`post-installation.md` §2](./post-installation.md#2-storefront-quick-start--logic-only) — it covers the whole buy path; go to [`.agents/skills/commerce/docs/api-storefront.md`](./docs/api-storefront.md) for anything beyond it. Navigation comes from three actions — `list-categories` (tree), `list-ribbons` (flat, with counts) and `list-attributes` (filter UIs). What to render in the grid vs. the product page — and which fields only one of the two calls returns — is [`references/product-render.md`](./references/product-render.md); **ribbons are the most-skipped part of it and belong in both views**.
-
-### If you build a storefront, these four are not optional
-
-Agents keep shipping storefronts that miss these, and each one breaks buying outright. **In a React app, rules 2 and 3 are already implemented — `useCheckout` and `useOrderReturn` from `@/commerce/storefront` (post-installation.md §2.4); use them instead of re-deriving the logic.** The rules below stay stated in API terms so non-React (or non-hook) storefronts can follow them too; details in [`docs/api-storefront.md`](./docs/api-storefront.md) and [`references/storefront-product-page.md`](./references/storefront-product-page.md).
-
-1. **Products with variants need one selector per attribute — and the selection must resolve to a variation.** `get-product` gives `product.attributes` (every entry is an axis — there is no product type) and `variations` (the combinations). Render a control per axis, never a list of combinations, then send the resolved `variation_id`:
-   ```js
-   import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
-   const view = resolveSelection(product, variations, selection);   // axes, availability, price, addToCart
-   await addItem(view.addToCart);   // useCart(); or add-item with cart_token + ...view.addToCart
-   ```
-   `add-item` **rejects a product with attributes unless it gets a `variation_id`** (`400 variation_required`), so a page that ignores this cannot sell anything.
+**This file is the map. It tells you what to read, when, and what you can skip.**
+Nothing else in this skill needs to be open right now.
+
+The kit ships, already written and tested: 20 `commerce.*` entities, the
+`commerce/*` backend functions (storefront API, admin API, payments, webhooks,
+emails), the shared commerce engine, a complete admin back office at
+`/store-admin`, the `commerce/StoreAdmin` copilot, and the storefront's entire
+logic layer (`@/commerce/storefront`, `@/commerce/utils`). None of that costs
+you generation — your work is the store's *UI and data*, not the plumbing.
+
+**Paths in this skill.** Every skill file named anywhere — in these docs, in a
+checklist, in a code comment — is written **relative to this skill's folder**
+(`.agents/skills/commerce/` in an installed app). So `references/online-payments.md`
+means `.agents/skills/commerce/references/online-payments.md`, and
+`install/03-data.md` means `.agents/skills/commerce/install/03-data.md`. Resolve
+them from the skill folder, never from the directory of the file that mentioned
+them — a comment in `src/…` naming `install/03-data.md` is not
+`src/install/03-data.md`. (Markdown links between skill files are ordinary
+relative links and resolve as written.)
+
+## Installing right now?
+
+Read **[`install/01-install.md`](./install/01-install.md)** and follow it. It
+routes you to `install/02-storefront.md` when you start the UI and
+`install/03-data.md` when you seed the catalog — in that order, at those
+moments. Read nothing else up front: those three files are the whole install,
+and each one says when a reference is genuinely needed.
+
+## Four things to hold from the start
+
+- **Entity names are dotted; SDK access is bracket syntax only** —
+  `base44.entities["commerce.Product"]`. `commerce__Product` and `Product` do
+  not exist. The full data-model map is [`docs/entities.md`](./docs/entities.md);
+  never scan `base44/entities/` to find a name.
+- **Store configuration is declared in one seed call**, not assembled by editing
+  records: catalog, shipping zones ("€20 in Europe, €100 worldwide" is a
+  six-line `locations` payload), currency, payment methods. See
+  [`install/03-data.md`](./install/03-data.md).
+- **Don't weaken the admin gating.** Three layers — the UI guard, entity RLS,
+  and `requireAdmin()` in every admin function — see
+  [`install/01-install.md`](./install/01-install.md). Keep all three when you
+  touch routes or schemas.
+- **Online card payments are optional and off by default.** A seeded store takes
+  manual (`offline`) payment and works end to end. Cards are a late, deliberate
+  step, and the decision plus the timing live in
+  [`install/03-data.md`](./install/03-data.md).
+
+## The storefront: logic is premade, UI never is
+
+**The UI is yours, all of it** — every page, element, class and word of copy,
+from the home page to the checkout's place-order button. That is where a brief
+like "make it feel like <site>" lives, and the kit deliberately ships **no
+markup and no CSS anywhere**: there are no premade components to drop in or
+restyle. You design the storefront the way you would any app.
+
+**The logic ships as headless hooks** (`@/commerce/storefront`) — checkout
+repricing from the address, variant resolution, cart state, coupon redemption,
+review policies, order-return verification. Every store's version of these is
+functionally identical and hand-writing them is where storefront bugs cluster,
+so **never re-implement what a hook does**. Each hook returns a complete
+view-model — a `status` to branch on, ready-to-map arrays, handlers, error
+objects — that your markup renders:
+
+```jsx
+import { useCart, CartLine, useTotalsLines } from "@/commerce/storefront";
+const { status, lines } = useCart();   // branch on status, map lines into YOUR rows
+```
 
-2. **Checkout must recalculate shipping from the address and send a choice.** `useCheckout` does all of it: it calls `set-shipping-address` automatically once the address is complete (recalculating options, cost and tax; `400 shipping_not_available` → its `addressError`), resolves `shipping_status`, and blocks `placeOrder` until the choice is made. Hand-rolled flows must do the same by hand: call `set-shipping-address` as soon as the customer provides an address, then read `shipping_status` on the returned cart — `auto_selected` (one option, already applied) · `chosen` · `choice_required` → **show `available_shipping_methods` and call `choose-shipping-method`** · `missing_address` → collect the address first (a single-location store shows its options even before one). `place-order` refuses with `400 shipping_method_required` until then — that is not a bug to work around. (`chosen_shipping_method` on the cart is the rate **id**, a string — display it by looking up its entry's `title`/`cost`, never by rendering the id.)
+The admin UI (`src/commerce/admin/`) is finished and **also yours to change** —
+restyle it, add pages, rework flows. To understand the backend it talks to, read
+[`docs/api-admin.md`](./docs/api-admin.md).
 
-3. **Handle card payments if the store offers them, and build `/order-received` either way.** Render whatever gateways `get-store-info` reports — a default-seeded store offers `offline` only (cards are off by default, and enabled only with a provider wired: [`post-installation.md` §4.1](./post-installation.md#41-off-by-default--enable-only-with-a-provider-wired)), so never hardcode a card option. Choosing the card gateway returns `payment.checkout_url` — `useCheckout().placeOrder` redirects there for you (with no provider implemented — one file, [`post-installation.md` §4.2](./post-installation.md#42-wiring-a-provider--one-file) — it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: one `useOrderReturn()` call rendered by `status` (hand-rolled: `commerce/payments` `complete-return` with the query params). Without that page a customer pays into a 404 and the order is never marked paid. Also persist the `cart_token` from **every** cart response (the provider/client do this) — `add-item` silently starts a fresh cart when the stored token is stale.
+Four rules the API enforces — a storefront that skips them cannot complete a
+purchase. In a React app the hooks implement all four; your markup just has to
+render what they hand back. The API-level statements are in
+[`docs/api-storefront.md`](./docs/api-storefront.md) for non-React clients:
 
-4. **Never advertise what isn't configured — and never configure what can't be reached.** "Free shipping over €150" must come from a real shipping rate that is free or carries a `free_over` threshold on a Shipping & Tax Location. Locations are admin-only data, so a storefront cannot read them: the live answer is the cart's `available_shipping_methods` after the address is set, and `shipping-promos.js` normalizes the rules wherever the records *are* in hand. No rule means no banner. **Coupons are the same rule in reverse:** codes are admin-only data that a customer can only use by typing them, so a store with coupons needs a code field — `useCart().applyCoupon`, in the cart or, when there's no cart page, in the checkout — rendering `discount_total` and invalid codes inline. No field means no coupons: don't seed them, don't name a code in the copy ([`post-installation.md` §2.3/§2.4](./post-installation.md#23-cart)).
+1. A product with variants needs **one selector per attribute**, resolved to a
+   `variation_id` (`useProduct` + `variantAxes`).
+2. Checkout must **recalculate shipping from the address and send a choice**
+   (`useCheckout` — automatic).
+3. **`/order-received` must exist** and render the return state, including a
+   manual order's payment instructions (`useOrderReturn`).
+4. **Never advertise what isn't configured** — no free-shipping banner without a
+   real rate, no coupon codes without a field to redeem them in.
 
-All functions return the envelope `{ success, data }` (or `{ success, error, code }`); with the SDK the body is on `res.data`:
+All backend functions return the envelope `{ success, data }`; with the SDK the
+payload is `res.data.data`:
 
 ```js
 const res = await base44.functions.invoke("commerce/storefront-catalog", { action: "list-products", per_page: 12 });
-const { products, has_next } = res.data.data;   // res.data = envelope, .data = payload
+const { products, has_next } = res.data.data;
 ```
 
-## Topic references
-
-Open the matching file under `.agents/skills/commerce/references/` only when a task touches its area:
-
-| Topic | Read when the task involves | Reference |
-|---|---|---|
-| Product rendering (list + page) | what to show in a product grid vs. the product page, field availability across `list-products`/`get-product`, **ribbons in both views**, variant pricing on cards, adding a page-only field to the listing call | [`references/product-render.md`](./references/product-render.md) |
-| Variant selection | attribute-level selectors, resolving a selection to a variation, availability states, incomplete-selection pricing, add-to-cart contract | [`references/storefront-product-page.md`](./references/storefront-product-page.md) |
-| Reviews | stars on cards and the product page, the review list + submit form (public by email, backend ships complete), the auto-approve toggle, UI-enforced policies (login-gated, verified-only, required rating) | [`references/reviews.md`](./references/reviews.md) |
-| Admin product form | changing the product editor — its stacked sections are **Price & Inventory** (tax group, then the attributes, then a row per variant, or a single *Base price* row when there are none), **Modifiers** (`meta_data`), **Downloads**, **Linked products**; one **Visible** toggle drives `status`. Variants reconcile from the attribute values automatically: no generate step, no per-variant delete. Weight and dimensions are per variant. | [`references/admin-product-form.md`](./references/admin-product-form.md) |
-| Online payments | a store that has **opted into card payments** (they are off by default and no provider ships) — the order side (checkout, confirmation, payment links, refund records) *and* the payment webhook are premade; wiring a provider means implementing the four functions in one file (`shared/commerce/card-payment.ts`), and this reference holds the rules plus a complete Stripe implementation | [`references/online-payments.md`](./references/online-payments.md) |
-| Scheduled work | recurring maintenance — stock-hold release, abandoned-cart cleanup, webhook-log pruning, counter-drift repair | [`references/scheduled-work.md`](./references/scheduled-work.md) |
-| Emails | transactional order emails, per-type overrides, deliverability, the email log | [`references/emails.md`](./references/emails.md) |
-| Webhooks | outbound webhooks, HMAC signing, delivery log, auto-disable behavior | [`references/webhooks.md`](./references/webhooks.md) |
-| Images & downloads | catalog image uploads, downloadable products, private files & signed URLs | [`references/media-and-downloads.md`](./references/media-and-downloads.md) |
-| Limits & performance | pagination caps, search, no-transaction consequences, record size, reports scaling | [`references/limits-and-performance.md`](./references/limits-and-performance.md) |
-| Guest access & security | public storefront functions, `cart_token`/`order_key` handling, RLS boundaries | [`references/guest-access-security.md`](./references/guest-access-security.md) |
+## Where to look for what
+
+Open a file when its work starts — not while planning. The last column is there
+so you can answer "would that file help?" without paying for it.
+
+| Topic | Open when | Already covered without opening | Size |
+|---|---|---|---|
+| [`install/01-install.md`](./install/01-install.md) | installing — it routes you to 02 and 03 | — | 8K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | — | 14K |
+| [`install/03-data.md`](./install/03-data.md) | seeding the catalog, shipping, payments decision | — | 14K |
+| [`docs/entities.md`](./docs/entities.md) | any direct entity read/write, or "which entity holds X" | function-mediated flows never need it; the addressing rule is above | 11K |
+| [`references/catalog-rendering.md`](./references/catalog-rendering.md) | which fields each catalog call returns, variant edge cases | the install's product list/page chunks already render correct cards, prices and selectors | 12K |
+| [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond the standard recipe, taxes, editing locations later | "€X in a region, €Y worldwide" is inline in `install/03-data.md` | 8K |
+| [`references/online-payments.md`](./references/online-payments.md) | the store opted into cards and you are wiring the provider **now** | the decision and its timing are in `install/03-data.md`; wiring Stripe is a one-file copy, not code to write | 9K |
+| [`references/reviews.md`](./references/reviews.md) | moderation, or a policy beyond the `policy` prop | `useProductReviews` covers list + form + policies | 4K |
+| [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | the seeded defaults are right for a new store | 5K |
+| [`references/emails.md`](./references/emails.md) | order-email recipients, subjects, per-type overrides, the log | transactional emails already send | 5K |
+| [`references/admin-product-form.md`](./references/admin-product-form.md) | editing the shipped product editor | the editor works as shipped | 4K |
+| [`references/store-admin-agent.md`](./references/store-admin-agent.md) | changing the StoreAdmin copilot or its tools | it registers and works on install | 3K |
+| [`references/guest-access-security.md`](./references/guest-access-security.md) | **adding your own function or entity**, or questions about RLS/identity | the shipped functions already handle guest access | 5K |
+| [`references/operations.md`](./references/operations.md) | scheduled maintenance, scaling limits, outbound webhooks | nothing here is needed to ship a store | 5K |
+| [`docs/api-storefront.md`](./docs/api-storefront.md) | filters, customer accounts, refunds, a non-React client — anything past the happy path | the entire buy path | 40K |
+| [`docs/api-admin.md`](./docs/api-admin.md) | changing admin pages, automating against admin functions, the full seed contract | — | 28K |
+
+**The read budget.** Content you pull into context is re-read on every later
+call, so a file opened while planning costs many times what the same file costs
+opened at the moment it is used. Open one reference when its task starts, take
+what you need, and when a stage's checklist passes, record that stage's
+carry-forward lines and treat the file as gone. If a reference and this map
+disagree, the reference wins — but if a *rule* appears in code (a hook's return
+value, its doc comment), the code wins over both.

package/skills/commerce/docs/api-admin.md

@@ -2,27 +2,11 @@
 
 For building store automation or an alternative admin UI against the Base44 Commerce Template. The bundled admin UI (`src/commerce/admin/`) uses exactly this surface.
 
-## Data-access contract
-
-Two access styles. **Reads are direct** entity SDK calls; **mutations with side effects go through `commerce/admin-*` functions**; simple config entities are **direct CRUD** (protected by admin-only RLS).
-
-| Resource | Reads | Writes | Why |
-|---|---|---|---|
-| commerce.Product, commerce.ProductVariation | direct (`filter`/`get`/`list`) | **`commerce/admin-products`** | derived pricing/stock, taxonomy counts, webhooks |
-| commerce.Order, commerce.OrderNote | direct | **`commerce/admin-orders`** | lifecycle side effects (stock, emails, webhooks, dates) |
-| commerce.OrderRefund | direct | **`commerce/admin-refunds`** | restock, totals, refund status transition |
-| commerce.Coupon | direct | **`commerce/admin-coupons`** | code normalization/uniqueness, webhooks |
-| commerce.Customer | direct | **`commerce/admin-customers`** | email uniqueness, invite/link, stats |
-| commerce.ProductReview | direct | **`commerce/admin-reviews`** | rating recalculation |
-| commerce.ProductCategory, commerce.ProductRibbon | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | category slug uniqueness; ribbon get-or-create by name |
-| commerce.ProductAttribute, commerce.ProductAttributeTerm | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | attribute `code` uniqueness; value rename rewrites products; attribute delete cascades its values |
-| commerce.ShippingTaxLocation | direct | **direct CRUD** | config; consumed by the pricing engine at read time |
-| commerce.PaymentGateway | direct | **`commerce/seed-store`** `payment_methods` to switch methods on/off; **direct CRUD** to change a record (add or rename a manual option, its `description`, bank accounts, `order`) | one seed call converges every gateway row to the given set, so "enable cards", "card-only" and "offline-only" are one idempotent call; the record's own fields are ordinary config — the admin's Settings → Payments screen edits them directly |
-| commerce.StoreSettings | direct | **direct CRUD** (one record per `group_id`) | grouped config |
-| commerce.Webhook | direct | **direct CRUD** (+ `commerce/admin-webhooks` for test/redeliver) | definition is data; dispatch is engine |
-| commerce.WebhookDelivery, commerce.EmailLog | direct (read-only logs) | written by the engine | audit logs |
-
-**Every entity is admin-only on read *and* write** — including the catalog. Storefront access goes exclusively through the `commerce/storefront-*` functions, which run with the service role and project only what is safe; a direct entity read or write from a non-admin is rejected by the backend regardless of the UI. See [`references/guest-access-security.md`](../references/guest-access-security.md).
+## Data access
+
+Two styles. **Reads are direct** entity SDK calls. **Mutations with side effects go through `commerce/admin-*` functions**; plain config entities are direct CRUD. Which entity is which, its key fields, its derived fields and the exact write path is the catalog table in [**`entities.md`**](./entities.md) — including the addressing rule (`base44.entities["commerce.<Name>"]`, bracket syntax only) that a guessed spelling gets wrong.
+
+**Every entity is admin-only on read *and* write**, catalog included. Storefront access goes exclusively through the `commerce/storefront-*` functions, which run with the service role and project only what is safe; a direct entity read or write from a non-admin is rejected by the backend regardless of the UI. See [`../references/guest-access-security.md`](../references/guest-access-security.md).
 
 ## Invocation & envelope
 
@@ -45,7 +29,7 @@ Success: `{ success: true, data }`. Failure: `{ success: false, error, code }` w
 Actions: `save` · `delete` · `batch` · `duplicate` · `set-stock` · `search` · `save-term` · `delete-term` · `list-terms`
 
 - **`save`** — `{ product, variations? }`. Upserts the product (create if no `id`); when `variations` is provided, diffs them (create/update/delete-missing).
-  > **Selling variants takes both of these in *this* call**: the attribute listed **on the product** as `attributes: [{ attribute_id, name, position, options: [...] }]`, plus a `variations` array with one entry per stocked combination (each `{ attributes: [{ attribute_id, name, option }], sku, regular_price, manage_stock: "yes", stock_quantity, status: "publish" }`) and `default_attributes` for the pre-selected combination. There is **no `type` field**: carrying attributes is what makes a product sell variants, so a `commerce.ProductAttribute` record on its own changes nothing — and a product listing an attribute with no variations cannot be added to a cart at all (`400 variation_required`). Descriptive properties belong in `meta_data`, not `attributes`. **Don't set the parent's price** — `regular_price`, `price` and `on_sale` are derived from the cheapest publishable variant on every save, which is what makes catalog cards, price sorting and price filters agree. Enforces SKU + slug uniqueness across products *and* variations (auto-suffixes slug on collision; `duplicate_sku` on SKU clash). Derives `price`/`on_sale` from the sale window and `stock_status` when stock is managed; updates category/ribbon `count`; rolls parent stock **and price** up when the product has attributes; fires `product.created`/`product.updated`. → `{ product, variations }`.
+  > **Selling variants takes both of these in *this* call**: the attribute listed **on the product** as `attributes: [{ attribute_id, name, position, options: [...] }]`, plus a `variations` array with one entry per stocked combination (each `{ attributes: [{ attribute_id, name, option }], sku, regular_price, manage_stock: "yes", stock_quantity, status: "publish" }`) and `default_attributes` for the pre-selected combination. There is **no `type` field**: carrying attributes is what makes a product sell variants, so a `commerce.ProductAttribute` record on its own changes nothing — and a product listing an attribute with no variations cannot be added to a cart at all (`400 variation_required`). Descriptive properties belong in `meta_data`, not `attributes`. **Don't set the parent's price** — it is rolled up from the cheapest publishable variant on every save ([derived fields](./entities.md#derived-fields--never-write-these)). Enforces SKU + slug uniqueness across products *and* variations (auto-suffixes slug on collision; `duplicate_sku` on SKU clash); derives `price`/`on_sale` from the sale window, `stock_status` when stock is managed, and category/ribbon `count`; fires `product.created`/`product.updated`. → `{ product, variations }`.
 - **`delete`** — `{ id }`. Cascades variations, decrements counts, fires `product.deleted`.
 - **`batch`** — `{ create?: [], update?: [], delete?: [] }` (≤100 total) → per-item results.
 - **`duplicate`** — `{ id }` → new draft copy (name "(Copy)", suffixed SKU, reset sales/ratings) incl. variations.
@@ -142,7 +126,7 @@ Actions: `test` · `redeliver` (webhook definitions themselves are direct `comme
 
 ## commerce/admin-reports
 
-All actions scan orders on demand (counted = `date_paid` set, or status `processing`/`completed`). See the commerce skill reference `.agents/skills/commerce/references/limits-and-performance.md` for scaling.
+All actions scan orders on demand (counted = `date_paid` set, or status `processing`/`completed`). Scaling: [`../references/operations.md`](../references/operations.md).
 
 | Action | Payload | Returns |
 |---|---|---|
@@ -175,16 +159,93 @@ Actions: `status` · `admin-email-recipients` · `recount-terms` · `recount-cou
 
 Actions: `create-link` · `complete-return` · `verify` — the admin side of online payments (the same function serves customers, who authorize with `order_key` instead; see [`api-storefront.md`](./api-storefront.md)).
 
-- **`create-link`** — `{ order_id }` → `{ url, reference }`: a provider-hosted payment page for an unpaid order, i.e. the **payment link** to send a customer. Accepts an order with **any** payment method (including none, as admin-created orders start) and switches it onto the card gateway, logging the change — refunds key off `payment_method`, so this keeps the order honest about how it was paid. `409 already_paid`, `400 card_payments_disabled`, `503 no_card_payment_provider`.
+- **`create-link`** — `{ order_id }` → `{ url, reference }`: a provider-hosted payment page for an unpaid order — the **payment link** to send a customer. Accepts an order on **any** payment method (including none, as admin-created orders start) and switches it onto the card gateway, logging the change: refunds key off `payment_method`, so this keeps the order honest about how it was paid. `409 already_paid`, `400 card_payments_disabled`, `503 no_card_payment_provider`.
 - **`verify`** — `{ order_id }` → `{ paid, already_confirmed, status, order }`: re-asks the provider and moves the order to `processing` when the money is there. Idempotent.
-- **`complete-return`** — `{ order_id, order_key, payment?, return_url? }` → `{ state, paid, already_confirmed, status, order, payment_link, payment_instructions }`: what the storefront's **mandatory** `/order-received` page calls — confirm, progress the order, and hand back a render-ready result plus a fresh payment link while unpaid (card) or the gateway's payment instructions (manual).
+- **`complete-return`** — what the storefront's mandatory `/order-received` page calls; full contract in [`api-storefront.md`](./api-storefront.md#commercepayments--online-payment-for-an-order).
 
 `commerce/payment-webhook` is the provider's server-to-server callback (raw body, no `action` envelope). The function is **premade** — it validates every event through `card-payment.ts`'s `parseWebhook` and never trusts an event body on its own: an unverified event only names an order, and payment is verified through `checkCardPaymentPaid` against the provider's API, so no signing secret is needed. Until `card-payment.ts` is implemented it answers `400 webhook_not_implemented`; events it can't tie to an order are acknowledged with `200 { ignored: true }` so providers don't retry. See [`../references/online-payments.md`](../references/online-payments.md).
 
 ## commerce/seed-store
 
-Not action-routed. Body `{ store_name?, currency?, weight_unit?, dimension_unit?, payment_methods?, with_sample_data?, products?, coupons?, locations? }`. **`payment_methods`** (gateway slugs, e.g. `["offline", "card"]`) enables exactly the listed gateways and disables every other gateway row — the one-call way to honor "card-only"/"offline-only"/"both"; explicit values win on re-runs, unknown slugs fail as `400 invalid_payload`, and the response reports `payment_methods: { enabled, disabled }` (`null` when not passed). **Omitted, the seed enables `offline` and leaves `card` disabled** — cards are off by default, so passing `"card"` is what turns them on: only do so with a provider wired in `shared/commerce/card-payment.ts`, or about to be, since an enabled card option with nothing behind it answers `503 no_card_payment_provider` at checkout ([`post-installation.md` §4.1](../post-installation.md#41-off-by-default--enable-only-with-a-provider-wired)). **`store_name` is required** when the `emails` group doesn't exist yet (**400** `store_name_required` otherwise) — pass the app's name **as the platform shows it** — ask the user or read it from the dashboard. `base44/config.jsonc` → `name` is *not* authoritative: it can still say `New App` for an app the platform calls `Canvas`. A backend function can't read either, its environment being only `BASE44_APP_ID`. It lands in `emails.store_name` — one setting serving as both the store name in email subjects and the sender name on every transactional email; a nameless store renders subjects like `[]: New order #1002`, which is why seeding refuses one. Requires admin. Runs a **canary schema check** first — on any incompatibility returns **422** `{ success:false, code:"schema_incompatible", errors:[{ entity, error }] }` and writes nothing. Otherwise seeds defaults idempotently, then the catalog. On an already-seeded store a passed `store_name` fills a **blank** name and never overwrites one the merchant chose. **`currency`** (ISO code, validated against the shared currencies table) and **`weight_unit`/`dimension_unit`** set the `general` group; unknown values fail as **400** `invalid_payload`. Unlike `store_name` they **always win** — there is no blank state to distinguish a merchant's choice from the seeded default, so passing one on a re-run updates the store. Prices are formatted with `Intl.NumberFormat` — the currency is a value, there are no format settings.
+Not action-routed — the body **is** the payload. Requires admin. This is the **canonical seed contract**; the worked example lives in [`../install/03-data.md`](../install/03-data.md).
+
+**Order of operations**, so a failure says how much was written: (1) validate — pure, so bad input is **`400 invalid_payload`** carrying every problem at once in `errors: [{ path, error }]`, before anything runs; (2) **canary schema probe** per entity the seeder writes — any incompatibility is **`422 schema_incompatible`** with `errors: [{ entity, error }]`, nothing written; (3) defaults, idempotently (settings groups, gateways, and the fallback location **only when the payload brings no `locations`**); (4) the catalog, rolling back everything this call created on a mid-write failure (**`500 catalog_seed_failed`**), reused taxonomy untouched.
+
+### Payload — store setup
+
+| Key | Type | Effect |
+|---|---|---|
+| `store_name` | string | **Required on a first seed** (the `emails` group doesn't exist yet) — otherwise **`400 store_name_required`**. Lands in `emails.store_name`: both the name in email subjects and the sender name, so a nameless store renders `[]: New order #1002`. On an already-seeded store it **fills a blank** name and never overwrites one the merchant chose. |
+| `currency` | ISO code | Sets `general.currency`, validated against the shared currencies table. Prices are formatted with `Intl.NumberFormat` — there are no format settings. |
+| `weight_unit` | `kg`\|`g`\|`lbs`\|`oz` | Sets `general.weight_unit`. |
+| `dimension_unit` | `cm`\|`m`\|`mm`\|`in`\|`yd` | Sets `general.dimension_unit`. |
+| `payment_methods` | non-empty array of gateway slugs, e.g. `["card"]` | Enables exactly these and **disables every other gateway row**, so "card-only"/"offline-only"/"both" is one idempotent call, no entity editing. Unknown slugs fail `400 invalid_payload` listing the known ones. |
+| `with_sample_data` | boolean | The template's demo catalog, **only when the store has zero products**. Cannot combine with `products`/`coupons`/`locations`. |
+| `products` `coupons` `locations` | arrays | The catalog payload — below. |
+
+`currency`, the units and `payment_methods` **always win**, first seed and re-runs alike: there is no blank state distinguishing a merchant's choice from the default, so passing one is an instruction. `store_name` is the exception (fill-blank only) — pass the app's name **as the platform shows it**: `base44/config.jsonc` → `name` is not authoritative (it can say `New App` for an app the platform calls `Canvas`) and a function's env is only `BASE44_APP_ID`, so ask the user or read the dashboard.
+
+**Omit `payment_methods` and the seed enables `offline`, leaving `card` disabled** — cards are off by default and only belong on with a provider wired, since an enabled card option with nothing behind it answers `503 no_card_payment_provider` at checkout. The decision: [`../install/03-data.md`](../install/03-data.md).
+
+### Payload — `products` / `coupons`
+
+The one-call catalog bootstrap. Entries reference categories/ribbons/attributes **by display name** — taxonomy is get-or-created (slugs/codes derived, existing records matched case-insensitively and reused, their casing canonicalized into the product), so no id juggling.
+
+| Key | Shape | Notes |
+|---|---|---|
+| `categories` `ribbons` | `["Dresses"]` | display names; created if new, reused if not |
+| `attributes` | `[{ name, options }]` or `{ <name>: [options] }` | declares the variant axes |
+| `variations` | `[{ options: { <name>: <option> }, ...overrides }]` | the stocked combinations. **Omit it to auto-generate all** combinations, each inheriting the product-level price/sale fields |
+| `default_options` | `{ <name>: <option> }` | the pre-selected combination |
+| everything else | `commerce.Product` fields | `name` (required), `slug`, `sku`, `status`, `regular_price`, `sale_price`, `images`, `featured`, `virtual`, `downloadable`, `downloads`, `tax_status`, `tax_group`, `stock_quantity`, `weight`, `dimensions`, `meta_data` |
+
+A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without one it draws on the parent's pooled stock (`"parent"`), and its SKU is synthesized from the parent's when absent. Parent price and `stock_status` are derived by the same helpers as `save` ([derived fields](./entities.md#derived-fields--never-write-these)), but **no `product.created` webhooks fire** — bootstrap precedes subscribers, so use `admin-products` for webhook-visible creates. **Re-runs converge**: a product whose `sku` (or, with none, derived slug) already exists is skipped and reported, so retries never duplicate; an explicit variation SKU already in use is **`409 duplicate_sku`**. `coupons` is a thin passthrough (code lowercased, skip-if-exists).
 
-**`products`** is the one-call catalog bootstrap — the worked example and full semantics are in [`../post-installation.md` §3.1](../post-installation.md#31-the-products-payload). Each entry references categories/ribbons/attributes by **display name** (taxonomy is get-or-created: slugs/codes derived, existing records matched case-insensitively and reused, with the stored casing canonicalized into the product). `attributes: [{ name, options }]` (or `{ <name>: [options] }`) declares the variant axes; `variations: [{ options: { <name>: <option> }, ...overrides }]` lists the stocked combinations — omit it to auto-generate **all** combinations, each inheriting the product-level price/sale fields. A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without one it draws on the parent's pooled stock (`"parent"`). Variation SKUs are synthesized from the parent SKU when absent. Parent `price`/`regular_price`/`on_sale` are rolled up from the cheapest publishable variant, `stock_status` derived, category/ribbon counts maintained — same helpers as `admin-products` `save`, but **no `product.created` webhooks are dispatched** (bootstrap precedes webhook subscribers; use `admin-products` for webhook-visible creates). Payload problems fail before any write as **400** `invalid_payload` with `errors: [{ path, error }]`; an explicit variation SKU already in use is **409** `duplicate_sku`; a mid-write failure rolls back everything the call created (**500** `catalog_seed_failed`) without touching reused taxonomy. **Re-runs converge**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported, so retries never duplicate. Limits: ≤100 products, ≤50 variations per product, ≤500 variations per call, ≤50 coupons/locations. `coupons` is a thin passthrough (code lowercased, skip-if-exists); **`locations`** creates Shipping & Tax Locations (`{ name, countries?: ["IL"], shipping_rates: [{ name, cost, free_over? }], tax_groups?: [{ name, rates: [{ name, rate }] }], shipping_tax?: { type: "percent"|"fixed", value } }` — the default `Products` tax group is added when missing; skip-if-exists by name). Passing any `locations` suppresses the seeded "Rest of the world" fallback — yours become the store's only locations; without them the free-shipping fallback is seeded. `with_sample_data: true` seeds the template's demo catalog instead (only when the store has zero products) and cannot be combined with the catalog keys.
+**Limits:** ≤100 products, ≤50 variations per product, ≤500 variations per call, ≤50 coupons, ≤50 locations.
+
+### Payload — `locations`
+
+Seeding `locations` is **the** way to set shipping up. Each entry becomes a `commerce.ShippingTaxLocation`, skip-if-exists **by name**.
+
+| Key | Shape | Notes |
+|---|---|---|
+| `name` | string, required | the skip-if-exists match key |
+| `countries` | `["IL", "DE"]` | ISO country codes → `{ type: "country" }` regions |
+| `continents` | `["EU"]` | one of `AF` `AN` `AS` `EU` `NA` `OC` `SA`, sparing you a 51-code country list. `EU` is the **continent** Europe, not the European Union. An unknown code fails listing all seven |
+| `regions` | `[{ type, code }]` | raw escape hatch (`country`\|`state`\|`continent`; state codes are `US:CA`) |
+| `rest_of_world` | `true` | the **catch-all** every unmatched address falls to. It has no regions, so combining it with `countries`/`continents`/`regions` is a contradiction and fails validation |
+| `order` | integer | match priority, **ascending**. Defaults to the **payload position**, so the array reads as the priority; an explicit value wins |
+| `shipping_rates` | `[{ id?, name, cost, free_over? }]` | one checkout choice each. `id` is minted from the location + rate names when omitted, and must stay stable (carts and orders reference the chosen rate by it). `free_over` = discounted items subtotal at which it becomes free. Negative `cost` fails |
+| `tax_groups` | `[{ name, rates: [{ name, rate }] }]` | a `Products` group is prepended when missing (products pick one by name via `tax_group`). A `rate` outside 0–100 fails |
+| `shipping_tax` | `{ type: "percent"\|"fixed", value }` | tax on the shipping line |
+
+```js
+locations: [
+  { name: "Europe",    continents: ["EU"],    shipping_rates: [{ name: "Standard", cost: 20 }] },
+  { name: "Worldwide", rest_of_world: true,   shipping_rates: [{ name: "International", cost: 100 }] },
+]
+```
+
+**A payload carrying `locations` suppresses the seeded `Rest of the world` fallback** (free standard delivery, `order: 999`) — yours become the store's only shipping data, since a second no-region location beside them would be a fallback nobody asked for: shadowed today, live the moment theirs is reordered or deleted. The cost: **locations with no catch-all ship only to the listed regions**, every other address getting `shipping_not_available` at checkout. Plausibly intended, so not an error — it returns as `warnings: ["no_catchall_location: …"]`. Full model: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
+
+### Response
+
+```js
+{
+  seeded: { settings_groups, gateways, locations },   // counts created by this call
+  sample_data: {…} | false,                          // same shape as `catalog`
+  catalog: {                                         // null when no catalog keys were passed
+    categories, ribbons, attributes, terms,          // each { created, reused }
+    products_created, products_skipped, variations_created,
+    coupons: { created, skipped }, locations: { created, skipped },
+    products: [ { name, id, slug, sku, variation_count }
+              | { name, skipped: true, reason: "sku_exists"|"slug_exists", existing_id } ],
+  } | null,
+  store_name: { value, action: "created"|"filled"|"unchanged"|"kept_existing" },
+  currency:   { value, action: "created"|"updated"|"unchanged" } | null,
+  payment_methods: { enabled: [slug], disabled: [slug] } | null,   // null when not passed
+  warnings: [ "no_catchall_location: …" ],           // ALWAYS present; empty = nothing to flag
+}
+```
 
-→ `{ seeded: { settings_groups, gateways, locations }, sample_data: {...} | false, catalog: { categories|ribbons|attributes|terms: { created, reused }, products_created, products_skipped, variations_created, coupons, locations, products: [{ name, id, slug, sku, variation_count } | { name, skipped: true, reason: "sku_exists"|"slug_exists", existing_id }] } | null, store_name: { value, action: "created" | "filled" | "unchanged" | "kept_existing" }, currency: { value, action: "created" | "updated" | "unchanged" } | null }`.
+Record `products[].slug` — those are the URLs your storefront routes to — and read `warnings` unconditionally.