create-cartbase 0.1.0 → 0.1.1

package/dist/index.js

@@ -68,9 +68,9 @@ as flags they are written into .env.local, otherwise placeholders are.`);
     const key = typeof flags.get("key") === "string" ? flags.get("key") : "";
     fs.writeFileSync(path.join(target, ".env.local"), [
         "# Your store's inputs — Cartbase admin, Settings.",
-        `NEXT_PUBLIC_BARTER_URL=${url}`,
-        `NEXT_PUBLIC_BARTER_CLIENT_ID=${clientId}`,
-        `NEXT_PUBLIC_BARTER_PUBLISHABLE_KEY=${key}`,
+        `NEXT_PUBLIC_CARTBASE_URL=${url}`,
+        `NEXT_PUBLIC_CARTBASE_CLIENT_ID=${clientId}`,
+        `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=${key}`,
         "",
     ].join("\n"));
     const filled = url && clientId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/BUILD-A-STOREFRONT.md

@@ -12,9 +12,9 @@ What you need before starting (all three are in your Cartbase admin under
 
 | Input | Example | Where it goes |
 |---|---|---|
-| API origin | `https://admin.bitfar.co` | `NEXT_PUBLIC_BARTER_URL` |
-| Store client id | `1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd` (uuid) | `NEXT_PUBLIC_BARTER_CLIENT_ID` |
-| Publishable API key | `pk_…` (optional, channel scope) | `NEXT_PUBLIC_BARTER_PUBLISHABLE_KEY` |
+| API origin | `https://admin.bitfar.co` | `NEXT_PUBLIC_CARTBASE_URL` |
+| Store client id | `1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd` (uuid) | `NEXT_PUBLIC_CARTBASE_CLIENT_ID` |
+| Publishable API key | `pk_…` (optional, channel scope) | `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` |
 
 Sanity-check the store before writing any code:
 
@@ -73,7 +73,7 @@ whole checkout orchestration) only work same-origin. Unless your
 storefront is served from the Cartbase deployment origin itself, proxy the
 store surface through your own origin — in Next.js one rewrite does it —
 and give the BROWSER client `window.location.origin` as `baseUrl`
-(server-side calls hit `NEXT_PUBLIC_BARTER_URL` directly and are
+(server-side calls hit `NEXT_PUBLIC_CARTBASE_URL` directly and are
 unaffected; see `examples/storefront/next.config.ts` for the working
 rewrite):
 
@@ -81,7 +81,7 @@ rewrite):
 // next.config.ts — proxy browser SDK traffic to the API origin
 async rewrites() {
   return [{ source: "/api/store/:path*",
-            destination: `${process.env.NEXT_PUBLIC_BARTER_URL}/api/store/:path*` }]
+            destination: `${process.env.NEXT_PUBLIC_CARTBASE_URL}/api/store/:path*` }]
 }
 ```
 

package/template/app/docs/README.md

@@ -1,76 +1,77 @@
-# docs/storefront/ — the bulletproof storefront docs
-
-**Audience: an AGENT building a storefront from a blank Next.js app.** These
-docs are the entire knowledge transfer — every call shape, every curl, every
-setting, every component contract. If a storefront can't be built from these
-files alone, the fix is a doc fix, never tribal knowledge.
-
-Start at **[BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md)** — the runbook.
-Domain files below are its reference chapters.
-
-## Executable-docs contract (docs-truth CI)
-
-Docs that can lie aren't bulletproof, so every ```bash block in every file
-here is **extracted and executed** against the real test server by
-`tests/docs/storefront-curls.test.ts`. A drifted doc FAILS the build.
-
-Rules for doc authors (agents included):
-
-1. All ```bash blocks in one file form ONE script, executed top-to-bottom
-   with `bash -euo pipefail`. Later blocks may use variables exported by
-   earlier blocks (`CART_ID=$(curl … | grep -o …)`).
-2. The harness pre-exports: `BASE` (test-server origin), `CLIENT_ID` (dev
-   tenant id), `PUBLISHABLE_KEY` (the B2B-channel dev key — channel-scoped,
-   use only where the doc discusses key scoping).
-3. Every curl uses `-sf` (silent + fail-on-HTTP-error) unless the block
-   demonstrates an error case — then capture the status explicitly
-   (`-o /dev/null -w '%{http_code}'`) and assert it (`test "$STATUS" = 404`).
-4. Assert shape, not just liveness: pipe to `grep -q '"key"'` (or `node -e`
-   for anything structural). A block that checks nothing proves nothing.
-5. A block that must NOT run (illustrative only, external side effects)
-   starts with `# doc-noexec` on its first line. Use sparingly — every
-   noexec block is a hole in the truth gate.
-6. Blocks must be idempotent-safe on the shared dev tenant: create what you
-   read, suffix names with `$RUN` (pre-exported unique stamp), and clean up
-   in a final block when you created durable rows.
-
-## Per-domain file format
-
-One file per domain. For each endpoint, in order:
-
-- **Purpose** — one sentence, when a storefront calls it.
-- **Auth** — which headers (anon `x-client-id` / publishable key / Bearer).
-- **Request** — method, path, query/body shape (jsonc block).
-- **Response** — shape (jsonc block), with field notes.
-- **Working curl** — executable per the contract above.
-- **Errors** — status + `code` for every contract-listed failure.
-- **SDK** — the `@cartbase/storefront/api` function that wraps it.
-- **Components** — which `@cartbase/storefront` UI components consume it.
-- **Settings** — admin settings that change its behavior (checkout rules,
-  locales, consent, accounts mode…).
-
-## Files
-
-| File | Domain |
-|---|---|
-| [BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md) | The agent runbook — blank app → completed checkout |
-| [products.md](products.md) | Products, variants, pricing context |
-| [search.md](search.md) | Search, facets, related products |
-| [collections.md](collections.md) | Collections + membership listings |
-| [categories.md](categories.md) | Categories, tags, types |
-| [regions.md](regions.md) | Regions, currencies, locales |
-| [carts.md](carts.md) | Cart lifecycle + line items |
-| [gift-cards.md](gift-cards.md) | Gift-card tender on carts |
-| [checkout.md](checkout.md) | Shipping options, payment providers/collections, prepare-checkout orchestration, complete |
-| [orders.md](orders.md) | Order reads, display-id lookup, transfers |
-| [customers.md](customers.md) | Customer profile, addresses, documents |
-| [subscriptions.md](subscriptions.md) | Subscription portal: schedule control, contract edits, payment-method recovery |
-| [auth.md](auth.md) | Passwordless code login + session discipline |
-| [content.md](content.md) | Pages + blogs |
-| [menus.md](menus.md) | Navigation menus |
-| [metaobjects.md](metaobjects.md) | Merchant-defined content types |
-| [reviews.md](reviews.md) | Review widget, token wizard, photo rewards |
-| [integrations.md](integrations.md) | Store config: carriers, COD, tracking block, lockers |
-| [consent.md](consent.md) | Consent Mode v2 banner config |
-| [redirects.md](redirects.md) | 404-path URL redirects |
-| [components.md](components.md) | UI component families: contracts + required SDK calls |
+# docs/storefront/ — the bulletproof storefront docs
+
+**Audience: an AGENT building a storefront from a blank Next.js app.** These
+docs are the entire knowledge transfer — every call shape, every curl, every
+setting, every component contract. If a storefront can't be built from these
+files alone, the fix is a doc fix, never tribal knowledge.
+
+Start at **[BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md)** — the runbook.
+Domain files below are its reference chapters.
+
+## Executable-docs contract (docs-truth CI)
+
+Docs that can lie aren't bulletproof, so every ```bash block in every file
+here is **extracted and executed** against the real test server by
+`tests/docs/storefront-curls.test.ts`. A drifted doc FAILS the build.
+
+Rules for doc authors (agents included):
+
+1. All ```bash blocks in one file form ONE script, executed top-to-bottom
+   with `bash -euo pipefail`. Later blocks may use variables exported by
+   earlier blocks (`CART_ID=$(curl … | grep -o …)`).
+2. The harness pre-exports: `BASE` (test-server origin), `CLIENT_ID` (dev
+   tenant id), `PUBLISHABLE_KEY` (the B2B-channel dev key — channel-scoped,
+   use only where the doc discusses key scoping).
+3. Every curl uses `-sf` (silent + fail-on-HTTP-error) unless the block
+   demonstrates an error case — then capture the status explicitly
+   (`-o /dev/null -w '%{http_code}'`) and assert it (`test "$STATUS" = 404`).
+4. Assert shape, not just liveness: pipe to `grep -q '"key"'` (or `node -e`
+   for anything structural). A block that checks nothing proves nothing.
+5. A block that must NOT run (illustrative only, external side effects)
+   starts with `# doc-noexec` on its first line. Use sparingly — every
+   noexec block is a hole in the truth gate.
+6. Blocks must be idempotent-safe on the shared dev tenant: create what you
+   read, suffix names with `$RUN` (pre-exported unique stamp), and clean up
+   in a final block when you created durable rows.
+
+## Per-domain file format
+
+One file per domain. For each endpoint, in order:
+
+- **Purpose** — one sentence, when a storefront calls it.
+- **Auth** — which headers (anon `x-client-id` / publishable key / Bearer).
+- **Request** — method, path, query/body shape (jsonc block).
+- **Response** — shape (jsonc block), with field notes.
+- **Working curl** — executable per the contract above.
+- **Errors** — status + `code` for every contract-listed failure.
+- **SDK** — the `@cartbase/storefront/api` function that wraps it.
+- **Components** — which `@cartbase/storefront` UI components consume it.
+- **Settings** — admin settings that change its behavior (checkout rules,
+  locales, consent, accounts mode…).
+
+## Files
+
+| File | Domain |
+|---|---|
+| [BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md) | The agent runbook — blank app → completed checkout |
+| [products.md](products.md) | Products, variants, pricing context |
+| [search.md](search.md) | Search, facets, related products |
+| [collections.md](collections.md) | Collections + membership listings |
+| [categories.md](categories.md) | Categories, tags, types |
+| [regions.md](regions.md) | Regions, currencies, locales |
+| [carts.md](carts.md) | Cart lifecycle + line items |
+| [gift-cards.md](gift-cards.md) | Gift-card tender on carts |
+| [checkout.md](checkout.md) | Shipping options, payment providers/collections, prepare-checkout orchestration, complete |
+| [orders.md](orders.md) | Order reads, display-id lookup, transfers |
+| [customers.md](customers.md) | Customer profile, addresses, documents |
+| [subscriptions.md](subscriptions.md) | Subscription portal: schedule control, contract edits, payment-method recovery |
+| [auth.md](auth.md) | Passwordless code login + session discipline |
+| [content.md](content.md) | Pages + blogs |
+| [menus.md](menus.md) | Navigation menus |
+| [metaobjects.md](metaobjects.md) | Merchant-defined content types |
+| [reviews.md](reviews.md) | Review widget, token wizard, photo rewards |
+| [integrations.md](integrations.md) | Store config: carriers, COD, tracking block, lockers |
+| [consent.md](consent.md) | Consent Mode v2 banner config |
+| [redirects.md](redirects.md) | 404-path URL redirects |
+| [components.md](components.md) | UI component families: contracts + required SDK calls |
+| [platform.md](platform.md) | Platform fingerprints: generator meta, window.Cartbase, x-cartbase-version header, cart cookie naming |

package/template/app/docs/carts.md

@@ -305,11 +305,11 @@ curl -sf -X DELETE "$BASE/api/store/carts/$CART_ID/line-items/$LINE_ID" \
   cart promotion and recomputes totals (automatic promotions layer in on
   their own — only coded ones travel through here).
 - **Auth** — anon `x-client-id`.
-- **Request** — `{promo_codes: string[]}` on BOTH verbs (Medusa reads the
-  DELETE body, not query).
+- **Request** — `{promo_codes: string[]}` on BOTH verbs (the DELETE reads
+  its body, not query params).
 - **Response** — `200 {cart}` (decorated; `cart.promotions` is the raw
   pivot embed `[{promotion: {...}}]`). Unknown codes on REMOVE silently
-  no-op (Medusa parity); on ADD they error.
+  no-op by design; on ADD they error.
 - **Errors** — 404 `cart_not_found`; 404 `promotion_not_found` (unknown
   code on add), 400 `promotion_inactive` (draft/expired code on add), 400
   zod (empty array / non-string entries).

package/template/app/docs/checkout.md

@@ -35,7 +35,7 @@ While checkout stays mounted: `syncPaymentAmount()` after anything that
 changes the total; `refreshPaymentIfTerminal()` from Stripe Elements
 `loaderror` (never proactively).
 
-**Manual (Medusa-style, for custom flows):** `updateCart` (address+email) →
+**Manual (step-by-step, for custom flows):** `updateCart` (address+email) →
 `addShippingMethod` → `createPaymentCollection` → `initiatePaymentSession`
 → `completeCart`. Both paths are executed against the live server below.
 
@@ -430,7 +430,7 @@ curl -sf -X POST "$BASE/api/store/carts/$CART_ID/refresh-payment-if-terminal" \
 
 ---
 
-## Manual path — collections + sessions (Medusa-style)
+## Manual path — collections + sessions (step-by-step)
 
 ### POST /api/store/payment-collections
 

package/template/app/docs/components.md

@@ -195,7 +195,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.
@@ -206,11 +206,11 @@ format.
   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;
+  (code truth `src/lib/stripe/providers.ts`) plus legacy provider prefixes;
   `pp_system_default` = COD. Affected by: enabled payment providers +
   checkout rules (which ids 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).
@@ -303,7 +303,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);
@@ -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`
@@ -861,7 +861,8 @@ 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
+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

package/template/app/docs/deploy.md

@@ -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/platform.md

@@ -0,0 +1,126 @@
+# Platform fingerprints — Cartbase detection
+
+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/regions.md

@@ -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/next.config.ts

@@ -15,12 +15,12 @@ const nextConfig: NextConfig = {
     // A real store should allowlist its media domain via remotePatterns.
     unoptimized: true,
   },
-  // The barter store API ships NO CORS headers — browser-side SDK calls
+  // The Cartbase store API ships NO CORS headers — browser-side SDK calls
   // must be same-origin. Proxy them through the app origin (the browser
   // client's baseUrl is window.location.origin); server-side SDK calls go
-  // straight to NEXT_PUBLIC_BARTER_URL and are unaffected.
+  // straight to NEXT_PUBLIC_CARTBASE_URL and are unaffected.
   async rewrites() {
-    const barterUrl = process.env.NEXT_PUBLIC_BARTER_URL
+    const barterUrl = process.env.NEXT_PUBLIC_CARTBASE_URL
     if (!barterUrl) return []
     return [
       {

package/template/app/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.1.0",
+    "@cartbase/storefront": "^0.2.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/src/app/checkout/page.tsx

@@ -1,49 +1,51 @@
-import { cookies } from "next/headers"
-import { redirect } from "next/navigation"
-import { retrieveCart } from "@cartbase/storefront/api/carts"
-import {
-  listPaymentProviders,
-  listShippingOptions,
-} from "@cartbase/storefront/api/checkout"
-import { getIntegrationsConfig } from "@cartbase/storefront/api/integrations"
-import { CART_COOKIE } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-import { CheckoutPageClient } from "./checkout-page-client"
-
-/**
- * Checkout (runbook step 8 / checkout.md): list shipping options and
- * payment providers WITH `cart_id` (server-side rule filtering), fetch the
- * integrations `cod` block, and hand everything to the orchestrated
- * client layout. Redirect completed/missing carts server-side
- * (checkout-client mount rule).
- */
-export default async function CheckoutPage() {
-  const jar = await cookies()
-  const cartId = jar.get(CART_COOKIE)?.value
-  if (!cartId) redirect("/")
-
-  const client = await getServerClient()
-  const cart = await retrieveCart(client, cartId)
-    .then((res) => res.cart)
-    .catch(() => null)
-  if (!cart || (cart.items ?? []).length === 0) redirect("/")
-  if (cart.completed_at) redirect("/")
-
-  const [shippingOptions, paymentProviders, integrations] = await Promise.all([
-    listShippingOptions(client, { cart_id: cart.id }),
-    listPaymentProviders(client, {
-      cart_id: cart.id,
-      region_id: cart.region_id ?? undefined,
-    }),
-    getIntegrationsConfig(client),
-  ])
-
-  return (
-    <CheckoutPageClient
-      cart={cart}
-      shippingOptions={shippingOptions.shipping_options}
-      paymentProviders={paymentProviders.payment_providers}
-      codConfig={integrations.cod}
-    />
-  )
-}
+import { cookies } from "next/headers"
+import { redirect } from "next/navigation"
+import { retrieveCart } from "@cartbase/storefront/api/carts"
+import {
+  listPaymentProviders,
+  listShippingOptions,
+} from "@cartbase/storefront/api/checkout"
+import { getIntegrationsConfig } from "@cartbase/storefront/api/integrations"
+import { readCartCookie } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+import { CheckoutPageClient } from "./checkout-page-client"
+
+/**
+ * Checkout (runbook step 8 / checkout.md): list shipping options and
+ * payment providers WITH `cart_id` (server-side rule filtering), fetch the
+ * integrations `cod` block, and hand everything to the orchestrated
+ * client layout. Redirect completed/missing carts server-side
+ * (checkout-client mount rule).
+ */
+export default async function CheckoutPage() {
+  const jar = await cookies()
+  // Back-compat: prefer `_cartbase_cart`, fall back to the legacy
+  // `_barter_cart_id` name (platform-fingerprints card).
+  const cartId = readCartCookie((name) => jar.get(name)?.value)
+  if (!cartId) redirect("/")
+
+  const client = await getServerClient()
+  const cart = await retrieveCart(client, cartId)
+    .then((res) => res.cart)
+    .catch(() => null)
+  if (!cart || (cart.items ?? []).length === 0) redirect("/")
+  if (cart.completed_at) redirect("/")
+
+  const [shippingOptions, paymentProviders, integrations] = await Promise.all([
+    listShippingOptions(client, { cart_id: cart.id }),
+    listPaymentProviders(client, {
+      cart_id: cart.id,
+      region_id: cart.region_id ?? undefined,
+    }),
+    getIntegrationsConfig(client),
+  ])
+
+  return (
+    <CheckoutPageClient
+      cart={cart}
+      shippingOptions={shippingOptions.shipping_options}
+      paymentProviders={paymentProviders.payment_providers}
+      codConfig={integrations.cod}
+    />
+  )
+}

package/template/app/src/app/layout.tsx

@@ -1,105 +1,113 @@
-import type { Metadata } from "next"
-import Link from "next/link"
-import { cookies } from "next/headers"
-import { retrieveCart, type Cart } from "@cartbase/storefront/api/carts"
-import { getConsent } from "@cartbase/storefront/api/consent"
-import { getMenu, type Menu } from "@cartbase/storefront/api/menus"
-import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
-import { CartButtonClient } from "@cartbase/storefront/common/cart-button-client"
-import { CART_COOKIE } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-import { Providers } from "./providers"
-import "./globals.css"
-
-export const metadata: Metadata = {
-  title: "Barter Example Store",
-  description: "Reference storefront built on @cartbase/storefront",
-}
-
-/**
- * Runbook steps 3–4: bootstrap store config at layout level, then mount
- * order inside <body>: ConsentInit FIRST (static, synchronous), then the
- * consent-gated UI, then navigation. A store with no menus 404s every
- * handle — render no nav, never crash (menus.md).
- */
-async function fetchMenu(handle: string): Promise<Menu | null> {
-  const client = await getServerClient()
-  try {
-    const { menu } = await getMenu(client, handle)
-    return menu
-  } catch {
-    return null // unknown/deleted handle (404) → graceful "no nav"
-  }
-}
-
-function MenuNav({ menu }: { menu: Menu | null }) {
-  if (!menu || menu.items.length === 0) return null
-  return (
-    <nav className="flex items-center gap-4">
-      {menu.items.map((item) => (
-        <Link
-          key={`${item.title}-${item.url}`}
-          href={item.url}
-          className="text-sm text-muted-foreground hover:text-foreground"
-        >
-          {item.title}
-        </Link>
-      ))}
-    </nav>
-  )
-}
-
-export default async function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  const client = await getServerClient()
-  const jar = await cookies()
-  const cartId = jar.get(CART_COOKIE)?.value ?? null
-
-  const [consentRes, mainMenu, footerMenu, cart] = await Promise.all([
-    getConsent(client),
-    fetchMenu("main-menu"),
-    fetchMenu("footer"),
-    cartId
-      ? retrieveCart(client, cartId)
-          .then((res): Cart | null => res.cart)
-          .catch(() => null) // stale cookie → empty cart state
-      : Promise.resolve(null),
-  ])
-
-  return (
-    <html lang="en">
-      <body>
-        <ConsentInit />
-        <Providers cart={cart} consent={consentRes.consent}>
-          <header className="border-b border-border">
-            <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between gap-6">
-              <Link href="/" className="font-semibold text-lg">
-                Barter Example Store
-              </Link>
-              <div className="flex items-center gap-6">
-                <MenuNav menu={mainMenu} />
-                <Link
-                  href="/search"
-                  className="text-sm text-muted-foreground hover:text-foreground"
-                >
-                  Search
-                </Link>
-                <CartButtonClient cart={cart} />
-              </div>
-            </div>
-          </header>
-          <main>{children}</main>
-          <footer className="border-t border-border mt-12">
-            <div className="max-w-7xl mx-auto px-4 py-8 text-sm text-muted-foreground flex items-center justify-between">
-              <span>Barter Example Store</span>
-              <MenuNav menu={footerMenu} />
-            </div>
-          </footer>
-        </Providers>
-      </body>
-    </html>
-  )
-}
+import type { Metadata } from "next"
+import Link from "next/link"
+import { cookies } from "next/headers"
+import { retrieveCart, type Cart } from "@cartbase/storefront/api/carts"
+import { getConsent } from "@cartbase/storefront/api/consent"
+import { getMenu, type Menu } from "@cartbase/storefront/api/menus"
+import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
+import { CartButtonClient } from "@cartbase/storefront/common/cart-button-client"
+import { createStorefrontMetadata, PlatformInit } from "@cartbase/storefront/platform"
+import { BARTER_CLIENT_ID, readCartCookie } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+import { Providers } from "./providers"
+import "./globals.css"
+
+// createStorefrontMetadata (platform-fingerprints card) stamps
+// `<meta name="generator" content="Cartbase" />` on every page — never
+// hand-write `generator` here.
+export const metadata: Metadata = createStorefrontMetadata({
+  title: "Barter Example Store",
+  description: "Reference storefront built on @cartbase/storefront",
+})
+
+/**
+ * Runbook steps 3–4: bootstrap store config at layout level, then mount
+ * order inside <body>: ConsentInit FIRST (static, synchronous), then the
+ * consent-gated UI, then navigation. A store with no menus 404s every
+ * handle — render no nav, never crash (menus.md).
+ */
+async function fetchMenu(handle: string): Promise<Menu | null> {
+  const client = await getServerClient()
+  try {
+    const { menu } = await getMenu(client, handle)
+    return menu
+  } catch {
+    return null // unknown/deleted handle (404) → graceful "no nav"
+  }
+}
+
+function MenuNav({ menu }: { menu: Menu | null }) {
+  if (!menu || menu.items.length === 0) return null
+  return (
+    <nav className="flex items-center gap-4">
+      {menu.items.map((item) => (
+        <Link
+          key={`${item.title}-${item.url}`}
+          href={item.url}
+          className="text-sm text-muted-foreground hover:text-foreground"
+        >
+          {item.title}
+        </Link>
+      ))}
+    </nav>
+  )
+}
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const client = await getServerClient()
+  const jar = await cookies()
+  // Back-compat: prefer the new `_cartbase_cart` cookie, fall back to the
+  // legacy `_barter_cart_id` name so an existing visitor's cart survives
+  // the rename (platform-fingerprints card).
+  const cartId = readCartCookie((name) => jar.get(name)?.value) ?? null
+
+  const [consentRes, mainMenu, footerMenu, cart] = await Promise.all([
+    getConsent(client),
+    fetchMenu("main-menu"),
+    fetchMenu("footer"),
+    cartId
+      ? retrieveCart(client, cartId)
+          .then((res): Cart | null => res.cart)
+          .catch(() => null) // stale cookie → empty cart state
+      : Promise.resolve(null),
+  ])
+
+  return (
+    <html lang="en">
+      <body>
+        <ConsentInit />
+        <PlatformInit storeId={BARTER_CLIENT_ID} />
+        <Providers cart={cart} consent={consentRes.consent}>
+          <header className="border-b border-border">
+            <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between gap-6">
+              <Link href="/" className="font-semibold text-lg">
+                Barter Example Store
+              </Link>
+              <div className="flex items-center gap-6">
+                <MenuNav menu={mainMenu} />
+                <Link
+                  href="/search"
+                  className="text-sm text-muted-foreground hover:text-foreground"
+                >
+                  Search
+                </Link>
+                <CartButtonClient cart={cart} />
+              </div>
+            </div>
+          </header>
+          <main>{children}</main>
+          <footer className="border-t border-border mt-12">
+            <div className="max-w-7xl mx-auto px-4 py-8 text-sm text-muted-foreground flex items-center justify-between">
+              <span>Barter Example Store</span>
+              <MenuNav menu={footerMenu} />
+            </div>
+          </footer>
+        </Providers>
+      </body>
+    </html>
+  )
+}

package/template/app/src/lib/cart-actions.ts

@@ -1,43 +1,47 @@
-"use server"
-
-import { revalidatePath } from "next/cache"
-import { cookies } from "next/headers"
-import { addLineItem, createCart } from "@cartbase/storefront/api/carts"
-import { CART_COOKIE, CART_COOKIE_MAX_AGE } from "./config"
-import { getServerClient } from "./server-client"
-
-/**
- * PDP add-to-cart server action (carts.md: create the cart lazily on the
- * first add — region falls back to the store default; persist `cart.id`
- * in a cookie). Passed into `ProductTemplate`'s `addToCart` seam.
- */
-export async function addToCartAction(input: {
-  variantId: string
-  quantity: number
-}): Promise<void> {
-  const client = await getServerClient()
-  const jar = await cookies()
-  const cartId = jar.get(CART_COOKIE)?.value
-
-  if (cartId) {
-    await addLineItem(client, cartId, {
-      variant_id: input.variantId,
-      quantity: input.quantity,
-    })
-  } else {
-    const { cart } = await createCart(client, {
-      currency_code: "eur",
-      items: [{ variant_id: input.variantId, quantity: input.quantity }],
-    })
-    jar.set(CART_COOKIE, cart.id, {
-      path: "/",
-      sameSite: "lax",
-      httpOnly: false, // the browser-side drawer persists the same cookie
-      maxAge: CART_COOKIE_MAX_AGE,
-    })
-  }
-
-  // Layout refetches the cart snapshot → CartDrawerProvider sees the new
-  // product-line count and auto-opens the drawer.
-  revalidatePath("/", "layout")
-}
+"use server"
+
+import { revalidatePath } from "next/cache"
+import { cookies } from "next/headers"
+import { addLineItem, createCart } from "@cartbase/storefront/api/carts"
+import { CART_COOKIE, CART_COOKIE_MAX_AGE, readCartCookie } from "./config"
+import { getServerClient } from "./server-client"
+
+/**
+ * PDP add-to-cart server action (carts.md: create the cart lazily on the
+ * first add — region falls back to the store default; persist `cart.id`
+ * in a cookie). Passed into `ProductTemplate`'s `addToCart` seam.
+ *
+ * Reads via `readCartCookie` (new `_cartbase_cart` name, falls back to the
+ * legacy `_barter_cart_id` — platform-fingerprints card); every WRITE uses
+ * the new name only, so a visitor's cart survives the rename.
+ */
+export async function addToCartAction(input: {
+  variantId: string
+  quantity: number
+}): Promise<void> {
+  const client = await getServerClient()
+  const jar = await cookies()
+  const cartId = readCartCookie((name) => jar.get(name)?.value)
+
+  if (cartId) {
+    await addLineItem(client, cartId, {
+      variant_id: input.variantId,
+      quantity: input.quantity,
+    })
+  } else {
+    const { cart } = await createCart(client, {
+      currency_code: "eur",
+      items: [{ variant_id: input.variantId, quantity: input.quantity }],
+    })
+    jar.set(CART_COOKIE, cart.id, {
+      path: "/",
+      sameSite: "lax",
+      httpOnly: false, // the browser-side drawer persists the same cookie
+      maxAge: CART_COOKIE_MAX_AGE,
+    })
+  }
+
+  // Layout refetches the cart snapshot → CartDrawerProvider sees the new
+  // product-line count and auto-opens the drawer.
+  revalidatePath("/", "layout")
+}

package/template/app/src/lib/config.ts

@@ -1,12 +1,17 @@
 /** Shared storefront configuration (BUILD-A-STOREFRONT.md — inputs table). */
 
-export const BARTER_URL = process.env.NEXT_PUBLIC_BARTER_URL ?? ""
-export const BARTER_CLIENT_ID = process.env.NEXT_PUBLIC_BARTER_CLIENT_ID ?? ""
+export const BARTER_URL = process.env.NEXT_PUBLIC_CARTBASE_URL ?? ""
+export const BARTER_CLIENT_ID = process.env.NEXT_PUBLIC_CARTBASE_CLIENT_ID ?? ""
 export const BARTER_PUBLISHABLE_KEY =
-  process.env.NEXT_PUBLIC_BARTER_PUBLISHABLE_KEY || undefined
+  process.env.NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY || undefined
 
-/** Cart-id cookie — owned by the app (the SDK never persists the cart). */
-export const CART_COOKIE = "_barter_cart_id"
+/**
+ * Cart-id cookie — owned by the app (the SDK never persists the cart);
+ * the NAME is owned by the library so every consumer emits the same wire
+ * fingerprint (platform-fingerprints card). `readCartCookie` is the
+ * backward-compat reader for the legacy `_barter_cart_id` name.
+ */
+export { CART_COOKIE, readCartCookie } from "@cartbase/storefront/lib/cookie-names"
 export const CART_COOKIE_MAX_AGE = 60 * 60 * 24 * 30 // 30 days
 
 /** Locale cookie read by the clients' `getLocale`. */