create-cartbase 0.1.0 → 0.1.2

package/template/app/docs/components.md

@@ -1,4 +1,4 @@
-# Components — `@cartbase/storefront` UI families
+# Components
 
 The component layer of `@cartbase/storefront`: what each family ships, the SDK
 calls it requires, the admin settings that change its behavior, and its mount
@@ -20,8 +20,7 @@ app's CSS; no component hardcodes a color.
 
 ---
 
-## Family: tracking (`@cartbase/storefront/tracking/*`) — SHIPPED
-
+## Family: tracking (`@cartbase/storefront/tracking/*`)
 Meta Pixel + GA4 + Rybbit + Consent Mode v2. The Cartbase split of duties:
 **this package fires client events and writes attribution; server-side CAPI /
 GA4 Measurement Protocol sending is Cartbase-backend-owned** (the
@@ -154,8 +153,7 @@ Meta side) and `gtag('set','user_data',…)`. Call alongside
 
 ---
 
-## Family: primitives (`@cartbase/storefront/primitives/*`) — SHIPPED
-
+## Family: primitives (`@cartbase/storefront/primitives/*`)
 Generic shadcn-style building blocks. No SDK calls, no admin settings —
 pure UI over the theme tokens.
 
@@ -172,8 +170,7 @@ pure UI over the theme tokens.
 
 ---
 
-## Family: lib (`@cartbase/storefront/lib/*`) — SHIPPED
-
+## Family: lib (`@cartbase/storefront/lib/*`)
 Pure helpers — no React except `dual-price`, no fetches. The SDK never
 invents server truths: prices/totals arrive computed from the API
 (`variant.calculated_price`, `cart.total`); these helpers only select and
@@ -195,7 +192,7 @@ format.
 - `lib/get-product-price` — `getProductPrice({product, variantId})` /
   `getPricesForVariant` → formatted `VariantPrice` (cheapest + selected)
   from server-computed `calculated_price`. Reads Cartbase's flat
-  `price_list_type` with the Medusa nested shape as fallback. Affected by:
+  `price_list_type` with a legacy nested shape as fallback. Affected by:
   price lists / B2B pricing context (what `calculated_price` contains),
   currency + region query context.
 - `lib/get-percentage-diff` — sale badge math.
@@ -204,21 +201,23 @@ format.
 - `lib/sort-products` — client-side re-sort of a fetched page
   (`price_asc|price_desc|created_at`); the API's `order` param stays the
   authority for paginated listings.
-- `lib/payment-constants` — `isStripeLike` / `isPaypal` / `isManual` +
-  `paymentInfoMap`. Translated to Cartbase ids: matches `pp_stripe` exactly
-  (code truth `src/lib/stripe/providers.ts`) plus the Medusa-era prefixes;
-  `pp_system_default` = COD. Affected by: enabled payment providers +
-  checkout rules (which ids ever reach the client).
+- `lib/payment-constants` — `isStripeLike` / `isPaypal` +
+  `paymentInfoMap`. Two tender shapes since the pp_* kill: a processor
+  `provider_id` (`pp_stripe` exact, code truth
+  `src/lib/stripe/providers.ts`, plus legacy Medusa-era prefixes as
+  fallbacks) or a merchant METHOD rendered by its snapshot NAME — a
+  method never has a provider id to bucket. Affected by: connected
+  processors + enabled methods + checkout rules (which entries ever
+  reach the client).
 - `lib/store-api-error` — `storeApiError(err)`: display-boundary normalizer
-  (capitalized message + terminal period), successor of `medusaError`.
+  (capitalized message + terminal period).
   Catch `StoreApiError` directly instead when branching on `status`/`code`.
 - `lib/hooks/use-intersection`, `lib/hooks/use-toggle-state` — viewport +
   toggle micro-hooks (client).
 
 ---
 
-## Family: checkout (`@cartbase/storefront/checkout/*`) — SHIPPED
-
+## Family: checkout (`@cartbase/storefront/checkout/*`)
 The full checkout page family, production-proven (deferred-
 intent architecture — no payment session exists until Buy click) onto the
 Cartbase orchestration endpoints. The flow every component serves
@@ -227,7 +226,7 @@ Cartbase orchestration endpoints. The flow every component serves
 ```
 listShippingOptions(cart_id) + listPaymentProviders(cart_id)  (render pickers)
    → Buy click → prepareCheckout (ONE atomic, compensated call)
-   → pp_stripe: stripe.confirmPayment(client_secret) | pp_cod/pp_manual: skip
+   → pp_stripe: stripe.confirmPayment(client_secret) | merchant method: skip
    → completeCart → navigate to the confirmed page
 ```
 
@@ -264,21 +263,24 @@ code-first through the error-copy maps, never raw API strings.
   call REACTIVELY from Elements `loaderror` only), `carts.completeCart`.
 - **Props contract** — `{client, cart, customer, availableShippingMethods,
   availablePaymentMethods, countryCode?, countries?, paymentMethodFilter?,
-  codConfig?, orderConfirmedPath?, onOrderPlaced?,
+  orderConfirmedPath?, onOrderPlaced?,
   resolveTrackingMetadata?, logError?}`. `countries` is caller-supplied
-  (Cartbase regions embed NO countries array). `codConfig` = the
-  integrations `cod` block — the COD fee prediction is never hardcoded.
-  `logError` replaces the legacy log writers (all production log
-  points preserved). Returns the full orchestration surface
-  (`performBuyClick`, `optimisticTotal(Cents)`, `deliveryReady`, …).
+  (Cartbase regions embed NO countries array). Fee prediction is never
+  hardcoded: each method LISTING entry carries its own
+  `fee_amount`/`fee_label`. `logError` replaces the legacy log writers
+  (all production log points preserved). Returns the full orchestration
+  surface (`performBuyClick`, `optimisticTotal(Cents)`, `deliveryReady`, …).
 - **Cartbase specifics** — zero-remainder gift path: `prepareCheckout`
-  returning `client_secret:null` + `provider_id:null` SKIPS Stripe and
-  completes on the gift session ([gift-cards.md](gift-cards.md)). Provider
-  ids are `pp_stripe`/`pp_cod`/`pp_manual` exactly; `pp_manual` doubles as
-  the offline tab when no true COD provider exists (fee predicted only for
-  `pp_cod`). COD fee reads the cart-level `cod_fee_total` decoration.
+  returning `client_secret:null` + `provider_id:null` +
+  `payment_method_id:null` SKIPS Stripe and completes on the gift session
+  ([gift-cards.md](gift-cards.md)). Processors are `pp_stripe` exactly;
+  merchant methods list as `{payment_method_id, name, kind, instructions,
+  fee_amount, fee_label}` entries — the COD-kind method wins the offline
+  tab, else the first manual method. The charged fee reads the cart-level
+  `payment_method_fee_total` decoration.
 - **Settings** — checkout rules (filter the listings + complete guard),
-  COD integration (fee), Stripe credentials, gift cards, `accounts_mode`.
+  the methods' own fee configuration (Payments settings), Stripe
+  credentials, gift cards, `accounts_mode`.
 
 ### `<CheckoutClient />` — `checkout/checkout-client`
 
@@ -303,7 +305,7 @@ code-first through the error-copy maps, never raw API strings.
   `StripeElementsScope` mounts `<Elements mode:"payment">` where needed
   (`passthrough` renders children scope-less on COD-only stores);
   `StripeContext` boolean = "Stripe.js ready".
-- **SDK calls** — none (env: `NEXT_PUBLIC_STRIPE_KEY`, Medusa-era names
+- **SDK calls** — none (env: `NEXT_PUBLIC_STRIPE_KEY`; legacy env names
   kept as fallbacks).
 - **Mount rules** — `PaymentWrapper` wraps the page ONCE with
   `amount={optimisticTotalCents}` (cents at this Stripe boundary only);
@@ -383,11 +385,11 @@ code-first through the error-copy maps, never raw API strings.
   badge. `LineItemCard` is the standalone card variant.
 - **SDK calls** — `carts.updateLineItem` (quantity); child widgets below.
   Totals are rendered STRAIGHT from the cart decoration: `item_total`,
-  `shipping_total`, `cod_fee_total`/`cod_fee_label`, `discount_total`,
+  `shipping_total`, `payment_method_fee_total`/`payment_method_fee_label`, `discount_total`,
   `tax_total`, `total`, `gift_card_total`, `gift_card_remainder`.
 - **Props contract** — `{client, cart, optimisticShippingCost,
   onOptimisticShippingClear?, optimisticCodFee?, onOptimisticCodFeeClear?,
-  codFeeLabel?, showGiftCards?, onCartChange?}`. Optimistic values clear
+  methodFeeLabel?, showGiftCards?, onCartChange?}`. Optimistic values clear
   automatically once the server cart catches up.
 - **Settings** — COD integration (fee row), gift cards, promotions.
 
@@ -445,8 +447,7 @@ extra modules beyond the per-file exports, imported from
 
 ---
 
-## Family: cart-drawer (`@cartbase/storefront/cart-drawer/*`) — SHIPPED
-
+## Family: cart-drawer (`@cartbase/storefront/cart-drawer/*`)
 Sliding cart UI, production-proven layout. All
 components are `"use client"`. Money is EUR decimal major units everywhere
 (cart totals are SERVER truth from the decorated cart — components render,
@@ -570,8 +571,8 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
 - **Purpose** — full totals breakdown rendered EXACTLY from the decorated
   cart: `subtotal`, `discount_total` (>0, negated for display),
   `shipping_total` (once a shipping method is set; 0 renders FREE; before
-  that "calculated at checkout"), `tax_total` (>0), `cod_fee_total` (>0,
-  labeled by the server's `cod_fee_label`), `total`, then one row per
+  that "calculated at checkout"), `tax_total` (>0), `payment_method_fee_total` (>0,
+  labeled by the server's `payment_method_fee_label`), `total`, then one row per
   applied gift card (masked `last4`, negated; a depleted card stays listed
   at 0) and `gift_card_remainder` — what the remainder provider charges.
   Row selection is the pure `selectSummaryRows(cart)` (unit-tested).
@@ -609,8 +610,7 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
 
 ---
 
-## Family: products (`@cartbase/storefront/products/*`) — SHIPPED
-
+## Family: products (`@cartbase/storefront/products/*`)
 The PDP + product-card family, production-proven. All prices
 render the SERVER-computed `variant.calculated_price` via
 `lib/get-product-price` (Cartbase's flat `price_list_type` wire shape) — no
@@ -668,7 +668,7 @@ components read copy only through the context or explicit `labels` props).
 `optionsAsKeymap` / `optionsMatch` / `findMatchingVariant` — the
 option-choice → variant resolution extracted from product-actions, reading
 Cartbase's option-value LINK shape (`variant.options[].value.{option_id,value}`)
-with the Medusa flat-row fallback. Unit-tested
+with a legacy flat-row fallback. Unit-tested
 (tests/unit/storefront-catalog.test.ts).
 
 ### `<ImageGallery images />` — `products/image-gallery`
@@ -754,8 +754,7 @@ with the Medusa flat-row fallback. Unit-tested
   `ProductLabelsProvider` for i18n; `addToCart`/`openCart` seams as on
   `ProductActions`.
 
-## Family: store (`@cartbase/storefront/store/*`) — SHIPPED
-
+## Family: store (`@cartbase/storefront/store/*`)
 The listing family: paginated grids, sort, collection/category/search
 templates. Sorting discipline: the API's `order` param is the authority for
 paginated listings; client-side re-sort (`lib/sort-products`) exists ONLY
@@ -859,9 +858,9 @@ search UIs (chips, drawers) that want the same URL contract.
 
 ---
 
-## Family: order (`@cartbase/storefront/order/*`) — SHIPPED
-
-Order confirmation + account order views, production-proven. The Medusa `StoreOrder` was ONE object carrying computed line
+## Family: order (`@cartbase/storefront/order/*`)
+Order confirmation + account order views, production-proven. Some
+platforms ship ONE `StoreOrder` object carrying computed line
 totals, order totals, shipping methods and payments; Cartbase splits those
 across surfaces, so the family takes them as separate props — the Cartbase
 `StoreOrderDetail` (`api/orders`) carries items as version-pivot rows
@@ -893,7 +892,7 @@ component also takes a `labels` prop pick.
   rybbit, deduped by `order.display_id`) is APP-OWNED: fire it from the
   confirmation route exactly once per order per the tracking family's
   dedupe contract — the template deliberately does NOT fire it.
-- **Settings** — COD settings (fee row presence + `cod_fee_label`),
+- **Settings** — COD settings (fee row presence + `payment_method_fee_label`),
   checkout rules (which provider ids appear), store locales (labels pack).
 
 ### `<OrderConfirmationHeader order />` — `order/order-confirmation-header`
@@ -916,19 +915,19 @@ component also takes a `labels` prop pick.
   COD fees are never line items, so on pure Cartbase data the filter is a
   no-op safety net. Newest-first sort by `createdAt` when present.
 
-### `<OrderTotals totals currencyCode items? codFeeLabel? />` — `order/order-totals`
+### `<OrderTotals totals currencyCode items? methodFeeLabel? />` — `order/order-totals`
 
 - **Purpose** — the money breakdown: Subtotal / Shipping (FREE badge at
   0) / COD fee / Discount (negated) / Tax / Total, all via `DualPrice`.
 - **Data seam** — `OrderTotalsSource` (the decorated cart satisfies it:
   `item_subtotal`, `shipping_subtotal`, `discount_total`, `tax_total`,
-  `total`, `cod_fee_total`, `cod_fee_label`); the summary snapshot adapts
+  `total`, `payment_method_fee_total`, `payment_method_fee_label`); the summary snapshot adapts
   via `orderTotalsFromSummary`. Row policy is the pure, unit-tested
-  `selectOrderTotalsRows`: native `cod_fee_total` wins over a legacy fee
+  `selectOrderTotalsRows`: native `payment_method_fee_total` wins over a legacy fee
   LINE; a legacy fee line's net is subtracted from the visible subtotal
-  (v2.3.1 production fix); COD label preference `codFeeLabel` prop →
-  server `cod_fee_label` → fee-line title → `labels.codFee`.
-- **Settings** — COD settings (`cod_fee_total`/`cod_fee_label`),
+  (v2.3.1 production fix); COD label preference `methodFeeLabel` prop →
+  server `payment_method_fee_label` → fee-line title → `labels.paymentMethodFee`.
+- **Settings** — COD settings (`payment_method_fee_total`/`payment_method_fee_label`),
   promotions (discount row).
 
 ### `<OrderAddressCard order />` — `order/order-address-card`
@@ -953,11 +952,13 @@ component also takes a `labels` prop pick.
 
 ### `<OrderPaymentCard providerId cardLast4? />` — `order/order-payment-card`
 
-- Payment method card; `resolvePaymentTitle` buckets the provider id via
-  `lib/payment-constants` (`pp_stripe` → card, `pp_system_default` → COD)
-  through the locale pack, falling back to `paymentInfoMap` then the raw
-  id. Payment internals never cross the Cartbase store surface — the id
-  arrives via props from checkout state.
+- Payment method card; `resolvePaymentTitle(providerId, titles,
+  methodName?)` — the method's merchant NAME wins verbatim when present
+  (the snapshot from session data); otherwise the processor id buckets
+  via `lib/payment-constants` (`pp_stripe` = card) through the locale
+  pack, falling back to `paymentInfoMap` then the raw id. Payment
+  internals never cross the Cartbase store surface — both arrive via
+  props from checkout state.
 
 ### `<OrderTimeline fulfillmentStatus? />` — `order/order-timeline`
 
@@ -974,8 +975,7 @@ component also takes a `labels` prop pick.
 
 ---
 
-## Family: common (`@cartbase/storefront/common/*`) — SHIPPED
-
+## Family: common (`@cartbase/storefront/common/*`)
 Shared storefront chrome, production-proven.
 
 ### `<LocalizedLink href … />` — `common/localized-link`
@@ -1027,8 +1027,7 @@ Shared storefront chrome, production-proven.
 
 ---
 
-## Family: reviews-ui (`@cartbase/storefront/reviews-ui`) — SHIPPED
-
+## Family: reviews-ui (`@cartbase/storefront/reviews-ui`)
 Verified-purchase review components, ported from a production storefront,
 over `api/reviews`. ONE barrel export seam: everything imports from
 `@cartbase/storefront/reviews-ui`. Endpoint truth:

package/template/app/docs/consent.md

@@ -1,4 +1,4 @@
-# Consent — Consent Mode v2 banner config
+# Consent
 
 The store's CMP configuration for the built-in Consent Mode v2 banner
 (consent-management card). Defaults are **always applied server-side**, so

package/template/app/docs/content.md

@@ -1,4 +1,4 @@
-# Content — pages + blogs
+# Content
 
 Shopify Storefront `Page` / `Article` shapes **verbatim** so storefront code
 ports 1:1. **PUBLISHED only** — drafts and deleted rows 404 (lib status

package/template/app/docs/customers.md

@@ -1,4 +1,4 @@
-# Customers — profile, addresses, documents
+# Customers
 
 The signed-in customer surface. Every endpoint here requires a **customer
 session**: `authorization: Bearer <supabase jwt>` (minted by the

package/template/app/docs/deploy.md

@@ -1,4 +1,4 @@
-# Deploy & hosting
+# Deploy
 
 Cartbase builds and hosts your storefront. You send the app's source files
 — one snapshot of the whole project — and Cartbase turns it into a
@@ -25,7 +25,7 @@ headers the rest of this corpus uses. In practice you'll deploy through
 the admin UI (**Storefront** in the sidebar), the Cartbase CLI, or an
 agent connection — all three are wrappers over exactly these calls.
 Users who belong to several stores name the target store with an
-`x-barter-store: <client-id>` header.
+`x-cartbase-store: <client-id>` header.
 
 ## What a deploy is
 
@@ -62,9 +62,9 @@ anyway):
 
 | Variable | Value |
 |---|---|
-| `NEXT_PUBLIC_BARTER_URL` | The store's API origin |
-| `NEXT_PUBLIC_BARTER_CLIENT_ID` | The store's client id |
-| `NEXT_PUBLIC_BARTER_PUBLISHABLE_KEY` | The store's publishable key, when one exists |
+| `NEXT_PUBLIC_CARTBASE_URL` | The store's API origin |
+| `NEXT_PUBLIC_CARTBASE_CLIENT_ID` | The store's client id |
+| `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` | The store's publishable key, when one exists |
 
 Only these public values ever reach a storefront build — secret keys are
 never injected, so code that expects one is a design error.

package/template/app/docs/gift-cards.md

@@ -1,4 +1,4 @@
-# Gift cards — tender on carts
+# Gift cards
 
 Gift-card redemption is a **payment tender** (`pp_giftcard`), never a
 discount: cart totals and VAT compute first and **never move**; applied

package/template/app/docs/integrations.md

@@ -1,4 +1,4 @@
-# Store integrations config — carriers, COD, tracking, lockers
+# Integrations
 
 Store-public integration configuration for render/checkout time
 (couriers-port + tracking-integrations cards). The payload is **composed**

package/template/app/docs/menus.md

@@ -1,4 +1,4 @@
-# Menus — backend-owned navigation
+# Menus
 
 Shopify Storefront `Menu` shape **verbatim** (content-navigation card).
 Items store a typed resource reference; `url` is **computed at read time**

package/template/app/docs/metaobjects.md

@@ -1,4 +1,4 @@
-# Metaobjects — merchant-defined content types
+# Metaobjects
 
 Merchant-defined structured content (size charts, brand profiles, FAQ
 blocks) served by TYPE + HANDLE (metaobjects card). **ACTIVE entries only —

package/template/app/docs/orders.md

@@ -1,4 +1,4 @@
-# Orders — customer reads + transfers
+# Orders
 
 The authenticated customer's order surface: list, detail (items +
 fulfillments with tracking + addresses) and order transfers. There is **no

package/template/app/docs/platform.md

@@ -0,0 +1,126 @@
+# Platform fingerprints
+
+Every Cartbase-powered storefront emits a small, deliberate set of signals
+so platform-detection tools (Wappalyzer, BuiltWith) classify the site as
+**Ecommerce** — the same mechanism Shopify uses (`window.Shopify`,
+`X-ShopId`, `_shopify_s`). Full spec: `docs/cards/platform-fingerprints.md`.
+Category discipline: these are the ONLY signals emitted — nothing that
+reads as a framework, CMS, or website builder, and NEVER on `/api/admin/*`.
+
+SDK modules: `@cartbase/storefront/platform`, `@cartbase/storefront/lib/cookie-names`.
+
+---
+
+## Response header — `x-cartbase-version`
+
+- **Purpose** — every `/api/store/*` response carries the platform version,
+  so a single HTTP response proves the platform without loading a page.
+- **Auth** — none required to observe the header; it's stamped regardless
+  of whether the underlying call succeeds or errors (both `withLogging`
+  return paths).
+- **Value** — the platform's own semver (`src/lib/platform/identity.ts` →
+  `PLATFORM_VERSION`).
+- **Scope** — `/api/store/*` only. `/api/admin/*` never carries it (admin
+  is not a storefront).
+
+```bash
+# A successful call carries the header.
+HEADERS=$(curl -sfD - -o /dev/null "$BASE/api/store/consent" -H "x-client-id: $CLIENT_ID")
+echo "$HEADERS" | grep -qi '^x-cartbase-version: '
+
+# An ERROR response (missing x-client-id → 400 missing_client_id) still
+# carries it — the fingerprint is not a happy-path-only afterthought.
+ERR_HEADERS=$(curl -sD - -o /dev/null "$BASE/api/store/consent")
+echo "$ERR_HEADERS" | grep -qi '^x-cartbase-version: '
+
+# Admin surface never carries it (even though the same withLogging wrapper
+# runs the admin route too, once auth resolves).
+ADMIN_HEADERS=$(curl -sD - -o /dev/null "$BASE/api/admin/users/me")
+! echo "$ADMIN_HEADERS" | grep -qi '^x-cartbase-version: '
+```
+
+---
+
+## Meta tag — `<meta name="generator" content="Cartbase" />`
+
+- **Purpose** — the classic "what built this site" signal, read by every
+  detection tool's HTML scanner.
+- **SDK** — `createStorefrontMetadata(overrides?: Metadata): Metadata`
+  (`@cartbase/storefront/platform`). Call it in the root layout instead of
+  hand-writing `export const metadata` — `generator` always resolves to
+  `PLATFORM_NAME` ("Cartbase") and cannot be shadowed by a stray key in
+  `overrides` (the helper's own assignment applies AFTER the spread).
+- **Components** — every storefront's `app/layout.tsx` (see
+  `examples/storefront/src/app/layout.tsx` for the reference wiring).
+
+```ts
+// app/layout.tsx
+import { createStorefrontMetadata } from "@cartbase/storefront/platform"
+
+export const metadata: Metadata = createStorefrontMetadata({
+  title: "My Store",
+  description: "...",
+})
+// → renders <meta name="generator" content="Cartbase" /> on every page
+```
+
+This is a build-time Next.js Metadata API call, not a store-API endpoint —
+no curl to demonstrate; verified by
+`tests/unit/storefront-lib.test.ts` ("platform — generator metadata +
+window.Cartbase").
+
+---
+
+## JS global — `window.Cartbase`
+
+- **Purpose** — the strongest detector signal (how `window.Shopify` works):
+  a synchronous inline script sets `window.Cartbase = {version, storeId}`
+  before hydration.
+- **Shape** — `{ version: string, storeId: string }`. No PII, no email, no
+  secret — store id + platform version only.
+- **SDK** — `<PlatformInit storeId={...} />` (`@cartbase/storefront/platform`),
+  a server component shaped exactly like `<ConsentInit />`
+  (`@cartbase/storefront/tracking/consent-init`): one synchronous inline
+  `<script>`, mounted once near the top of `<body>`.
+- **Components** — mount once per app, next to `<ConsentInit />`. Never
+  mount in an admin bundle.
+
+```tsx
+// app/layout.tsx, inside <body>, first children:
+<ConsentInit />
+<PlatformInit storeId={CARTBASE_CLIENT_ID} />
+```
+
+Also build-time/render-only — no store-API curl to demonstrate; the exact
+script shape (`window.Cartbase={"version":"...","storeId":"..."};`, no
+extra keys) is verified by `tests/unit/storefront-lib.test.ts`.
+
+---
+
+## Cookies — `_cartbase_cart` (was `_barter_cart_id`)
+
+- **Purpose** — the cart-id cookie. The app still OWNS *setting* it (the
+  SDK never persists the cart — see [carts.md](carts.md)); the library
+  owns the NAME so every consumer emits the same fingerprint instead of
+  inventing its own prefix.
+- **SDK** — `CART_COOKIE`, `LEGACY_CART_COOKIE`, `readCartCookie(get)`
+  (`@cartbase/storefront/lib/cookie-names`). `readCartCookie` prefers the
+  new name and falls back to the legacy `_barter_cart_id` name, so an
+  existing visitor's cart survives the rename. Every WRITE uses the new
+  name only.
+- **`SESSION_COOKIE` (`_cartbase_session`)** — the name is reserved for a
+  future cookie-backed customer session. Nothing sets it today: auth is
+  pure Bearer-JWT, persisted by the consuming app (see
+  [auth.md](auth.md)). Defined now so a future session mechanism launches
+  with the fingerprint-correct name.
+
+```ts
+import { CART_COOKIE, readCartCookie } from "@cartbase/storefront/lib/cookie-names"
+
+const cartId = readCartCookie((name) => jar.get(name)?.value) // reads either name
+jar.set(CART_COOKIE, cart.id, { path: "/", maxAge: THIRTY_DAYS }) // writes the new name only
+```
+
+No store-API curl to demonstrate (this is a client-cookie contract, not a
+server response); verified by `tests/unit/storefront-lib.test.ts`
+("platform — cookie names + back-compat read").

package/template/app/docs/products.md

@@ -1,4 +1,4 @@
-# Products & variants
+# Products
 
 The catalog read surface. The product object documented here is THE
 canonical shape every discovery endpoint reuses (search results, collection

package/template/app/docs/redirects.md

@@ -1,4 +1,4 @@
-# URL redirects — 404-path lookup
+# Redirects
 
 Exact-match redirect lookup (seo-listings card 21). **Hot-path rule: call
 this ONLY from the storefront's not-found handler** — never on regular page

package/template/app/docs/regions.md

@@ -1,4 +1,4 @@
-# Regions, currencies, locales
+# Regions
 
 Catalog-context primitives a storefront resolves at boot: regions feed the
 pricing context (`region_id` → region currency), currencies tell you what the
@@ -29,8 +29,8 @@ SDK module: `@cartbase/storefront/api/regions`.
 ```
 
 - **Response** — ordered by name. NOTE: Cartbase regions carry NO embedded
-  `countries` array (divergence from Medusa's Store API — country/tax scope
-  lives server-side in `tax_regions`).
+  `countries` array — country/tax scope lives server-side in
+  `tax_regions`.
 
 ```jsonc
 {
@@ -202,6 +202,5 @@ echo "$LOCALES" | grep -q '"en"'
 - **Errors** — 400 `missing_client_id`.
 - **SDK** — `listLocales(client)`.
 - **Components** — locale switcher; `StorefrontClient`'s `getLocale` hook.
-- **Settings** — Admin → Settings → Store → locales (per-store
-  `store_locales` manager; Cartbase's intentional divergence from Medusa's
-  global locale catalog).
+- **Settings** — Admin → Settings → Store → locales (each store manages
+  its own locale list in `store_locales`).

package/template/app/docs/reviews.md

@@ -1,4 +1,4 @@
-# Reviews — widget, token wizard, photo rewards
+# Reviews
 
 Verified-purchase reviews. Reviews exist **only** via a
 single-use, order-scoped, expiring **token** minted by the request scanner

package/template/app/docs/search.md

@@ -1,4 +1,4 @@
-# Search & related products
+# Search
 
 Configurable storefront search (search-discovery card) plus the PDP's
 related-products rail. Results are the SAME canonical product objects the

package/template/app/docs/subscriptions.md

@@ -1,4 +1,4 @@
-# Subscriptions — the customer portal
+# Subscriptions
 
 The "My subscriptions" surface (subscriptions-portal card): list, detail,
 schedule control, contract edits, cancel/reactivate and payment-method