@base44/app-plugin-commerce 0.1.6 → 0.1.7

package/skills/commerce/installation-guidelines.md

@@ -1,6 +1,6 @@
 # Installation Guidelines
 
-How to install the Base44 Commerce Template into an existing Base44 app. This file lives inside the **commerce skill** folder and is installed into the app at `skills/commerce/installation-guidelines.md`. Once the files are in place, continue with [`post-installation.md`](./post-installation.md) (embedding the admin pages, seeding the store's data, the storefront quick start); day-2 guidance lives in [`skills/commerce/SKILL.md`](./SKILL.md), alongside the API references in [`skills/commerce/docs/`](./docs/).
+How to install the Base44 Commerce Template into an existing Base44 app. This file lives inside the **commerce skill** folder and is installed into the app at `.agents/skills/commerce/installation-guidelines.md`. Once the files are in place, continue with [`post-installation.md`](./post-installation.md) (embedding the admin pages, seeding the store's data, the storefront quick start); day-2 guidance lives in [`.agents/skills/commerce/SKILL.md`](./SKILL.md), alongside the API references in [`.agents/skills/commerce/docs/`](./docs/).
 
 > **If you are a Base44 agent working inside the runtime, read this first:**
 > - **Skip the `npx base44` commands.** The runtime deploys functions and pushes entities automatically the moment you write the files — writing a resource file *is* the deploy.
@@ -27,21 +27,21 @@ Relative to the script's own folder (`examples/commerce/scripts/`), it copies:
 | `../base44/agents/commerce/` | `../../../base44/agents/commerce/` |
 | `../src/commerce/admin/` | `../../../src/commerce/admin/` |
 | `../src/commerce/utils/` | `../../../src/commerce/utils/` |
-| `../skills/commerce/` | `../../../skills/commerce/` |
+| `../skills/commerce/` | `../../../.agents/skills/commerce/` |
 
-Directories are merged: files owned by the template are overwritten (re-running after a template update is safe); everything else in your app is left untouched. Files the template has since **renamed or retired** are deleted on install (it reports each one) — otherwise stale guidance would sit in `skills/` forever, and agents read whatever is there. The skill folder carries all the documentation — `SKILL.md`, this file, `post-installation.md`, the topic references in `references/` and the API docs in `docs/` — so the installed app gets it at `skills/commerce/` where agents pick it up natively; the template repo itself also stays under `examples/commerce/` for reference.
+Directories are merged: files owned by the template are overwritten (re-running after a template update is safe); everything else in your app is left untouched. Files the template has since **renamed or retired** are deleted on install (it reports each one) — otherwise stale guidance would sit in `.agents/skills/` forever, and agents read whatever is there. The skill folder carries all the documentation — `SKILL.md`, this file, `post-installation.md`, the topic references in `references/` and the API docs in `docs/` — so the installed app gets it at `.agents/skills/commerce/` where agents pick it up natively; the template repo itself also stays under `examples/commerce/` for reference.
 
 **Manual.** Equivalently, copy by hand:
 
 1. Copy `base44/entities/commerce.*`, `base44/functions/commerce/*`, `base44/shared/commerce/*` and `base44/agents/commerce/*` into your app's `base44/` dir (merge, don't overwrite unrelated files). `shared/` is bundled into every function at deploy time.
 2. Copy `src/commerce/admin/` → `src/commerce/admin/` and `src/commerce/utils/` → `src/commerce/utils/` (the storefront variant-selection helpers; framework-free, no deps).
-3. Copy `skills/commerce/` → `skills/commerce/` (the commerce skill — `SKILL.md`, this file, `post-installation.md`, the `references/` topic guides and the `docs/` API references — for agents working on the app).
+3. Copy `skills/commerce/` → `.agents/skills/commerce/` (the commerce skill — `SKILL.md`, this file, `post-installation.md`, the `references/` topic guides and the `docs/` API references — for agents working on the app).
 
 Confirm your `base44/config.jsonc` `entitiesDir`/`functionsDir` point at these folders (the defaults do).
 
 ## 2. Deploy and wire up
 
-1. `npx base44 entities push` — creates/updates the 24 entity schemas. *(CLI path only — the Base44 runtime deploys on write.)*
+1. `npx base44 entities push` — creates/updates the 20 entity schemas. *(CLI path only — the Base44 runtime deploys on write.)*
 2. `npx base44 functions deploy` — deploys the 16 functions. *(CLI path only.)*
 3. `npx base44 agents push` — registers the `commerce/StoreAdmin` agent (§3). *(CLI path only.)*
 4. Check the app's `package.json` for `sonner`, `recharts` and `react-markdown`, and run `npm i` **only** for the ones actually absent — all three ship with the default Base44 template, so the normal outcome is no install at all. Do not re-install a package that is already a dependency. Nothing else is needed. Verify the shadcn primitives listed in [`src/commerce/admin/README.md`](../../src/commerce/admin/README.md) exist in your app.
@@ -54,7 +54,7 @@ Check the install at any time:
 ```js
 const { data } = (await base44.functions.invoke("commerce/admin-tools", { action: "status" })).data;
 // → { template_version, seeded, settings_groups, counts: { "commerce.Product": n, ... },
-//     checks: { has_payment_gateways, has_default_zone } }
+//     checks: { has_payment_gateways, has_default_location } }
 ```
 
 `commerce/seed-store` is **idempotent** and starts with a **canary schema check**: it probe-writes one record per entity it will touch and deletes it. If you've modified an entity schema incompatibly, it aborts with HTTP 422 `schema_incompatible` and writes nothing:
@@ -77,7 +77,7 @@ The template ships an AI copilot for store operators:
 - **No `model` field, on purpose.** The platform's default-model path accepts slash-namespaced tool names; explicitly setting a `model` currently rejects them (LLM tool names must match `^[a-zA-Z0-9_-]{1,128}$`). If you set a model, the bot fails at message time with a `tools.0.custom.name` error.
 - **Variant safety** — the agent is instructed to never auto-pick a variation: for a product carrying attributes it fetches `{product, variations}` via `commerce/storefront-catalog get-product`, presents the variants as a table, and asks the operator which `variation_id` to use before touching an order, stock, or download grant.
 - **Bot UI** — `src/commerce/admin/bot/` (chat panel; "StoreAdmin bot" launcher at the bottom of the admin sidebar). Responses render as markdown via `react-markdown`, with the agent's GFM tables (`| col |` with `|---|` separators) rendered by the template's own `bot/pipe-tables.js` — no markdown plugin dependency. The panel lives behind the same `AuthGuard` as the rest of the admin.
-- **Config it can't change, it links to.** Store settings, tax rates, shipping zones, gateways and webhook definitions have no function tool, so the agent is instructed to name the screen and emit an `admin:`-scheme link (`[Settings → Tax](admin:settings/tax)`) rather than telling the operator to "do it manually". `bot/Markdown.jsx` resolves `admin:` through `useAdminHref()`, so links follow your actual mount point (`basePath`) and navigate in-app instead of opening a tab. If you add screens, add the path to the table in the agent's instructions.
+- **Config it can't change, it links to.** Store settings, Shipping & Tax Locations, gateways and webhook definitions have no function tool, so the agent is instructed to name the screen and emit an `admin:`-scheme link (`[Settings → Shipping & Tax](admin:settings/shipping-tax)`) rather than telling the operator to "do it manually". `bot/Markdown.jsx` resolves `admin:` through `useAdminHref()`, so links follow your actual mount point (`basePath`) and navigate in-app instead of opening a tab. If you add screens, add the path to the table in the agent's instructions.
 
 **Do not weaken the tool set.** The agent's power comes only from the admin functions' own `requireAdmin()` layer — don't add entity tools or service-role calls to the agent config, and keep `commerce/storefront-*` tools limited to the read-only catalog.
 
@@ -89,4 +89,4 @@ If your work includes a customer-facing shopfront, read **[`SKILL.md` → *If yo
 
 ## 5. Next steps
 
-Continue with [`post-installation.md`](./post-installation.md): embedding the admin pages (router mount, admin-role enforcement), seeding the store's data, and the logic-only storefront quick start. After that, [`skills/commerce/SKILL.md`](./SKILL.md) is the map for all day-2 work.
+Continue with [`post-installation.md`](./post-installation.md): embedding the admin pages (router mount, admin-role enforcement), seeding the store's data, and the logic-only storefront quick start. After that, [`.agents/skills/commerce/SKILL.md`](./SKILL.md) is the map for all day-2 work.

package/skills/commerce/post-installation.md

@@ -1,6 +1,6 @@
 # Post-installation
 
-What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, and build the storefront from the quick start below. Installed into the app at `skills/commerce/post-installation.md`.
+What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, and build the storefront from the quick start below. Installed into the app at `.agents/skills/commerce/post-installation.md`.
 
 ---
 
@@ -44,11 +44,11 @@ Even if the client guard were bypassed, layers 2 and 3 keep the store data safe.
 
 ## 2. Store data — seeding
 
-A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices), the `offline` and `stripe` payment gateways, three tax classes and a free "Rest of the world" fallback shipping zone — and, depending on the payload, the catalog. Pass **`currency`** (an ISO code, e.g. `"EUR"`) to set the store currency instead of the USD default — an explicit currency always wins, on a first seed and a re-run alike, and brings the currency's standard decimal count with it.
+A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices) and the `offline` and `card` payment gateways — and, depending on the payload, the catalog. A fallback "Rest of the world" **Shipping & Tax Location** (one free shipping rate, no tax) is seeded **only when the payload carries no `locations`** — locations you pass are the store's only shipping data, with no seeded fallback beside them. Pass **`currency`** (an ISO code, e.g. `"EUR"`) and/or **`weight_unit`**/**`dimension_unit`** to set the store's currency and measurement units instead of the defaults — explicit values always win, on a first seed and a re-run alike. (Prices are *formatted* with `Intl.NumberFormat` per the viewer's locale — the currency is a value; there are no format settings.)
 
 | Mode | Body | Products created |
 |---|---|---|
-| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `tax_rates`) | Yours — categories, attributes, variants and all, in this one call |
+| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) | Yours — categories, ribbons, attributes, variants and all, in this one call |
 | **Demo data** | `{ store_name, with_sample_data: true }` | The template's 10 generic demo products (skipped if any product exists) |
 | **No products** | `{ store_name }` | None — defaults only |
 
@@ -60,7 +60,9 @@ The call runs a canary schema check first — on **422** `schema_incompatible` f
 
 ### 2.1 The `products` payload
 
-Reference everything by **display name** — categories, tags, attributes and their options are get-or-created (slugs and codes derived, existing records matched case-insensitively and reused). Variants come from `attributes`: list each axis with the options the product comes in, and either pass explicit `variations` (only the combinations you stock, with per-variation overrides) or omit them to auto-generate **every combination**. Prices and the sale window are inherited from the product spec unless a variation overrides them; a variation with its own `stock_quantity` tracks it, one without draws on the parent's pooled `stock_quantity`.
+**This is the store's real data, not template data.** The call writes the actual `commerce.*` records the admin and the storefront API read from that moment on — nothing is post-processed, substituted or "filled in by the platform" later. Whatever you pass is exactly what `list-products`/`get-product` return, so pass final values (real copy, real prices, permanently-resolvable image URLs) and build the storefront on what the API returns — never on client-side constants mirroring the seed (e.g. a slug→image map): the database is the single source of truth, and such a mirror silently diverges the first time a product is edited in the admin.
+
+Reference everything by **display name** — categories, ribbons, attributes and their options are get-or-created (slugs and codes derived, existing records matched case-insensitively and reused). Variants come from `attributes`: list each axis with the options the product comes in, and either pass explicit `variations` (only the combinations you stock, with per-variation overrides) or omit them to auto-generate **every combination**. Prices and the sale window are inherited from the product spec unless a variation overrides them; a variation with its own `stock_quantity` tracks it, one without draws on the parent's pooled `stock_quantity`.
 
 ```js
 await base44.functions.invoke("commerce/seed-store", {
@@ -73,7 +75,7 @@ await base44.functions.invoke("commerce/seed-store", {
       regular_price: 19.99,
       stock_quantity: 50,                      // implies manage_stock: true
       categories: ["Clothing"],                // get-or-create by name
-      tags: ["bestseller"],
+      ribbons: ["Best Seller"],
       images: ["https://…/tee.jpg"],           // URLs or { src, alt }
       short_description: "A soft, breathable everyday tee.",
       description: "<p>Cut from combed cotton…</p><ul><li>100% combed cotton</li><li>Pre-shrunk</li></ul>",
@@ -99,10 +101,16 @@ await base44.functions.invoke("commerce/seed-store", {
     },
   ],
   coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],   // optional
+  locations: [{                              // optional — passing any makes these the store's ONLY locations (the free-shipping fallback is not seeded)
+    name: "Israel", countries: ["IL"],
+    shipping_rates: [{ name: "Standard", cost: 20, free_over: 150 }],
+    tax_groups: [{ name: "Products", rates: [{ name: "VAT", rate: 18 }] }],
+    shipping_tax: { type: "percent", value: 18 },   // or { type: "fixed", value: 5 }
+  }],
 });
 ```
 
-What the seeder does per product: derives a unique slug, checks SKU uniqueness, prices variations (`sale_price` + optional `date_on_sale_from/to` supported at both levels), rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant (never set a variant parent's price yourself — it's derived), sets `stock_status`, and maintains category/tag counts. Products default to `status: "publish"`; pass `"draft"` to review first. Other `commerce.Product` fields (`weight`, `dimensions`, `virtual`, `downloadable`, `downloads`, `meta_data`, …) pass through; unknown keys are rejected so typos surface instead of vanishing.
+What the seeder does per product: derives a unique slug, checks SKU uniqueness, prices variations (`sale_price` + optional `date_on_sale_from/to` supported at both levels), rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant (never set a variant parent's price yourself — it's derived), sets `stock_status`, and maintains category/ribbon counts. Products default to `status: "publish"`; pass `"draft"` to review first. Other `commerce.Product` fields (`weight`, `dimensions`, `virtual`, `downloadable`, `downloads`, `meta_data`, …) pass through; unknown keys are rejected so typos surface instead of vanishing.
 
 **Re-runs converge instead of duplicating**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported — safe for retries after a timeout, and for seeding into a store that already has products. Limits: ≤100 products and ≤500 variations per call, ≤50 variations per product (an auto-generated cartesian above that is rejected — pass explicit `variations`).
 
@@ -111,9 +119,9 @@ The response reports everything:
 ```jsonc
 { "seeded": { "settings_groups": 6, "gateways": 2, ... },
   "catalog": {
-    "categories": { "created": 2, "reused": 0 }, "tags": { ... }, "attributes": { ... }, "terms": { ... },
+    "categories": { "created": 2, "reused": 0 }, "ribbons": { ... }, "attributes": { ... }, "terms": { ... },
     "products_created": 2, "products_skipped": 0, "variations_created": 4,
-    "coupons": { "created": 1, "skipped": 0 }, "tax_rates": { "created": 0, "skipped": 0 },
+    "coupons": { "created": 1, "skipped": 0 }, "locations": { "created": 1, "skipped": 0 },
     "products": [
       { "name": "Classic T-Shirt", "id": "…", "slug": "classic-t-shirt", "sku": "TEE-CLASSIC", "variation_count": 0 },
       { "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "sku": "SNK-RUN", "variation_count": 4 }
@@ -123,13 +131,13 @@ The response reports everything:
   "currency": { "value": "EUR", "action": "created" } }   // "updated" | "unchanged" on re-runs; null when not passed
 ```
 
-**Images**: every product needs at least one. Use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product.
+**Images**: every product needs at least one, and the URL you seed is the URL the store serves — there are no placeholders to swap later. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. If an image isn't ready at seed time, seed without it and set it afterwards through the admin API — don't seed a dead path and compensate in the frontend.
 
 A successful response means the data is in — the catalog and settings are live exactly as reported. Write any remaining store-specific settings into `commerce.StoreSettings` (direct CRUD, one record per `group_id` — weight/dimension units are the usual ones; patch `values`, don't replace groups you weren't asked about).
 
 ### 2.2 Payments
 
-Card payments are **already implemented** (hosted payment page, payment links, refunds). **Get the payment provider connected at the beginning of the implementation** — have the platform's **Stripe** integration configured for the app while you build, so it is already connected by the time you create the checkout and a test order can prove the whole path. The `offline` gateway (manual reconciliation) works with nothing to configure. Provider internals, webhooks and refunds are day-2 material: [`references/online-payments.md`](./references/online-payments.md).
+The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions. The **Credit card** option needs a payment provider, which means implementing exactly two files (`shared/commerce/card-payment.ts` + the payment webhook); until then it answers `503 no_card_payment_provider` at checkout, or can simply be switched off. Details: [`references/online-payments.md`](./references/online-payments.md).
 
 ---
 
@@ -149,25 +157,26 @@ The cart is identified by a **`cart_token`** the backend mints — persist it in
 
 ```js
 const info = await inv("commerce/storefront-catalog", { action: "get-store-info" });
-// info.settings → { store_name, currency, currency_position, num_decimals, … } — format money with these
+// info.settings → { store_name, currency, weight_unit, … } — format money with
+// Intl.NumberFormat(undefined, { style: "currency", currency: info.settings.currency })
 // info.payment_gateways → [{ slug, title, description, online }] — you'll need this at checkout
 // info.countries / info.currencies → static tables for address forms and money display
 
 const { products, page, per_page, has_next } = await inv("commerce/storefront-catalog", {
   action: "list-products",
-  page: 1, per_page: 12,           // optional: search, category_id, tag_id, featured, on_sale,
+  page: 1, per_page: 12,           // optional: search, category_id, ribbon_id, featured, on_sale,
   sort: "-created_date",           //   min_price, max_price, in_stock_only
 });                                // sort: -created_date | name | price | -price | popularity | rating
 ```
 
-Each row is a full product record — for a card use `name`, `images[0]?.src`, `price`, `regular_price`, `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `tags` (`[{ id, name }]`, may be absent). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `{ action: "list-categories" }` (a tree via `parent_id`).
+Each row is a full product record — for a card use `name`, `images[0]?.src`, `price`, `regular_price`, `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `{ action: "list-categories" }` (a tree via `parent_id`).
 
 **Carry forward:** each card links to the product page by **`slug`**.
 
 ### 3.2 Product page — variant selection included
 
 ```js
-const { product, variations, categories, tags, reviews } =
+const { product, variations, categories, ribbons, reviews } =
   await inv("commerce/storefront-catalog", { action: "get-product", slug });   // or { id }
 
 // One selector PER product.attributes[] entry — never a flat list of variations.
@@ -184,21 +193,21 @@ const view = resolveSelection(product, variations, selection);
 // view.addToCart    → { product_id, variation_id } — null until the selection resolves
 ```
 
-Add to cart — **create** mints the `cart_token` on first add; every later call reuses it:
+Add to cart — `add-item` bootstraps the cart itself: a missing, stale or expired token starts a fresh cart, so the one rule is to **re-persist the `cart_token` from every response** (your cached token may have expired — 48h TTL — or been consumed by a checkout):
 
 ```js
-let cart_token = localStorage.getItem("cart_token");
-if (!cart_token) {
-  const cart = await inv("commerce/storefront-cart", { action: "create" });
-  cart_token = cart.cart_token;
-  localStorage.setItem("cart_token", cart_token);
-}
-await inv("commerce/storefront-cart", { action: "add-item", cart_token, ...view.addToCart, quantity: 1 });
+const cart = await inv("commerce/storefront-cart", {
+  action: "add-item",
+  cart_token: localStorage.getItem("cart_token") || undefined,   // fine if absent/stale
+  ...view.addToCart,
+  quantity: 1,
+});
+localStorage.setItem("cart_token", cart.cart_token);   // ALWAYS — the token may be a new cart's
 ```
 
-A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call. Show `reviews` (`{ items, has_next, average_rating, rating_count }`) and the `upsells`/`cross_sells` summaries the same response carries.
+A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call. Show `reviews` (`{ items, has_next, average_rating, rating_count }`) and the `upsells`/`cross_sells` summaries the same response carries. On the other cart actions a `404 cart_not_found|cart_expired` means the cached token went stale — clear it and treat the cart as empty.
 
-**Carry forward:** the **`cart_token`**.
+**Carry forward:** the **`cart_token`** — from the response, every time.
 
 ### 3.3 Cart
 
@@ -215,42 +224,51 @@ cart = await inv("commerce/storefront-cart", { action: "remove-item", cart_token
 cart = await inv("commerce/storefront-cart", { action: "apply-coupon", cart_token, code });
 ```
 
-Shipping is chosen **on the cart, before place-order** — this is the step storefronts most often skip, and `place-order` refuses without it (`400 shipping_method_required`):
+Shipping is chosen **on the cart, before place-order** — this is the step storefronts most often skip, and `place-order` refuses without it (`400 shipping_method_required`). **Call `set-shipping-address` the moment the customer provides an address** — every shipping option and cost is recalculated by that call (never reuse a list fetched earlier), and an address the store doesn't ship to **fails right there** with `400 shipping_not_available`, so the address form is where you surface it:
 
 ```js
+// as soon as the address is entered — this is what (re)calculates shipping options + cost
 cart = await inv("commerce/storefront-cart", { action: "set-shipping-address", cart_token,
-  address: { country, state, postcode, city } });
+  address: { country, state, postcode, city } });   // 400 shipping_not_available → show it on the address form
+// cart.chosen_shipping_method is the rate's ID (a string) — to display it, look
+// it up: cart.available_shipping_methods.find(m => m.id === cart.chosen_shipping_method)
+// and render that entry's title + cost. Never render the id itself.
 switch (cart.shipping_status) {
   case "auto_selected": break;          // only ONE option existed — the backend already applied it;
-                                        // no picker needed, just display cart.chosen_shipping_method
+                                        // no picker needed, just display the looked-up title + cost
   case "chosen": break;                 // customer's earlier choice still valid
   case "choice_required":               // several options — MUST render cart.available_shipping_methods
     // [{ id, title, cost }] as a picker, then send the customer's pick:
     cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method", cart_token,
       method_id: picked.id });          // the entry's id, not its method_id type
     break;
-  case "none_available": /* the store doesn't ship there — say so, don't place the order */ break;
+  case "missing_address": break;        // several zones, no address yet — shipping cost is NOT
+                                        // calculated; collect the address and call set-shipping-address
   case "not_needed": break;             // fully virtual cart
 }
 ```
 
+A store with exactly **one shipping zone** shows its options (and, auto-selected, the cost) on the cart even before an address is set — the options are the same everywhere. Several zones report `missing_address` until the address resolves one.
+
 **Carry forward:** the **`cart_token`** (address and method choice live on the cart).
 
 ### 3.4 Checkout & order-received
 
-The checkout page renders **two sets of options that are store data, never hardcoded**: the shipping methods (already resolved on the cart in step 3 — `place-order` refuses with `400 shipping_method_required` until `shipping_status` is `chosen`/`auto_selected`/`not_needed`) and the payment methods, which come from `info.payment_gateways` (step 1) — already filtered to what can actually take payment right now, so every entry you render is payable:
+The checkout page renders **two sets of options that are store data, never hardcoded**: the shipping methods (already resolved on the cart in step 3 — `place-order` refuses with `400 shipping_method_required` until `shipping_status` is `chosen`/`auto_selected`/`not_needed`) and the payment methods, which come from `info.payment_gateways` (step 1) — every gateway the admin has **enabled**:
 
 ```js
-// card payments ride the app's Stripe integration — setup & provider details:
-// skills/commerce/references/online-payments.md
+// wiring a card provider = implementing two files — details:
+// .agents/skills/commerce/references/online-payments.md
 const gateways = info.payment_gateways;   // [{ slug, title, description, online }] — admin-owned data
 // several → render a picker using the admin's title/description as the labels
 // exactly ONE → no picker: use it directly, but still show its title so the customer knows how they'll pay
 // none → checkout cannot complete — say so instead of rendering a dead button
-const payment_method = gateways.length === 1 ? gateways[0].slug : picked.slug;  // never a hardcoded "stripe"
+const payment_method = gateways.length === 1 ? gateways[0].slug : picked.slug;  // never a hardcoded "card"
 ```
 
-`online: true` marks the card/redirect gateway; `offline` is manual reconciliation. Then one call places the order:
+While the store has no card provider implemented, picking the card gateway fails `place-order` with `503 no_card_payment_provider` — tell the customer card payment is temporarily unavailable and offer the other methods.
+
+`online: true` marks the card/redirect gateway; every other gateway is manual reconciliation. Then one call places the order:
 
 ```js
 const res = await inv("commerce/storefront-checkout", {
@@ -260,11 +278,11 @@ const res = await inv("commerce/storefront-checkout", {
   // shipping: { … } if it differs from billing; customer_note?; return_url: window.location.origin
 });
 // res → { order_id, order_number, order_key, status, totals, order,
-//         payment_instructions,   // offline: { description, account_details } — render them
-//         payment }               // online: { status: "requires_payment", checkout_url, … } | null
+//         payment_instructions,   // manual gateways: { description, account_details } — render them
+//         payment }               // card: { status: "requires_payment", checkout_url, … } | null
 
 if (res.payment?.status === "requires_payment") window.location.href = res.payment.checkout_url;
-else showConfirmation(res);        // offline order placed — show payment_instructions
+else showConfirmation(res);        // manual order placed — show payment_instructions
 ```
 
 Every payment link returns to **`/order-received`** — the page from §1 step 3. It is one call, idempotent, safe on every visit:
@@ -272,21 +290,24 @@ Every payment link returns to **`/order-received`** — the page from §1 step 3
 ```js
 // GET /order-received?order_id=…&order_key=…&payment=success|cancel
 const params = new URLSearchParams(window.location.search);
-const { state, order, payment_link } = await inv("commerce/payments", {
+const { state, order, payment_link, payment_instructions } = await inv("commerce/payments", {
   action: "complete-return",
   order_id: params.get("order_id"), order_key: params.get("order_key"),
   payment: params.get("payment"),        // only a hint — the server verifies with the provider
   return_url: window.location.origin,
 });
 // state === "paid"      → thank-you + order summary (order is now marked paid)
-// state === "unpaid"    → offer payment_link.url to try again
+// state === "unpaid"    → card order: offer payment_link.url to pay now;
+//                         manual order: render payment_instructions ({ description, account_details })
 // state === "cancelled" → payment was cancelled — offer payment_link.url or support
 ```
 
+Two shapes to get right when rendering: **`order` carries flat totals** — `order.total`, `order.shipping_total`, `order.total_tax` — there is **no `order.totals` object** (that nested shape belongs to the cart view and the place-order response's top-level `totals`); and `payment_link` is `{ url, reference } | null` (card orders only).
+
 **Carry forward:** `order_id` + `order_key` are the guest's proof of ownership — `commerce/storefront-account` `get-order` with both returns the order for a tracking page (signed-in customers get `my-orders` with no key).
 
 ---
 
 ## 4. Next
 
-Continue with the commerce skill — [`skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, deeper storefront features ([`references/product-render.md`](./references/product-render.md) for what to render per view, [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variant edge cases, [`references/reviews.md`](./references/reviews.md) for the ready-made reviews backend), Stripe wiring, scheduled maintenance, emails, webhooks, and operational limits.
+Continue with the commerce skill — [`.agents/skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, deeper storefront features ([`references/product-render.md`](./references/product-render.md) for what to render per view, [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variant edge cases, [`references/reviews.md`](./references/reviews.md) for the ready-made reviews backend), payment provider wiring, scheduled maintenance, emails, webhooks, and operational limits.

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

@@ -4,20 +4,23 @@ Where to change what, in `src/commerce/admin/pages/products/`. The shape follows
 rule: **a product sells variants because it carries attributes** — there is no product
 type — so everything a customer actually buys is edited in one place.
 
-## Tabs
+## Sections
 
-`components/ProductDataPanel.jsx` builds the list. There are four, and two are conditional:
+`components/ProductDataPanel.jsx` stacks the sections one below the other — no side menu.
+There are four, and one is conditional:
 
-| Tab | File | Holds |
+| Section | File | Holds |
 |---|---|---|
-| **Price & Inventory** | `components/tabs/PriceInventoryTab.jsx` | Tax status/class and *limit to 1 per order* (product-wide) → the **Attributes** section → a row per purchasable thing |
+| **Price & Inventory** | `components/tabs/PriceInventoryTab.jsx` | Tax status/group and *limit to 1 per order* (product-wide) → the **Attributes** section → a row per purchasable thing |
 | **Modifiers** | `components/tabs/ModifiersTab.jsx` | `meta_data` key/value pairs — descriptive properties (Material, Care, GTIN). They never affect price, stock or variants |
 | **Downloads** | `components/tabs/DownloadsTab.jsx` | Only when `downloadable` |
 | **Linked products** | `components/tabs/LinkedTab.jsx` | Upsells and cross-sells |
 
-`Virtual` and `Downloadable` are checkboxes in the panel header, not tabs. There is no
-General, Inventory, Variations, Attributes, Shipping, Advanced or External tab — all of
-those were removed, and `scripts/install.js` retires the files on upgrade.
+`Virtual` and `Downloadable` are checkboxes in the panel header. The main column reads
+Name → Description → Short description → Product data; the sidebar's **Publish** box has a
+single **Visible** toggle driving `status` (publish/draft) — there is no catalog-visibility
+field. The product's **Tax group** names a group defined per Shipping & Tax Location
+(default `Products`).
 
 ## Price & Inventory
 
@@ -25,9 +28,9 @@ those were removed, and `scripts/install.js` retires the files on upgrade.
   edits the product's own fields. A product with attributes shows a row per variant.
   Both go through the same `PriceFields` / inventory / `ShippingFields` / `DownloadsFields`
   components, so there is one definition to change, not two.
-- **Shipping is per row.** Weight, dimensions and shipping class live on each variant (a
-  large mug weighs more than a small one); the Base price row edits the product's own.
-  Hidden when the product is virtual.
+- **Shipping is per row.** Weight and dimensions live on each variant (a large mug weighs
+  more than a small one); the Base price row edits the product's own. Hidden when the
+  product is virtual.
 - **The parent price is not editable** when variants exist — `commerce/admin-products`
   derives `regular_price`, `price` and `on_sale` from the cheapest publishable variant on
   save, and the seeder does the same. Don't add an input for it.
@@ -52,5 +55,5 @@ merchant touches anything. Keep that guard if you touch the effect.
 
 Attribute and value *records* are shared between products, so the **Manage attributes**
 dialog saves them immediately, unlike the rest of the form which batches until Save. There
-are no Attributes or Tags pages in the side menu: attributes are reachable only from here,
-tags from the `TaxonomyPanel` card in the product sidebar.
+are no Attributes or Ribbons pages in the side menu: attributes are reachable only from
+here, ribbons from the `TaxonomyPanel` card in the product sidebar.

package/skills/commerce/references/emails.md

@@ -1,10 +1,10 @@
 # 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 [`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.
+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 follow the same chain: `inventory.notification_recipient`, else the first `emails.admin_recipients` entry, else the first admin user.
+- 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.

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

@@ -12,7 +12,7 @@
 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 reviews, 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.
-- **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 `confirmOnlinePayment()`, which asks the provider and checks the session was opened for that order. Adding a gateway means writing an adapter (see [`online-payments.md`](./online-payments.md)), not a new "confirm" endpoint.
+- **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 two payment files (see [`online-payments.md`](./online-payments.md)), never a new "confirm" endpoint.
 - **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.