create-brainerce-store 1.84.0 → 1.85.0

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

@@ -1,218 +1,240 @@
-# 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).
-  Treat it as the build spec, not a lookup desk. `get-required-features` is
-  the functional checklist this store is measured against, and it is longer
-  than what any art-direction brief would make you think to build.
-  `get-critical-rules` and `get-business-flows` carry the sequences that cause
-  incidents when reordered. `get-sdk-docs`, `get-type-definitions` and
-  `get-code-example` give current method shapes instead of training-data
-  guesses, and `get-store-capabilities` reports what is actually toggled on
-  for `<%- connectionId %>` right now. Read the checklist before you start,
-  and again before you call the work done.
-- **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, donations, 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.
-
-### ⛔ This storefront never holds an admin API key
-
-Everything here runs on the sales channel's PUBLIC credentials, and that is the
-whole security model. `.env.local` ships no secret on purpose. Anything you put
-in a browser-reachable app is readable by anyone who opens devtools, so an
-admin API key (`brainerce_*`) in this project hands the merchant's entire live
-store to the first person who looks. Never add one to `.env.local`, to a
-hosting environment variable this app reads, or to any file under `src/`.
-
-**Gift cards are where this goes wrong**, because one feature name covers two
-very different powers:
-
-- **Redemption is yours to build.** `applyGiftCard()`, `removeGiftCard()` and
-  `checkGiftCardBalance()` are public storefront calls needing no key beyond
-  the sales channel. `src/ui/cart/gift-card-input.tsx` already wires the first
-  two into checkout. Restyle it freely.
-- **⛔ Issuing is not.** The `gift_cards:issue` scope mints stored value, which
-  is real money the merchant is liable for. It belongs to the dashboard, or to
-  server-side code on infrastructure the merchant controls. Never request that
-  scope for this storefront, never hold a key that carries it, and never add an
-  "issue a gift card" control to these pages. A merchant who wants to SELL gift
-  cards sells them as an ordinary product through normal checkout, and the
-  platform issues the card once payment clears.
-
-The same split governs every admin capability you may be tempted to reach for
-(creating discounts, editing inventory, refunding an order): this storefront
-reads and transacts as a shopper, the dashboard administers.
-
-Your job here is almost always **design**. It is never *only* design: the
-coverage checklist in `get-required-features` applies to a redesign exactly as
-it applies to a build from scratch.
-
-## 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: a full
-delete-and-rebuild of the *look* is encouraged and expected, and you can
-rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like. The store keeps working. (Stores scaffolded with `--canvas` ship
-`src/ui/` as bare unstyled skeletons, so there is no reference look at all and
-the design is entirely yours to create.) 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.
-
-### Rebuilding the look is free. Dropping a feature is not.
-
-Some files under `src/ui/` (and one under `src/core/`) are the ONLY place a
-mandatory checklist entry exists in this project. Delete one and the capability
-leaves the store with nothing to notice it by: no type error, no console
-warning, and no visual hole either, because these components auto-hide while
-the merchant has the feature switched off, so a deleted one and an idle one
-look identical on the page.
-These are the usual casualties of a redesign, because no art-direction brief
-asks for them by name:
-
-```
-product/  back-in-stock-form · customization-fields · modifier-group-selector
-          review-form · reviews-section · frequently-bought-together
-          discount-badge · stock-badge
-          product-client-section → the KIT "what's in the box" block
-core/     lib/kit.ts → the KIT stock resolver every badge and button reads
-cart/     reservation-countdown · coupon-input · cart-upgrade-banner
-          cart-bundle-offer · tax-estimate-line
-home/     discount-banner-strip
-layout/   newsletter-signup · announcement-bar · region-switcher<% if (i18nEnabled) { %>
-          language-switcher<% } %> · faq-section · rich-text-block
-```
-
-Restyle them, re-lay them out, rename them, fold them into other components,
-split them in half: all fine. What has to survive a rebuild is the SDK call
-each one makes and the states it handles (loading, empty, failed, and the
-merchant-has-it-off state that renders nothing).
-
-⛔ **The two KIT entries are the ones a redesign silently breaks.** A `KIT` is
-one product assembled from other catalog products, and three things have to
-survive whatever you do to the markup. (1) It is added to the cart as ONE line
-using the kit's own `productId`, with no `variantId` and no modifier
-selections; never loop `product.kitComponents` into `addToCart`, which charges
-the shopper twice and reserves the stock twice. (2) A kit has NO `inventory`
-object, so every badge and buy button must go through `resolveStockInfo` /
-`canPurchaseProduct` from `@/core/lib/kit`; reading `product.inventory`
-directly gives a kit a red "out of stock" badge beside an ENABLED buy button,
-or worse, renders a sold-out kit as buyable. (3) `kitComponents` is display
-only and arrives on the by-slug read alone, never on list responses. And do not
-assume a kit price is fixed: `kitPricingMode` may be `SUM` or
-`SUM_MINUS_PERCENT`, in which case the price is recomputed from the components
-on every read, so never cache one.
-
-The list is short on purpose and it is NOT the specification. It names the
-files people lose, not every mandatory entry. `get-required-features` is the
-specification, and step 1 of "Verify before declaring done" is what actually
-catches a loss. `git show HEAD:src/ui/<path>` brings back anything you already
-deleted: the scaffolder committed the tree before you touched it.
-
-**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. **Feature coverage, first and always.** Call `get-required-features` on the
-   `brainerce-docs` MCP server (already wired, nothing to set up) and confirm
-   every mandatory entry is still reachable in the running store. Do this
-   before the steps below, because if you rebuilt `src/ui/` a feature that
-   lived only in the shipped reference is now gone, and no other check can see
-   it: `tsc` cannot see a missing feature, and the component that used to
-   carry it auto-hid when the merchant had not switched it on, so the page
-   looks right either way.
-2. `pnpm exec tsc --noEmit` → 0 errors
-3. `pnpm dev` → drive the changed flow in a real browser (home → product →
-   add to cart → cart)
-4. Screenshot desktop (1440px) and mobile (390px)
-5. 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
+
+<% if (deferred) { %>**Not connected yet.** This project was scaffolded with
+`--defer-connection`: `.env.local` holds a placeholder id, and the name the
+scaffold knew is only the directory name, "<%- storeName %>". Finish with
+`npm run connect` (one browser approval; it creates a store and a sales
+channel if you have neither, then fetches the real store name and currency
+into `.env.local`). Those are `NEXT_PUBLIC_*` values, baked in at build time:
+rebuild, and restart `dev`, after connecting. Until then every API call fails
+by design. Once connected, everything below applies.
+<% } else { %>**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.
+<% } %>
+The store's display name is never hardcoded: `resolveStoreName()` /
+`useStoreName()` in `src/core/lib/` resolve it from the live store, then
+`NEXT_PUBLIC_STORE_NAME` (refreshed by `npm run setup`), then the scaffold
+literal. Read it from there; do not paste the name into components.
+
+- **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).
+  Treat it as the build spec, not a lookup desk. `get-required-features` is
+  the functional checklist this store is measured against, and it is longer
+  than what any art-direction brief would make you think to build.
+  `get-critical-rules` and `get-business-flows` carry the sequences that cause
+  incidents when reordered. `get-sdk-docs`, `get-type-definitions` and
+  `get-code-example` give current method shapes instead of training-data
+  guesses, and `get-store-capabilities` reports what is actually toggled on
+  for `<%- connectionId %>` right now. Read the checklist before you start,
+  and again before you call the work done.
+- **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, donations, 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.
+
+### ⛔ This storefront never holds an admin API key
+
+Everything here runs on the sales channel's PUBLIC credentials, and that is the
+whole security model. `.env.local` ships no secret on purpose. Anything you put
+in a browser-reachable app is readable by anyone who opens devtools, so an
+admin API key (`brainerce_*`) in this project hands the merchant's entire live
+store to the first person who looks. Never add one to `.env.local`, to a
+hosting environment variable this app reads, or to any file under `src/`.
+
+**Gift cards are where this goes wrong**, because one feature name covers two
+very different powers:
+
+- **Redemption is yours to build.** `applyGiftCard()`, `removeGiftCard()` and
+  `checkGiftCardBalance()` are public storefront calls needing no key beyond
+  the sales channel. `src/ui/cart/gift-card-input.tsx` already wires the first
+  two into checkout. Restyle it freely.
+- **⛔ Issuing is not.** The `gift_cards:issue` scope mints stored value, which
+  is real money the merchant is liable for. It belongs to the dashboard, or to
+  server-side code on infrastructure the merchant controls. Never request that
+  scope for this storefront, never hold a key that carries it, and never add an
+  "issue a gift card" control to these pages. A merchant who wants to SELL gift
+  cards sells them as an ordinary product through normal checkout, and the
+  platform issues the card once payment clears.
+
+The same split governs every admin capability you may be tempted to reach for
+(creating discounts, editing inventory, refunding an order): this storefront
+reads and transacts as a shopper, the dashboard administers.
+
+Your job here is almost always **design**. It is never *only* design: the
+coverage checklist in `get-required-features` applies to a redesign exactly as
+it applies to a build from scratch.
+
+## 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: a full
+delete-and-rebuild of the *look* is encouraged and expected, and you can
+rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like. The store keeps working. (Stores scaffolded with `--canvas` ship
+`src/ui/` as bare unstyled skeletons, so there is no reference look at all and
+the design is entirely yours to create.) 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.
+
+### Rebuilding the look is free. Dropping a feature is not.
+
+Some files under `src/ui/` (and one under `src/core/`) are the ONLY place a
+mandatory checklist entry exists in this project. Delete one and the capability
+leaves the store with nothing to notice it by: no type error, no console
+warning, and no visual hole either, because these components auto-hide while
+the merchant has the feature switched off, so a deleted one and an idle one
+look identical on the page.
+These are the usual casualties of a redesign, because no art-direction brief
+asks for them by name:
+
+```
+product/  back-in-stock-form · customization-fields · modifier-group-selector
+          review-form · reviews-section · frequently-bought-together
+          discount-badge · stock-badge
+          product-client-section → the KIT "what's in the box" block
+core/     lib/kit.ts → the KIT stock resolver every badge and button reads
+cart/     reservation-countdown · coupon-input · cart-upgrade-banner
+          cart-bundle-offer · tax-estimate-line
+home/     discount-banner-strip
+layout/   newsletter-signup · announcement-bar · region-switcher<% if (i18nEnabled) { %>
+          language-switcher<% } %> · faq-section · rich-text-block
+```
+
+Restyle them, re-lay them out, rename them, fold them into other components,
+split them in half: all fine. What has to survive a rebuild is the SDK call
+each one makes and the states it handles (loading, empty, failed, and the
+merchant-has-it-off state that renders nothing).
+
+⛔ **The two KIT entries are the ones a redesign silently breaks.** A `KIT` is
+one product assembled from other catalog products, and three things have to
+survive whatever you do to the markup. (1) It is added to the cart as ONE line
+using the kit's own `productId`, with no `variantId` and no modifier
+selections; never loop `product.kitComponents` into `addToCart`, which charges
+the shopper twice and reserves the stock twice. (2) A kit has NO `inventory`
+object, so every badge and buy button must go through `resolveStockInfo` /
+`canPurchaseProduct` from `@/core/lib/kit`; reading `product.inventory`
+directly gives a kit a red "out of stock" badge beside an ENABLED buy button,
+or worse, renders a sold-out kit as buyable. (3) `kitComponents` is display
+only and arrives on the by-slug read alone, never on list responses. And do not
+assume a kit price is fixed: `kitPricingMode` may be `SUM` or
+`SUM_MINUS_PERCENT`, in which case the price is recomputed from the components
+on every read, so never cache one.
+
+The list is short on purpose and it is NOT the specification. It names the
+files people lose, not every mandatory entry. `get-required-features` is the
+specification, and step 1 of "Verify before declaring done" is what actually
+catches a loss. `git show HEAD:src/ui/<path>` brings back anything you already
+deleted: the scaffolder committed the tree before you touched it.
+
+**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. **Feature coverage, first and always.** Call `get-required-features` on the
+   `brainerce-docs` MCP server (already wired, nothing to set up) and confirm
+   every mandatory entry is still reachable in the running store. Do this
+   before the steps below, because if you rebuilt `src/ui/` a feature that
+   lived only in the shipped reference is now gone, and no other check can see
+   it: `tsc` cannot see a missing feature, and the component that used to
+   carry it auto-hid when the merchant had not switched it on, so the page
+   looks right either way.
+2. `pnpm exec tsc --noEmit` → 0 errors
+3. `pnpm dev` → drive the changed flow in a real browser (home → product →
+   add to cart → cart)
+4. Screenshot desktop (1440px) and mobile (390px)
+5. RTL stores: check anchoring and arrow directions
+
+## i18n
+
+The interface language was fixed at scaffold time by `--language` (this store:
+`<%= language %>`). It decides which `messages/` ship and the `<html lang>` /
+`dir` of every page, and it is the one thing `npm run connect` / `npm run
+setup` do not change: they refresh the store name and currency from the live
+channel, never the language. A store in the wrong language is re-scaffolded,
+not adjusted.
+
+Every user-facing string goes through `useTranslations()` with keys in **all**
+files under `messages/`. The shipped copy is vertical-neutral placeholder
+content — it names no product category, and it is a starting point, not a
+voice: rewrite the hero, the story and the footer tagline in the merchant's
+own words before calling the store done. Hebrew: no
+uppercase transforms, no wide letter-spacing on headings, logical CSS
+properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).