create-brainerce-store 1.66.0 → 1.68.0

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.66.0",
+      version: "1.68.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.66.0",
+  "version": "1.68.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"

package/templates/nextjs/base/.env.local.ejs

@@ -1,24 +1,52 @@
-# Brainerce Sales Channel — preferred env var name.
-NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID=<%= connectionId %>
-# Legacy alias kept for backwards compatibility — both are accepted by the SDK.
-# @deprecated will be removed when SDK 2.0 ships.
-NEXT_PUBLIC_BRAINERCE_CONNECTION_ID=<%= connectionId %>
-
-# Store info (pre-fetched during setup to avoid flash on first load)
-NEXT_PUBLIC_STORE_NAME=<%- storeNameEnv %>
-NEXT_PUBLIC_STORE_CURRENCY=<%- currencyEnv %>
-
-# Backend API URL (server-side only — used by BFF proxy and SSR, never exposed to browser)
-BRAINERCE_API_URL=<%- apiBaseUrlEnv %>
-
-# Public API origin for the AI chat widget (public, unauthenticated endpoints only).
-# The widget streams chat directly from the browser, so this one IS public.
-NEXT_PUBLIC_BRAINERCE_API_URL=<%- apiBaseUrlEnv %>
-
-# Public site URL — used for sitemap, robots.txt, and SEO metadata
-NEXT_PUBLIC_SITE_URL=http://localhost:3000
-
-# Optional: floating WhatsApp contact button (used by some designs, e.g.
-# passepartout). Digits only, international format without "+"
-# (e.g. 14155550123). Leave unset to hide the button.
-# NEXT_PUBLIC_WHATSAPP_PHONE=
+# Brainerce Sales Channel — preferred env var name.
+NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID=<%= connectionId %>
+# Legacy alias kept for backwards compatibility — both are accepted by the SDK.
+# @deprecated will be removed when SDK 2.0 ships.
+NEXT_PUBLIC_BRAINERCE_CONNECTION_ID=<%= connectionId %>
+
+# Store info (pre-fetched during setup to avoid flash on first load)
+NEXT_PUBLIC_STORE_NAME=<%- storeNameEnv %>
+NEXT_PUBLIC_STORE_CURRENCY=<%- currencyEnv %>
+
+# Backend API URL (server-side only — used by BFF proxy and SSR, never exposed to browser)
+BRAINERCE_API_URL=<%- apiBaseUrlEnv %>
+
+# Public API origin for the AI chat widget (public, unauthenticated endpoints only).
+# The widget streams chat directly from the browser, so this one IS public.
+NEXT_PUBLIC_BRAINERCE_API_URL=<%- apiBaseUrlEnv %>
+
+# Public site URL — canonical tags, sitemap.xml, robots.txt, JSON-LD, and the
+# Origin header the Brainerce backend checks against your sales channel's
+# configured domain.
+#
+# Intentionally unset. Nothing at setup time knows where this store will be
+# served from, so the storefront resolves its own origin at runtime: hosting
+# platform variables first (Vercel / Netlify / Render / Railway / Cloudflare
+# Pages), then the incoming request's forwarded host. It is correct in local
+# development and on any host, with nothing set here.
+#
+# ⛔ Do not write a placeholder address into this variable. A wrong absolute
+# URL is indistinguishable from a right one to a search crawler, so a guess
+# here is worse than leaving it empty. Either set your real domain or nothing.
+#
+# Once you have that domain, set it — an explicit value is the only source a
+# request header cannot forge, and it keeps canonical URLs stable across
+# preview deployments:
+#
+#   SITE_URL=https://shop.example.com
+#
+# Set it in your hosting provider's environment variables, not in this file:
+# .env.local is gitignored and never travels with a deploy.
+# `NEXT_PUBLIC_SITE_URL` is still read as a backwards-compatible alias.
+#
+# On some hosts SITE_URL is NOT optional. Platforms whose proxy forwards
+# requests to the app as `Host: localhost:<port>` (OpenAI Sites /
+# *.chatgpt.site, among others) hide the real hostname from the server, so
+# nothing can be resolved from the request. Set SITE_URL there, or server-side
+# API calls send `Origin: http://localhost:3000` and a sales channel with a
+# configured Domain rejects them with 403.
+
+# Optional: floating WhatsApp contact button (used by some designs, e.g.
+# passepartout). Digits only, international format without "+"
+# (e.g. 14155550123). Leave unset to hide the button.
+# NEXT_PUBLIC_WHATSAPP_PHONE=

package/templates/nextjs/base/.eslintrc.json

@@ -1,57 +1,51 @@
-{
-  "extends": [
-    "next/core-web-vitals"
-  ],
-  "overrides": [
-    {
-      "files": [
-        "src/ui/**/*.{ts,tsx}"
-      ],
-      "rules": {
-        "no-restricted-imports": [
-          "error",
-          {
-            "patterns": [
-              {
-                "group": [
-                  "@/core/lib/*",
-                  "!@/core/lib/auth",
-                  "!@/core/lib/brainerce",
-                  "!@/core/lib/image-hosts",
-                  "!@/core/lib/navigation",
-                  "!@/core/lib/product-options",
-                  "!@/core/lib/sanitize",
-                  "!@/core/lib/sanitize-html",
-                  "!@/core/lib/translations",
-                  "!@/core/lib/use-currency",
-                  "!@/core/lib/utils"
-                ],
-                "message": "UI consumes data via @/core/hooks/* and @/core/providers/* — not core internals. (Approved presentation helpers are exempt.)"
-              }
-            ]
-          }
-        ]
-      }
-    },
-    {
-      "files": [
-        "src/core/**/*.{ts,tsx}"
-      ],
-      "rules": {
-        "no-restricted-imports": [
-          "error",
-          {
-            "patterns": [
-              {
-                "group": [
-                  "@/ui/*"
-                ],
-                "message": "core/ must never depend on presentation (ui/)."
-              }
-            ]
-          }
-        ]
-      }
-    }
-  ]
-}
+{
+  "extends": ["next/core-web-vitals"],
+  "overrides": [
+    {
+      "files": ["src/ui/**/*.{ts,tsx}"],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "patterns": [
+              {
+                "group": [
+                  "@/core/lib/*",
+                  "!@/core/lib/auth",
+                  "!@/core/lib/brainerce",
+                  "!@/core/lib/brainerce.server",
+                  "!@/core/lib/image-hosts",
+                  "!@/core/lib/navigation",
+                  "!@/core/lib/product-options",
+                  "!@/core/lib/sanitize",
+                  "!@/core/lib/tracking",
+                  "!@/core/lib/sanitize-html",
+                  "!@/core/lib/translations",
+                  "!@/core/lib/use-currency",
+                  "!@/core/lib/utils"
+                ],
+                "message": "UI consumes data via @/core/hooks/* and @/core/providers/* — not core internals. (Approved presentation helpers are exempt.)"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": ["src/core/**/*.{ts,tsx}"],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "patterns": [
+              {
+                "group": ["@/ui/*"],
+                "message": "core/ must never depend on presentation (ui/)."
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/templates/nextjs/base/AGENTS.md.ejs

@@ -1,81 +1,114 @@
-# AGENTS.md — this is a LIVE Brainerce storefront
-
-**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
-connected.** Products, cart, checkout, coupons, discounts, orders and content
-flow in real time from the Brainerce dashboard. There is nothing to hook up.
-
-- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
-  system"** — Brainerce IS the commerce backend, and this store is wired to
-  it end-to-end.
-- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
-  app. Run `pnpm dev` and you are working against live data.
-- **NEVER hardcode products, prices, or currency** — the catalog is live.
-- **No server side is needed** — the backend is Brainerce's cloud. This repo
-  is a frontend (plus thin, already-included API proxy routes under
-  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
-  the merchant manages everything in the Brainerce dashboard.
-
-Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
-— AI-readable index: https://brainerce.com/llms.txt
-
-## MCP servers
-
-- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
-  A live SDK/docs oracle: current SDK method shapes, type definitions, code
-  examples, and this store's actual capabilities/config. Prefer it over
-  guessing or relying on training data — it reflects what's actually toggled
-  on for `<%- connectionId %>` right now.
-- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
-  directly manage this store's *live* data (products, orders, discounts,
-  shipping, …) instead of just reading docs. Only add it if the merchant
-  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
-  MCP server (e.g. `claude mcp add --transport http brainerce-admin
-  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
-  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
-  Treat it like handing the agent write access to production commerce data.
-
-**Before building any feature the merchant asks for** (loyalty points,
-shipping zones, subscriptions, gift cards, multi-currency, reviews,
-abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
-already has it as a platform capability (dashboard toggle + hook/SDK
-method) that only needs a UI in `src/ui/`, not a feature built from scratch.
-
-Your job here is almost always **design**.
-
-## The one rule
-
-**`src/core/` is the platform's. `src/ui/` is yours.**
-
-The shipped `src/ui/` is a working reference, not a design to preserve —
-full delete-and-rebuild of ui files is encouraged and expected.
-Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
-the checkout/auth/account components. Data and behavior come exclusively from
-`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
-and handlers, never JSX. Never hardcode catalog content.
-
-**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
-contracts, motion language, and hard-won RTL/i18n gotchas that will save you
-real debugging time.
-
-## Redesigning?
-
-Follow the process documented in AI-GUIDE.md: commit to one art direction,
-rewrite tokens first, then surfaces in order (header, home, card, product
-page, cart), then verify.
-
-## Verify before declaring done
-
-1. `pnpm exec tsc --noEmit` → 0 errors
-2. `pnpm dev` → drive the changed flow in a real browser (home → product →
-   add to cart → cart)
-3. Screenshot desktop (1440px) and mobile (390px)
-4. RTL stores: check anchoring and arrow directions
-
-## i18n
-
-Every user-facing string goes through `useTranslations()` with keys in **all**
-files under `messages/`. The shipped copy is example boutique content — a
-starting point meant to be rewritten in the store's real voice. Hebrew: no
-uppercase transforms, no wide letter-spacing on headings, logical CSS
-properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).
+# AGENTS.md — this is a LIVE Brainerce storefront
+
+**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
+connected.** Products, cart, checkout, coupons, discounts, orders and content
+flow in real time from the Brainerce dashboard. There is nothing to hook up.
+
+- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
+  system"** — Brainerce IS the commerce backend, and this store is wired to
+  it end-to-end.
+- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
+  app. Run `pnpm dev` and you are working against live data.
+- **NEVER hardcode products, prices, or currency** — the catalog is live.
+- **No server side is needed** — the backend is Brainerce's cloud. This repo
+  is a frontend (plus thin, already-included API proxy routes under
+  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
+  the merchant manages everything in the Brainerce dashboard.
+
+Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
+— AI-readable index: https://brainerce.com/llms.txt
+
+## MCP servers
+
+- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
+  A live SDK/docs oracle: current SDK method shapes, type definitions, code
+  examples, and this store's actual capabilities/config. Prefer it over
+  guessing or relying on training data — it reflects what's actually toggled
+  on for `<%- connectionId %>` right now.
+- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
+  directly manage this store's *live* data (products, orders, discounts,
+  shipping, …) instead of just reading docs. Only add it if the merchant
+  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
+  MCP server (e.g. `claude mcp add --transport http brainerce-admin
+  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
+  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
+  Treat it like handing the agent write access to production commerce data.
+
+**Before building any feature the merchant asks for** (loyalty points,
+shipping zones, subscriptions, gift cards, multi-currency, reviews,
+abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
+already has it as a platform capability (dashboard toggle + hook/SDK
+method) that only needs a UI in `src/ui/`, not a feature built from scratch.
+
+Your job here is almost always **design**.
+
+## The one rule
+
+**`src/core/` is the platform's. `src/ui/` is yours.**
+
+The shipped `src/ui/` is a working reference, not a design to preserve —
+full delete-and-rebuild of ui files is encouraged and expected.
+Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
+the checkout/auth/account components. Data and behavior come exclusively from
+`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
+and handlers, never JSX. Never hardcode catalog content.
+
+**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
+contracts, motion language, and hard-won RTL/i18n gotchas that will save you
+real debugging time.
+
+## Redesigning?
+
+Follow the process documented in AI-GUIDE.md: commit to one art direction,
+rewrite tokens first, then surfaces in order (header, home, card, product
+page, cart), then verify.
+
+## The store's web address
+
+This project has no web address written into it, and that is deliberate — the
+scaffolder cannot know where you will deploy. `src/core/lib/site-url.ts`
+resolves it per request (hosting-platform variables, then the forwarded host),
+so canonical tags, `sitemap.xml`, `robots.txt` and JSON-LD are correct in local
+development and on any host with nothing configured.
+
+- **Never invent an address.** Do not write `NEXT_PUBLIC_SITE_URL`,
+  `SITE_URL`, `localhost`, or a placeholder domain into `.env.local`. A wrong
+  absolute URL is indistinguishable from a right one to a search crawler, so a
+  guess is worse than an empty value.
+- **Never hand-roll an origin** from `host` / `x-forwarded-proto` in a route
+  handler. Call `getCanonicalSiteUrl()` (for canonical/SEO URLs) or
+  `getRequestOrigin()` (for the `Origin` header sent to Brainerce). Hand-rolled
+  versions have shipped `http://` on HTTPS hosts and internal container
+  hostnames.
+- **Some hosts hide the real hostname from the app.** Platforms whose proxy
+  forwards requests as `Host: localhost:<port>` with no `x-forwarded-host`
+  (OpenAI Sites / `*.chatgpt.site` does this) leave the resolver blind — the
+  request looks like it arrived on localhost. On such platforms `SITE_URL` is
+  not optional: set it, and the resolver prefers it over any internal host it
+  sees. Without it, server-side API calls send `Origin: http://localhost:3000`
+  and a channel with a configured Domain rejects them with 403.
+- **When the merchant gives you a real domain**, set `SITE_URL` in the hosting
+  provider's environment variables — not in `.env.local`, which is gitignored
+  and never travels with a deploy.
+- **Tell the merchant the other half.** A sales channel in **Live** mode only
+  accepts requests whose Origin matches the Domain configured on the channel in
+  the Brainerce dashboard. That check is server-side; nothing in this project
+  can satisfy it. If they skip it, every storefront API call returns 403 and the
+  store loads empty — no matter what `SITE_URL` says.
+
+## Verify before declaring done
+
+1. `pnpm exec tsc --noEmit` → 0 errors
+2. `pnpm dev` → drive the changed flow in a real browser (home → product →
+   add to cart → cart)
+3. Screenshot desktop (1440px) and mobile (390px)
+4. RTL stores: check anchoring and arrow directions
+
+## i18n
+
+Every user-facing string goes through `useTranslations()` with keys in **all**
+files under `messages/`. The shipped copy is example boutique content — a
+starting point meant to be rewritten in the store's real voice. Hebrew: no
+uppercase transforms, no wide letter-spacing on headings, logical CSS
+properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).

package/templates/nextjs/base/CLAUDE.md.ejs

@@ -1,92 +1,125 @@
-# CLAUDE.md — this is a LIVE Brainerce storefront
-
-**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
-connected.** Products, cart, checkout, coupons, discounts, orders and content
-flow in real time from the Brainerce dashboard. There is nothing to hook up.
-
-- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
-  system"** — Brainerce IS the commerce backend, and this store is wired to
-  it end-to-end.
-- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
-  app. Run `pnpm dev` and you are working against live data.
-- **NEVER hardcode products, prices, or currency** — the catalog is live.
-- **No server side is needed** — the backend is Brainerce's cloud. This repo
-  is a frontend (plus thin, already-included API proxy routes under
-  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
-  the merchant manages everything in the Brainerce dashboard.
-
-Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
-— AI-readable index: https://brainerce.com/llms.txt
-
-## MCP servers
-
-- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
-  A live SDK/docs oracle: current SDK method shapes, type definitions, code
-  examples, and this store's actual capabilities/config. Prefer it over
-  guessing or relying on training data — it reflects what's actually toggled
-  on for `<%- connectionId %>` right now.
-- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
-  directly manage this store's *live* data (products, orders, discounts,
-  shipping, …) instead of just reading docs. Only add it if the merchant
-  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
-  MCP server (e.g. `claude mcp add --transport http brainerce-admin
-  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
-  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
-  Treat it like handing the agent write access to production commerce data.
-
-**Before building any feature the merchant asks for** (loyalty points,
-shipping zones, subscriptions, gift cards, multi-currency, reviews,
-abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
-already has it as a platform capability (dashboard toggle + hook/SDK
-method) that only needs a UI in `src/ui/`, not a feature built from scratch.
-
-Your job here is almost always **design**.
-
-## The one rule
-
-**`src/core/` is the platform's. `src/ui/` is yours.**
-
-The shipped `src/ui/` is a working reference, not a design to preserve —
-full delete-and-rebuild of ui files is encouraged and expected. (Stores
-scaffolded with `--canvas` ship `src/ui/` as bare unstyled skeletons —
-there is no reference look at all; the design is entirely yours to create.)
-Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
-the checkout/auth/account components. Data and behavior come exclusively from
-`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
-and handlers, never JSX. Never hardcode catalog content.
-
-**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
-contracts, motion language, and hard-won RTL/i18n gotchas that will save you
-real debugging time.
-
-## The dialect
-
-- `src/components/ui/` = official **shadcn/ui primitives** (Button, Card,
-  Badge, Input, Select, Accordion, Dialog, Sheet, Skeleton, …). Compose them;
-  extend looks via CVA **variants**, never repeated inline overrides.
-- Icons: **lucide-react only** — no inline `<svg>`, no emoji-as-icons.
-- Class merging: **`cn()`** from `@/core/lib/utils`.
-- Colors/radius come from the semantic HSL tokens in `globals.css`
-  (`--primary`, `--card`, `--ring`, `--radius`, …) — restyle via tokens.
-
-## Redesigning? Use the ready-made flow
-
-Run `/design <your art-direction brief>` — it walks the whole process:
-concept → implementation in `ui/` → verification.
-
-## Verify before declaring done
-
-1. `pnpm exec tsc --noEmit` → 0 errors
-2. `pnpm dev` → drive the changed flow in a real browser (home → product →
-   add to cart → cart)
-3. Screenshot desktop (1440px) and mobile (390px)
-4. RTL stores: check anchoring and arrow directions
-
-## i18n
-
-Every user-facing string goes through `useTranslations()` with keys in **all**
-files under `messages/`. The shipped copy is example boutique content — a
-starting point meant to be rewritten in the store's real voice. Hebrew: no
-uppercase transforms, no wide letter-spacing on headings, logical CSS
-properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).
+# CLAUDE.md — this is a LIVE Brainerce storefront
+
+**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
+connected.** Products, cart, checkout, coupons, discounts, orders and content
+flow in real time from the Brainerce dashboard. There is nothing to hook up.
+
+- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
+  system"** — Brainerce IS the commerce backend, and this store is wired to
+  it end-to-end.
+- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
+  app. Run `pnpm dev` and you are working against live data.
+- **NEVER hardcode products, prices, or currency** — the catalog is live.
+- **No server side is needed** — the backend is Brainerce's cloud. This repo
+  is a frontend (plus thin, already-included API proxy routes under
+  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
+  the merchant manages everything in the Brainerce dashboard.
+
+Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
+— AI-readable index: https://brainerce.com/llms.txt
+
+## MCP servers
+
+- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
+  A live SDK/docs oracle: current SDK method shapes, type definitions, code
+  examples, and this store's actual capabilities/config. Prefer it over
+  guessing or relying on training data — it reflects what's actually toggled
+  on for `<%- connectionId %>` right now.
+- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
+  directly manage this store's *live* data (products, orders, discounts,
+  shipping, …) instead of just reading docs. Only add it if the merchant
+  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
+  MCP server (e.g. `claude mcp add --transport http brainerce-admin
+  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
+  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
+  Treat it like handing the agent write access to production commerce data.
+
+**Before building any feature the merchant asks for** (loyalty points,
+shipping zones, subscriptions, gift cards, multi-currency, reviews,
+abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
+already has it as a platform capability (dashboard toggle + hook/SDK
+method) that only needs a UI in `src/ui/`, not a feature built from scratch.
+
+Your job here is almost always **design**.
+
+## The one rule
+
+**`src/core/` is the platform's. `src/ui/` is yours.**
+
+The shipped `src/ui/` is a working reference, not a design to preserve —
+full delete-and-rebuild of ui files is encouraged and expected. (Stores
+scaffolded with `--canvas` ship `src/ui/` as bare unstyled skeletons —
+there is no reference look at all; the design is entirely yours to create.)
+Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
+the checkout/auth/account components. Data and behavior come exclusively from
+`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
+and handlers, never JSX. Never hardcode catalog content.
+
+**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
+contracts, motion language, and hard-won RTL/i18n gotchas that will save you
+real debugging time.
+
+## The dialect
+
+- `src/components/ui/` = official **shadcn/ui primitives** (Button, Card,
+  Badge, Input, Select, Accordion, Dialog, Sheet, Skeleton, …). Compose them;
+  extend looks via CVA **variants**, never repeated inline overrides.
+- Icons: **lucide-react only** — no inline `<svg>`, no emoji-as-icons.
+- Class merging: **`cn()`** from `@/core/lib/utils`.
+- Colors/radius come from the semantic HSL tokens in `globals.css`
+  (`--primary`, `--card`, `--ring`, `--radius`, …) — restyle via tokens.
+
+## Redesigning? Use the ready-made flow
+
+Run `/design <your art-direction brief>` — it walks the whole process:
+concept → implementation in `ui/` → verification.
+
+## The store's web address
+
+This project has no web address written into it, and that is deliberate — the
+scaffolder cannot know where you will deploy. `src/core/lib/site-url.ts`
+resolves it per request (hosting-platform variables, then the forwarded host),
+so canonical tags, `sitemap.xml`, `robots.txt` and JSON-LD are correct in local
+development and on any host with nothing configured.
+
+- **Never invent an address.** Do not write `NEXT_PUBLIC_SITE_URL`,
+  `SITE_URL`, `localhost`, or a placeholder domain into `.env.local`. A wrong
+  absolute URL is indistinguishable from a right one to a search crawler, so a
+  guess is worse than an empty value.
+- **Never hand-roll an origin** from `host` / `x-forwarded-proto` in a route
+  handler. Call `getCanonicalSiteUrl()` (for canonical/SEO URLs) or
+  `getRequestOrigin()` (for the `Origin` header sent to Brainerce). Hand-rolled
+  versions have shipped `http://` on HTTPS hosts and internal container
+  hostnames.
+- **Some hosts hide the real hostname from the app.** Platforms whose proxy
+  forwards requests as `Host: localhost:<port>` with no `x-forwarded-host`
+  (OpenAI Sites / `*.chatgpt.site` does this) leave the resolver blind — the
+  request looks like it arrived on localhost. On such platforms `SITE_URL` is
+  not optional: set it, and the resolver prefers it over any internal host it
+  sees. Without it, server-side API calls send `Origin: http://localhost:3000`
+  and a channel with a configured Domain rejects them with 403.
+- **When the merchant gives you a real domain**, set `SITE_URL` in the hosting
+  provider's environment variables — not in `.env.local`, which is gitignored
+  and never travels with a deploy.
+- **Tell the merchant the other half.** A sales channel in **Live** mode only
+  accepts requests whose Origin matches the Domain configured on the channel in
+  the Brainerce dashboard. That check is server-side; nothing in this project
+  can satisfy it. If they skip it, every storefront API call returns 403 and the
+  store loads empty — no matter what `SITE_URL` says.
+
+## Verify before declaring done
+
+1. `pnpm exec tsc --noEmit` → 0 errors
+2. `pnpm dev` → drive the changed flow in a real browser (home → product →
+   add to cart → cart)
+3. Screenshot desktop (1440px) and mobile (390px)
+4. RTL stores: check anchoring and arrow directions
+
+## i18n
+
+Every user-facing string goes through `useTranslations()` with keys in **all**
+files under `messages/`. The shipped copy is example boutique content — a
+starting point meant to be rewritten in the store's real voice. Hebrew: no
+uppercase transforms, no wide letter-spacing on headings, logical CSS
+properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).