@base44/app-plugin-commerce 0.1.3 → 0.1.4

package/skills/commerce/installation-guidelines.md

@@ -53,14 +53,15 @@ 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: {...}, checks: [...] }
+// → { template_version, seeded, settings_groups, counts: { "commerce.Product": n, ... },
+//     checks: { has_payment_gateways, has_default_zone } }
 ```
 
 `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:
 
 ```json
 { "success": false, "code": "schema_incompatible",
-  "errors": [{ "entity": "Product", "error": "..." }] }
+  "errors": [{ "entity": "commerce.Product", "error": "..." }] }
 ```
 
 The admin setup screen surfaces these errors verbatim. Sample catalog data is only created when `with_sample_data: true` **and** the store has zero products.
@@ -74,7 +75,7 @@ The template ships an AI copilot for store operators:
 - **Agent definition** — [`base44/agents/commerce/StoreAdmin.jsonc`](../../base44/agents/commerce/StoreAdmin.jsonc), registered as **`commerce/StoreAdmin`** (the folder namespaces the agent, exactly like functions). The hosted runtime registers it when the file lands; on the CLI path run `npx base44 agents push`.
 - **Tools** — the `commerce/*` backend functions attached directly (`commerce/admin-products`, `commerce/admin-orders`, …, `commerce/seed-store`, plus read-only `commerce/storefront-catalog` for enumerating product variations). Tool calls run **with the chatting user's credentials**, so `requireAdmin()` in every admin function still authorizes the actual user — the agent has no entity tools and no service-role shortcut; a non-admin chatting with it gets `401/403` from every admin operation.
 - **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 variable products it fetches `{product, variations}` via `commerce/storefront-catalog get-product`, presents the variations as a table, and asks the operator which `variation_id` to use before touching an order, stock, or download grant.
+- **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.
 

package/skills/commerce/post-installation.md

@@ -15,13 +15,13 @@ The admin UI is a self-contained React app under `src/commerce/admin/`. Its only
 3. Mount the router:
    ```jsx
    import AdminApp from "@/commerce/admin";
-   <Route path="/admin/*" element={<AdminApp />} />
+   <Route path="/store-admin/*" element={<AdminApp />} />
    ```
    **You must also build a payment return page** (`/order-received` by default) — this is **mandatory for payment links to work at all**. If your route differs, set it in Settings → General → *Payment return path*, or payment links will send customers to a 404. Every link (checkout, the admin's payment link, emails) returns there; without the route a paying customer hits a 404, and since confirming is what marks an order paid, orders would stay unpaid. The page is a thin wrapper over one backend call, `commerce/payments` `complete-return`, which confirms the payment and returns `{ state, order, payment_link }` for the paid / unpaid / cancelled cases — the contract and rules are in [`references/online-payments.md`](./references/online-payments.md).
 
-   **Give the app root something too.** A blank Base44 app has no `/` route, so after mounting only `/admin/*` the app's own URL still renders its "page not found" screen — which reads exactly like a broken install. Until a storefront exists, redirect: `<Route path="/" element={<Navigate to="/admin" replace />} />`.
+   **Give the app root something too.** A blank Base44 app has no `/` route, so after mounting only `/store-admin/*` the app's own URL still renders its "page not found" screen — which reads exactly like a broken install. Until a storefront exists, redirect: `<Route path="/" element={<Navigate to="/store-admin" replace />} />`.
 
-   The **`/*` splat is required** — the admin renders its own nested routes, so a bare `path="/admin"` matches only the dashboard and every deeper link 404s. If you mount at a different base path, pass the prefix *without* the splat: `<AdminApp basePath="/store-admin" />` (a pattern passed by mistake, `basePath="/store-admin/*"`, is normalized rather than baked into every link). Opening the literal mount pattern `/admin/*` — pasted from these docs, or left in a hand-written nav link — lands on the dashboard instead of a "page not found" dead end; a genuinely wrong path like `/admin/ordrs` still 404s, with a link back.
+   The **`/*` splat is required** — the admin renders its own nested routes, so a bare `path="/store-admin"` matches only the dashboard and every deeper link 404s. If you mount at a different base path, pass the prefix *without* the splat: `<AdminApp basePath="/backoffice" />` (a pattern passed by mistake, `basePath="/backoffice/*"`, is normalized rather than baked into every link). Opening the literal mount pattern `/store-admin/*` — pasted from these docs, or left in a hand-written nav link — lands on the dashboard instead of a "page not found" dead end; a genuinely wrong path like `/store-admin/ordrs` still 404s, with a link back.
 
 ### Admin-role enforcement (do not weaken)
 
@@ -51,45 +51,42 @@ A fresh install has **no settings and no catalog**. Don't decide this silently a
 | Option | What you do | Result | Cost |
 |---|---|---|---|
 | **A — Generate the store's data** (best when you know the app's niche) | `commerce/seed-store` with `{ store_name, with_sample_data: false }`, then create real categories, attributes, products and images through the admin API (§2.1) | Store is **ready** — the admin opens straight onto a populated dashboard, no first-run screen | **Spends tokens**: you author every name, description and price, and image generation is billed per image |
-| **B — Default demo data** | `commerce/seed-store` with `{ store_name, with_sample_data: true }` | Store is **ready**, populated with the template's ~12 generic demo products | **Near-zero**: one function call, static content and stock image URLs |
+| **B — Default demo data** | `commerce/seed-store` with `{ store_name, with_sample_data: true }` | Store is **ready**, populated with the template's 10 generic demo products | **Near-zero**: one function call, static content and stock image URLs |
 | **C — Nothing** | don't call `seed-store` at all | The admin shows its first-run **"Set up your store"** screen; the operator initializes defaults themselves | none |
 
 Say the cost part out loud when you ask — it's the main trade-off between A and B, and the user is the one paying for it. A generated catalog of a dozen products with images is a real chunk of generation (text for every product plus one image call each); the static demo seed is a single backend call with no generation at all. If the user wants a populated store only to click around the admin, B is the better deal; A is worth it when the catalog is meant to survive into the real store.
 
-**Both A and B must pass `store_name`** — the app's name as the platform shows it. It is required on a first seed (**400** `store_name_required` without it), because nothing server-side can read the app's name and an unnamed store sends subjects like `[]: New order #1002`. On an already-seeded store the call fills a blank name and never overwrites one the merchant chose; the response reports which happened as `store_name: { value, action }` (`created` · `filled` · `unchanged` · `kept_existing`). The sender name is separate and needs nothing: leave `emails.from_name` blank and Base44 sends as the app's name.
+**Both A and B must pass `store_name`** — the app's name as the platform shows it. It is required on a first seed (**400** `store_name_required` without it), because nothing server-side can read the app's name and an unnamed store sends subjects like `[]: New order #1002`. It lands in `emails.store_name` — that is the only place it lives, and it drives email subjects, headings and the sender name. It is also published to storefronts as `settings.store_name` by `get-store-info`, so it is the public shop name too. On an already-seeded store the call fills a blank name and never overwrites one the merchant chose; the response reports which happened as `store_name: { value, action }` (`created` · `filled` · `unchanged` · `kept_existing`). It is the sender name too — there is no separate from-name; leave `store_name` blank and Base44 sends as the app's name.
 
-Both A and B call `seed-store`, which creates the business defaults — the seven settings groups (`general`, `products`, `inventory`, `downloadable`, `tax`, `shipping`, `emails`), payment gateways, tax classes and a fallback shipping zone. **Creating the `general` settings group is what marks the business as ready:** the admin's `SettingsProvider` (`src/commerce/admin/context/SettingsContext.jsx`) renders the first-run setup screen only while that group is missing. So under A and B the modal never appears — do **not** add a separate "ready" flag or suppress the screen in code; leave it working for option C, which is the only case it's meant for.
+Both A and B call `seed-store`, which creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`), payment gateways, tax classes and a fallback shipping zone. **Creating the `general` settings group is what marks the business as ready:** the admin's `SettingsProvider` (`src/commerce/admin/context/SettingsContext.jsx`) renders the first-run setup screen only while that group is missing. So under A and B the modal never appears — do **not** add a separate "ready" flag or suppress the screen in code; leave it working for option C, which is the only case it's meant for.
 
 Confirm afterwards:
 
 ```js
 const { data } = (await base44.functions.invoke("commerce/admin-tools", { action: "status" })).data;
 // → seeded: true (i.e. settings_groups includes "general"),
-//   settings_groups: ["general", "products", ...], counts: { Product: n, ... }
+//   settings_groups: ["general", "products", ...], counts: { "commerce.Product": n, ... }
 ```
 
 ### 2.1 Generating the store's data (option A)
 
 The goal is a catalog that looks like **this** business, not a demo. Order of operations:
 
-1. **Defaults first** — `commerce/seed-store` with `{ with_sample_data: false, store_name: "<the app's name>" }`. `store_name` is **required** on a first seed (else **400** `store_name_required`) — use the app's name as the platform shows it (ask the user if unsure — `base44/config.jsonc` → `name` can be stale, e.g. `New App` for an app called `Canvas`), since the function cannot read it. It lands as the store name and, by inheritance, the "from" name on transactional emails. It's idempotent and runs a canary schema check; on `422 schema_incompatible` fix the reported entities before continuing. Never follow it with `with_sample_data: true` — you'd mix demo products into a real catalog (the sample seeder is skipped once any product exists, so this usually silently does nothing, which is worse).
-2. **Business settings** — ask for, or infer from the app, the store name, currency, base country/state and units, and write them into the relevant `commerce.StoreSettings` groups (direct CRUD, one record per `group_id`; patch `values`, don't replace groups you weren't asked about).
-3. **Taxonomy** — create `commerce.ProductCategory` (direct CRUD, nest via `parent_id`) and, if products vary, `commerce.ProductAttribute` + `commerce.ProductAttributeTerm` (e.g. Size, Color). Reuse one global attribute across products rather than duplicating per-product local ones.
-4. **Products** — `commerce/admin-products` `save` (or `batch`, ≤100 items) per product. Write real merchandising copy: a distinct `name`, a one-line `short_description`, an HTML `description` (paragraph + `<ul>` of specifics), plus `sku`, `regular_price`, optional `sale_price`, `manage_stock: true` + `stock_quantity` where stock is tracked, `category_ids` and `images[]`. (`manage_stock` is a boolean on Product but `"yes"|"no"|"parent"` on ProductVariation.)
-5. **Variable products — an attribute in the attributes list does NOTHING on its own.** This is the step agents get wrong: they create a global `Size` attribute with terms, and every product stays simple, unsellable as a variant. A product is only variable when **all four** of these are true, and the last two happen in the *same* `commerce/admin-products` `save` call:
-   1. `type: "variable"` on the product;
-   2. the attribute is listed **on the product** with `variation: true` and its `options` — not just in `commerce.ProductAttribute`;
-   3. a `variations` array is sent with one entry per combination you actually stock;
-   4. `default_attributes` names the combination to pre-select.
+1. **Defaults first** — `commerce/seed-store` with `{ with_sample_data: false, store_name: "<the app's name>" }`. `store_name` is **required** on a first seed (else **400** `store_name_required`) — use the app's name as the platform shows it (ask the user if unsure — `base44/config.jsonc` → `name` can be stale, e.g. `New App` for an app called `Canvas`), since the function cannot read it. It lands in `emails.store_name`, which is both the name in email subjects and the sender name. It's idempotent and runs a canary schema check; on `422 schema_incompatible` fix the reported entities before continuing. Never follow it with `with_sample_data: true` — you'd mix demo products into a real catalog (the sample seeder is skipped once any product exists, so this usually silently does nothing, which is worse).
+2. **Business settings** — ask for, or infer from the app, the store name (in the `emails` group), currency and units, and write them into the relevant `commerce.StoreSettings` groups (direct CRUD, one record per `group_id`; patch `values`, don't replace groups you weren't asked about).
+3. **Taxonomy** — create these through `commerce/admin-products` **`save-term`** (`taxonomy: "category" | "tag" | "attribute" | "attribute-term"`), not direct entity CRUD: `save-term` is what derives a category's unique slug and an attribute's unique `code` (the key a storefront filter URL carries), makes tag creation get-or-create by name, and initializes `count`. A direct create leaves an attribute with a blank `code`. Nest categories via `parent_id`; for variants create the attribute (`{name, code, order}`) then its values (`{attribute_id, name, order}`) for e.g. Size and Color. Attributes are shared: create Size once and reuse it across shoes and shirts, picking per product which of its values apply.
+4. **Products** — `commerce/admin-products` `save` (or `batch`, ≤100 items) per product. Write real merchandising copy: a distinct `name`, a one-line `short_description`, an HTML `description` (paragraph + `<ul>` of specifics), plus `sku`, `regular_price`, optional `sale_price`, `manage_stock: true` + `stock_quantity` where stock is tracked, `category_ids` and `images[]`. **On a product that will carry attributes, price the variations and leave the parent's price alone** — `regular_price`, `price` and `on_sale` are rolled up from the cheapest publishable variant on every save, so anything you set there is discarded. (`manage_stock` is a boolean on Product but `"yes"|"no"|"parent"` on ProductVariation.)
+5. **Variants — an attribute in the attributes list does NOTHING on its own.** This is the step agents get wrong: they create a shared `Size` attribute with values, and every product stays a single item. There is **no product type and no per-attribute flag** — a product sells variants because it carries attributes — so listing the attribute **on the product**, with the values that product comes in, is what declares it. Two things must be true, and both happen in the *same* `commerce/admin-products` `save` call:
+   1. the attribute is listed **on the product** with its `options` — not just in `commerce.ProductAttribute`;
+   2. a `variations` array is sent with one entry per combination you actually stock (plus `default_attributes` for the combination to pre-select).
 
    ```js
    await call("admin-products", "save", {
      product: {
-       name: "Runner Sneaker", type: "variable", status: "publish", sku: "SNK",
-       regular_price: 89,                        // lowest variation price, so cards/filters work
+       name: "Runner Sneaker", status: "publish", sku: "SNK",
        category_ids: [shoesId], images: [{ src: "…" }],
        attributes: [{ attribute_id: sizeAttrId, name: "Size", position: 0,
-                      visible: true, variation: true, options: ["41", "42", "43"] }],
+                      options: ["41", "42", "43"] }],
        default_attributes: [{ attribute_id: sizeAttrId, name: "Size", option: "42" }],
      },
      variations: [
@@ -103,11 +100,11 @@ The goal is a catalog that looks like **this** business, not a demo. Order of op
    });
    ```
 
-   Give a visual axis (Color) a per-variation `image`. `manage_stock` is `"yes"|"no"|"parent"` on a variation but a boolean on the product. **Then check your work**: re-read the product and assert `variations.length > 0` — a variable product with no variations cannot be added to a cart at all (`400 variation_required`), and the storefront has nothing to show.
+   Give a visual axis (Color) a per-variation `image`. `manage_stock` is `"yes"|"no"|"parent"` on a variation but a boolean on the product. **Then check your work**: re-read the product and assert `variations.length > 0` — a product with attributes and no variations cannot be added to a cart at all (`400 variation_required`), and the storefront has nothing to show. Descriptive properties (Material, Care) are **not** attributes: put them in `meta_data`, which the admin surfaces as *modifiers*.
 6. **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 the `{ src, name, alt }` shape and a working Unsplash pattern). Match the image to the product — a generated catalog with mismatched or missing images reads as broken.
 7. **Optional extras** — a launch coupon via `commerce/admin-coupons` `save`; tax rates via `commerce.TaxRate` direct CRUD if the user sells into taxed regions.
-8. **Payments — once the store has something to sell.** Leave this until the catalog, shipping and settings are in place: connecting a payment provider is a step the *user* has to take in the platform dashboard, so asking for it first interrupts setup and leaves nothing to test the payment against. When the store is otherwise ready, raise it — don't wait to be asked.** Card payments are **already implemented** (hosted payment page, payment links, refunds); they only need a provider connected. The other gateways (`cod`, `bacs`, `cheque`) are **manual** — nobody pays online and someone reconciles by hand. So tell the user card payments are ready and ask them to connect the **Stripe** connector for the app, then **redeploy the backend functions** — the platform injects `STRIPE_SECRET_KEY` at deploy time, so a provider connected after the last deploy is invisible to already-deployed functions and the store still reports *no payment provider connected*. On a hosted app, edit any file under `base44/shared/commerce/` (bump the deploy marker at the top of `payments.ts`) to redeploy every `commerce/*` function; on the CLI, `npx base44 functions deploy`. Then confirm with `commerce/admin-tools` → `payment-connector-status`. Nothing to code. The card gateway is enabled by default and stays hidden from customers until a provider is connected, so enabling it early is safe. Declining is a legitimate choice — then switch that gateway off and make the manual flow explicit in the checkout copy. Details: [`references/online-payments.md`](./references/online-payments.md).
-9. **Report back** — tell the user what you created (counts by category/type, currency, enabled gateways) and that the store is ready at `/admin`.
+8. **Payments — once the store has something to sell.** Leave this until the catalog, shipping and settings are in place: connecting a payment provider is a step the *user* has to take in the platform dashboard, so asking for it first interrupts setup and leaves nothing to test the payment against. When the store is otherwise ready, raise it — don't wait to be asked. Card payments are **already implemented** (hosted payment page, payment links, refunds); they only need a provider connected. The other gateway (`offline`) is **manual** — nobody pays online and someone reconciles by hand. So tell the user card payments are ready and ask them to set up the platform's **Stripe integration** for the app (app dashboard → Integrations → Stripe — *not* an OAuth connector; there is no Stripe connector in Base44's catalog), then **redeploy the backend functions** — the platform injects `STRIPE_SECRET_KEY` at deploy time, so a provider connected after the last deploy is invisible to already-deployed functions and the store still reports *no payment provider connected*. On a hosted app, edit any file under `base44/shared/commerce/` (bump the deploy marker at the top of `payments.ts`) to redeploy every `commerce/*` function; on the CLI, `npx base44 functions deploy`. Then confirm with `commerce/admin-tools` → `payment-connector-status`. Nothing to code. The card gateway is enabled by default and stays hidden from customers until a provider is connected, so enabling it early is safe. Declining is a legitimate choice — then switch that gateway off and make the manual flow explicit in the checkout copy. Details: [`references/online-payments.md`](./references/online-payments.md).
+9. **Report back** — tell the user what you created (counts by category, currency, enabled gateways) and that the store is ready at `/store-admin`.
 
 Keep the generated catalog small unless asked — roughly 8–15 products across 3–5 categories, with at least one variable product if the business plausibly has options. Cost scales with the catalog: every product is generated copy plus at least one generated image, so confirm before going past that range rather than quietly producing a 50-product store. Products are created as `status: "publish"` only if you set it; leave them `draft` if the user wants to review before going live.
 
@@ -124,7 +121,7 @@ So future agent sessions know the store exists and read the skill before touchin
 
 ## My Skills
 
-- `skills/commerce/SKILL.md` — 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 admin UI mounted at `/admin`, and the `commerce/StoreAdmin` agent (admin copilot bot in the admin sidebar). Read before working on store features — catalog, cart, checkout, orders, payments, emails, webhooks, or the admin UI.
+- `skills/commerce/SKILL.md` — 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 bot in the admin sidebar). Read before working on store features — catalog, cart, checkout, orders, payments, emails, webhooks, or the admin UI.
 ```
 
 ---
@@ -146,9 +143,9 @@ So the work is UI: stars on cards and the product page, a reviews list, and a su
 - anonymous callers get **`401 login_required`** — put the form behind a login prompt instead of hiding reviews from guests;
 - a new review is **`hold`** unless `auto_approve_reviews`, so tell the submitter it's awaiting approval rather than showing it as live;
 - `only_verified_reviews` requires the customer to have a `processing`/`completed` order with that product (**`403 verified_only`**), and `review_rating_required` makes the rating mandatory (**`400 rating_required`**);
-- the store can switch reviews off (`products.enable_reviews`) or per product (`reviews_allowed`) — read those and hide the UI when false.
+- the store can switch reviews off store-wide (`products.enable_reviews`) — read it and hide the UI when false.
 
-Shapes and error codes: [`docs/api-storefront.md`](./docs/api-storefront.md#submit-review). Where ratings belong per view: [`references/product-render.md`](./references/product-render.md).
+Shapes and error codes: [`docs/api-storefront.md`](./docs/api-storefront.md#submit-review--auth). Where ratings belong per view: [`references/product-render.md`](./references/product-render.md).
 
 ---
 

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

@@ -0,0 +1,56 @@
+# The admin product form
+
+Where to change what, in `src/commerce/admin/pages/products/`. The shape follows one
+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
+
+`components/ProductDataPanel.jsx` builds the list. There are four, and two are conditional:
+
+| Tab | 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 |
+| **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.
+
+## Price & Inventory
+
+- **Rows.** A product with no attributes shows one collapsed **Base price** row, which
+  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.
+- **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.
+- **Copy from.** Pick a variant, tick Price / Inventory / Shipping, push it onto the rest.
+  `sku` and `image` are deliberately excluded — a copied SKU fails the save with
+  `duplicate_sku`.
+
+## Attributes drive the variants
+
+`components/AttributesSection.jsx` edits `product.attributes[]`; the variant list
+reconciles itself in a `useEffect` in `PriceInventoryTab.jsx`:
+
+- adding a value adds the missing combinations, **inheriting the first existing variant** —
+  or the product's own price when there is none yet, so adding Size to a €19.99 mug gives
+  priced variants;
+- removing a value drops the combinations it made impossible.
+
+So there is no *Generate variants* button and no per-variant delete: the attributes are the
+control. Reconciliation is keyed on an attribute signature and **skipped on first render** —
+a product whose stored variants don't match its attributes must not be rewritten before the
+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.

package/skills/commerce/references/emails.md

@@ -5,9 +5,10 @@ Transactional email is sent via `base44.integrations.Core.SendEmail` from the sh
 - 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.
-- The **"from" name** is `emails.from_name`, and it seeds **blank on purpose**: it inherits `general.store_name`, and when both are blank `SendEmail` is called without `from_name`, in which case **Base44 sends as the app's name** (verified: an app named *Canvas* with both 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. Settings → Emails shows the inherited value as the field's placeholder.
-- 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 `general.store_name` sends `New order #1002` rather than `[Canvas]: New order #1002`. Set the store name if you want it in the subject line.
+- The **store name** is `emails.store_name` — one setting, used for both the `{store_name}` in subjects/headings and the sender name. It lives nowhere else, but it is not email-only: `storefrontSafeSettings()` publishes it as `settings.store_name` on `get-store-info`, so it is also the public shop name. `commerce/seed-store` fills it from the `store_name` it is passed, and Settings → Emails is where a merchant changes it.
+- It seeds **blank on purpose**: a blank name means `SendEmail` is called without `from_name`, in which case **Base44 sends as the app's name** (verified: an app named *Canvas* with it blank delivered mail from "Canvas"). So the sender is the app name unless the store overrides it — one place to rename, and no hardcoded default.
+- That fallback does **not** reach subjects or headings: those are rendered by this template, which has no access to the app name, so a store with no `emails.store_name` sends `New order #1002` rather than `[Canvas]: New order #1002`. Set the store name if you want it in the subject line.
 - Subjects and headings tolerate a **blank** store name: `{store_name}` substitution drops empty brackets and collapses the gap, so an unnamed store sends `New order #1002`, never `[]: New order #1002`.
 - `emails_sent[]` on each order dedupes lifecycle emails so a re-entered status won't re-send.
-- Deliverability (SPF/DKIM) and the sending address depend on your Base44 email configuration — the store only sets `from_name`. Every send is recorded in the `commerce.EmailLog` entity.
+- Deliverability (SPF/DKIM) and the sending address depend on your Base44 email configuration — the store only sets the sender *name*. Every send is recorded in the `commerce.EmailLog` entity.
 - **Reading `commerce.EmailLog`:** one row per address per attempt. `target` is `admin` or `customer` — the same split the Recipient column shows in Settings → Emails (stock notifications count as `admin`). `order_id` is the id **users are shown**: the `order_number` from the admin Orders list and every email subject (`#1023` → `1023`). The internal Order record id is in `order_record_id`, which is what the admin routes on. Rows written before these fields existed still carry the record id in `order_id` and have no `target`; they are not backfilled.

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

@@ -1,8 +1,8 @@
 # Guest access & security
 
 - Storefront functions are **public** (anonymous invocation); confirm your app allows unauthenticated function calls. Checkout accepts guests unconditionally — there is no store setting that forces login. A login-required store has to enforce that in the shopfront you build (and, if it must not be bypassable, by adding the check to `commerce/storefront-checkout` `place-order`).
-- **All entities are admin-only RLS**, including the catalog (Product, ProductVariation, categories, tax/shipping config, payment gateways). Storefronts read the catalog through `commerce/storefront-catalog` (service role), never by querying entities directly with the client SDK — a direct read from a non-admin is rejected by the backend. This is deliberate: a world-readable catalog row exposes more than a shopper should see (`downloads[].file_url`, `purchase_note`, draft/hidden products, stock and sales internals, gateway `settings` such as BACS bank details). Do **not** relax any catalog entity's read RLS to `true`; if a shopfront needs a field, surface it through the storefront function instead.
-- The storefront catalog function strips the paywalled fields (`downloads`, `download_limit`, `download_expiry`, `purchase_note`) from every product/variation it returns. Downloadable files are reached only through `commerce/storefront-account` `get-download`, which enforces ownership, download limits, expiry and short-lived signed URLs — keep that the only path to a `file_url`.
+- **All entities are admin-only RLS**, including the catalog (Product, ProductVariation, categories, tax/shipping config, payment gateways). Storefronts read the catalog through `commerce/storefront-catalog` (service role), never by querying entities directly with the client SDK — a direct read from a non-admin is rejected by the backend. This is deliberate: a world-readable catalog row exposes more than a shopper should see (`downloads[].file_url`, draft/hidden products, stock and sales internals, gateway `settings` such as the offline gateway's bank details). Do **not** relax any catalog entity's read RLS to `true`; if a shopfront needs a field, surface it through the storefront function instead.
+- The storefront catalog function strips the paywalled fields (`downloads`, `download_limit`, `download_expiry`) from every product/variation it returns. Downloadable files are reached only through `commerce/storefront-account` `get-download`, which enforces ownership, download limits, expiry and short-lived signed URLs — keep that the only path to a `file_url`.
 - `cart_token` and `order_key` are **bearer credentials** — possession grants access to that cart/order. Always serve over HTTPS; don't log them; treat them like secrets.
 - Carts and orders have admin-only RLS; customers never touch those entities directly — all access is mediated by `commerce/storefront-*` functions using the service role after verifying the caller.
 - The admin side has three enforcement layers (UI guard, entity RLS, `requireAdmin()` function guard) — see [`post-installation.md`](../post-installation.md); never weaken them.

package/skills/commerce/references/limits-and-performance.md

@@ -2,7 +2,7 @@
 
 ## Limits & concurrency
 
-- **Pagination.** The SDK `filter`/`list` cap out at 5,000 records/page and there is **no total-count API**. Server-side scans use paged loops (`shared/scan.ts` `scanAll`, page size 500). Admin lists use limit+skip with a `limit+1` "has-next" probe — the UI shows *Page N ‹ ›*, never a total.
+- **Pagination.** The SDK `filter`/`list` cap out at 5,000 records/page and there is **no total-count API**. Server-side scans use paged loops (`base44/shared/commerce/scan.ts` `scanAll`, page size 500). Admin lists use limit+skip with a `limit+1` "has-next" probe — the UI shows *Page N ‹ ›*, never a total.
 - **Search** is server-side (`search` actions scan + JS-filter) because entity `filter` is exact-match only.
 - **Reports** scan orders on demand — fine to ~10k orders per range. Beyond that, materialize an `OrderStats` entity updated on each order transition and aggregate from it (sketch: one record per day per status with summed totals; `commerce/admin-reports` reads the pre-aggregated rows instead of scanning `commerce.Order`).
 - **No transactions.** A few consequences, all documented in code:

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

@@ -4,7 +4,7 @@
 
 - `base44/shared/commerce/payments.ts` — the **provider-neutral payment utility** every caller uses, plus the one-line `ACTIVE_PROVIDER` binding.
 - `base44/shared/commerce/stripe.ts` — the Stripe adapter (the only file that speaks Stripe).
-- `base44/functions/commerce/payments/` — `status` · `create-link` · `verify`.
+- `base44/functions/commerce/payments/` — `status` · `create-link` · `complete-return` · `verify`.
 - `base44/functions/commerce/payment-webhook/` — the provider's signed callback.
 - `commerce/storefront-checkout` `place-order` returns a `checkout_url`; `commerce/admin-refunds` refunds through the provider; the admin order page has a **Payment** panel.
 
@@ -12,7 +12,7 @@
 
 ## 1. What to do when building a store (strong recommendation, not a rule)
 
-A store that can't take a card is usually not what the user wants: the gateways that work with no provider at all (`cod`, `bacs`, `cheque`) are **manual** — the customer leaves without paying and someone reconciles by hand. So **recommend online payment clearly** — but **at the right moment, which is not first.**
+A store that can't take a card is usually not what the user wants: the gateway that works with no provider at all (`offline`) is **manual** — the customer leaves without paying and someone reconciles by hand. So **recommend online payment clearly** — but **at the right moment, which is not first.**
 
 **Sequence it after the store exists.** Connecting a provider is a step only the *user* can take, in the platform dashboard: asking for it up front stops your work dead on someone else's action, and even once done there is nothing to verify against — no product to buy, no shipping method, no order. Set the store up first (settings → catalog → shipping), *then* raise payments, as the last thing before the store is usable or before you build checkout. The card gateway ships enabled and stays hidden from customers until a provider is connected, so nothing is broken while you wait, and nothing is lost by doing it late.
 
@@ -60,11 +60,11 @@ Card data never touches this app — the customer pays on the provider's page.
 
 1. `success_url` / `cancel_url` — a full page URL per outcome;
 2. `return_url` — **your return page**, used for both outcomes (`payment=success|cancel` distinguishes them). A bare origin (`https://shop`, no path) is instead treated as a base, since there's no page in it;
-3. the store's **Storefront URL** + **Payment return path** (both in general settings: `store_url`, `order_received_path`), or the origin the request came from + that path.
+3. the origin the request came from (the storefront that called this) + the store's **Payment return path** (`settings.general.order_received_path`).
 
 Every result carries `order_id`, `order_key` and `payment`, **including URLs you supplied** — a `success_url` without them can't verify anything. Existing query parameters survive. With nothing to build from, the call fails `400 return_url_required` rather than letting the provider answer "Not a valid URL".
 
-**Set the return path to whatever route you built.** It defaults to `/order-received`, and a wrong value sends paying customers to a 404 — including the confusing `/<your-page>/<your-page>` you get if you treat `return_url` as a base and your page path as a suffix. The admin's payment links deliberately pass no URL at all: the route belongs to the storefront, so they use the store's configured path.
+**Set the return path to whatever route you built.** It defaults to `/order-received`, and a wrong value sends paying customers to a 404 — including the confusing `/<your-page>/<your-page>` you get if you treat `return_url` as a base and your page path as a suffix. The admin's payment links deliberately pass no URL at all: the route belongs to the storefront, so they resolve to the app's own origin plus the store's configured path.
 
 ### MANDATORY: the payment return page (`/order-received`)
 
@@ -101,7 +101,7 @@ Rules for whatever you build:
 - **Handle all three states**, not just the happy one — `unpaid` is common (bank delays, closed tabs) and needs a *Check again* plus *Pay now*, not an error.
 - **Don't gate it behind login.** Guests pay too; `order_key` in the link is the credential.
 
-**Storefront wiring** (the only integration work):**Storefront wiring** (the only integration work):
+**Storefront wiring** (the only integration work):
 
 ```js
 const res = await inv("commerce/storefront-checkout", {
@@ -128,7 +128,7 @@ The order page's **Payment** panel shows the method, total, paid state and payme
 - **Create payment link** — the provider-hosted page for exactly that order's total; copy it to the customer.
 - **Check payment** — re-asks the provider and moves the order on if the money arrived.
 
-**The order's current payment method doesn't matter.** Asking for a link *is* the decision to collect online, and an admin-created order starts with no method at all, so `create-link` accepts any unpaid order and switches it onto the online gateway, recording the change in the order log (`Payment method set to Credit card (was Cash on delivery)…`). That switch matters beyond tidiness: refunds key off `payment_method`, so an order paid by card must say so or it can't be refunded through the provider. The panel warns before it happens.
+**The order's current payment method doesn't matter.** Asking for a link *is* the decision to collect online, and an admin-created order starts with no method at all, so `create-link` accepts any unpaid order and switches it onto the online gateway, recording the change in the order log (`Payment method set to Credit card (was Offline payment)…`). That switch matters beyond tidiness: refunds key off `payment_method`, so an order paid by card must say so or it can't be refunded through the provider. The panel warns before it happens.
 
 The one refusal is a store that has **turned online payment off** — `400 online_payments_disabled` — because that's the operator declining it, not a missing setup.
 
@@ -186,9 +186,9 @@ Rules for any checkout UI you build:
 - **Fetch, don't assume.** `commerce/storefront-catalog` → `get-store-info` returns `payment_gateways`, filtered to `enabled: true`, sorted by the admin's `order`, and with any online gateway **dropped while no provider is connected** — so what you render is always payable. Each entry is `{ slug, title, description, online }`.
 - **Use the admin's copy.** Show `title`/`description` as the customer-facing labels instead of your own strings, and key your logic off `slug` (`online: true` marks the one that redirects to a hosted page).
 - **Render the zero-state honestly.** An empty `payment_gateways` means checkout cannot complete; say so rather than showing a dead button.
-- **Let the server arbitrate.** Gateway `settings` are intentionally *not* exposed to the storefront, so the client cannot evaluate rules like `cod`'s `enable_for_methods` / `enable_for_virtual`. Send the chosen `slug` and treat `400 invalid_payment_method` from `place-order` as the authoritative answer.
+- **Let the server arbitrate.** Gateway `settings` are intentionally *not* exposed to the storefront, so the client cannot evaluate a gateway's own rules. Send the chosen `slug` and treat `400 invalid_payment_method` from `place-order` as the authoritative answer.
 - **Re-fetch rather than cache hard.** An admin can enable, disable or reorder gateways at any time; a long-lived cached list is how a storefront drifts out of sync with the store.
-- **Show `payment_instructions` from the response** for manual flows (`bacs`/`cheque`/`cod`) rather than hardcoding bank details in the UI.
+- **Show `payment_instructions` from the response** for the `offline` flow rather than hardcoding bank details in the UI.
 
 ## 8. Never hardcode payment availability
 

package/skills/commerce/references/product-render.md

@@ -5,7 +5,7 @@ What to show for a product, and **which view can show it**. Both storefront surf
 | View | Call | Returns |
 |---|---|---|
 | Listing / grid / search results / tag & category pages | `commerce/storefront-catalog` `list-products` | `{ products: [row...], page, per_page, has_next }` |
-| Product page | `commerce/storefront-catalog` `get-product` | `{ product, variations, categories, tags, reviews, upsells, cross_sells, grouped_products }` |
+| Product page | `commerce/storefront-catalog` `get-product` | `{ product, variations, categories, tags, reviews, upsells, cross_sells }` |
 
 Request/response shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). Variant selection mechanics (axes, resolving a selection to a variation, unavailable combinations): [`storefront-product-page.md`](./storefront-product-page.md).
 
@@ -19,48 +19,50 @@ A listing **row** is the product record itself (minus paywalled fields), plus re
 
 | Data | `list-products` row | `get-product` | Notes |
 |---|---|---|---|
-| `id`, `name`, `slug`, `type`, `status` | ✅ | ✅ | |
-| `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | For `variable`, the parent `price` is a starting point, not the truth — see §3 |
+| `id`, `name`, `slug`, `status` | ✅ | ✅ | There is no `type` field — a product sells variants when `attributes[]` is non-empty |
+| `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | With variants the parent `price` is a starting point, not the truth — see §3 |
 | `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`. `images` can be **empty** — render a placeholder, don't leave a broken `img` (on the product page `resolveSelection`'s `display.image` is `null` in that same case) |
 | `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
 | `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
-| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the raw axes/spec array |
-| **`tags`** (resolved `{id, name, slug}`) | ✅ | ✅ | `get-product` returns the full tag records; rows carry the short form |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive properties the admin calls **modifiers** |
+| **`tags`** (resolved `{id, name}`) | ✅ | ✅ | `get-product` returns the full tag records; rows carry the short form |
 | `tag_ids`, `category_ids` | ✅ | ✅ | Raw ids |
 | **`categories`** (resolved) | ❌ *ids only* | ✅ | See §5 to add |
-| **`variations[]`** (per-variation price/stock/image/attributes) | ❌ | ✅ | The reason a variable product can't be fully priced from a row |
+| **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | The reason a product with variants can't be fully priced from a row |
 | **`reviews`** (paged items + `average_rating`/`rating_count`) | ❌ | ✅ | Row still has the aggregate numbers |
 | **`upsells`, `cross_sells`** (summaries) | ❌ | ✅ | `{id, name, slug, price, on_sale, image}` |
-| **`grouped_products`** (children of a grouped product) | ❌ | ✅ | |
-| `downloads[]`, `download_limit`, `download_expiry`, `purchase_note` | ❌ | ❌ | **Never** exposed publicly — paywalled/post-purchase. Gated by `commerce/storefront-account` `get-download` |
+| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** exposed publicly — paywalled. Gated by `commerce/storefront-account` `get-download` |
 
 ## 2. Tags — render them in **both** views
 
 Tags are a flat, cross-cutting axis ("gift", "summer", "vegan"); categories are the hierarchical spine. Generated storefronts routinely omit tags entirely. Don't.
 
-- **Listing rows carry resolved `tags`** (`{id, name, slug}`), so a card can render them with no extra call. One or two chips per card is useful ("New", "Bundle"); more is noise. Hide the block when the array is empty — never a dangling "Tags:" label.
-- **On the product page**, render `product.tags` (the top-level `tags` array, with `description` and `count` available) as chips near the metadata, visually lighter than the category breadcrumb.
-- **Every chip links to a filtered listing** — `list-products` with `tag_id` — never a dead label. Keep the tag in the URL (`/shop?tag=<slug>` or `/tag/<slug>`) so the page is shareable and survives reload; resolve slug → id with `list-tags`.
+- **Listing rows carry resolved `tags`** (`{id, name}`), so a card can render them with no extra call. One or two chips per card is useful ("New", "Bundle"); more is noise. Hide the block when the array is empty — never a dangling "Tags:" label.
+- **On the product page**, render `product.tags` (the top-level `tags` array) as chips near the metadata, visually lighter than the category breadcrumb.
+- **Every chip links to a filtered listing** — `list-products` with `tag_id` — never a dead label. A tag has no slug, so key the URL on its id (`/shop?tag=<tag_id>`) so the page is shareable and survives reload. Use `list-tags` for a name to label it with.
 - **Offer tags as a listing filter** from `list-tags`, which hides tags no published product carries and gives a `count` for labels like "Gift (12)". `tag_id` stacks with `category_id`, price, `on_sale`, `featured`, `in_stock_only`.
-- **Tag landing page:** `list-products` filtered by `tag_id`, with the tag's `name` as heading and `description` as intro copy when present.
+- **Tag landing page:** `list-products` filtered by `tag_id`, with the tag's `name` as the heading.
 - Don't put tags in the breadcrumb, and don't use them as variant options — a size or colour is an `attribute`, not a tag.
+- Descriptive properties (Material, Care) are **modifiers** in `meta_data`, not tags and not attributes. Render them as a spec table on the product page.
 
-## 3. Product types in each view
+## 3. Product shapes in each view
 
-| `product.type` | Card | Product page |
-|---|---|---|
-| `simple` | price, **Add to cart** straight from the card if you want one | single **Add to cart** — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
-| `variable` | price **range or `From €19`** (see below), never selectors — link through | one selector per attribute: [`storefront-product-page.md`](./storefront-product-page.md) |
-| `grouped` | link through, no cart action | not purchasable itself: render `grouped_products` as children with their own quantity inputs, each added as its own cart line |
-| `external` | link through | `product.button_text` linking to `product.external_url`; no cart interaction |
+There are only two shapes, and **`attributes[]` tells them apart** — there is no `type` field:
+
+| Shape | Test | Card | Product page |
+|---|---|---|---|
+| **Single item** | `attributes` is empty | price, **Add to cart** straight from the card if you want one | single **Add to cart** — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
+| **Has variants** | `attributes` is non-empty | price **range or `From €19`** (see below), never selectors — link through | one selector per attribute: [`storefront-product-page.md`](./storefront-product-page.md) |
+
+A product with attributes is **only** sellable through a variant: `add-item` without a `variation_id` is `400 variation_required`, and there is no fall-back to the parent. So one with attributes but no variations is unsellable by design, not by accident.
 
-Downloadable/virtual products are `simple`/`variable` with `downloadable: true` — see [`media-and-downloads.md`](./media-and-downloads.md).
+Downloadable/virtual products are either shape with `downloadable: true` — see [`media-and-downloads.md`](./media-and-downloads.md).
 
-### A variable product's parent `price` is not its price
+### A variant parent's `price` is its *from* price
 
-The backend rolls **stock** up from variations to the parent, but **not price** — a variable parent's `price` is only whatever was set on the parent record, often nothing. A row has no `variations`, so a card cannot compute the real range; show `From {product.price}` or a range, never the parent price presented as *the* price, and never `€0`.
+`admin-products` rolls both **stock** and **price** up from the variations: a parent's `regular_price`, `price` and `on_sale` are derived from the cheapest publishable variant on every save. So the parent price is real and safe to sort and filter on — but it is the **lowest** price, not *the* price.
 
-This is a **data** problem before it is a UI one: `list-products` sorts and filters on `product.price ?? 0`, so a variable product with no parent price **sorts as free and drops out of every price-range filter**. Fix it in the catalog — set the parent's `regular_price` to the lowest variation price (purchasing is unaffected: a variable line always prices from its variation). Then cards, sorting and filters all agree.
+A listing row has no `variations`, so a card still cannot compute the full range from a row alone: render `From {product.price}`, never the parent price presented as *the* price. On the product page you have `variations`, so show the real range via `priceRange` from the variant helpers.
 
 ## 4. Sensible defaults per view
 

package/skills/commerce/references/storefront-product-page.md

@@ -1,6 +1,6 @@
 # Variant selection on the product page
 
-The one interaction agents reliably get wrong: turning a variable product into controls a customer can buy from. Everything else about the page — what to show, and which fields each call returns — is [`product-render.md`](./product-render.md); request/response shapes are [`docs/api-storefront.md`](../docs/api-storefront.md).
+The one interaction agents reliably get wrong: turning a product with variants into controls a customer can buy from. Everything else about the page — what to show, and which fields each call returns — is [`product-render.md`](./product-render.md); request/response shapes are [`docs/api-storefront.md`](../docs/api-storefront.md).
 
 The logic ships: **`src/commerce/utils/variants.js`** (framework-free, no I/O, full JSDoc on every export — read it for signatures). Import it and spend your effort on the markup.
 
@@ -8,7 +8,7 @@ The logic ships: **`src/commerce/utils/variants.js`** (framework-free, no I/O, f
 
 ## 1. The model, and the rule
 
-`get-product` returns `{ product, variations }`. `product.attributes[]` entries with `variation: true` are the **axes**, in `position` order; each `variations[]` record is one combination. `visible: true` + `variation: false` attributes are descriptive — a spec table, **never** a selector.
+`get-product` returns `{ product, variations }`. **Every** `product.attributes[]` entry is an **axis**, in `position` order; each `variations[]` record is one combination. There is no product type and no per-attribute flag — carrying attributes is what makes a product sell variants. Descriptive properties are `meta_data` (the admin calls them modifiers) — a spec table, **never** a selector.
 
 **One control per axis. Never one option per variation.** Do not flatten `variations[]` into `Red / S`, `Red / M`, `Blue / S`, … — that is `n × m` noise, it hides the product's structure, and it stops scaling immediately.
 
@@ -43,16 +43,16 @@ Bind the UI to `view` — not to `product.*` — so a selection actually changes
 | `purchasable` | gate **Add to cart** on this (resolved *and* buyable) |
 | `addToCart` | `{ product_id, variation_id }` to spread into the cart call, or `null` |
 
-`view.variation` and `view.candidates` are there when you need the record itself or the variations still reachable. For a `simple` product `resolveSelection` returns no axes, `complete: true` and a ready `addToCart` — the same code path; it branches on `product.type`, so `variations` can be `[]`.
+`view.variation` and `view.candidates` are there when you need the record itself or the variations still reachable. For a product with no attributes `resolveSelection` returns no axes, `complete: true` and a ready `addToCart` — the same code path; it branches on whether there are axes, so `variations` can be `[]`.
 
-A **variable product with no usable variations** — `type: "variable"` but nothing in `variations[]`, the state an attribute record alone leaves you in — is deliberately *not* given a parent fallback, because `add-item` would reject it. You get axes whose `options` arrays are empty, `purchasable: false` and `addToCart: null`. Render it as unavailable rather than painting selector groups with no buttons, and guard the "Select a …" label: with no `variation: true` attributes at all, `missingAxes` is empty and `view.missingAxes[0]?.name` is `undefined`.
+A **product with attributes but no usable variations** — the state attaching an attribute and stopping leaves you in — is deliberately *not* given a parent fallback, because `add-item` would reject it. You get axes whose `options` arrays are empty, `purchasable: false` and `addToCart: null`. Render it as unavailable rather than painting selector groups with no buttons, and guard the "Select a …" label: with no attributes at all, `missingAxes` is empty and `view.missingAxes[0]?.name` is `undefined`.
 
 The other exports cover what the view model doesn't: `selectionForVariation` (variation → selection, to hydrate controls from a cart line or `?variation=` link), `selectionToParams`/`selectionFromParams` (URL round-trip), `priceRange`, and the individual pieces if you build your own view model. Signatures and edge cases are in the JSDoc; two behaviors are easy to miss when hand-rolling: non-publishable variations never leak an option into the UI, and an empty `option` on an axis means **"any"**.
 
 ## 3. The three UI decisions the helpers can't make for you
 
 - **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → keep it visible and label it. `onbackorder` counts as available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
-- **Incomplete selection.** Show `view.priceRange` (`$21.99 – $23.99`, or `From $21.99`) — never `$0`, and never the parent `price`, which for a variable product is not its price ([`product-render.md` §3](./product-render.md#3-product-types-in-each-view)). Keep **Add to cart** disabled with a hint at what's missing.
+- **Incomplete selection.** Show `view.priceRange` (`$21.99 – $23.99`, or `From $21.99`) — never `$0`, and never the parent `price`, which for a product with variants is not its price ([`product-render.md` §3](./product-render.md#3-product-shapes-in-each-view)). Keep **Add to cart** disabled with a hint at what's missing.
 - **Initial state and linkability.** Start from `defaultSelection` (honours the merchant's `default_attributes`, preselects single-option axes). Mirror the selection into the URL with `selectionToParams` and hydrate with `selectionFromParams`, so a chosen variant is shareable and survives a refresh.
 
 Route every click through `selectOption` and dead ends take care of themselves: it keeps the just-picked option and clears only conflicting axes (Red/L → click Blue → `{ Color: Blue }`, size re-open) instead of leaving the customer on a combination that resolves to nothing.
@@ -63,21 +63,21 @@ Route every click through `selectOption` and dead ends take care of themselves:
 await base44.functions.invoke("commerce/storefront-cart", {
   action: "add-item",
   cart_token,
-  ...view.addToCart,   // { product_id, variation_id } — variation_id is REQUIRED for type "variable"
+  ...view.addToCart,   // { product_id, variation_id } — variation_id is REQUIRED once a product has attributes
   quantity,
 });
 ```
 
-Handle `400 variation_required` (empty `variation_id` on a variable product — the page has a bug), the stock codes (`out_of_stock`, `insufficient_stock`, …), and `404 variation_not_found` (catalog changed underneath the page: refetch `get-product`). `product.sold_individually` caps the quantity control at 1.
+Handle `400 variation_required` (empty `variation_id` on a product with attributes — the page has a bug), the stock codes (`out_of_stock`, `insufficient_stock`, …), and `404 variation_not_found` (catalog changed underneath the page: refetch `get-product`). `product.sold_individually` caps the quantity control at 1.
 
 ## 5. Checklist
 
 - [ ] One control per axis in `view.axes` — no combination list anywhere in the UI.
-- [ ] Non-variation visible attributes render as specs, not selectors.
+- [ ] `meta_data` modifiers render as specs, not selectors.
 - [ ] Image, price, SKU and availability all come from `view.display`, with a placeholder for `display.image === null`.
 - [ ] Incomplete selection shows `view.priceRange` — never `$0`, never the parent `price`.
 - [ ] `"unavailable"` disabled, `"out_of_stock"` labelled; every click routed through `selectOption`.
 - [ ] Initial state from `defaultSelection`; selection mirrored into the URL.
 - [ ] **Add to cart** gated on `view.purchasable`, sending `view.addToCart`.
-- [ ] A variable product with empty `axes[].options` shows as unavailable — no empty selector groups, no "Select a undefined".
+- [ ] A product with empty `axes[].options` shows as unavailable — no empty selector groups, no "Select a undefined".
 - [ ] Tags, ratings, upsells and the rest per [`product-render.md`](./product-render.md).

package/skills/commerce/references/webhooks.md

@@ -1,6 +1,8 @@
 # Webhooks
 
-`webhooks.ts` `dispatch()` fires on `order.*`, `product.*`, `customer.*`, `coupon.*` (created/updated/deleted, plus order/product `restored`). Each active `commerce.Webhook` matching the topic receives an HTTP POST with headers `X-Commerce-Webhook-Topic/-Resource/-Event/-ID/-Delivery-ID/-Signature`. The signature is **base64 HMAC-SHA256** of the body, keyed by the webhook's `secret` (Web Crypto).
+Managed in the admin at **Settings → Webhooks** (`settings/webhooks`; the source still lives under `pages/status/`).
+
+`webhooks.ts` `dispatch()` fires on `order.*`, `product.*`, `customer.*`, `coupon.*` (created/updated/deleted, note that `restored` is selectable on a webhook but **never emitted** — nothing dispatches it). Each active `commerce.Webhook` matching the topic receives an HTTP POST with headers `X-Commerce-Webhook-Topic/-Resource/-Event/-ID/-Delivery-ID/-Signature`. The signature is **base64 HMAC-SHA256** of the body, keyed by the webhook's `secret` (Web Crypto).
 
 - Every attempt is logged as a `commerce.WebhookDelivery` (request/response bodies truncated to 32 KB). Prune with `commerce/admin-tools` `prune-webhook-deliveries`.
 - `failure_count` increments on non-2xx/timeout and resets on success; a webhook auto-disables after **5** consecutive failures.

package/src/commerce/admin/README.md

@@ -1,4 +1,4 @@
-# Store Admin (`src/commerce/admin/`)
+# Store Management (`src/commerce/admin/`)
 
 React admin UI for the Base44 commerce template. Copy this
 folder into a Base44 app built on the default template (Vite + React +
@@ -27,14 +27,14 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    ```jsx
    import AdminApp from "@/commerce/admin";
 
-   <Route path="/admin/*" element={<AdminApp />} />
+   <Route path="/store-admin/*" element={<AdminApp />} />
    // mounted elsewhere? → <AdminApp basePath="/backoffice" />
    ```
 
 5. Make sure your user has the **admin role** (Base44 dashboard → Users, or
    `base44.users.inviteUser(email, "admin")`). Signed-in users without the
    admin role get an access-denied screen — do not weaken this check.
-6. Open `/admin`. If the store has never been seeded (no `general` StoreSettings
+6. Open `/store-admin`. If the store has never been seeded (no `general` StoreSettings
    group) the first-run screen appears and seeds store defaults, optionally with
    sample data when the store has no products yet. If `commerce/seed-store` was
    already run during installation — including when an agent generated a real
@@ -61,7 +61,7 @@ backend functions directly as its tools.
 
 alert, alert-dialog, badge, button, calendar, card, checkbox, command, dialog,
 dropdown-menu, input, label, popover, radio-group, scroll-area, select,
-separator, sheet, skeleton, switch, table, tabs, textarea, tooltip
+separator, sheet, skeleton, switch, table, tabs, textarea
 
 The default Base44 template ships all of these. If one is missing:
 

package/src/commerce/admin/context/BasePathContext.jsx

@@ -2,15 +2,15 @@ import React, { createContext, useContext } from "react";
 import { normalizeBasePath } from "../lib/paths";
 
 /**
- * The URL prefix the admin app is mounted under (default `/admin`).
+ * The URL prefix the admin app is mounted under (default `/store-admin`).
  * All internal links are built from this, so the admin folder works no matter
  * where the consumer mounts it: `<AdminApp basePath="/backoffice" />`.
  */
-const BasePathContext = createContext("/admin");
+const BasePathContext = createContext("/store-admin");
 
-export function BasePathProvider({ value = "/admin", children }) {
+export function BasePathProvider({ value = "/store-admin", children }) {
   // normalizeBasePath also tolerates the route *pattern* being passed in
-  // (`basePath="/admin/*"`), an easy copy/paste slip from the mount — every
+  // (`basePath="/store-admin/*"`), an easy copy/paste slip from the mount — every
   // internal link would otherwise carry a literal "*" segment.
   return <BasePathContext.Provider value={normalizeBasePath(value)}>{children}</BasePathContext.Provider>;
 }
@@ -19,7 +19,7 @@ export function useBasePath() {
   return useContext(BasePathContext);
 }
 
-/** Returns a builder: href("orders/123") → "/admin/orders/123"; href() → "/admin". */
+/** Returns a builder: href("orders/123") → "/store-admin/orders/123"; href() → "/store-admin". */
 export function useAdminHref() {
   const base = useBasePath();
   return (path = "") => (path ? `${base}/${String(path).replace(/^\/+/, "")}` : base);