create-brainerce-store 1.52.2 → 1.52.4

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.52.2",
+      version: "1.52.4",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -393,6 +393,9 @@ async function scaffold(options) {
   const templateVars = {
     projectName: options.projectName,
     connectionId: options.connectionId,
+    /** Raw store name for prose contexts (markdown docs) — JS/env contexts
+     *  must keep using the escaped storeNameJs / storeNameEnv variants. */
+    storeName: cleanStoreName,
     storeNameJs: toJsStringLiteral(cleanStoreName),
     titleTemplateJs: toJsStringLiteral(`%s | ${cleanStoreName}`),
     storeNameEnv: toEnvLiteral(cleanStoreName),
@@ -969,7 +972,9 @@ live in messages/ (or let an AI session rewrite them).`
       );
       logger.info(
         `
-Want a unique design? Open this folder in Claude Code and run:
+Want a unique design? Open THE STORE FOLDER ITSELF in Claude Code
+(not a parent folder \u2014 that's how CLAUDE.md auto-loads and the AI
+knows this is a live, connected Brainerce storefront), then run:
   /design <your art-direction brief>
 (commerce stays intact \u2014 see AI-GUIDE.md)`
       );

package/package.json

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

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

@@ -0,0 +1,65 @@
+# 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
+
+**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-`).

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

@@ -103,6 +103,37 @@ Beautiful is the top priority — the first render must wow. Hard rules:
     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`.

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

@@ -0,0 +1,76 @@
+# 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
+
+**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-`).

package/templates/nextjs/base/AGENTS.md

@@ -1,41 +0,0 @@
-# AGENTS.md — this is a Brainerce storefront
-
-This store's commerce engine (cart, checkout, variants, auth, i18n) is
-already wired and working. 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, 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/`. 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

@@ -1,52 +0,0 @@
-# CLAUDE.md — this is a Brainerce storefront
-
-This store's commerce engine (cart, checkout, variants, auth, i18n) is
-already wired and working. 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, 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/`. Hebrew: no uppercase transforms, no wide
-letter-spacing on headings, logical CSS properties only (`ms-/me-`, `ps-/pe-`,
-`start-/end-`).