create-brainerce-store 1.88.0 → 1.89.0

package/templates/nextjs/base/AI-GUIDE.md

@@ -1,221 +1,259 @@
-# AI-GUIDE — designing this store safely
-
-You (an AI coding assistant, or a human designer) have been asked to redesign
-this storefront. This guide is the contract that lets you go as bold as you
-want without breaking commerce. It was distilled from real agency builds.
-
-## The one rule
-
-**`src/core/` is the platform's. `src/ui/` is yours.**
-
-Everything under `src/ui/` may be rewritten from scratch — layouts, markup,
-classes, animations, entire visual languages. (Canvas-mode stores —
-scaffolded with `--canvas` — ship `src/ui/` as bare unstyled skeletons with
-`DESIGN ME` markers; same rules apply, you're just starting from zero.) Everything under `src/core/`
-(and `src/app/api/`) keeps the store working: cart, checkout, variants,
-inventory, auth, SEO, i18n. Never modify it. If a redesign seems to require a
-core change, stop and say so instead.
-
-## File map
-
-| Path | Owner | Notes |
-|------|-------|-------|
-| `src/ui/layout/` | you | header, footer, announcement bar |
-| `src/ui/home/` | you | homepage sections |
-| `src/ui/product/` | you | card, grid, listing, product page, price, badges, selectors |
-| `src/ui/cart/` | you | cart page pieces |
-| `src/ui/shared/` | you | loader, image wrapper |
-| `src/app/globals.css` | you | tokens + global styles |
-| `src/components/ui/` | shared | shadcn/ui primitives — compose them, extend via variants |
-| `src/core/**` | platform | hooks, lib, providers — read, never edit |
-| `src/components/{checkout,auth,account,seo}` | platform | core-styled in v1; they inherit your tokens |
-| `src/app/**` | platform | thin routes; edit only to wire new ui components |
-
-## The dialect (shadcn/ui + lucide + cn)
-
-This store speaks the same component dialect as Lovable / v0 / Bolt output:
-
-- **`src/components/ui/` holds official shadcn/ui primitives** (button, card,
-  badge, input, label, textarea, select, checkbox, radio-group, separator,
-  accordion, dialog, sheet, skeleton, tabs, tooltip). Compose them in `src/ui/`
-  instead of hand-rolling controls. Need a new look? **Extend via CVA
-  variants** (add a variant to `buttonVariants`/`badgeVariants`), never by
-  inline-overriding the same styles in twenty call sites.
-- **Icons: lucide-react only.** No inline `<svg>` paths, no emoji-as-icons,
-  no second icon set. Consistent 16/20/24px sizes.
-- **Class merging: `cn()`** from `@/core/lib/utils` (clsx + tailwind-merge) —
-  it's the same helper shadcn expects, already wired into every primitive.
-- **Tokens drive everything**: primitives read `--primary`, `--card`,
-  `--input`, `--ring`, `--radius`, etc. from `globals.css`. Restyle the store
-  by changing tokens (and variants), not by scattering literal colors.
-- `rounded`, `rounded-md`, `rounded-lg` all derive from `--radius`
-  (shadcn convention), so corner radius follows the theme automatically.
-
-## The hook contract (your data supply)
-
-UI components get *everything* from `@/core/hooks/*` and
-`@/core/providers/store-provider` — never from `@/core/lib` directly:
-
-- `useHomeData()` → `{ products, banners, loading }`
-- `useProductListing()` → products + filters/sort/facets/pagination + handlers
-- `useProductPage(product)` → variant/image selection, `priceInfo`, `inventory`,
-  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, `addToCartError`,
-  customization + modifier state and errors
-  - `addToCartError` is `'CART_FULL' | 'FAILED' | null`. **Render it, and render it
-    outside any `modifierGroups.length > 0` block** — a cart holds at most 50
-    distinct products and the 51st add is refused, so a design that drops this
-    leaves the shopper tapping a button that resets and adds nothing. Copy lives
-    in `productDetail.cartFull` / `productDetail.addToCartFailed`.
-  - Five more components hold the same message in their OWN local state, because
-    they add to the cart without this hook: `ui/product/product-card.tsx`,
-    `ui/product/frequently-bought-together.tsx`, `ui/cart/cart-bundle-offer.tsx`
-    (all three: `addError`), `app/checkout/page.tsx` (`bumpError`) and
-    `ui/cart/cart-upgrade-banner.tsx` (`upgradeError`). All five use
-    `toAddToCartError()` from `@/core/lib/add-to-cart-error`. **Nothing checks that
-    you kept them** — `check-template-parity.js` compares `@/ui/...` imports and SDK
-    calls only, so dropping one of these leaves a green build and a silent button.
-  - `ui/cart/cart-item.tsx` carries the same idea for the two writes it owns,
-    in its own `lineError` state: a failed quantity change or a failed Remove
-    used to log to the console and leave the row looking untouched. It uses
-    `getErrorCode()` from the same file (not `toAddToCartError()` — the 50-line
-    cap cannot refuse a quantity change, and "we could not add this" would be a
-    lie about a removal) and four `cart.*` strings, mapped in `LINE_ERROR_KEYS`:
-    `notEnoughStock`, `itemUnavailable`, `quantityUpdateFailed`, `removeFailed`.
-    The first two are for refusals a retry can never clear, so do not collapse
-    them into the generic one. Nothing checks that you kept any of this either.
-  - `ui/cart/cart-upgrade-banner.tsx` additionally swaps one cart line for
-    another, and the ORDER of its two SDK calls is a correctness property, not a
-    style choice: it **adds the upgrade first and removes the original second**,
-    so a failed add leaves the cart untouched instead of losing the shopper's
-    line. It also carries `upgradeAdded`, which stops a retry adding the upgrade
-    twice, and a third message, `cart.upgradeOriginalNotRemoved`, for the case
-    where the add landed and the removal did not. If you rebuild that component,
-    keep all three; the reasoning is in the JSDoc on `handleUpgrade`.
-- `useCartPage()` / `useCart()` → `{ cart, itemCount, totals, refreshCart }`
-
-Hooks return data and handlers, never JSX. All catalog content (names, prices,
-images, stock) comes from them — **never hardcode products**.
-
-## Verification loop (before you declare anything done)
-
-1. **Feature coverage.** Call `get-required-features` on the `brainerce-docs`
-   MCP server (wired by the scaffolder in `.mcp.json`, no setup) and confirm
-   every mandatory entry is still reachable. First step, not last: you were
-   invited to rewrite `src/ui/` from scratch, and a feature that lived only in
-   the shipped reference is gone now with nothing to notice it by. `tsc`
-   cannot see a missing feature, and these components render nothing while the
-   merchant has the feature off, so a deleted one and an idle one look the
-   same. `CLAUDE.md` lists the files people usually lose; the MCP tool is the
-   actual specification.
-2. `pnpm exec tsc --noEmit` → must be 0.
-3. `pnpm dev` → drive the real flow you changed: home → listing → product →
-   add to cart → cart → checkout page renders.
-4. Screenshot desktop (1440) AND mobile (390), in the store's language.
-5. If the store is RTL: check nothing is left-anchored that should be
-   right-anchored, and directional arrows point with the reading direction.
-
-## The quality bar (distilled from Lovable / v0 / Bolt system prompts)
-
-Beautiful is the top priority — the first render must wow. Hard rules:
-
-1. **Design system first**: define all HSL semantic tokens in globals.css
-   BEFORE styling any component. Never direct colors (`text-white`,
-   `bg-black`) in classNames — tokens only.
-2. **Color budget: exactly 3-5 colors.** 1 brand color, 2-3 neutrals, 1-2
-   accents. Never purple/violet unless the merchant asked. No gradients by
-   default — solid colors; gradients only as subtle accents if requested.
-3. **Max 2 font families** (1 display + 1 body, both with the store's
-   script). Body line-height 1.4-1.6. Nothing below 14px.
-4. **Mobile-first**; flexbox by default, grid for true 2D; no absolute
-   positioning unless necessary.
-5. **Tailwind discipline**: spacing scale only (`p-4`, never `p-[16px]`),
-   `gap-*` over margins between siblings, `text-balance` on headlines.
-6. **Real imagery everywhere** — product photos from the catalog do the
-   heavy lifting; free stock hotlinks (Pexels/Unsplash) for editorial
-   sections. NEVER abstract filler shapes (gradient circles, blobs).
-   NEVER emojis as icons — one icon set, consistent 16/20/24px sizes.
-7. **Content-rich**: no section may render empty or thin. Empty states are
-   designed states with copy and structure, not blank space.
-8. Component variants in the design system, not inline overrides.
-9. Semantic HTML + ARIA + alt text + `sr-only` labels — always.
-10. **Verify with your eyes**: screenshot after each major surface, critique
-    it ("would a Lovable user accept this?"), fix, and only then move on.
-
-
-## Motion language (CSS-first)
-
-The store should feel alive, premium and intentional — every animation guides
-attention, confirms an action, or rewards exploration. Rules:
-
-- **Timing tokens** (use these, never ad-hoc numbers): 80ms instant feedback ·
-  180ms hover · 300ms UI state change · 500-600ms section entrance · 900ms
-  hero only. Stagger siblings 40-80ms.
-- **Easing**: entrances `cubic-bezier(0.16, 1, 0.3, 1)` (out-expo); springy
-  pops `cubic-bezier(0.34, 1.56, 0.64, 1)` (out-back); loops and hovers
-  ease-in-out. Exits faster than entrances.
-- **Reveals**: below-the-fold sections animate on viewport entry
-  (IntersectionObserver — see `src/ui/shared/reveal.tsx`), never tied to
-  scroll distance. One orchestrated reveal per section beats scattered
-  effects; `viewport once` — do not re-animate on every scroll.
-- **Micro-interactions**: CSS/WAAPI first (see `src/ui/shared/fly-to-cart.ts`
-  for the pattern) — ripple, bump, image zoom, quick-add slide-up are all
-  achievable without a library.
-- **Pointer effects** (magnetic buttons, tilt cards, custom cursor, mouse
-  parallax): desktop only — gate on `(pointer: fine)` and no-op under
-  `prefers-reduced-motion`. `will-change: transform` ONLY on elements animated
-  per-frame; never sprinkle it broadly.
-- **Never `transition-all`** — always name the property
-  (`transition-transform`, `transition-opacity`). Animate only compositor
-  properties (`transform`, `opacity`) — never layout properties
-  (width/height/top/margin). 60fps is non-negotiable.
-- **Ambient effects** (gradient blobs, particles): maximum one per page, hero
-  only — never on inner pages.
-- **framer-motion / GSAP are not installed.** They are allowed, but they are
-  new runtime dependencies — flag it to the user before adding.
-
-## Hard-won gotchas (each one cost a real debugging session)
-
-- **RTL + cloned images**: `next/image` renders its `<img>` with `inset: 0`.
-  If you clone one for an animation and set `left`, the leftover `right: 0`
-  wins in RTL documents (over-constrained boxes resolve to the RIGHT).
-  Set `inset: 'auto'` before positioning.
-- **Never name a custom class `overline`** — it is a Tailwind utility
-  (`text-decoration-line: overline`) and will draw a line above your text.
-- **`rounded` / `rounded-md` / `rounded-lg` all follow `--radius`** (shadcn
-  convention, wired in tailwind.config.ts) — change the token, not the
-  classes, when you want sharper or softer corners.
-- **Hebrew has no uppercase** — remove `text-transform: uppercase` and wide
-  `letter-spacing` from heading styles; they are Latin idioms that distort
-  Hebrew (tracking is acceptable only at caption sizes).
-- **Logical properties only**: `ms-/me-`, `ps-/pe-`, `start-/end-`,
-  `text-start/end`. Never `ml-/mr-`, `left-/right-`, `text-left/right`,
-  `flex-row-reverse`.
-- **Motion**: wrap every animation in a `prefers-reduced-motion: reduce`
-  guard. One well-orchestrated reveal beats scattered effects.
-- **Fonts**: any face used for body or headlines must include the store's
-  script (e.g. Google Fonts `hebrew` subset). Latin-only display faces are
-  accent-only.
-
-## Never do
-
-- Modify `src/core/`, `src/app/api/`, or checkout/auth/account internals.
-- Remove accessibility attributes (`aria-*`, `role`, `alt`, focus styles).
-- Hardcode catalog content, prices, or currency symbols.
-- Hardcode the store name. `SiteHeader` / `SiteFooter` receive it as a prop
-  from the layout; anywhere else use `useStoreName()` (client) or
-  `resolveStoreName(storeInfo)` (server) from `src/core/lib/`. The name the
-  scaffold knew may be nothing more than the project directory.
-- Swallow the add-to-cart / checkout error states — restyle them, keep them.
-- Drop a `src/ui/` component that is the only place a mandatory feature
-  exists. Rebuilding the look is free; losing the SDK call inside it is not,
-  and it is silent. See "Rebuilding the look is free" in `CLAUDE.md` for the
-  files people usually lose, and `get-required-features` for the real list.
-- Introduce new runtime dependencies without flagging it.
-
-## Adding things
-
-- New homepage section → new component in `src/ui/home/`, composed in
-  `home-client.tsx`, data via existing hooks only.
-- New UI copy → add keys to **both** `messages/he.json` and
-  `messages/en.json` (or all supported locales), use `useTranslations()`.
-- New microinteraction → CSS-first; JS only for things CSS cannot do.
+# AI-GUIDE — designing this store safely
+
+You (an AI coding assistant, or a human designer) have been asked to redesign
+this storefront. This guide is the contract that lets you go as bold as you
+want without breaking commerce. It was distilled from real agency builds.
+
+## The one rule
+
+**`src/core/` is the platform's. `src/ui/` is yours.**
+
+Everything under `src/ui/` may be rewritten from scratch — layouts, markup,
+classes, animations, entire visual languages. (Canvas-mode stores —
+scaffolded with `--canvas` — ship `src/ui/` as bare unstyled skeletons with
+`DESIGN ME` markers; same rules apply, you're just starting from zero.) Everything under `src/core/`
+(and `src/app/api/`) keeps the store working: cart, checkout, variants,
+inventory, auth, SEO, i18n. Never modify it. If a redesign seems to require a
+core change, stop and say so instead.
+
+## File map
+
+| Path | Owner | Notes |
+|------|-------|-------|
+| `src/ui/layout/` | you | header, footer, announcement bar |
+| `src/ui/home/` | you | homepage sections |
+| `src/ui/product/` | you | card, grid, listing, product page, price, badges, selectors |
+| `src/ui/cart/` | you | cart page pieces |
+| `src/ui/shared/` | you | loader, image wrapper |
+| `src/app/globals.css` | you | tokens + global styles |
+| `src/components/ui/` | shared | shadcn/ui primitives — compose them, extend via variants |
+| `src/core/**` | platform | hooks, lib, providers — read, never edit |
+| `src/components/{checkout,auth,account,seo}` | platform | core-styled in v1; they inherit your tokens |
+| `src/app/**` | platform | thin routes; edit only to wire new ui components |
+
+## The dialect (shadcn/ui + lucide + cn)
+
+This store speaks the same component dialect as Lovable / v0 / Bolt output:
+
+- **`src/components/ui/` holds official shadcn/ui primitives** (button, card,
+  badge, input, label, textarea, select, checkbox, radio-group, separator,
+  accordion, dialog, sheet, skeleton, tabs, tooltip). Compose them in `src/ui/`
+  instead of hand-rolling controls. Need a new look? **Extend via CVA
+  variants** (add a variant to `buttonVariants`/`badgeVariants`), never by
+  inline-overriding the same styles in twenty call sites.
+- **Icons: lucide-react only.** No inline `<svg>` paths, no emoji-as-icons,
+  no second icon set. Consistent 16/20/24px sizes.
+- **Class merging: `cn()`** from `@/core/lib/utils` (clsx + tailwind-merge) —
+  it's the same helper shadcn expects, already wired into every primitive.
+- **Tokens drive everything**: primitives read `--primary`, `--card`,
+  `--input`, `--ring`, `--radius`, etc. from `globals.css`. Restyle the store
+  by changing tokens (and variants), not by scattering literal colors.
+- `rounded`, `rounded-md`, `rounded-lg` all derive from `--radius`
+  (shadcn convention), so corner radius follows the theme automatically.
+
+## The hook contract (your data supply)
+
+UI components get *everything* from `@/core/hooks/*` and
+`@/core/providers/store-provider` — never from `@/core/lib` directly, except
+the approved presentation helpers listed (as `!@/core/lib/...`) in the `src/ui`
+`no-restricted-imports` rule in `.eslintrc.json`. `next build` runs that lint,
+so importing any other `@/core/lib` module from `src/ui` fails the build:
+
+- `useHomeData()` → `{ products, banners, loading }`
+- `useProductListing()` → products + filters/sort/facets/pagination + handlers
+- `useProductPage(product)` → variant/image selection, `priceInfo`, `inventory`,
+  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, `addToCartError`,
+  customization + modifier state and errors
+  - `addToCartError` is `'CART_FULL' | 'FAILED' | null`. **Render it, and render it
+    outside any `modifierGroups.length > 0` block** — a cart holds at most 50
+    distinct products and the 51st add is refused, so a design that drops this
+    leaves the shopper tapping a button that resets and adds nothing. Copy lives
+    in `productDetail.cartFull` / `productDetail.addToCartFailed`.
+  - Five more components hold the same message in their OWN local state, because
+    they add to the cart without this hook: `ui/product/product-card.tsx`,
+    `ui/product/frequently-bought-together.tsx`, `ui/cart/cart-bundle-offer.tsx`
+    (all three: `addError`), `app/checkout/page.tsx` (`bumpError`) and
+    `ui/cart/cart-upgrade-banner.tsx` (`upgradeError`). All five use
+    `toAddToCartError()` from `@/core/lib/add-to-cart-error`. **Nothing checks that
+    you kept them** — `check-template-parity.js` compares `@/ui/...` imports and SDK
+    calls only, so dropping one of these leaves a green build and a silent button.
+  - `ui/cart/cart-item.tsx` carries the same idea for the two writes it owns,
+    in its own `lineError` state: a failed quantity change or a failed Remove
+    used to log to the console and leave the row looking untouched. It uses
+    `getErrorCode()` from the same file (not `toAddToCartError()` — the 50-line
+    cap cannot refuse a quantity change, and "we could not add this" would be a
+    lie about a removal) and four `cart.*` strings, mapped in `LINE_ERROR_KEYS`:
+    `notEnoughStock`, `itemUnavailable`, `quantityUpdateFailed`, `removeFailed`.
+    The first two are for refusals a retry can never clear, so do not collapse
+    them into the generic one. Nothing checks that you kept any of this either.
+  - `ui/cart/cart-upgrade-banner.tsx` additionally swaps one cart line for
+    another, and the ORDER of its two SDK calls is a correctness property, not a
+    style choice: it **adds the upgrade first and removes the original second**,
+    so a failed add leaves the cart untouched instead of losing the shopper's
+    line. It also carries `upgradeAdded`, which stops a retry adding the upgrade
+    twice, and a third message, `cart.upgradeOriginalNotRemoved`, for the case
+    where the add landed and the removal did not. If you rebuild that component,
+    keep all three; the reasoning is in the JSDoc on `handleUpgrade`.
+- `useCartPage()` / `useCart()` → `{ cart, itemCount, totals, refreshCart }`
+
+Hooks return data and handlers, never JSX. All catalog content (names, prices,
+images, stock) comes from them — **never hardcode products**.
+
+## Verification loop (before you declare anything done)
+
+1. **Feature coverage.** Call `get-required-features` on the `brainerce-docs`
+   MCP server (wired by the scaffolder in `.mcp.json`, no setup) and confirm
+   every mandatory entry is still reachable. First step, not last: you were
+   invited to rewrite `src/ui/` from scratch, and a feature that lived only in
+   the shipped reference is gone now with nothing to notice it by. `tsc`
+   cannot see a missing feature, and these components render nothing while the
+   merchant has the feature off, so a deleted one and an idle one look the
+   same. `CLAUDE.md` lists the files people usually lose; the MCP tool is the
+   actual specification.
+2. `pnpm exec tsc --noEmit` → must be 0.
+3. `pnpm dev` → drive the real flow you changed: home → listing → product →
+   add to cart → cart → checkout page renders.
+4. Screenshot desktop (1440) AND mobile (390), in the store's language.
+5. If the store is RTL: check nothing is left-anchored that should be
+   right-anchored, and directional arrows point with the reading direction.
+
+## The quality bar (distilled from Lovable / v0 / Bolt system prompts)
+
+Beautiful is the top priority — the first render must wow. Hard rules:
+
+1. **Design system first**: define all HSL semantic tokens in globals.css
+   BEFORE styling any component. Never direct colors (`text-white`,
+   `bg-black`) in classNames — tokens only.
+2. **Color budget: exactly 3-5 colors.** 1 brand color, 2-3 neutrals, 1-2
+   accents. Never purple/violet unless the merchant asked. No gradients by
+   default — solid colors; gradients only as subtle accents if requested.
+3. **Max 2 font families** (1 display + 1 body, both with the store's
+   script). Body line-height 1.4-1.6. Nothing below 14px.
+4. **Mobile-first**; flexbox by default, grid for true 2D; no absolute
+   positioning unless necessary.
+5. **Tailwind discipline**: spacing scale only (`p-4`, never `p-[16px]`),
+   `gap-*` over margins between siblings, `text-balance` on headlines.
+6. **Real imagery everywhere** — product photos from the catalog do the
+   heavy lifting; free stock hotlinks (Pexels/Unsplash) for editorial
+   sections. NEVER abstract filler shapes (gradient circles, blobs).
+   NEVER emojis as icons — one icon set, consistent 16/20/24px sizes.
+7. **Content-rich**: no section may render empty or thin. Empty states are
+   designed states with copy and structure, not blank space.
+8. Component variants in the design system, not inline overrides.
+9. Semantic HTML + ARIA + alt text + `sr-only` labels — always.
+10. **Verify with your eyes**: screenshot after each major surface, critique
+    it ("would a Lovable user accept this?"), fix, and only then move on.
+
+
+## Motion language (CSS-first)
+
+The store should feel alive, premium and intentional — every animation guides
+attention, confirms an action, or rewards exploration. Rules:
+
+- **Timing tokens** (use these, never ad-hoc numbers): 80ms instant feedback ·
+  180ms hover · 300ms UI state change · 500-600ms section entrance · 900ms
+  hero only. Stagger siblings 40-80ms.
+- **Easing**: entrances `cubic-bezier(0.16, 1, 0.3, 1)` (out-expo); springy
+  pops `cubic-bezier(0.34, 1.56, 0.64, 1)` (out-back); loops and hovers
+  ease-in-out. Exits faster than entrances.
+- **Reveals**: below-the-fold sections animate on viewport entry
+  (IntersectionObserver — see `src/ui/shared/reveal.tsx`), never tied to
+  scroll distance. One orchestrated reveal per section beats scattered
+  effects; `viewport once` — do not re-animate on every scroll.
+- **Micro-interactions**: CSS/WAAPI first (see `src/ui/shared/fly-to-cart.ts`
+  for the pattern) — ripple, bump, image zoom, quick-add slide-up are all
+  achievable without a library.
+- **Pointer effects** (magnetic buttons, tilt cards, custom cursor, mouse
+  parallax): desktop only — gate on `(pointer: fine)` and no-op under
+  `prefers-reduced-motion`. `will-change: transform` ONLY on elements animated
+  per-frame; never sprinkle it broadly.
+- **Never `transition-all`** — always name the property
+  (`transition-transform`, `transition-opacity`). Animate only compositor
+  properties (`transform`, `opacity`) — never layout properties
+  (width/height/top/margin). 60fps is non-negotiable.
+- **Ambient effects** (gradient blobs, particles): maximum one per page, hero
+  only — never on inner pages.
+- **framer-motion / GSAP are not installed.** They are allowed, but they are
+  new runtime dependencies — flag it to the user before adding.
+
+## Hard-won gotchas (each one cost a real debugging session)
+
+- **RTL + cloned images**: `next/image` renders its `<img>` with `inset: 0`.
+  If you clone one for an animation and set `left`, the leftover `right: 0`
+  wins in RTL documents (over-constrained boxes resolve to the RIGHT).
+  Set `inset: 'auto'` before positioning.
+- **Never name a custom class `overline`** — it is a Tailwind utility
+  (`text-decoration-line: overline`) and will draw a line above your text.
+- **`rounded` / `rounded-md` / `rounded-lg` all follow `--radius`** (shadcn
+  convention, wired in tailwind.config.ts) — change the token, not the
+  classes, when you want sharper or softer corners.
+- **Hebrew has no uppercase** — remove `text-transform: uppercase` and wide
+  `letter-spacing` from heading styles; they are Latin idioms that distort
+  Hebrew (tracking is acceptable only at caption sizes).
+- **Logical properties only**: `ms-/me-`, `ps-/pe-`, `start-/end-`,
+  `text-start/end`. Never `ml-/mr-`, `left-/right-`, `text-left/right`,
+  `flex-row-reverse`.
+- **Motion**: wrap every animation in a `prefers-reduced-motion: reduce`
+  guard. One well-orchestrated reveal beats scattered effects.
+- **Fonts**: any face used for body or headlines must include the store's
+  script (e.g. Google Fonts `hebrew` subset). Latin-only display faces are
+  accent-only.
+- **Public paths go through `localePath(locale, '/x')`** (`@/core/lib/locale-path`),
+  never `` `/${locale}/x` ``. The default locale arrives as a real `params.locale`
+  too, and the middleware 308-redirects `/{default}/x` to `/x`, so a canonical
+  tag, breadcrumb link or JSON-LD url built the second way points at a redirect.
+- **Every indexable page sets its own `alternates.canonical`; the root layout sets
+  none.** A layout-level canonical is inherited by every page without its own and
+  tells Google they are duplicates of it. `openGraph` on a page REPLACES the
+  layout's object (it does not merge), so repeat `siteName` there.
+- **Product meta description: `deriveSeoDescription(product)`**, never
+  `product.seoDescription` alone. The merchant's text can arrive under either
+  `seoDescription` or `metaDescription`; reading one silently falls back to the
+  start of the description.
+- **`og:type: product` and the `product:*` price/availability tags are real
+  `<meta property>` elements** (`components/seo/product-og-meta.tsx`). Next's
+  `openGraph.type` has no `product`, and `metadata.other` renders `name=`, which
+  the crawlers that read these tags ignore. Do not also set `openGraph.type` on
+  the product page, or it carries two `og:type` tags.
+- **`/products` and the home grid are server-seeded.** `app/products/page.tsx`
+  reads the URL (search, filters, sort, `?page=`) and passes the first render's
+  products through `ListingSeedProvider`; `core/lib/listing-query.ts` is the ONE
+  function turning a URL into a query, shared by that page and
+  `useProductListing`. Do not fork it, and do not put the listing back behind
+  `'use client'` or a `<Suspense>` fallback: the server HTML must contain the
+  products, not a spinner. A seeded hook starts with `loading` false.
+- **Metadata, JSON-LD and breadcrumb strings come from the message files**
+  (`getServerNamespace('seo', locale)`), not from literals or a
+  `locale === 'he'` ternary (English for every third language). The visible
+  breadcrumb and the BreadcrumbList JSON-LD are built from the SAME items; the
+  JSON-LD components take a required `breadcrumbs` prop.
+
+## Never do
+
+- Modify `src/core/`, `src/app/api/`, or checkout/auth/account internals.
+- Remove accessibility attributes (`aria-*`, `role`, `alt`, focus styles).
+- Hardcode catalog content, prices, or currency symbols.
+- Hardcode the store name. `SiteHeader` / `SiteFooter` receive it as a prop
+  from the layout; anywhere else use `useStoreName()` (client) or
+  `resolveStoreName(storeInfo)` (server) from `src/core/lib/`. The name the
+  scaffold knew may be nothing more than the project directory.
+- Swallow the add-to-cart / checkout error states — restyle them, keep them.
+- Drop a `src/ui/` component that is the only place a mandatory feature
+  exists. Rebuilding the look is free; losing the SDK call inside it is not,
+  and it is silent. See "Rebuilding the look is free" in `CLAUDE.md` for the
+  files people usually lose, and `get-required-features` for the real list.
+- Introduce new runtime dependencies without flagging it.
+
+## Adding things
+
+- New homepage section → new component in `src/ui/home/`, composed in
+  `home-client.tsx`, data via existing hooks only.
+- New place that shows a star rating or a review count (a card, a banner,
+  structured data) → gate it with `useReviewsEnabled()` (client) or
+  `reviewsAreOn(storeInfo)` from `src/core/lib/store-info` (server). Products
+  keep their stored `avgRating` and `reviewCount` while the merchant has reviews
+  switched off, so `reviewCount > 0` alone would show a rating for reviews nobody
+  can open.
+- New UI copy → add keys to **both** `messages/he.json` and
+  `messages/en.json` (or all supported locales), use `useTranslations()`.
+- New microinteraction → CSS-first; JS only for things CSS cannot do.

package/templates/nextjs/base/TRANSLATIONS.md

@@ -79,6 +79,12 @@ The `StoreProvider` (`src/providers/store-provider.tsx`) calls `client.setLocale
 
 You never overlay translations yourself — the SDK does it on every request.
 
+### Meta descriptions
+
+On a product read, `seoDescription` is the **effective** meta description: the active locale's translation when there is one, otherwise the merchant's stored text (which is also served as `metaDescription`). It is `null` only when the merchant wrote none. Never read one of the two names alone: call `deriveSeoDescription(product)`, which takes whichever is present and falls back to a stripped `description`, then the name. The product page (`src/app/products/[slug]/page.tsx`) does exactly that.
+
+When you WRITE a product translation, send either name: `metaDescription` is accepted as `seoDescription`.
+
 ## RTL (Hebrew, Arabic, Persian, Urdu, Yiddish)
 
 `src/i18n.ts` exports `getDirection(locale)` that delegates to the SDK's `getDirectionForLocale()`. The layout uses it on `<html dir={…}>`:

package/templates/nextjs/base/scripts/agent-docs.mjs

@@ -0,0 +1,76 @@
+/**
+ * Keep CLAUDE.md and AGENTS.md truthful once `npm run connect` has connected
+ * the store.
+ *
+ * WHY THIS EXISTS. A project scaffolded with `--defer-connection` starts both
+ * files with a "Not connected yet" paragraph, rendered ONCE at scaffold time.
+ * `connect` then wrote the id into `.env.local` and never touched them, so a
+ * connected store kept telling every coding agent that read it that it was not
+ * connected. The agent believed the file, concluded the store had no channel and
+ * asked the user to connect it again.
+ *
+ * ⛔ THE PATTERN BELOW IS COUPLED TO TWO TEMPLATES. It must keep matching the
+ * deferred paragraph in `CLAUDE.md.ejs` and `AGENTS.md.ejs` (first words
+ * "**Not connected yet.**", last sentence "Once connected, everything below
+ * applies."). `scripts/check-template-parity.js` renders both files deferred and
+ * fails `prepublishOnly` if this stops matching, because a pattern that silently
+ * matches nothing is exactly the bug it fixes.
+ *
+ * Only the channel id goes into the prose, and only when it has the shape of one:
+ * the store NAME is owner-controlled text, and these files are read by agents as
+ * instructions. The name is not needed: the doc already says to read it from
+ * `resolveStoreName()`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const AGENT_DOC_FILES = ['CLAUDE.md', 'AGENTS.md'];
+
+export const NOT_CONNECTED_PARAGRAPH =
+  /\*\*Not connected yet\.\*\*[\s\S]*?Once connected, everything below applies\./;
+
+const CHANNEL_ID = /^vc_[A-Za-z0-9_-]+$/;
+
+/** The paragraph a connected storefront's docs open with. Mirrors the
+ *  non-deferred branch of the two templates, minus the store name. */
+export function connectedParagraph(connectionId) {
+  return (
+    `**Sales channel \`${connectionId}\` — already connected.** Products, cart,\n` +
+    'checkout, coupons, discounts, orders and content flow in real time from the\n' +
+    'Brainerce dashboard. There is nothing to hook up.'
+  );
+}
+
+/**
+ * Rewrite the "Not connected yet" paragraph in each agent doc under `dir`.
+ * Returns the names of the files it changed. Never throws: a doc that cannot be
+ * read or written must not undo a connection that already succeeded.
+ *
+ * A doc whose paragraph was edited by hand no longer matches and is left alone.
+ * A project that already connected before this script existed is not helped
+ * either: it carries the old `connect.mjs`, which never calls this. Its owner
+ * deletes the paragraph by hand (see the create-brainerce-store CHANGELOG).
+ */
+export function markAgentDocsConnected(dir, connectionId) {
+  if (typeof connectionId !== 'string' || !CHANNEL_ID.test(connectionId)) return [];
+  const changed = [];
+  for (const name of AGENT_DOC_FILES) {
+    const path = resolve(dir, name);
+    try {
+      if (!existsSync(path)) continue;
+      const body = readFileSync(path, 'utf8');
+      if (!NOT_CONNECTED_PARAGRAPH.test(body)) continue;
+      // A function replacement, so `$` sequences in the id can never be read as
+      // replacement patterns.
+      const next = body.replace(NOT_CONNECTED_PARAGRAPH, () => connectedParagraph(connectionId));
+      // Keep a CRLF file CRLF (the paragraph is matched across either ending).
+      const out = body.includes('\r\n') ? next.replace(/\r?\n/g, '\r\n') : next;
+      writeFileSync(path, out);
+      changed.push(name);
+    } catch {
+      // Best effort by design.
+    }
+  }
+  return changed;
+}