@base44/app-plugin-commerce 0.7.1 → 0.8.1

package/README.md

@@ -10,7 +10,7 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 - **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` — one call seeds the business defaults **and the whole catalog** (products with attributes in, variants/categories/taxonomy created internally).
 - **Payments: manual methods work out of the box; online cards are opt-in** — the seed enables the manual `offline` method (bank transfer, cash on delivery, pickup: on-hold + instructions, no code) and leaves the `card` gateway **disabled**. The order side of card payments *is* premade — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records — so a store that opts in wires a provider by implementing **four functions in one file**, `base44/shared/commerce/card-payment.ts`. **For Stripe there is nothing to write**: `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation used as-is — copy it over the stub and enable the gateway. Any other provider (PayPal, Adyen, a local PSP) follows the same shape. Enable the gateway only with a provider behind it, or checkout answers `503 no_card_payment_provider`. The rule and timing: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); provider mechanics: [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md). The admin can add more manual methods in Settings → Payments.
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, 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, and full settings including webhooks. Admin-role gated.
+- **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. Localized — ships in English (default), German, Spanish, French, Japanese and Portuguese, switched by one line of code, with a documented recipe for adding any other language (no i18n dependency; see [`src/commerce/admin/README.md`](./src/commerce/admin/README.md) and the skill's `references/admin-localization.md`).
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/reviews/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and price ranges; `price.js` encodes the from-price and price-range rules; `totals.js` projects a cart *or* an order into one summary shape; `address-spec.js` is the checkout address form as data; `images.js` and `ribbons.js` normalize the two catalog fields that are arrays of objects (`{src, name, alt}` images, `{id, name}` ribbons) rather than strings; `types.js` writes the catalog shapes down as JSDoc typedefs (`StorefrontProduct` and the rest), so what a field holds is answerable from the frontend; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" states a configured rule rather than an invented number.
 - **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. **It ships no customer-facing copy either**: where a state needs words you get the *state* — `buy.state`, a picker's `hint.code`, the checkout's `blockers`, a review's `status` — and write the sentence. What ships is every piece of logic that is the same in all stores: `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine` (+ `useCartUI`/`CartUIProvider` for a drawer), `useCheckout`/`CheckoutProvider`/`useCheckoutContext`, `useOrderReturn`/`orderReceivedUrl` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings), one deliberately rendered-but-unstyled component (`AddressFields` — the checkout address form, whose state/province and `autoComplete` mechanics are where hand-rolled forms break; it ships no CSS and styles via `data-part` selectors or class props), and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productRibbons`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …) and names its return type from `storefront/types.js`, so a page reads a field's shape off the hook instead of off a backend function. Needs React and nothing else.
 - **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.
@@ -85,18 +85,12 @@ From your existing Base44 app:
    npx npq install <only the missing names>   # npq audits the package before npm installs it
    ```
    See [`src/commerce/admin/README.md`](./src/commerce/admin/README.md) for the exact shadcn component list.
-5. **Mount the admin** as a layout route in your app's `src/App.jsx` — Base44 discovers an app's pages by reading the literal `<Route>` JSX in that file, so the screens that should be listed as pages are declared there and the rest run off a splat handled by the kit's own router:
+5. **Mount the admin router** in your app:
    ```jsx
-   import AdminApp, { AdminRoutes } from "@/commerce/admin";
+   import AdminApp from "@/commerce/admin";
    // inside your <Routes>:
-   <Route path="/store-admin" element={<AdminApp />}>
-     <Route index element={<Dashboard />} />
-     <Route path="orders" element={<OrdersList />} />
-     {/* …products, customers, coupons, reports… */}
-     <Route path="*" element={<AdminRoutes />} />   {/* editors, settings, webhooks */}
-   </Route>
+   <Route path="/store-admin/*" element={<AdminApp />} />
    ```
-   Name the section they group under in `base44/ui.jsonc` (app-owned — edit in place): `{ "version": 1, "sections": [{ "path": "/store-admin/*", "name": "Store Management" }] }`
 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 `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, the payment gateway rows (`offline` enabled, `card` off — enable it only with a provider wired) and — unless you pass your own `locations` — a fallback Shipping & Tax Location, plus the catalog: pass `products` (whole products with attributes — variants, categories, ribbons and taxonomy are created internally) or `with_sample_data: true` for the generic demo. 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. Worked example: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); the full payload contract: [`skills/commerce/docs/api-admin.md`](./skills/commerce/docs/api-admin.md). Shipping zones are part of the same call — `locations` takes `continents: ["EU"]` and `rest_of_world: true`, so "€20 in Europe, €100 worldwide" is six lines.
 

package/base44/entities/commerce.ProductReview.jsonc

@@ -24,7 +24,7 @@
     },
     "review": {
       "type": "string",
-      "description": "Review content"
+      "description": "Review text. May be empty for a stars-only review (submit-review requires text or a rating, not both)."
     },
     "rating": {
       "type": "integer",
@@ -38,7 +38,7 @@
       "description": "Derived: reviewer purchased the product. Set by commerce/storefront-catalog submit-review."
     }
   },
-  "required": ["product_id", "review"],
+  "required": ["product_id"],
   "rls": {
     "read": { "user_condition": { "role": "admin" } },
     "create": { "user_condition": { "role": "admin" } },

package/base44/functions/commerce/storefront-catalog/entry.ts

@@ -396,12 +396,16 @@ async function submitReview(sr: any, p: any, user: any): Promise<any> {
   const review = String(p.review ?? "").trim();
   const rating = p.rating == null ? null : Math.floor(Number(p.rating));
 
-  if (!review) {
-    throw new HttpError(400, "review is required.", "review_incomplete");
-  }
   if (rating != null && (rating < 0 || rating > 5)) {
     throw new HttpError(400, "Rating must be between 0 and 5.", "invalid_rating");
   }
+  // Text or stars — either alone is a valid review. Requiring text rejected
+  // every stars-only submission from a form that treats the write-up as
+  // optional, with a 400 the customer can't act on. Rating 0 is "unrated"
+  // (the aggregates ignore it), so it can't stand in for the missing text.
+  if (!review && !(rating != null && rating >= 1)) {
+    throw new HttpError(400, "A review needs text or a star rating.", "review_incomplete");
+  }
 
   const verified = await hasPurchased(sr, reviewerEmail, product.id);
 

package/package.json

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

package/scripts/install.js

@@ -217,10 +217,8 @@
     "\n" +
     "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
     "     Base44 template — check package.json and npm i only what is truly missing\n" +
-    '  2. Mount the admin in src/App.jsx: <Route path="/store-admin" element={<AdminApp />}>\n' +
-    "     with the main screens as literal child <Route>s (that file is what the platform\n" +
-    '     discovers pages from) and <Route path="*" element={<AdminRoutes />} /> for the\n' +
-    "     rest, plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
+    '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
+    "     plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
     "  3. Seed the store — one commerce/seed-store call (store_name required) takes the\n" +
     "     catalog, currency, shipping locations and payment methods\n" +
     "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"

package/skills/commerce/SKILL.md

@@ -29,6 +29,11 @@ install, then the storefront UI, then the catalog. Every install runs all three,
 so fetching them one at a time defers nothing you will not read anyway and costs
 a model round trip per file. Read nothing *else* up front.
 
+**Admin language.** English: nothing to do. de/es/fr/ja/pt: in
+`src/commerce/admin/i18n/index.js` repoint `import active from "./locales/de.js"`
+and stop — never edit admin screens. Other:
+[`references/admin-localization.md`](./references/admin-localization.md).
+
 ## Four things to hold from the start
 
 - **Entity names are dotted; SDK access is bracket syntax only** —
@@ -117,18 +122,19 @@ batch (above).
 
 | Topic | Open when | Size |
 |---|---|---|
-| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 8K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 35K |
+| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 37K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond 03's recipe, taxes, day-2 edits | 8K |
 | [`references/online-payments.md`](./references/online-payments.md) | enabling card payments, or wiring the provider — at install or any time later | 8K |
 | [`references/storefront-verification.md`](./references/storefront-verification.md) | driving the storefront from a browser script | 3K |
-| [`references/reviews.md`](./references/reviews.md) | review policies (login-gated, verified buyers), moderation | 5K |
+| [`references/reviews.md`](./references/reviews.md) | review policies (open by default; login-gated, verified buyers), moderation | 6K |
 | [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | 5K |
 | [`references/emails.md`](./references/emails.md) | order-email recipients, subjects, the log | 5K |
 | [`references/admin-product-form.md`](./references/admin-product-form.md) | editing the shipped product editor | 6K |
+| [`references/admin-localization.md`](./references/admin-localization.md) | a language **outside** en/de/es/fr/ja/pt (the six ship; switching is one import) | 5K |
 | [`references/store-admin-agent.md`](./references/store-admin-agent.md) | changing the StoreAdmin copilot | 3K |
 | [`references/guest-access-security.md`](./references/guest-access-security.md) | **adding your own function or entity**; RLS/identity questions | 5K |
 | [`references/operations.md`](./references/operations.md) | scheduled maintenance, scaling limits, outbound webhooks | 7K |

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

@@ -114,14 +114,14 @@ This is the **only** way a storefront can enumerate ribbons (the entity is admin
 No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — each attribute (`id, name, code, order`) with its values (`id, attribute_id, name, order, count`), both sorted by `order`; for filter UIs. Filter with `list-products` `attribute_id` (id or attribute **name**) + `attribute_term` (the value name); `code` is the stable key for a URL.
 
 ### `submit-review`
-**Payload:** `{ product_id, email?, reviewer?, review, rating? }` — `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
+**Payload:** `{ product_id, email?, reviewer?, review?, rating? }` — at least one of `review` (text) or `rating` (1–5); `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
 
 > A React storefront reaches this call as `submitReview` (and the paginated list as `getProductReviews`) on the client from `@/commerce/storefront`'s `useStorefront()`, with the list itself already riding along on the product; policies and moderation are [`../references/reviews.md`](../references/reviews.md). Read on for the raw contract.
 
-**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
+**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. **Text or stars — either alone is valid**: `rating` is 0–5 (0 = unrated, so a stars-only submission needs 1–5); `review_incomplete` fires only when both are missing. `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
 
 **Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
-**Errors:** `404 not_found`, `400 email_required|review_incomplete|invalid_rating`.
+**Errors:** `404 not_found`, `400 email_required|review_incomplete` (neither text nor stars)`|invalid_rating`.
 
 ---
 

package/skills/commerce/install/01-install.md

@@ -1,10 +1,9 @@
 ---
 stage: install/01
 read_when: "The commerce kit's files were just copied into the app, or you are installing it now."
-skip_when: "src/App.jsx already declares the admin's screens as literal <Route> JSX under a /store-admin layout route, and / routes somewhere real."
+skip_when: "The admin already mounts at /store-admin/* behind the shipped AuthGuard and / routes somewhere real."
 forget_when: "The checklist at the bottom of this file passes (admin mounts, / routes somewhere real, /order-received exists)."
 carry_forward:
-  - "The admin's six picker-visible routes are literal <Route> JSX in src/App.jsx (the platform discovers pages by reading that file — an array or a .map() discovers nothing); the rest run off its <Route path=\"*\" element={<AdminRoutes />} />."
   - "Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them."
   - "/order-received must exist as a route: every payment link returns there, and confirming is what marks an order paid."
   - "The storefront header shows a visible \"Store manager\" link to /store-admin when the signed-in user's role is admin, and nothing for everyone else."
@@ -42,33 +41,18 @@ Image generation is the slowest step and nothing depends on it until seed time;
 
 The only dependency edges are *image URLs → seed payload* and *seed done → real products on the pages*.
 
-## Mount the admin
-
-The admin mounts as a **layout route in the app's own `src/App.jsx`**: the six screens the store owner opens from the builder are declared there as literal `<Route>` JSX, and everything deeper goes to `<AdminRoutes />` on a splat. The platform discovers an app's pages by reading that file — a screen declared anywhere else is unreachable from the page picker.
+## Mount the admin router
 
 ```jsx
-import AdminApp, { AdminRoutes } from "@/commerce/admin";
-import Dashboard from "@/commerce/admin/pages/Dashboard";   // …and orders/OrdersList,
-// products/ProductsList, customers/CustomersList, coupons/CouponsList, reports/Reports
-
-{/* Literal JSX — the platform reads this file, it never runs it. Do not refactor into a map. */}
-<Route path="/store-admin" element={<AdminApp />}>
-  <Route index            element={<Dashboard />} />
-  <Route path="orders"    element={<OrdersList />} />
-  <Route path="products"  element={<ProductsList />} />
-  <Route path="customers" element={<CustomersList />} />
-  <Route path="coupons"   element={<CouponsList />} />
-  <Route path="reports"   element={<Reports />} />
-  <Route path="*"         element={<AdminRoutes />} />   {/* editors, settings, webhooks */}
-</Route>
+import AdminApp from "@/commerce/admin";
+import { Navigate } from "react-router-dom";
+
+<Route path="/store-admin/*" element={<AdminApp />} />
 <Route path="/" element={<Navigate to="/store-admin" replace />} />   {/* until a storefront exists */}
 <Route path="/order-received" element={<OrderReceived />} />          {/* mandatory — see below */}
 ```
 
-- **Those seven lines, as they are.** The splat is what keeps the app's listed pages to six instead of 26: `path="*"` is skipped, so the editors, settings tabs and webhook screens stay navigable without appearing there, and `<AdminRoutes />` still serves the admin's own 404.
-- **Don't add `settings` to the list** — it is a tabbed layout around a nested route, so it only renders correctly from the splat.
-- **Elsewhere than `/store-admin`**: change the layout route's path and pass the prefix — `<AdminApp basePath="/backoffice" />`; the children are unchanged.
-- **Name the group** in `base44/ui.jsonc` — app-owned, so edit it in place, keep any other keys, never recreate a deleted one: `{ "version": 1, "sections": [{ "path": "/store-admin/*", "name": "Store Management" }] }`
+- **The `/*` splat is required** — without it every nested admin link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` (prefix without the splat).
 - **Give `/` something** — a blank app has no `/` route, and "page not found" at the app's own URL reads like a broken install.
 - **Link the admin from the storefront header** — otherwise the merchant has no way in but typing the URL. Resolve the signed-in user once (`base44.auth.me()`, rejection/no session = not an admin, never blocking the page) and render a plainly visible "Store manager" link to `/store-admin` in the header when `role === "admin"` — and nothing at all for everyone else.
 - **`/order-received` is mandatory**, even offline-only: every payment link returns there, and confirming is what marks an order paid — without it a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()` ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General (`general.order_received_path`).
@@ -85,7 +69,7 @@ Storefront functions are public on purpose (per-action verification, above). To
 
 ## Done — forget this file
 
-- [ ] The `/store-admin` layout route is in `src/App.jsx` with its six literal `<Route>` screens and the `path="*"` → `<AdminRoutes />` splat; `base44/ui.jsonc` names the section; the three enforcement layers untouched.
+- [ ] `/store-admin/*` mounted with the splat, behind the shipped `AuthGuard`; the three enforcement layers untouched.
 - [ ] `/` routes somewhere real; `/order-received` is a route.
 - [ ] The storefront header shows a visible `/store-admin` link to signed-in admins, and to nobody else.
 - [ ] Anonymous function invocation is allowed in the app's settings.

package/skills/commerce/install/02-storefront.md

@@ -48,7 +48,7 @@ import AdminApp from "@/commerce/admin";
       <Route path="/product/:slug" element={<ProductPage />} />
       {/* /bag, /checkout, and /order-received — which is mandatory */}
     </Route>
-    <Route path="/store-admin" element={<AdminApp />}>…</Route>   {/* own chrome, outside the provider */}
+    <Route path="/store-admin/*" element={<AdminApp />} />   {/* own chrome, outside the provider */}
   </Routes>
 </BrowserRouter>
 
@@ -116,7 +116,7 @@ import { useProductList, useCategories, useStoreInfo, useFormatMoney, productPri
 
 ⚑ **Render paging whenever `hasNext` is true** — `{list.hasNext && <button type="button" onClick={list.next} disabled={list.busy}>…</button>}` (append mode: `list.loadMore`); a page that renders nothing for paging ships a catalog silently capped at `per_page`. Drive filters from `useCategories()`/`useRibbons()` data via `setParams`, never from hardcoded names — a renamed ribbon must not strand a dead button.
 
-A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design and not an order to render in. An even grid of identical cards, each carrying the same name/price/stars trio, is where a generated store lands by default and almost never where this catalog belongs: give the grid a rhythm (a hero piece spanning two columns, an editorial break between rows, a denser tile for a large catalog), and lead each card with the one or two fields *these* products are judged on — carat weight, focal length, edition size, ABV — read off `productSpecs(row)`, not the fields every store shows.
+A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design and not an order to render in. An even grid of identical cards, each carrying the same name/price/stars trio, is where a generated store lands by default and almost never where this catalog belongs: give the grid a rhythm (a hero piece spanning two columns, an editorial break between rows, a denser tile for a large catalog), and lead each card with the one or two fields *these* products are judged on — carat weight, focal length, ABV — read off `productSpecs(row)`.
 
 ⚑ **Ribbons belong in both views** — grid and product page. They are the merchant's own merchandising ("Limited", "Last pieces"), and each links to its filtered listing (`/collection?ribbon_id=<id>`). `productRibbons(row)` hands you `{id, name}` **objects** — render `r.name`, key the link on `r.id`; the entry itself in JSX is React's "Objects are not valid as a React child". Never render a bare "Ribbons:" label with nothing after it. ⚑ **A ribbon link inside a card that is itself a link nests `<a>` in `<a>`** — invalid, React warns. In the grid use plain labels, or link the image and title rather than the whole card; keep ribbon links on the product page.
 
@@ -156,9 +156,13 @@ Build your layout from — all optional, **not one component style**:
 - **Variant selector** — `variantAxes(view, p.pick)`, one entry per axis:
 
   ```jsx
+  const SWATCH = { Ivory: "#F2EDE4", "Obsidian Black": "#101014" };   // this catalog's colour names → CSS
   {variantAxes(view, p.pick).map((axis) => (
     <fieldset key={axis.key}>{/* label from axis.name / axis.selectedOption */}
-      {axis.options.map((o) => (
+      {axis.options.map((o) => /colou?r/i.test(axis.name) ? (
+        <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}
+                className="swatch" style={{ background: SWATCH[o.value] }} title={o.value} aria-label={o.value} />
+      ) : (
         <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}>
           {o.value}{/* o.outOfStock → mark visibly */}
         </button>
@@ -167,7 +171,7 @@ Build your layout from — all optional, **not one component style**:
   ))}
   ```
 
-  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. **Render each axis by what it is** — swatches for a colour axis, chips with a size guide beside a size axis; every axis as the identical chip row is a generated-page tell. That differentiation is semantic — what the control *shows* — built from your classes, not extra chrome around each row.
+  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. ⚑ **Pick the control per attribute, as the branch above does**: a colour axis as colour circles (the name stays reachable — `title`, `aria-label`, and the axis label showing `selectedOption`), size chips beside a size guide, a select for a long list; a specialty control where it genuinely fits, not on every axis — but every axis as the same bare chip row is the flattest page this kit produces. Any control keeps the contract: disabled, out-of-stock marked, selection visible.
 - **Buy box** — one button, and **you supply its four words**:
 
   ```jsx
@@ -190,7 +194,16 @@ Build your layout from — all optional, **not one component style**:
 
   ⚑ **Never `.map()` the whole list into one grey label/value table** — that is the single most reliable tell of a generated product page. Design the two or three rows that carry *this* catalog's meaning as what they are (a weight set in the display face, a composition as bars, a provenance beside its place); let the rest fall through to the plain row, and don't feel obliged to keep them in one block — a spec can sit under the gallery, beside the price, or inside the description. Branch on `s.key` too where one particular modifier deserves its own treatment regardless of type. ⚑ **Look a spec up with `findSpec(rows, "care")`** (ignores case, spaces, `_`, `-`): meta keys are free text (`care`, `Care`, `Care Instructions`), so `rows.find(s => s.label === "Care")` silently never matches and renders the fallback forever. `[]` means no section at all.
 - **Breadcrumbs** — from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons (`productRibbons(product)`) are labels, not breadcrumbs.
-- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()`, open to guests. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
+- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). ⚑ **Both shapes are exact** — entity-style names (`content`, `reviewer_name`) throw on submit and render blank in the list:
+
+  ```jsx
+  const client = useStorefront();               // submitReview is a CLIENT METHOD, not a barrel export
+  p.reviews                                     // { items, page, per_page, has_next }
+  p.reviews.items[0]                            // { id, reviewer, review, rating, verified, created_date }
+  await client.submitReview({ product_id, review, rating, reviewer, email })   // NOT content/reviewer_name/reviewer_email
+  ```
+
+  Text or stars — either alone submits. ⚑ **The form renders for every visitor by default** (guests supply an email; hide it when signed in) — login-gate it only when the store asks. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every auto-approving store — and refresh the list after, or the review doesn't appear. Codes, policies, moderation: [`../references/reviews.md`](../references/reviews.md).
 - **Title** — give each page type its own `<title>` and description; a store whose every page shares one static title is invisible to search. Nothing here emits structured data either — if the store wants rich results, emit your own `Product`/`Offer` JSON-LD from `product` and `view.display` (price, currency, availability).
 
 ## Cart / bag
@@ -249,9 +262,9 @@ import { CheckoutProvider, useCheckoutContext, AddressFields, ShippingMethodPick
 
 `useCheckout` reprices shipping/tax from the address automatically (debounced, never on a half-typed address), derives the shipping and payment choices, gates the button, and `placeOrder()` handles **both** navigations — online gateway → provider redirect, everything else → `/order-received` — as **full page loads** (`<CheckoutProvider options={{ orderReceivedPath: null }}>` for a router transition instead). `CheckoutProvider` shares it across the page's regions.
 
-⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected". Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
+⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected". ⚑ Picks are instant: both pickers reflect a click immediately (shipping optimistically), and `mustChoose` stays true after a choice — the radios keep rendering, still changeable; never disable options while `syncing`/`choosing` (the hint covers it). Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
 
-⚑ **A disabled place-order button must say why** — the silent disabled button is the most common checkout dead end. `blockers` is an array of codes; write one line per code, in the store's voice, anchored near the field that fixes it: `empty_cart` (bag is empty) · `billing_incomplete` (required address fields — `missingBillingFields` names them) · `shipping_address_incomplete` (the separate delivery address) · `shipping_address_required` (no address to price yet) · `shipping_method_required` (choose a delivery option) · `shipping_not_available` (this address can't be delivered to) · `payment_method_required` (choose how to pay) · `cart_loading` / `shipping_recalculating` (transient — a quiet "one moment", not an error).
+⚑ **A disabled place-order button must say why** — the silent disabled button is the most common checkout dead end. `blockers` is an array of codes; write one line per code, in the store's voice, anchored near the field that fixes it: `empty_cart` · `billing_incomplete` (required address fields — `missingBillingFields` names them) · `shipping_address_incomplete` (the separate delivery address) · `shipping_address_required` (no address to price yet) · `shipping_method_required` (choose a delivery option) · `shipping_not_available` (can't deliver there) · `payment_method_required` · `cart_loading` / `shipping_recalculating` (transient — a quiet "one moment", not an error).
 
 The pickers' `hint.code` works the same way (`missing_address`, `none_available`, `syncing` for shipping; `none_available` for payment): write those words once, and prefer `hint.serverMessage` when it is set — the backend's explanation is more specific than anything you can write.
 
@@ -282,7 +295,7 @@ function CheckoutForm() {
                 {m.title} {m.costLabel}
               </label>
             ))}
-            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
+            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}{/* the lone option */}
           </fieldset>
         )}
       </ShippingMethodPicker>
@@ -304,7 +317,7 @@ function CheckoutForm() {
 
 **`<AddressFields>` is the one shipped component — use it, never hand-roll the address form.** It owns what hand-rolled forms get wrong: the state/province field appears with the right options once a country is picked (shipping rates and taxes match on country *plus* state, so a form without it mis-prices US/CA/AU orders with no error anywhere), every field keeps its `autoComplete` token (what makes browser autofill work), required marks arm on first blur, and the server's "we don't ship there" lands on the country field. `which="shipping"` renders null until `shipToDifferent` is on — the deliver-elsewhere checkbox itself is yours, wired to `c.shipToDifferent` / `c.setShipToDifferent`.
 
-It ships **no CSS** bar a `max-width:100%` cap on the selects (an unstyled checkout must not scroll sideways): every element carries `data-part` (`address-fields`, `field`, `label`, `control`, `required`, `error`) plus `data-key` (the field) and `data-span` (1 or 2 — the field's natural width in a two-column grid), so style it in your `index.css` via `[data-part]` selectors or pass `className`/`classes={{ field, label, control, error }}`. ⚑ **`data-part` sits on the element, not a wrapper** — `select[data-part="control"]`, never `[data-part="control"] input`: the descendant form matches nothing and ships the form unstyled. Props: `includeCompany` (default false), `includePhone` (default true), `omit={["…"]}`, `labels={{ postcode: "ZIP code" }}` (over `addressFieldSpec`'s plain-convention defaults), `selectPlaceholder`, and two escape hatches — `inputRender` swaps the control only (spread the handed `dom` props onto your input), `fieldRender` replaces the whole labeled block. `c.missingBillingFields` stays the live list of what is still missing, if you want your own per-field marks.
+It ships **no CSS** bar a `max-width:100%` cap on the selects (an unstyled checkout must not scroll sideways): every element carries `data-part` (`address-fields`, `field`, `label`, `control`, `required`, `error`) plus `data-key` (the field) and `data-span` (1 or 2 — the field's natural width in a two-column grid), so style it in your `index.css` via `[data-part]` selectors or pass `className`/`classes={{ field, label, control, error }}`. ⚑ **`data-part` sits on the element, not a wrapper** — `select[data-part="control"]`, never `[data-part="control"] input`: the descendant form matches nothing and ships the form unstyled. Props: `includeCompany` (false), `includePhone` (true), `omit={["…"]}`, `labels={{ postcode: "ZIP code" }}`, `selectPlaceholder`, and two escape hatches — `inputRender` swaps the control only (spread the handed `dom` props onto your input), `fieldRender` replaces the whole labeled block. `c.missingBillingFields` stays the live list of what is missing, for your own per-field marks.
 
 ⚑ **The `stage === "submitted"` guard goes above the empty-cart branch** — placing an order clears the cart before the browser navigates, and without the guard the page flashes an empty bag over a just-placed order.
 

package/skills/commerce/references/admin-localization.md

@@ -0,0 +1,95 @@
+---
+stage: reference
+read_when: "The admin must run in a language OUTSIDE the six that ship (en/de/es/fr/ja/pt), or you are adding new admin UI text that has to localize."
+skip_when: "The admin stays in English (nothing to do) — or it runs in German, Spanish, French, Japanese or Portuguese, which is one import line in src/commerce/admin/i18n/index.js and needs nothing from this file. Also skip for storefront copy (the storefront ships none — write it directly in the store's language) and for transactional emails (backend templates — references/emails.md)."
+forget_when: "The language is switched or the locale file is written, and the admin renders in it."
+carry_forward:
+  - "Admin language = one import line in src/commerce/admin/i18n/index.js; no runtime picker, no npm package."
+  - "New locale file = copy of locales/en.js with every value translated and {placeholders} kept verbatim; missing keys fall back to English."
+---
+
+# Admin localization
+
+> **You probably don't need this file.** English is the default — nothing to
+> do. German, Spanish, French, Japanese and Portuguese ship complete: repoint
+> one import in `src/commerce/admin/i18n/index.js` and you are done. This file
+> is for a **seventh** language, or for adding new admin text. In no case do
+> you read or rewrite the admin's screens — the language never lives there.
+
+The Store Management UI (`src/commerce/admin/`) renders every user-visible
+string through `t()` from `src/commerce/admin/i18n/index.js`. The wording
+lives in flat message catalogs at `src/commerce/admin/i18n/locales/<lang>.js`.
+Shipped complete: `en` (default + fallback), `de`, `es`, `fr`, `ja`, `pt`.
+
+It is all plain JavaScript inside the plugin — **no i18n npm package, nothing
+to install**. Dates (`lib/format.js`), money (`hooks/useMoney.js`) and
+country/currency display names (`Intl.DisplayNames`) format from the same
+locale automatically; `lib/geo-data.js` keeps English state/province names
+(proper nouns, mirrored from backend data) — do not translate that file.
+
+## Scope — what this does and does not cover
+
+- **Covers:** every admin screen — navigation, tables, editors, settings,
+  dialogs, toasts, the first-run setup screen, enum labels
+  (`lib/constants.js` reads its labels from the catalog).
+- **Does not cover:** the storefront (headless — it ships no copy; write your
+  storefront's copy directly in the store's language) and transactional
+  emails (backend templates — `references/emails.md`). The StoreAdmin bot's
+  UI chrome is localized; the bot's *answers* come from the agent and follow
+  the language the admin types in.
+
+## Switch the admin to a shipped language
+
+Edit **one line** in `src/commerce/admin/i18n/index.js` — repoint the
+`active` import:
+
+```js
+import en from "./locales/en.js";
+import active from "./locales/de.js"; // was "./locales/en.js" — admin now renders in German
+```
+
+Leave the `en` import alone: it is the fallback for any key a locale misses.
+There is deliberately no language picker in the UI — a store's back office
+runs in one language, chosen in code. If the plugin is ever re-copied by an
+update, re-apply this one-line edit.
+
+## Add a language that is not shipped
+
+1. Copy `src/commerce/admin/i18n/locales/en.js` to
+   `src/commerce/admin/i18n/locales/<code>.js` (e.g. `it.js`, `nl.js`,
+   `pt-BR.js`).
+2. Set its `$locale` to the language's BCP-47 tag (e.g. `"it"`, `"pt-BR"`) —
+   this drives `Intl` date/number/name formatting, not just messages.
+3. Translate **every value**; never change a key. Keep `{placeholders}`
+   verbatim — they are interpolated by name (`{count}`, `{email}`, `{page}`).
+   Keep the tone consistent with the shipped files (formal register: German
+   "Sie", Japanese です/ます).
+4. Point the `active` import in `i18n/index.js` at the new file (step above).
+
+A partial file is safe: any key the file misses renders in English rather
+than breaking, so translate-verify-iterate works. Your new locale file is not
+part of the published package, so plugin updates won't overwrite it — only
+the one-line import needs re-applying.
+
+## Adding new admin UI text
+
+Never hard-code a user-visible string in an admin component. Render it as
+`t("area.slug")` (import `{ t }` from the admin's `i18n/`, relative path) and
+add the key to `locales/en.js`, namespaced by admin area
+(`orders.`, `products.`, `settings.`, … — shared vocabulary lives under
+`common.`). Then add the same key to every shipped locale file; if you skip
+one, that language shows the English text for that key. Interpolation:
+`t("orders.n_deleted", { count })` with catalog value `"{count} order(s)
+deleted"`.
+
+Keep the locale files structurally identical — same keys in every file. A
+quick parity check:
+
+```bash
+node --input-type=module -e '
+import { readdirSync } from "node:fs";
+const dir = new URL(`file://${process.cwd()}/src/commerce/admin/i18n/locales/`);
+const keys = async (f) => Object.keys((await import(new URL(f, dir))).default).sort().join("\n");
+const base = await keys("en.js");
+for (const f of readdirSync(dir)) console.log(f, (await keys(f)) === base ? "ok" : "KEY MISMATCH");'
+```

package/skills/commerce/references/catalog-rendering.md

@@ -93,7 +93,7 @@ Both lists are inventories of what the data supports — **not a layout and not
 
 **Card:** image, name, `price.label`, a sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `productSpecs`). Link the whole card through; the layout is yours.
 
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, upsells/cross-sells. All but the markup is handed to you: `productImages(product)` + your own active index, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `p.reviews` (+ `submitReview` off `useStorefront()`), and `p.upsells`/`p.crossSells` — added with `useCart().addItem`, matching "already in cart" by product id.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, upsells/cross-sells. All but the markup is handed to you: `productImages(product)` + your own active index, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `p.reviews` (+ `useStorefront().submitReview`), and `p.upsells`/`p.crossSells` — added with `useCart().addItem`, matching "already in cart" by product id.
 
 **Attributes and modifiers are individually designable.** `productSpecs(product)` rows are `{key, label, titleLabel, value}` plus an inferred `type` — `"numeric"` / `"duration"` (with `number` and `unit` split out), `"location"`, `"list"` (with `items`), `"text"` — so the rendering branch is already made for you: a weight can be a figure, a composition bars, a provenance a place. ⚑ **Never `.map()` the whole list into one grey label/value table**; design the two or three rows this catalog is judged on and let the rest fall through to a plain row. ⚑ **Look a row up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`: meta keys are free text typed per product (`care`, `Care`, `Care Instructions`), so an equality test on `label` — or on one spelling of `key` — silently never fires and the feature renders its fallback forever; `titleLabel` is the display-cased form, for a heading. What a row *looks* like is a per-catalog design decision — not one uniform chip row per axis and one grey table ([`../install/02-storefront.md`](../install/02-storefront.md)); §5's rules govern selector *behaviour*, never its form.
 

package/skills/commerce/references/reviews.md

@@ -5,6 +5,7 @@ skip_when: "The product page already renders `p.reviews` and submits through `su
 forget_when: "A review submits, appears (or is held) as the store's auto-approve setting dictates, and the aggregate rating renders."
 carry_forward:
   - "Reviews are part of the happy path: the list arrives with the product, submitting is one client call. The confirmation copy must come from the submit response's `status`, never hardcoded."
+  - "The review form renders for every visitor by default — guests included, with an email field. Login-gating is an explicit store request, implemented as one conditional around the form."
 ---
 
 # Reviews
@@ -16,7 +17,7 @@ Reviews are **part of the happy path**, not an extra: the backend always shipped
 Both live on the storefront client in `@/commerce/utils` — in React, `useStorefront()` is that client:
 
 - **`getProductReviews(slugOrRef, { page, per_page })`** → `{ items, page, per_page, has_next, average_rating, rating_count }`. The same reviews `get-product` returns — page or refresh the list without re-fetching the page; `useProduct(slug, { reviewsPerPage })` sizes the first one.
-- **`submitReview({ product_id, review, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. `review` is the body text and is required; `rating` is optional, **0–5**; `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
+- **`useStorefront().submitReview({ product_id, review?, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. ⚑ **A client method, never a barrel export** — importing the name itself from `@/commerce/storefront` throws `does not provide an export named …` and the whole app renders blank. **Text or stars — at least one**: `review` is the body text, `rating` is **1–5 stars** (0 counts as unrated); stars-only and text-only are both valid, only both missing rejects. `reviewer` is the display name. ⚑ **One set of names, both directions** — the payload above, rows back as `{ id, reviewer, review, rating, verified, created_date }`. Not the entity's columns: a near-miss (`content`, `reviewer_name`, `reviewer_email`, …) throws client-side rather than being aliased, since the same wrong names would render the list blank too. It **rejects** with `email_required` | `review_incomplete` (neither text nor stars) | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
 
 ## What ships
 
@@ -25,17 +26,17 @@ Both live on the storefront client in `@/commerce/utils` — in React, `useStore
 - `storefront-account` `my-reviews` lists a signed-in customer's own — what a "My reviews" account tab renders from;
 - moderation is in the admin (Products → Reviews); `commerce/admin-reviews` recalculates the product's rating on every status change.
 
-## The policy is the store's
+## The policy is the store's — and open is the default
 
-Which visitors may submit is a gate **you** render, in your own words. The three patterns worth knowing:
+Which visitors may submit is a gate **you** render, in your own words — and **the default is no gate at all**. Build the form for every visitor, signed in or not (that is the server's own rule); a review form a guest cannot use is a policy the store has to ask for, never something to add on your own initiative. The two stricter patterns are each one small change away when the store does ask:
 
 | Policy | Who may submit | How you implement it |
 |---|---|---|
-| **Open** (the server's own rule) | anyone with a valid email | render the form for everyone; the email field is required for guests |
-| **Login-gated** | a signed-in visitor only | render the form only when your app has a user; otherwise your "sign in to review" line |
+| **Open — the default** | anyone with a valid email | render the form for everyone; the email field is required for guests, hidden when signed in |
+| **Login-gated** | a signed-in visitor only | one conditional around the same form: render it when your app has a user, otherwise your "sign in to review" line |
 | **Verified buyers** | someone whose own orders include a `processing`/`completed` order for this product | check `storefront-account` `my-orders` for the product, gate on the result |
 
-Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side), and make the stars mandatory by validating before you call. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
+Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side). The server needs only one of text/stars — if your form makes either (or both) mandatory, validate before you call, so the customer meets your words rather than a raw 400. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
 
 ## Auto-approval and moderation
 

package/src/commerce/admin/README.md

@@ -25,20 +25,12 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    npx npq install <only the missing names>   # npq audits the package before npm installs it
    ```
 
-4. Mount it as a layout route in the app's own `src/App.jsx` — that is the file
-   Base44 discovers an app's pages from, so the screens that should be listed as
-   pages are declared there literally, and the rest go to `<AdminRoutes />` on a
-   splat. The full step is the skill's `install/01-install.md`.
+4. Mount the app in your router:
 
    ```jsx
-   import AdminApp, { AdminRoutes } from "@/commerce/admin";
-
-   <Route path="/store-admin" element={<AdminApp />}>
-     <Route index element={<Dashboard />} />
-     <Route path="orders" element={<OrdersList />} />
-     {/* …products, customers, coupons, reports… */}
-     <Route path="*" element={<AdminRoutes />} />
-   </Route>
+   import AdminApp from "@/commerce/admin";
+
+   <Route path="/store-admin/*" element={<AdminApp />} />
    // mounted elsewhere? → <AdminApp basePath="/backoffice" />
    ```
 
@@ -83,17 +75,47 @@ npx shadcn@latest add <component>
 ## Layout of this folder
 
 ```
-index.jsx        AdminApp: providers → auth guard → layout → <Outlet/>
-routes.jsx       Route table + <AdminRoutes/> (the splat handler App.jsx delegates to)
+index.jsx        AdminApp: providers → auth guard → layout → routes
+routes.jsx       Route table + <AdminRoutes/>
 layout/          AdminLayout, Sidebar, Topbar, AuthGuard (admin-role gate), AccessDenied
 bot/             StoreAdminBot (chat panel over the commerce/StoreAdmin agent), Markdown (GFM renderer)
 context/         SettingsContext (store settings + first-run seeding), BasePathContext
 hooks/           useAsync, usePagedList, useRealtime (live updates), useMoney, useDebounce
+i18n/            t() + locale; locales/ = en (default), de, es, fr, ja, pt
 lib/             api (function calls), constants, format, geo-data, order/product utils
 components/      DataTable, SearchSelect, MoneyInput, DateRangePicker, AddressForm, …
 pages/           All admin pages (orders, products, coupons, customers, reports, settings, webhooks)
 ```
 
+## Localization
+
+Every user-visible string renders through `t()` from `i18n/`; the wording
+lives in `i18n/locales/<lang>.js`. English (`en`) is the default and the
+fallback; `de`, `es`, `fr`, `ja` and `pt` ship complete. Dates, money and
+country/currency names follow the same locale via the browser's `Intl` —
+no i18n package is involved anywhere.
+
+**Switch language** — edit one line in `i18n/index.js`:
+
+```js
+import active from "./locales/en.js"; // ← point at "./locales/de.js" for German
+```
+
+There is deliberately no runtime picker: a store's back office runs in one
+language. (Re-apply this one-line edit if a plugin update re-copies this
+folder.)
+
+**Add a language** — copy `i18n/locales/en.js` to `i18n/locales/<code>.js`,
+set its `$locale` to the BCP-47 tag, translate every value keeping
+`{placeholders}` verbatim, then point the `active` import at the new file.
+Missing keys fall back to English, so a partial file renders mixed rather
+than broken.
+
+**Adding admin UI text?** Render it as `t("area.slug")`, add the key to
+`i18n/locales/en.js`, and translate it in each shipped locale (or leave it —
+it falls back to English). Full recipe for agents: the commerce skill's
+`references/admin-localization.md`.
+
 ## Live-updating views
 
 The dashboard, the orders list and the reports tabs refresh themselves — a new