@base44/app-plugin-commerce 0.1.3 → 0.1.4

package/README.md

@@ -2,16 +2,16 @@
 
 A **Commerce backend + admin UI** for [Base44](https://base44.com) apps, delivered as a copyable file set. Drop `base44/` and `src/commerce/` into an existing Base44 app to add a full store: catalog, orders, coupons, customers, reviews, tax, shipping, webhooks, reports and transactional emails — plus a public storefront API for building your own shopfront.
 
-It provides a full-featured **commerce data model and behavior** (product types, order lifecycle, coupon rules, tax priority/compound math, shipping zones) using Base44-idiomatic primitives (entity JSON schemas, Deno functions, the Base44 SDK).
+It provides a full-featured **commerce data model and behavior** (variant-driven products, order lifecycle, coupon rules, tax priority/compound math, shipping zones) using Base44-idiomatic primitives (entity JSON schemas, Deno functions, the Base44 SDK).
 
 ## What's included
 
-- **24 entities** — Products (simple/grouped/external/variable), variations, categories, tags, attributes + terms, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, tax classes/rates, shipping zones/methods, payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
+- **24 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, tags, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, tax classes/rates, shipping zones/methods, payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
 - **16 backend functions** — 9 admin (`commerce/admin-products`, `commerce/admin-orders`, `commerce/admin-refunds`, `commerce/admin-coupons`, `commerce/admin-customers`, `commerce/admin-reviews`, `commerce/admin-webhooks`, `commerce/admin-reports`, `commerce/admin-tools`), 4 storefront (`commerce/storefront-catalog`, `commerce/storefront-cart`, `commerce/storefront-checkout`, `commerce/storefront-account`), 2 payment (`commerce/payments`, `commerce/payment-webhook`), and an idempotent `commerce/seed-store`.
 - **Online card payments, implemented** — hosted payment page, payment links for unpaid orders, two idempotent confirmation paths (customer return + signed webhook) and refunds through the provider. Wired to **Stripe** out of the box behind a provider-neutral payment utility, so the store takes cards as soon as the connector is connected — no charge flow to write — and moving to another provider means implementing one adapter. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, payments utility + Stripe adapter, plus static country/currency/continent data.
-- **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, full settings, webhooks. Admin-role gated.
-- **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free functions for the shopfront you build: `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variable-product price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
+- **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
+- **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free functions for the shopfront you build: `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/), which holds [`SKILL.md`](./skills/commerce/SKILL.md) (the short map agents start from), [`installation-guidelines.md`](./skills/commerce/installation-guidelines.md), [`post-installation.md`](./skills/commerce/post-installation.md), per-topic guides in [`references/`](./skills/commerce/references/) and the API references in [`docs/`](./skills/commerce/docs/) — the whole folder is installed into the app so agents pick it up natively.
 
@@ -83,10 +83,10 @@ From your existing Base44 app:
    ```jsx
    import AdminApp from "@/commerce/admin";
    // inside your <Routes>:
-   <Route path="/admin/*" element={<AdminApp />} />
+   <Route path="/store-admin/*" element={<AdminApp />} />
    ```
 6. **Grant yourself the `admin` role** (Base44 dashboard → users, or `users.inviteUser(email, "admin")`). The admin UI refuses non-admins.
-7. **Seed the store.** Either open `/admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, gateways, tax classes and a fallback shipping zone, plus a sample catalog when `with_sample_data: true` and the store is empty. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. If an agent is installing this, it should **ask which data the user wants** first — a generated catalog for their actual business, the generic demo data, or nothing: see [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
+7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, gateways, tax classes and a fallback shipping zone, plus a sample catalog when `with_sample_data: true` and the store is empty. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. If an agent is installing this, it should **ask which data the user wants** first — a generated catalog for their actual business, the generic demo data, or nothing: see [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
 
 ## Quick start (Base44 MCP / hosted apps)
 
@@ -98,8 +98,8 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 
 ## What's NOT included
 
-- **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **helper logic**: [`src/commerce/utils/`](./src/commerce/utils/) — framework-free variant-selection functions (map a Size/Color selection to a `ProductVariation` and back, per-option availability, variable-product price ranges) — plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
-- **No payment credentials** — the card integration itself *is* included (see above), but a store can only charge once someone connects a payment provider's connector for the app. Until then the card option stays hidden from customers and the manual gateways (bank transfer / cheque / COD) carry checkout.
+- **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **helper logic**: [`src/commerce/utils/`](./src/commerce/utils/) — framework-free variant-selection functions (map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) — plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
+- **No payment credentials** — the card integration itself *is* included (see above), but a store can only charge once someone connects a payment provider's connector for the app. Until then the card option stays hidden from customers and the offline gateway (bank transfer, cash on delivery) carries checkout.
 - **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see *Scheduled work* in [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md).
 
 ## Next steps

package/base44/agents/commerce/StoreAdmin.jsonc

@@ -10,15 +10,15 @@
 {
   "name": "StoreAdmin",
   "description": "Store administration copilot for the commerce template: manage products, orders, refunds, coupons, customers, reviews, reports and maintenance.",
-  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {with_sample_data?} with no action key) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, tax rates, shipping zones, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Tax](admin:settings/tax)`. The chat resolves that to wherever the admin is mounted, so never write `/admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency, store name/address, coupon & tax toggles | Settings → General | admin:settings/general |\n| Catalog defaults, review settings | Settings → Products | admin:settings/products |\n| Stock thresholds, hold minutes, inventory recipient | Settings → Inventory | admin:settings/inventory |\n| Tax classes, tax rates, price display | Settings → Tax | admin:settings/tax |\n| Shipping zones, methods, shipping classes | Settings → Shipping | admin:settings/shipping |\n| Enabling a gateway, bank/BACS details | Settings → Payments | admin:settings/payments |\n| From-name, admin notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Creating or deleting a webhook (you CAN test and redeliver) | Webhooks | admin:webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live in the store's tax settings. Open [Settings → Tax](admin:settings/tax) to add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, tags, attributes and attribute terms yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — only link to admin:products/categories, admin:products/tags or admin:products/attributes if they want to review or reorder them by hand.\n\n## Product variants — be careful\nProducts of type \"variable\" are sold as variations, and every variation can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a variable product, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for variable products; the backend rejects a bare product_id for them.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
+  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {store_name, with_sample_data?} with no action key — store_name is REQUIRED on a first seed) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, tax rates, shipping zones, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Tax](admin:settings/tax)`. The chat resolves that to wherever the admin is mounted, so never write `/store-admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency and price formatting, payment return path | Settings → General | admin:settings/general |\n| Catalog defaults, review settings | Settings → Products | admin:settings/products |\n| Stock thresholds, hold minutes, inventory recipient | Settings → Inventory | admin:settings/inventory |\n| Tax classes, tax rates, price display | Settings → Tax | admin:settings/tax |\n| Shipping zones, methods, shipping classes | Settings → Shipping | admin:settings/shipping |\n| Enabling a gateway, offline bank details | Settings → Payments | admin:settings/payments |\n| Store name (subjects + sender), admin notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Creating or deleting a webhook (you CAN test and redeliver) | Settings → Webhooks | admin:settings/webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live in the store's tax settings. Open [Settings → Tax](admin:settings/tax) to add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, tags, attributes and attribute values yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — link to admin:products/categories if they want to review or reorder categories by hand. Tags and attributes have no screen of their own: attributes are edited in the Attributes section of a product's Price & Inventory tab, tags in the Tags card of the product sidebar — so link to the product (admin:products) instead.\n\n## Product variants — be careful\nA product that carries attributes is sold through its variants (there is no product type), and every variant can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a product that carries attributes, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for a product with attributes.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
   "tool_configs": [
     {
       "function_name": "commerce/admin-products",
-      "description": "Product & variation management, plus category/tag terms. Actions: save {product, variations?} (upsert + derived price/stock, SKU/slug uniqueness), delete {id}, batch {create?,update?,delete?}, duplicate {id}, set-stock {id, variation_id?, quantity}, search {q?, category_id?, type?, stock_status?, status?, sort?, limit?, skip?} → {rows, has_next}, list-terms {taxonomy, q?, attribute_id?, limit?, skip?} → {rows, has_next}, save-term {taxonomy, term: {...}} (upsert; slug auto-derived and made unique), delete-term {taxonomy, id, detach?}. taxonomy is \"category\" | \"tag\" | \"attribute\" | \"attribute-term\"; term fields per taxonomy: category {id?, name, slug?, description?, parent_id?, image?, menu_order?}, tag {id?, name, slug?, description?}, attribute {id?, name, slug?, type?, order_by?, has_archives?}, attribute-term {id?, attribute_id (required), name, slug?, description?, menu_order?}. Create these yourself with save-term — do NOT tell the operator to create them by hand. list-terms first and reuse a match before creating a duplicate. Deleting an attribute deletes its terms. A variable product needs a ProductAttribute (+ its terms) to exist before product.attributes[].options can reference it, so create the attribute and terms first, then save the product."
+      "description": "Product & variant management, plus category/tag/attribute records. Actions: save {product, variations?} (upsert + derived price/stock, SKU/slug uniqueness), delete {id}, batch {create?,update?,delete?}, duplicate {id}, set-stock {id, variation_id?, quantity}, search {q?, category_id?, stock_status?, status?, sort?, limit?, skip?} → {rows, has_next}, list-terms {taxonomy, q?, attribute_id?, limit?, skip?} → {rows, has_next}, save-term {taxonomy, term: {...}} (upsert), delete-term {taxonomy, id, detach?}. taxonomy is \"category\" | \"tag\" | \"attribute\" | \"attribute-term\"; term fields per taxonomy: category {id?, name, slug?, description?, parent_id?, image?, menu_order?}, tag {id?, name}, attribute {id?, name, code?, order?}, attribute-term {id?, attribute_id (required), name, order?}. Only categories have a slug. Creating a tag is get-or-create by name. Renaming an attribute value rewrites every product that uses it. Create these yourself with save-term — do NOT tell the operator to create them by hand. list-terms first and reuse a match before creating a duplicate. Deleting an attribute deletes its values. A product sells variants because it carries attributes — there is no type field — so the ProductAttribute (+ its values) must exist before product.attributes[].options can reference it: create the attribute and values first, then save the product with attributes[] and variations[]. For a product with attributes do NOT set the parent's regular_price/sale_price: the parent's regular_price, price and on_sale are rolled up from the cheapest published variation on every save, so anything you set there is overwritten."
     },
     {
       "function_name": "commerce/admin-orders",
-      "description": "Order lifecycle. Actions: create-draft, create {items, ...}, update {order_id, patch}, update-status {order_id, status, note?}, bulk-status {ids, status}, status-counts, search {q?, status?, date_min?, date_max?, sort?, limit?, skip?}, recalculate {order_id}, apply-coupon/remove-coupon {order_id, code}, add-note {order_id, note, is_customer_note?}, delete-note {note_id}, send-email {order_id, type}, grant-download {order_id, product_id}, revoke-download {permission_id}, delete {order_id}, release-expired-holds. Item specs: {product_id, variation_id?, quantity, price_override?} — variation_id REQUIRED for variable products (ask the operator which variation; never auto-pick). Statuses: pending, processing, on-hold, completed, cancelled, refunded, failed."
+      "description": "Order lifecycle. Actions: create-draft, create {items, ...}, preview {items, ...} (price without saving), update {order_id, patch}, update-status {order_id, status, note?}, bulk-status {ids, status}, status-counts, search {q?, status?, date_min?, date_max?, sort?, limit?, skip?}, recalculate {order_id}, apply-coupon/remove-coupon {order_id, code}, add-note {order_id, note, is_customer_note?}, delete-note {note_id}, send-email {order_id, type}, grant-download {order_id, product_id}, revoke-download {permission_id}, delete {order_id}, release-expired-holds. Item specs: {product_id, variation_id?, quantity, price_override?} — variation_id REQUIRED for a product that carries attributes (ask the operator which variation; never auto-pick). Statuses: pending, processing, on-hold, completed, cancelled, refunded, failed."
     },
     {
       "function_name": "commerce/admin-refunds",
@@ -46,19 +46,19 @@
     },
     {
       "function_name": "commerce/admin-tools",
-      "description": "System status & maintenance. Actions: status (template_version, seeded, entity counts, health checks), recount-terms, recount-coupon-usage, recalculate-customer-stats-all, prune-webhook-deliveries {keep_days}, clear-abandoned-carts {older_than_days}, regenerate-download-permissions {order_id}."
+      "description": "System status & maintenance. Actions: status (template_version, seeded, entity counts, health checks), payment-connector-status, admin-email-recipients, recount-terms, recount-coupon-usage, recalculate-customer-stats-all, prune-webhook-deliveries {keep_days}, clear-abandoned-carts {older_than_days}, regenerate-download-permissions {order_id}."
     },
     {
       "function_name": "commerce/seed-store",
-      "description": "Initialize store defaults (idempotent; canary schema check first). Body: {with_sample_data?: boolean} — no action key. Sample catalog only created when the store has zero products."
+      "description": "Initialize store defaults (idempotent; canary schema check first). Body: {store_name: string, with_sample_data?: boolean} — no action key. store_name is REQUIRED on a first seed (else 400 store_name_required): pass the app's name as the platform shows it, since a function's env cannot read it. It becomes the email subject prefix and the sender name. Sample catalog only created when the store has zero products."
     },
     {
       "function_name": "commerce/payments",
-      "description": "Online payment for an order. Actions: status {} → {provider, connected, gateway_slug} (is a payment provider connected?), create-link {order_id} → {url} (provider-hosted payment page for an UNPAID online order — the link to send a customer; 409 already_paid, 400 not_an_online_payment, 503 payment_provider_unavailable), verify {order_id} → {paid, status} (re-ask the provider and move the order on if paid; idempotent)."
+      "description": "Online payment for an order. Actions: status {} → {provider, connected, gateway_slug} (is a payment provider connected?), create-link {order_id} → {url} (provider-hosted payment page for an UNPAID online order — the link to send a customer; 409 already_paid, 400 not_an_online_payment, 503 payment_provider_unavailable), verify {order_id} → {paid, status} (re-ask the provider and move the order on if paid; idempotent), complete-return {order_id, order_key, payment?} (what the storefront's return page calls: confirms, advances the order and hands back {state, order, payment_link})."
     },
     {
       "function_name": "commerce/storefront-catalog",
-      "description": "Read-only public catalog browsing — use get-product BEFORE putting a variable product on an order, to list its variations and ask the operator which one. Actions: get-store-info, list-products {q?, category_id?, tag_id?, featured?, on_sale?, min_price?, max_price?, sort?, page?, per_page?}, get-product {id | slug} → {product, variations, ...}, list-categories, list-tags, list-reviews {product_id, page?, per_page?}."
+      "description": "Read-only public catalog browsing — use get-product BEFORE putting a product that carries attributes on an order, to list its variations and ask the operator which one. Actions: get-store-info, list-products {q?, category_id?, tag_id?, attribute_id?, attribute_term?, featured?, on_sale?, in_stock_only?, min_price?, max_price?, sort? (default \"-created_date\"), page?, per_page?}, get-product {id | slug} → {product, variations, ...}, list-categories, list-tags, list-attributes. There is no list-reviews — a product's reviews come back inside get-product, and moderation is commerce/admin-reviews."
     }
   ]
 }

package/base44/entities/commerce.Order.jsonc

@@ -84,7 +84,7 @@
     },
     "payment_method": {
       "type": "string",
-      "description": "PaymentGateway slug (e.g. bacs|cheque|cod|stripe)"
+      "description": "PaymentGateway slug (e.g. offline|stripe)"
     },
     "payment_method_title": {
       "type": "string",

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -1,12 +1,12 @@
 {
   "name": "commerce.PaymentGateway",
   "type": "object",
-  "description": "Payment gateway configuration (data model only — no processing). Seeded: bacs, cheque, cod, stripe (placeholder). Secrets are never stored here; use Base44 secrets.",
+  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and stripe (processed by commerce/payments + commerce/payment-webhook). Secrets are never stored here; use Base44 secrets.",
   "properties": {
     "slug": {
       "type": "string",
       "minLength": 1,
-      "description": "Unique gateway id, e.g. bacs | cheque | cod | stripe"
+      "description": "Unique gateway id, e.g. offline | stripe"
     },
     "title": {
       "type": "string",
@@ -35,7 +35,7 @@
     },
     "settings": {
       "type": "object",
-      "description": "Per-gateway settings. bacs: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; cod: {enable_for_methods, enable_for_virtual}; stripe: {connector: \"stripe\"} placeholder — see skills/commerce/references/online-payments.md"
+      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; stripe: {connector: \"stripe\"} — see skills/commerce/references/online-payments.md"
     }
   },
   "required": ["slug"],

package/base44/entities/commerce.Product.jsonc

@@ -1,7 +1,7 @@
 {
   "name": "commerce.Product",
   "type": "object",
-  "description": "A store product (simple, grouped, external, or variable). Full-featured product model.",
+  "description": "A store product. It sells variants when it carries attributes \u2014 there is no type field. Descriptive properties live in meta_data (the admin calls them modifiers).",
   "properties": {
     "name": {
       "type": "string",
@@ -12,12 +12,6 @@
       "type": "string",
       "description": "URL slug, unique (enforced in commerce/admin-products)"
     },
-    "type": {
-      "type": "string",
-      "enum": ["simple", "grouped", "external", "variable"],
-      "default": "simple",
-      "description": "Product type"
-    },
     "status": {
       "type": "string",
       "enum": ["draft", "pending", "private", "publish"],
@@ -51,7 +45,7 @@
     "regular_price": {
       "type": "number",
       "minimum": 0,
-      "description": "Regular price"
+      "description": "Regular price. For a product with attributes this is rolled up from the cheapest published variation."
     },
     "sale_price": {
       "type": "number",
@@ -70,12 +64,12 @@
     },
     "price": {
       "type": "number",
-      "description": "Derived: sale_price when sale is active, else regular_price. Maintained by commerce/admin-products."
+      "description": "Derived: sale_price when sale is active, else regular_price — or, for a product with attributes, the cheapest published variation's price. Maintained by commerce/admin-products."
     },
     "on_sale": {
       "type": "boolean",
       "default": false,
-      "description": "Derived: whether the sale window is currently active. Maintained by commerce/admin-products."
+      "description": "Derived: whether the sale window is currently active — or, for a product with attributes, whether any published variation is on sale. Maintained by commerce/admin-products."
     },
     "virtual": {
       "type": "boolean",
@@ -108,15 +102,6 @@
       "default": -1,
       "description": "Days until download access expires, -1 = never"
     },
-    "external_url": {
-      "type": "string",
-      "format": "uri",
-      "description": "Target URL for external/affiliate products"
-    },
-    "button_text": {
-      "type": "string",
-      "description": "Buy-button text for external products"
-    },
     "tax_status": {
       "type": "string",
       "enum": ["taxable", "shipping", "none"],
@@ -175,11 +160,6 @@
       "type": "string",
       "description": "ShippingClass id"
     },
-    "reviews_allowed": {
-      "type": "boolean",
-      "default": true,
-      "description": "Allow customer reviews"
-    },
     "average_rating": {
       "type": "number",
       "default": 0,
@@ -200,15 +180,6 @@
       "items": { "type": "string" },
       "description": "Cross-sell Product ids"
     },
-    "grouped_products": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Child Product ids for type=grouped"
-    },
-    "purchase_note": {
-      "type": "string",
-      "description": "Note shown to the customer after purchase"
-    },
     "category_ids": {
       "type": "array",
       "items": { "type": "string" },
@@ -234,22 +205,20 @@
     },
     "attributes": {
       "type": "array",
-      "description": "Assigned attributes (global via attribute_id, or custom/local when attribute_id is empty)",
+      "description": "Variant axes. Every entry is one axis: attaching an attribute is what makes the product sell variants. Descriptive properties belong in meta_data instead.",
       "items": {
         "type": "object",
         "properties": {
-          "attribute_id": { "type": "string", "description": "ProductAttribute id; empty for custom/local attribute" },
+          "attribute_id": { "type": "string", "description": "ProductAttribute id" },
           "name": { "type": "string" },
-          "position": { "type": "integer" },
-          "visible": { "type": "boolean", "description": "Visible on the product page" },
-          "variation": { "type": "boolean", "description": "Used for variations" },
-          "options": { "type": "array", "items": { "type": "string" } }
+          "position": { "type": "integer", "description": "Order the axes are presented in" },
+          "options": { "type": "array", "items": { "type": "string" }, "description": "Values this product comes in, by ProductAttributeTerm name" }
         }
       }
     },
     "default_attributes": {
       "type": "array",
-      "description": "Pre-selected variation attributes for variable products",
+      "description": "Pre-selected variant combination",
       "items": {
         "type": "object",
         "properties": {
@@ -259,11 +228,6 @@
         }
       }
     },
-    "menu_order": {
-      "type": "integer",
-      "default": 0,
-      "description": "Custom sort position"
-    },
     "total_sales": {
       "type": "integer",
       "default": 0,

package/base44/entities/commerce.ProductAttribute.jsonc

@@ -1,32 +1,20 @@
 {
   "name": "commerce.ProductAttribute",
   "type": "object",
-  "description": "Global product attribute (e.g. Color, Size). Terms live in ProductAttributeTerm.",
+  "description": "A variant axis shared between products (e.g. Color, Size). Its values live in ProductAttributeTerm. Edited in the Attributes section of a product's Price & Inventory tab, or via commerce/admin-products save-term.",
   "properties": {
     "name": {
       "type": "string",
       "minLength": 1
     },
-    "slug": {
+    "code": {
       "type": "string",
-      "description": "Unique slug (enforced in admin UI / functions)"
+      "description": "Stable machine key, unique (enforced in commerce/admin-products save-term). Derived from the name; what a storefront filter URL should carry."
     },
-    "type": {
-      "type": "string",
-      "enum": ["select"],
-      "default": "select",
-      "description": "Attribute type"
-    },
-    "order_by": {
-      "type": "string",
-      "enum": ["menu_order", "name", "name_num", "id"],
-      "default": "menu_order",
-      "description": "Default term sort order"
-    },
-    "has_archives": {
-      "type": "boolean",
-      "default": false,
-      "description": "Enable attribute archives"
+    "order": {
+      "type": "integer",
+      "default": 0,
+      "description": "Sort position among attributes"
     }
   },
   "required": ["name"],

package/base44/entities/commerce.ProductAttributeTerm.jsonc

@@ -1,7 +1,7 @@
 {
   "name": "commerce.ProductAttributeTerm",
   "type": "object",
-  "description": "A term (option value) of a global ProductAttribute.",
+  "description": "One value of a ProductAttribute (e.g. Size \u2192 M). Products reference it by name in attributes[].options, so renaming one rewrites those references (commerce/admin-products save-term).",
   "properties": {
     "attribute_id": {
       "type": "string",
@@ -11,16 +11,10 @@
       "type": "string",
       "minLength": 1
     },
-    "slug": {
-      "type": "string",
-      "description": "Unique within the attribute (enforced in admin UI / functions)"
-    },
-    "description": {
-      "type": "string"
-    },
-    "menu_order": {
+    "order": {
       "type": "integer",
-      "default": 0
+      "default": 0,
+      "description": "Sort position within the attribute"
     },
     "count": {
       "type": "integer",

package/base44/entities/commerce.ProductTag.jsonc

@@ -1,19 +1,12 @@
 {
   "name": "commerce.ProductTag",
   "type": "object",
-  "description": "Product tag.",
+  "description": "Product tag. Created and picked from the product form; storefronts filter by id (list-products tag_id).",
   "properties": {
     "name": {
       "type": "string",
       "minLength": 1
     },
-    "slug": {
-      "type": "string",
-      "description": "URL slug, unique (enforced in admin UI / functions)"
-    },
-    "description": {
-      "type": "string"
-    },
     "count": {
       "type": "integer",
       "default": 0,

package/base44/entities/commerce.ProductVariation.jsonc

@@ -1,7 +1,7 @@
 {
   "name": "commerce.ProductVariation",
   "type": "object",
-  "description": "A variation of a variable Product, identified by its attribute combination.",
+  "description": "A variation of a Product that carries attributes, identified by its attribute combination.",
   "properties": {
     "product_id": {
       "type": "string",

package/base44/entities/commerce.StoreSettings.jsonc

@@ -5,7 +5,7 @@
   "properties": {
     "group_id": {
       "type": "string",
-      "enum": ["general", "products", "inventory", "downloadable", "tax", "shipping", "emails"],
+      "enum": ["general", "products", "inventory", "tax", "shipping", "emails"],
       "description": "Settings group; unique (one record per group, enforced by seed/admin UI)"
     },
     "values": {