@base44/app-plugin-commerce 0.1.5 → 0.1.7

package/base44/shared/commerce/totals.ts

@@ -3,12 +3,14 @@
  * Used by: commerce/storefront-cart `totals` (preview), commerce/storefront-checkout
  * `place-order` (authoritative), commerce/admin-orders `create`/`recalculate`.
  *
- * Pipeline (standard commerce semantics): resolve lines → coupons → fees → shipping → tax → totals.
+ * Pipeline: resolve lines → coupons → fees → shipping → tax → totals.
  * All internal math is ex-tax; tax-inclusive catalog prices are netted first.
+ * Shipping options and tax both come from the ONE matched
+ * commerce.ShippingTaxLocation (see shared/commerce/shipping.ts + tax.ts).
  */
 import { round2, distributeProportionally } from "./money.ts";
-import { applyRates, extractInclusiveTax, matchTaxRates, sumTax } from "./tax.ts";
-import { availableMethods, matchZone } from "./shipping.ts";
+import { applyRates, DEFAULT_TAX_GROUP, extractInclusiveTax, shippingTaxFor, sumTax, taxRatesFor } from "./tax.ts";
+import { availableRates, matchLocation } from "./shipping.ts";
 import { applyCoupons } from "./coupons.ts";
 import { getSetting } from "./settings.ts";
 import { uuid } from "./sequence.ts";
@@ -24,7 +26,7 @@ export interface TotalsItem {
 export interface TotalsFee {
   name: string;
   amount: number;
-  tax_class?: string;
+  tax_group?: string;
   tax_status?: string; // taxable | none
   line_id?: string;
 }
@@ -35,11 +37,9 @@ export interface TotalsInput {
   fees?: TotalsFee[];
   billing?: any;
   shipping_address?: any;
-  chosenShippingMethodId?: string; // ShippingZoneMethod id
+  chosenShippingMethodId?: string; // the chosen shipping rate id
   settings: Record<string, any>;   // groups object from getSettings()
-  taxRates?: any[];
-  zones?: any[];
-  zoneMethods?: any[];
+  locations?: any[];               // commerce.ShippingTaxLocation records
 }
 
 export interface TotalsResult {
@@ -57,17 +57,16 @@ export interface TotalsResult {
   total_tax: number;
   total: number;
   prices_include_tax: boolean;
-  available_shipping_methods: Array<{ id: string; method_id: string; title: string; cost: number }>;
-  matched_zone_id: string | null;
+  available_shipping_methods: Array<{ id: string; title: string; cost: number }>;
+  matched_location_id: string | null;
 }
 
-/** Effective tax class/status with variation "parent" inheritance. */
-function effectiveTax(product: any, variation?: any): { tax_class: string; tax_status: string } {
+/** Effective tax group/status with variation "parent" status inheritance. */
+function effectiveTax(product: any, variation?: any): { tax_group: string; tax_status: string } {
   const status = variation?.tax_status && variation.tax_status !== "parent"
     ? variation.tax_status
     : product.tax_status ?? "taxable";
-  const cls = (variation?.tax_class || product.tax_class) ?? "standard";
-  return { tax_class: cls, tax_status: status };
+  return { tax_group: product.tax_group || DEFAULT_TAX_GROUP, tax_status: status };
 }
 
 function resolveTaxAddress(input: TotalsInput): any {
@@ -76,18 +75,28 @@ function resolveTaxAddress(input: TotalsInput): any {
   return input.shipping_address ?? input.billing ?? {}; // "shipping" default
 }
 
+/**
+ * Resolve the location for an address; with no address, a store with exactly
+ * ONE location still resolves to it — its options and taxes are the same for
+ * every address, so a cart can price before the customer types anything.
+ */
+function locationFor(locations: any[], addr: any): any | null {
+  if (addr?.country) return matchLocation(locations, addr);
+  return locations.length === 1 ? locations[0] : null;
+}
+
 /** Run the full totals pipeline. Pure aside from reading its inputs. */
 export function calculateTotals(input: TotalsInput): TotalsResult {
   const settings = input.settings ?? {};
   const pricesIncludeTax = !!getSetting(settings, "tax", "prices_include_tax", false);
-  const taxRates = input.taxRates ?? [];
-  const taxAddress = resolveTaxAddress(input);
+  const locations = input.locations ?? [];
+  const taxLocation = locationFor(locations, resolveTaxAddress(input));
 
   // ── 1. resolve lines (ex-tax) ────────────────────────────────────────────
   const lines = (input.items || []).map((it) => {
     const src = it.variation ?? it.product;
-    const { tax_class, tax_status } = effectiveTax(it.product, it.variation);
-    const rates = tax_status === "taxable" ? matchTaxRates(taxRates, taxAddress, tax_class) : [];
+    const { tax_group, tax_status } = effectiveTax(it.product, it.variation);
+    const rates = tax_status === "taxable" ? taxRatesFor(taxLocation, tax_group) : [];
     let unitPrice = Number(src.price ?? it.product?.price ?? 0);
     let subtotal = round2(unitPrice * it.quantity);
     if (pricesIncludeTax && rates.length) {
@@ -103,7 +112,7 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
       sku: (it.variation?.sku || it.product?.sku) ?? "",
       quantity: it.quantity,
       unit_price: unitPrice,
-      tax_class,
+      tax_group,
       tax_status,
       rates,
       subtotal,
@@ -114,7 +123,6 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
       taxes: [] as any[],
       attributes: it.attributes ?? [],
       meta_data: it.meta_data ?? [],
-      shipping_class_id: (it.variation?.shipping_class_id || it.product?.shipping_class_id) ?? "",
       virtual: !!(it.variation?.virtual ?? it.product?.virtual),
       product: it.product,
       variation: it.variation,
@@ -134,7 +142,7 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
   const feeLines = (input.fees || []).map((f) => ({
     line_id: f.line_id ?? uuid(),
     name: f.name,
-    tax_class: f.tax_class ?? "standard",
+    tax_group: f.tax_group ?? DEFAULT_TAX_GROUP,
     tax_status: f.tax_status ?? "taxable",
     total: round2(Number(f.amount) || 0),
     total_tax: 0,
@@ -145,44 +153,41 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
   const shippingEnabled = getSetting(settings, "shipping", "enable_shipping", true) !== false;
   const needsShipping = lines.some((l) => !l.virtual);
   const shippingLines: any[] = [];
-  let available: Array<{ id: string; method_id: string; title: string; cost: number }> = [];
-  let matchedZoneId: string | null = null;
+  let available: Array<{ id: string; title: string; cost: number }> = [];
+  const shipLocation = shippingEnabled && needsShipping
+    ? locationFor(locations, input.shipping_address)
+    : null;
 
-  if (shippingEnabled && needsShipping && input.shipping_address?.country) {
-    const zone = matchZone(input.zones ?? [], input.shipping_address);
-    if (zone) {
-      matchedZoneId = zone.id ?? null;
-      const cart = { lines, itemsSubtotal, itemsSubtotalAfterDiscount: itemsAfterDiscount };
-      const offers = availableMethods(zone, input.zoneMethods ?? [], cart, settings, coupons);
-      available = offers.map((o) => ({
-        id: o.method.id,
-        method_id: o.method.method_id,
-        title: o.method.title || defaultMethodTitle(o.method.method_id),
-        cost: o.cost,
-      }));
-      if (input.chosenShippingMethodId) {
-        const chosen = offers.find((o) => o.method.id === input.chosenShippingMethodId);
-        if (chosen) {
-          shippingLines.push({
-            line_id: uuid(),
-            method_id: chosen.method.method_id,
-            instance_id: chosen.method.id,
-            method_title: chosen.method.title || defaultMethodTitle(chosen.method.method_id),
-            total: chosen.cost,
-            total_tax: 0,
-            taxes: [] as any[],
-          });
-        }
+  if (shipLocation) {
+    const cart = { itemsSubtotal, itemsSubtotalAfterDiscount: itemsAfterDiscount };
+    const offers = availableRates(shipLocation, cart, coupons);
+    available = offers.map((o) => ({
+      id: o.rate.id,
+      title: o.rate.name || "Shipping",
+      cost: o.cost,
+    }));
+    if (input.chosenShippingMethodId) {
+      const chosen = offers.find((o) => o.rate.id === input.chosenShippingMethodId);
+      if (chosen) {
+        shippingLines.push({
+          line_id: uuid(),
+          method_id: "rate",
+          instance_id: chosen.rate.id,
+          method_title: chosen.rate.name || "Shipping",
+          total: chosen.cost,
+          total_tax: 0,
+          taxes: [] as any[],
+        });
       }
     }
   }
 
   // ── 5. tax ───────────────────────────────────────────────────────────────
-  // aggregated per rate for order-level tax_lines
-  const agg = new Map<string, { rate: any; tax_total: number; shipping_tax_total: number }>();
-  const bump = (rate: any, tax: number, shippingTax: number) => {
-    const key = rate.id ?? `${rate.name}-${rate.priority}`;
-    const cur = agg.get(key) ?? { rate, tax_total: 0, shipping_tax_total: 0 };
+  // aggregated per rate label for order-level tax_lines
+  const agg = new Map<string, { label: string; rate_percent: number; tax_total: number; shipping_tax_total: number }>();
+  const bump = (label: string, ratePercent: number, tax: number, shippingTax: number) => {
+    const key = `${label}|${ratePercent}`;
+    const cur = agg.get(key) ?? { label, rate_percent: ratePercent, tax_total: 0, shipping_tax_total: 0 };
     cur.tax_total = round2(cur.tax_total + tax);
     cur.shipping_tax_total = round2(cur.shipping_tax_total + shippingTax);
     agg.set(key, cur);
@@ -195,32 +200,28 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
     l.subtotal_tax = sumTax(subApplied);
     l.total_tax = sumTax(totApplied);
     l.taxes = totApplied.map((t, i) => ({
-      rate_id: t.rate.id ?? "",
+      label: t.rate.name || "Tax",
       total: t.amount,
       subtotal: subApplied[i]?.amount ?? 0,
     }));
-    for (const t of totApplied) bump(t.rate, t.amount, 0);
+    for (const t of totApplied) bump(t.rate.name || "Tax", t.rate.rate, t.amount, 0);
   }
   for (const fee of feeLines) {
     if (fee.tax_status !== "taxable") continue;
-    const rates = matchTaxRates(taxRates, taxAddress, fee.tax_class);
+    const rates = taxRatesFor(taxLocation, fee.tax_group);
     const applied = applyRates(fee.total, rates);
     fee.total_tax = sumTax(applied);
-    fee.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
-    for (const t of applied) bump(t.rate, t.amount, 0);
+    fee.taxes = applied.map((t) => ({ label: t.rate.name || "Tax", total: t.amount }));
+    for (const t of applied) bump(t.rate.name || "Tax", t.rate.rate, t.amount, 0);
   }
-  if (shippingLines.length) {
-    // shipping_tax_class "inherit" = first taxable line's class (intended behavior)
-    const cfg = getSetting(settings, "tax", "shipping_tax_class", "inherit");
-    const cls = cfg === "inherit"
-      ? (lines.find((l) => l.tax_status === "taxable")?.tax_class ?? "standard")
-      : cfg;
-    const rates = matchTaxRates(taxRates, taxAddress, cls).filter((r) => r.shipping !== false);
+  if (shippingLines.length && taxLocation) {
     for (const sl of shippingLines) {
-      const applied = applyRates(sl.total, rates);
-      sl.total_tax = sumTax(applied);
-      sl.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
-      for (const t of applied) bump(t.rate, 0, t.amount);
+      const tax = shippingTaxFor(taxLocation, sl.total);
+      if (tax <= 0) continue;
+      sl.total_tax = tax;
+      sl.taxes = [{ label: "Shipping tax", total: tax }];
+      const pct = taxLocation.shipping_tax?.type === "fixed" ? 0 : Number(taxLocation.shipping_tax?.value) || 0;
+      bump("Shipping tax", pct, 0, tax);
     }
   }
 
@@ -243,12 +244,11 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
 
   const total = round2(itemsSubtotal - discountTotal + feesTotal + shippingTotal + totalTax);
 
-  const taxLines = [...agg.values()].map(({ rate, tax_total, shipping_tax_total }) => ({
-    rate_id: rate.id ?? "",
-    rate_code: buildRateCode(rate),
-    label: rate.name ?? "Tax",
-    rate_percent: Number(rate.rate) || 0,
-    compound: !!rate.compound,
+  const taxLines = [...agg.values()].map(({ label, rate_percent, tax_total, shipping_tax_total }) => ({
+    rate_id: "",
+    rate_code: label.replace(/\s+/g, "-").toUpperCase(),
+    label,
+    rate_percent,
     tax_total,
     shipping_tax_total,
   }));
@@ -269,7 +269,7 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
     total,
     prices_include_tax: pricesIncludeTax,
     available_shipping_methods: available,
-    matched_zone_id: matchedZoneId,
+    matched_location_id: shipLocation?.id ?? taxLocation?.id ?? null,
   };
 }
 
@@ -283,7 +283,7 @@ function stripLine(l: any): any {
     sku: l.sku,
     quantity: l.quantity,
     price: l.quantity ? round2(l.total / l.quantity) : 0, // post-discount ex-tax unit price
-    tax_class: l.tax_class,
+    tax_group: l.tax_group,
     subtotal: l.subtotal,
     subtotal_tax: l.subtotal_tax,
     total: l.total,
@@ -293,17 +293,3 @@ function stripLine(l: any): any {
     meta_data: l.meta_data,
   };
 }
-
-function buildRateCode(rate: any): string {
-  const parts = [rate.country || "ANY", rate.state || "", (rate.name || "TAX").replace(/\s+/g, "-"), String(rate.priority ?? 1)];
-  return parts.filter(Boolean).join("-").toUpperCase();
-}
-
-function defaultMethodTitle(methodId: string): string {
-  switch (methodId) {
-    case "flat_rate": return "Flat rate";
-    case "free_shipping": return "Free shipping";
-    case "local_pickup": return "Local pickup";
-    default: return methodId;
-  }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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

@@ -18,7 +18,7 @@
  *   ../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/
  *
  * Merge semantics: directories are merged — files owned by the template are
  * overwritten (so re-running after a template update is safe), everything
@@ -89,12 +89,19 @@
   // ── retired files ─────────────────────────────────────────────────────────
   // Copying merges, so a template file that gets renamed would otherwise linger
   // in the app forever — and stale guidance is worse than none, since agents
-  // read whatever is in skills/. Anything this template used to own and no
-  // longer ships is listed here and removed on install.
+  // read whatever is in .agents/skills/. Anything this template used to own and
+  // no longer ships is listed here and removed on install.
   const RETIRED = [
-    ["skills", "commerce", "references", "stripe-payments.md"], // → references/online-payments.md
+    // The commerce skill moved from skills/commerce/ to .agents/skills/commerce/;
+    // remove the old copy so agents don't keep reading the stale one.
+    ["skills", "commerce"],
+    [".agents", "skills", "commerce", "references", "stripe-payments.md"], // → references/online-payments.md
+    // Payments moved to the two-file model (card-payment.ts + the webhook);
+    // the Stripe adapter and the provider-status hook are gone.
+    ["base44", "shared", "commerce", "stripe.ts"],
+    ["src", "commerce", "admin", "hooks", "usePaymentProvider.js"],
     // Attributes and their values are edited in the Attributes section of the
-    // Price & Inventory tab, tags in the product sidebar; the product type and the
+    // Price & Inventory section, ribbons in the product sidebar; the product type and the
     // Advanced tab are gone entirely.
     ["src", "commerce", "admin", "pages", "products", "Attributes.jsx"],
     ["src", "commerce", "admin", "pages", "products", "AttributeTerms.jsx"],
@@ -109,6 +116,20 @@
     // are per variant, so the product-level Shipping tab has nothing left.
     ["src", "commerce", "admin", "pages", "products", "components", "tabs", "AttributesTab.jsx"],
     ["src", "commerce", "admin", "pages", "products", "components", "tabs", "ShippingTab.jsx"],
+    // The zone/class tax-and-shipping model became one Shipping & Tax Location
+    // (commerce.ShippingTaxLocation + the settings/shipping-tax screen), and
+    // ProductTag became commerce.ProductRibbon.
+    ["base44", "entities", "commerce.TaxClass.jsonc"],
+    ["base44", "entities", "commerce.TaxRate.jsonc"],
+    ["base44", "entities", "commerce.ShippingClass.jsonc"],
+    ["base44", "entities", "commerce.ShippingZone.jsonc"],
+    ["base44", "entities", "commerce.ShippingZoneMethod.jsonc"],
+    ["base44", "entities", "commerce.ProductTag.jsonc"],
+    ["src", "commerce", "admin", "pages", "settings", "ProductsSettings.jsx"],
+    ["src", "commerce", "admin", "pages", "settings", "TaxSettings.jsx"],
+    ["src", "commerce", "admin", "pages", "settings", "TaxRatesTable.jsx"],
+    ["src", "commerce", "admin", "pages", "settings", "ShippingSettings.jsx"],
+    ["src", "commerce", "admin", "pages", "settings", "ShippingZoneEditor.jsx"],
   ];
   let retiredRemoved = 0;
   for (const parts of RETIRED) {
@@ -144,7 +165,7 @@
     { label: "utils", from: ["src", "commerce", "utils"], to: ["src", "commerce", "utils"] },
     // Commerce skill — SKILL.md, install/post-install guides, references/
     // and docs/, the guidance agents read before working on the store.
-    { label: "skills", from: ["skills", "commerce"], to: ["skills", "commerce"] },
+    { label: "skills", from: ["skills", "commerce"], to: [".agents", "skills", "commerce"] },
   ];
   for (const job of dirJobs) {
     const src = path.join(templateRoot, ...job.from);
@@ -159,7 +180,7 @@
     (retiredRemoved ? ` (${retiredRemoved} retired file${retiredRemoved === 1 ? "" : "s"} removed)` : ""),
   );
   console.log(
-    "\nNext steps (see skills/commerce/installation-guidelines.md + post-installation.md):\n" +
+    "\nNext steps (see .agents/skills/commerce/installation-guidelines.md + post-installation.md):\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" +

package/skills/commerce/SKILL.md

@@ -1,24 +1,24 @@
 ---
 name: commerce
-description: Base44 Commerce template — 24 commerce.* entities, 16 commerce/* backend functions (storefront + admin APIs + online payments), the shared commerce engine under base44/shared/commerce/, the Store Management UI mounted at /store-admin, and the commerce/StoreAdmin agent (admin copilot). Read before working on store features — the admin UI, storefront building, Stripe wiring, scheduled maintenance, emails, webhooks, downloads, or scaling limits.
+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.
 ---
 
 # 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 [`skills/commerce/references/`](./references/) — open one only when your task touches that area. The API references live in [`skills/commerce/docs/`](./docs/).
+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 [`skills/commerce/post-installation.md`](./post-installation.md) — keep all of them intact when changing routes or schemas.
+> - **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.
 
 ## IMPORTANT — first-time installation
 
-If the template was just installed (or you are installing it right now), read [`skills/commerce/post-installation.md`](./post-installation.md) **before anything else**: 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 and taxonomy created internally — §2) — and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout that make reading the full API docs unnecessary for the happy path. The full install-from-scratch steps are in [`skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
+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**: 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 — §2) — and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout that make reading the full API docs unnecessary for the happy path. 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 [`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**; the storefront *API* is complete (token-based cart), plus framework-free helpers in [`src/commerce/utils/`](../../src/commerce/utils/) (`variants.js`, `shipping-promos.js` — import from `@/commerce/utils`). Start from the logic-only quick start in [`post-installation.md` §3](./post-installation.md#3-storefront-quick-start--logic-only) — it covers the whole buy path; go to [`skills/commerce/docs/api-storefront.md`](./docs/api-storefront.md) for anything beyond it. Navigation comes from three actions — `list-categories` (tree), `list-tags` (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); **tags are the most-skipped part of it and belong in both views**.
+- **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**; the storefront *API* is complete (token-based cart), plus framework-free helpers in [`src/commerce/utils/`](../../src/commerce/utils/) (`variants.js`, `shipping-promos.js` — import from `@/commerce/utils`). Start from the logic-only quick start in [`post-installation.md` §3](./post-installation.md#3-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
 
@@ -32,11 +32,11 @@ Agents keep shipping storefronts that miss these, and each one breaks buying out
    ```
    `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.
 
-2. **Checkout must present shipping options and send a choice.** After `set-shipping-address`, read `shipping_status` on the cart: `auto_selected` (one option, already applied) · `chosen` · `choice_required` → **you must show `available_shipping_methods` and call `choose-shipping-method`** · `none_available` → say so. `place-order` refuses with `400 shipping_method_required` until then — that is not a bug to work around.
+2. **Checkout must present shipping options and send a choice.** Call `set-shipping-address` **as soon as the customer provides an address** — it recalculates the options and cost, and fails with `400 shipping_not_available` when the store doesn't ship there. Then read `shipping_status` on the returned cart: `auto_selected` (one option, already applied) · `chosen` · `choice_required` → **you must 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 the choice by looking it up in `available_shipping_methods` for its `title`/`cost`, never by rendering the id or dotting into it.)
 
-3. **Take card payments, and build `/order-received`.** (Ask the user to connect the provider *after* the store is set up — it's their step in the dashboard, and a catalog plus a shipping method is what makes a test payment provable.) Choosing the online gateway returns `payment.checkout_url` — redirect there. Every payment link comes back to `/order-received`, which **you must implement**: call `commerce/payments` `complete-return` with the query params and render its `state`. Without that page a customer pays into a 404 and the order is never marked paid.
+3. **Handle card payments, and build `/order-received`.** Choosing the card gateway returns `payment.checkout_url` — redirect there (until a payment provider is implemented it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: call `commerce/payments` `complete-return` with the query params and render its `state`. 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 — `add-item` silently starts a fresh cart when the stored token is stale.
 
-4. **Never advertise what isn't configured.** "Free shipping over €150" must come from a real `free_shipping` zone method. Zones are admin-only data, so a storefront cannot read them: the live answer is the cart's `available_shipping_methods` after `set-shipping-address`, and `shipping-promos.js` normalizes the rules wherever the records *are* in hand. No rule means no banner.
+4. **Never advertise what isn't configured.** "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 `set-shipping-address`, and `shipping-promos.js` normalizes the rules wherever the records *are* in hand. No rule means no banner.
 
 All functions return the envelope `{ success, data }` (or `{ success, error, code }`); with the SDK the body is on `res.data`:
 
@@ -47,15 +47,15 @@ const { products, has_next } = res.data.data;   // res.data = envelope, .data =
 
 ## Topic references
 
-Open the matching file under `skills/commerce/references/` only when a task touches its area:
+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`, **tags in both views**, variant pricing on cards, adding a page-only field to the listing call | [`references/product-render.md`](./references/product-render.md) |
+| 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 (backend ships complete), moderation statuses, verified-only and rating-required behaviors | [`references/reviews.md`](./references/reviews.md) |
-| Admin product form | changing the product editor — its tabs are **Price & Inventory** (tax, then the attributes, then a row per variant, or a single *Base price* row when there are none), **Modifiers** (`meta_data`), **Downloads**, **Linked products**. Variants reconcile from the attribute values automatically: no generate step, no per-variant delete. Weight, dimensions and shipping class are per variant. | [`references/admin-product-form.md`](./references/admin-product-form.md) |
-| Online payments | **any storefront or checkout work** — card payments ship implemented (hosted page, payment links, signed webhook, refunds) behind a provider-neutral utility wired to Stripe; connect a provider to go live, or implement one adapter to use another | [`references/online-payments.md`](./references/online-payments.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 | **any storefront or checkout work** — the order side (checkout, confirmation, payment links, refund records) is premade; wiring a provider means implementing exactly two files (`shared/commerce/card-payment.ts` + the payment webhook) | [`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) |