@cimplify/sdk 0.42.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/sdk",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Cimplify Commerce SDK for storefronts",
   "keywords": [
     "cimplify",

package/templates/storefront-bakery/.claude/skills/cimplify-storefront/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: cimplify-storefront
+description: Build, customize, rebrand, or deploy a Cimplify-scaffolded storefront. Triggers when the user asks to create a storefront, rebrand a Cimplify template, change the palette, add a page, deploy to Cimplify, or works in a project containing `lib/brand.ts` and `next.config.ts` with `cacheComponents`.
+---
+
+# Cimplify Storefront skill
+
+You're working on a project scaffolded from `bunx @cimplify/sdk init`. The architecture is opinionated and the rebrand surface is intentionally small. Read `AGENTS.md` at the project root for the file ↔ brand-field map for *this template's* industry; this skill gives you the playbook that's the same across all six.
+
+## The contract — never break
+
+1. **`lib/brand.ts` is the only place for content edits.** Every visible string reads from this file. If a string isn't in `brand`, *add a field* to the `Brand` interface — don't hardcode it in a page or component.
+2. **`app/globals.css` `@theme { … }`** holds palette + radius + font references. To re-skin the entire site, edit only this block.
+3. **Server Components are cached** via `'use cache'` + `cacheTag(tags.X())` + `cacheLife("hours")`. Don't downgrade them to `"use client"` to avoid an issue — fix the issue.
+4. **Client islands** (anything reading `useSearchParams`, `usePathname`, `useRouter`, `useState`) live behind `<Suspense>`.
+5. **`cacheComponents: true`** in `next.config.ts` is non-negotiable. Don't turn it off.
+6. **`bun run test:run` (vitest)** is the canonical test runner. `bun test` will show false failures because Bun's `vi` shim is incomplete.
+7. **Cart, checkout, orders stay client.** They're session-bound. Don't try to SSR them.
+
+## The brand-field schema (in `lib/brand.ts`)
+
+```
+identity:        name, shortName, microTag, description, schemaType, currency, locale
+contact:         address, streetAddress, city, countryCode, phone, phoneTel, email, privacyEmail, hours
+socials:         [{ label, href, icon }]   // icon ∈ instagram|x|tiktok|facebook|youtube|linkedin|whatsapp
+header:          { nav: [{ label, href }] }
+hero:            { badge, title, subtitle, primaryCtaLabel, secondaryCtaLabel?, secondaryCtaHref? }
+optional:        trustItems[]?, brandStrip?, promo?, tradeIn?     // render conditionally
+newsletter:      { eyebrow, title, body, placeholder, submitLabel, successLabel }
+about:           { eyebrow, title, paragraphs[], sections[{ heading, body }] }
+faq:             { eyebrow, title, sections[{ title, items[{ q, a }] }], contactPrompt, contactEmail }
+terms,
+privacy,
+shipping,
+returns,
+accessibility:   { eyebrow, title, lastUpdated, sections[{ heading, body | { intro, bullets[] } }] }
+account:         eyebrows + titles for /account, /login, /signup
+contactPage:     { eyebrow, title, body, reasons[], directLines[{ label, value, href }] }
+trackOrder:      { eyebrow, title, body }
+footer:          { blurb, sitemap[{ title, links[] }], poweredBy? }
+llms:            { summary }                           // opens /llms.txt
+mock:            { seed, businessId }
+```
+
+## Playbook — common tasks
+
+### Rebrand a storefront for a new merchant
+
+1. Edit `lib/brand.ts`. Replace every field with the merchant's content. Use the brief / context the user gave you.
+2. Edit `app/globals.css` `@theme { … }`. Change `--color-primary`, `--color-background`, `--color-foreground`, optionally `--radius`. Use OKLCH; if the brand only gave hex, convert.
+3. (Optional) Swap fonts in `app/layout.tsx` — `next/font/google` import + the variable wired into the `<html>` className.
+4. Set `.env.local`: `NEXT_PUBLIC_CIMPLIFY_API_URL`, `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`, `NEXT_PUBLIC_SITE_URL`.
+
+Don't touch any other file. If the rebrand needs content not in the schema, add the field to `Brand` first, populate it, then read it from the page.
+
+### Add a new section / component
+
+1. Build it as a Server Component in `components/` (or a client island in `*-client.tsx` if interactive).
+2. Read merchant copy from `brand`. Add new fields to the `Brand` interface if needed.
+3. Wrap interactive bits in `<Suspense fallback={…}>` so the cached chrome streams.
+4. Compose into the page.
+
+### Wire a Server Action that mutates data
+
+```ts
+"use server";
+import { getServerClient, revalidateProducts } from "@cimplify/sdk/server";
+
+export async function createProduct(input: ProductInput) {
+  await getServerClient().catalogue.createProduct(input);
+  revalidateProducts();
+}
+```
+
+After every mutation, call the matching `revalidate*` helper from `@cimplify/sdk/server`: `revalidateProducts`, `revalidateProduct(id)`, `revalidateCategories`, `revalidateCategory(id)`, `revalidateCollections`, `revalidateCollection(id)`, `revalidateBusiness`.
+
+### Add a Server Component data fetch
+
+```ts
+import { cacheTag, cacheLife } from "next/cache";
+import { getServerClient, tags } from "@cimplify/sdk/server";
+
+async function getX() {
+  "use cache";
+  cacheTag(tags.products());
+  cacheLife("hours");
+  const r = await getServerClient().catalogue.getProducts({ limit: 24 });
+  if (!r.ok) throw new Error(r.error.message);
+  return r.value.items;
+}
+```
+
+### Eject an SDK component for deeper customization
+
+Try `classNames`, `renderImage`, `renderLink`, slot props first. If those run out:
+
+```bash
+bunx @cimplify/sdk eject --list
+bunx @cimplify/sdk eject product-card --dir src/components/cimplify
+```
+
+Once ejected, the file is yours. Hooks/types still come from `@cimplify/sdk`.
+
+### Deploy
+
+```bash
+bunx @cimplify/sdk login
+bunx @cimplify/sdk projects create my-store
+bunx @cimplify/sdk link <project-id>
+bunx @cimplify/sdk env push
+bunx @cimplify/sdk deploy --prod
+bunx @cimplify/sdk logs --follow
+bunx @cimplify/sdk domains add my-store.com
+```
+
+## Pitfalls — explicit ❌ list
+
+- ❌ Hardcoding any visible string in a page or component. Always `brand.X`.
+- ❌ Disabling `cacheComponents: true` to silence a warning. Fix the warning by wrapping the dynamic call in `<Suspense>`.
+- ❌ Using `unstable_cache` — Next 16's canonical primitive is `'use cache'` + `cacheTag` + `cacheLife`.
+- ❌ Bypassing `getServerClient()` and calling `createCimplifyClient` directly in a Server Component — loses per-request memoization.
+- ❌ Mutating data without calling the matching `revalidate*` helper.
+- ❌ Adding an `app/error.tsx` handler that calls `reset()` without logging — silently swallowed errors hide bugs.
+- ❌ Running `bun test` and reporting failures. Use `bun run test:run` (vitest).
+- ❌ Editing the per-template `AGENTS.md` to remove notes about TODOs (contact form, newsletter fake submits) — they're real.
+
+## Where things live
+
+| Need | Look here |
+|---|---|
+| Which page reads which `brand.X` field | `AGENTS.md` at project root |
+| Architectural rules | `AGENTS.md` at project root + this skill |
+| Running locally | `bun dev` (boots mock + Next together) |
+| Switching mock seed | edit `dev:mock` in `package.json` and `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID` in `.env.local` |
+| Full SDK reference | `docs/sdk/storefronts.md` in the Cimplify repo |
+
+## What to do when the user asks something out-of-scope
+
+If the user asks for something the template doesn't support out of the box:
+
+1. **Check first** — is there an SDK component or hook that does it? `@cimplify/sdk/react` has 50+ components, 30+ hooks. Search `node_modules/@cimplify/sdk/dist/react.d.mts` if needed.
+2. **Compose from existing parts** before authoring new ones.
+3. **If genuinely missing** — build the new component, hoist its strings into `brand.ts`, document in `AGENTS.md`.
+
+Don't introduce competing patterns (a new caching strategy, a new auth flow, a new theming system). The template's opinions are intentional.

package/templates/storefront-bakery/.cursor/rules/cimplify-storefront.mdc

@@ -0,0 +1,25 @@
+---
+description: Cimplify storefront — architectural rules and rebrand contract for a project scaffolded from `bunx @cimplify/sdk init`. Triggers when files like lib/brand.ts, app/globals.css, components/header.tsx, or .cimplify/project.json are in the workspace.
+globs: ["lib/brand.ts", "app/**", "components/**", ".env.local", "next.config.ts"]
+alwaysApply: true
+---
+
+# Cimplify storefront
+
+This project was scaffolded from a Cimplify template. Read `AGENTS.md` at the project root for the file ↔ `brand.X` field map and `.claude/skills/cimplify-storefront/SKILL.md` for the full playbook.
+
+## The contract
+
+1. **`lib/brand.ts`** — every visible string. If something isn't there, add a field to the `Brand` interface; don't hardcode.
+2. **`app/globals.css` `@theme` block** — palette, radius, font references.
+3. **Server Components are cached** via `'use cache'` + `cacheTag(tags.X())` + `cacheLife("hours")`. Don't downgrade to client to silence a warning.
+4. **Client islands** behind `<Suspense>`.
+5. **`cacheComponents: true`** in `next.config.ts` is non-negotiable.
+6. Use **`bun run test:run`** (vitest), not `bun test`.
+
+## Don't
+
+- Hardcode visible strings in pages/components.
+- Use `unstable_cache` (Next 16 uses `'use cache'`).
+- Bypass `getServerClient()` (loses per-request memoization).
+- Mutate without calling the matching `revalidate*` helper from `@cimplify/sdk/server`.

package/templates/storefront-bakery/AGENTS.md

@@ -6,8 +6,8 @@ If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this store
 
 To rebrand this storefront end-to-end as a different merchant:
 
-1. **Edit `lib/brand.ts`.** Every visible string reads from this file. Replace each field with the merchant's actual content.
-2. **Edit `app/globals.css`** — the `@theme { … }` block holds the design tokens (palette, radius, font references). Tweak to match the merchant's brand.
+1. **Edit `lib/brand.ts`.** Every visible string reads from this file.
+2. **Edit `app/globals.css`** — the `@theme { … }` block holds the design tokens (palette, radius, font references).
 3. **Edit `.env.local`** — set `NEXT_PUBLIC_CIMPLIFY_API_URL`, `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`, `NEXT_PUBLIC_SITE_URL`.
 
 That is the entire rebrand. Do not modify any `.tsx` file in `app/` or `components/` for content changes — they are design-only and read from `brand`.
@@ -22,30 +22,81 @@ That is the entire rebrand. Do not modify any `.tsx` file in `app/` or `componen
 - ❌ Don't disable `cacheComponents: true` in `next.config.ts`.
 - ❌ Don't use `unstable_cache` — Next 16 uses the `'use cache'` directive.
 
-## File map (what reads from where)
+## Page surface
+
+```
+app/
+  page.tsx                       Home — hero, collection strips, category grid
+  shop/page.tsx                  Full catalogue (SDK <CataloguePage/>)
+  search/page.tsx                Search (SDK <SearchPage/>)
+  collections/[slug]/page.tsx    Collection landing
+  categories/[slug]/page.tsx     Category landing
+
+  cart/page.tsx                  SDK <CartPage/>
+  checkout/page.tsx              SDK <CheckoutPage/>
+  orders/[id]/page.tsx           Post-checkout confirmation (also target of /track-order)
+
+  account/page.tsx               <CimplifyAccount /> (iframe — handles sign-in, dashboard)
+  account/orders/page.tsx        <CimplifyAccount section="orders" />
+  account/addresses/page.tsx     <CimplifyAccount section="addresses" />
+  account/settings/page.tsx      <CimplifyAccount section="settings" />
+  login/page.tsx                 redirect → /account (iframe owns sign-in UI)
+  signup/page.tsx                redirect → /account (iframe owns sign-up UI)
+
+  contact/page.tsx               Contact form (Server Action wiring TODO; currently fakes submit)
+  track-order/page.tsx           Guest order lookup → /orders/[id]
+
+  about/page.tsx                 Brand story
+  faq/page.tsx                   FAQ
+  shipping/page.tsx              Standalone shipping policy
+  returns/page.tsx               Standalone returns policy
+  accessibility/page.tsx         Accessibility statement (WCAG 2.1 AA)
+  terms/page.tsx                 Terms of Service
+  privacy/page.tsx               Privacy Policy
+
+  sitemap-page/page.tsx          Human-readable HTML sitemap
+  sitemap.ts                     XML sitemap (search engines)
+  robots.ts                      robots.txt
+  llms.txt/route.ts              LLM-friendly Markdown index
+  opensearch.xml/route.ts        Browser address-bar search description
+  error.tsx, not-found.tsx       Global boundaries
+```
+
+## File ↔ brand-field map
 
 | File | Reads from `brand` |
 |---|---|
-| `app/layout.tsx` | metadata, OpenGraph, Organization JSON-LD |
+| `app/layout.tsx` | identity, contact, socials, schemaType (Organization JSON-LD), `metadataBase` |
 | `app/page.tsx` | `brand.hero` (Hero badge / title / subtitle) |
 | `app/about/page.tsx` | `brand.about` |
 | `app/faq/page.tsx` | `brand.faq` |
 | `app/terms/page.tsx` | `brand.terms` |
 | `app/privacy/page.tsx` | `brand.privacy` |
+| `app/shipping/page.tsx` | `brand.shipping` |
+| `app/returns/page.tsx` | `brand.returns` |
+| `app/accessibility/page.tsx` | `brand.accessibility` |
+| `app/contact/page.tsx` | `brand.contactPage`, `brand.contact` |
+| `app/track-order/page.tsx` | `brand.trackOrder` |
+| `app/account/*/page.tsx` | `brand.account` (eyebrows + titles only — Cimplify Link iframe owns the UI) |
+| `app/login/page.tsx`, `app/signup/page.tsx` | `brand.account` (metadata only — both redirect to `/account`) |
 | `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
-| `app/sitemap.ts`, `robots.ts` | (no brand strings — derives from product data) |
+| `app/opensearch.xml/route.ts` | `brand.shortName`, `brand.name` |
+| `app/sitemap.ts`, `robots.ts` | derives URLs from product/category data |
 | `app/not-found.tsx` | `brand.name` (page title) |
 | `components/header.tsx` | `brand.shortName`, `brand.microTag`, `brand.header.nav` |
-| `components/footer.tsx` | `brand.footer`, contact, socials |
+| `components/footer.tsx` | `brand.footer`, `brand.contact`, `brand.socials` |
 
 ## Bakery-specific notes
 
-- Product detail uses a **URL-driven modal** (`?product=<slug>`), not a static `/products/[slug]` route. This fits impulse-purchase food UX. Don't refactor without a reason.
-- Schema.org type is `Bakery`. `lib/brand.ts` sets this in `schemaType` — change if rebranding to a different industry.
+- Product detail uses a **URL-driven modal** (`?product=<slug>`), not a static `/products/[slug]` route. Fits impulse-purchase food UX.
+- Schema.org `@type` is `Bakery` — set in `brand.schemaType`.
+- Mock seed: `--seed default` (Akua's Bakery). To preview a different industry, edit `dev:mock` in `package.json` and update `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`.
 
-## Mock seed
+## Known TODOs (not blocking, but worth knowing)
 
-Wired to `--seed default` (Akua's Bakery) via `package.json` `dev:mock`. To preview another seed, change the flag or run `bunx @cimplify/sdk --seed restaurant` directly and update `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID` in `.env.local`.
+- `app/contact/contact-form.tsx` fakes a successful submit. In production, wire a Server Action that calls `client.support.sendMessage(...)` from `@cimplify/sdk/server`.
+- `components/newsletter.tsx` (homepage strip) similarly fakes submit. Wire to a real list provider.
+- Hero / lookbook imagery is Unsplash placeholder — replace with merchant assets.
 
 ## Quick start
 

package/templates/storefront-bakery/CLAUDE.md

@@ -0,0 +1,22 @@
+# CLAUDE.md
+
+This project was scaffolded from a Cimplify storefront template (`bunx @cimplify/sdk init`).
+
+## Read these first
+
+- **`AGENTS.md`** at the project root — the file ↔ `brand.X` field map for *this template's* industry, plus the architectural rules.
+- **`.claude/skills/cimplify-storefront/SKILL.md`** — the playbook for common tasks (rebrand, add a section, wire a Server Action, deploy, eject a component). Invoke it whenever you're asked to change content, palette, copy, or routing.
+
+## The two-line summary
+
+1. **Edit `lib/brand.ts`** for any visible string.
+2. **Edit `app/globals.css` `@theme` block** for any palette / radius / font change.
+
+That covers ~95% of what merchants ask for. For anything else, follow the `cimplify-storefront` skill.
+
+## Don't do
+
+- Hardcode strings in pages or components.
+- Disable `cacheComponents: true` in `next.config.ts`.
+- Use `unstable_cache` — Next 16's canonical primitive is `'use cache'`.
+- Run `bun test` (Bun's `vi` shim is incomplete) — use `bun run test:run`.

package/templates/storefront-fashion/.claude/skills/cimplify-storefront/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: cimplify-storefront
+description: Build, customize, rebrand, or deploy a Cimplify-scaffolded storefront. Triggers when the user asks to create a storefront, rebrand a Cimplify template, change the palette, add a page, deploy to Cimplify, or works in a project containing `lib/brand.ts` and `next.config.ts` with `cacheComponents`.
+---
+
+# Cimplify Storefront skill
+
+You're working on a project scaffolded from `bunx @cimplify/sdk init`. The architecture is opinionated and the rebrand surface is intentionally small. Read `AGENTS.md` at the project root for the file ↔ brand-field map for *this template's* industry; this skill gives you the playbook that's the same across all six.
+
+## The contract — never break
+
+1. **`lib/brand.ts` is the only place for content edits.** Every visible string reads from this file. If a string isn't in `brand`, *add a field* to the `Brand` interface — don't hardcode it in a page or component.
+2. **`app/globals.css` `@theme { … }`** holds palette + radius + font references. To re-skin the entire site, edit only this block.
+3. **Server Components are cached** via `'use cache'` + `cacheTag(tags.X())` + `cacheLife("hours")`. Don't downgrade them to `"use client"` to avoid an issue — fix the issue.
+4. **Client islands** (anything reading `useSearchParams`, `usePathname`, `useRouter`, `useState`) live behind `<Suspense>`.
+5. **`cacheComponents: true`** in `next.config.ts` is non-negotiable. Don't turn it off.
+6. **`bun run test:run` (vitest)** is the canonical test runner. `bun test` will show false failures because Bun's `vi` shim is incomplete.
+7. **Cart, checkout, orders stay client.** They're session-bound. Don't try to SSR them.
+
+## The brand-field schema (in `lib/brand.ts`)
+
+```
+identity:        name, shortName, microTag, description, schemaType, currency, locale
+contact:         address, streetAddress, city, countryCode, phone, phoneTel, email, privacyEmail, hours
+socials:         [{ label, href, icon }]   // icon ∈ instagram|x|tiktok|facebook|youtube|linkedin|whatsapp
+header:          { nav: [{ label, href }] }
+hero:            { badge, title, subtitle, primaryCtaLabel, secondaryCtaLabel?, secondaryCtaHref? }
+optional:        trustItems[]?, brandStrip?, promo?, tradeIn?     // render conditionally
+newsletter:      { eyebrow, title, body, placeholder, submitLabel, successLabel }
+about:           { eyebrow, title, paragraphs[], sections[{ heading, body }] }
+faq:             { eyebrow, title, sections[{ title, items[{ q, a }] }], contactPrompt, contactEmail }
+terms,
+privacy,
+shipping,
+returns,
+accessibility:   { eyebrow, title, lastUpdated, sections[{ heading, body | { intro, bullets[] } }] }
+account:         eyebrows + titles for /account, /login, /signup
+contactPage:     { eyebrow, title, body, reasons[], directLines[{ label, value, href }] }
+trackOrder:      { eyebrow, title, body }
+footer:          { blurb, sitemap[{ title, links[] }], poweredBy? }
+llms:            { summary }                           // opens /llms.txt
+mock:            { seed, businessId }
+```
+
+## Playbook — common tasks
+
+### Rebrand a storefront for a new merchant
+
+1. Edit `lib/brand.ts`. Replace every field with the merchant's content. Use the brief / context the user gave you.
+2. Edit `app/globals.css` `@theme { … }`. Change `--color-primary`, `--color-background`, `--color-foreground`, optionally `--radius`. Use OKLCH; if the brand only gave hex, convert.
+3. (Optional) Swap fonts in `app/layout.tsx` — `next/font/google` import + the variable wired into the `<html>` className.
+4. Set `.env.local`: `NEXT_PUBLIC_CIMPLIFY_API_URL`, `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`, `NEXT_PUBLIC_SITE_URL`.
+
+Don't touch any other file. If the rebrand needs content not in the schema, add the field to `Brand` first, populate it, then read it from the page.
+
+### Add a new section / component
+
+1. Build it as a Server Component in `components/` (or a client island in `*-client.tsx` if interactive).
+2. Read merchant copy from `brand`. Add new fields to the `Brand` interface if needed.
+3. Wrap interactive bits in `<Suspense fallback={…}>` so the cached chrome streams.
+4. Compose into the page.
+
+### Wire a Server Action that mutates data
+
+```ts
+"use server";
+import { getServerClient, revalidateProducts } from "@cimplify/sdk/server";
+
+export async function createProduct(input: ProductInput) {
+  await getServerClient().catalogue.createProduct(input);
+  revalidateProducts();
+}
+```
+
+After every mutation, call the matching `revalidate*` helper from `@cimplify/sdk/server`: `revalidateProducts`, `revalidateProduct(id)`, `revalidateCategories`, `revalidateCategory(id)`, `revalidateCollections`, `revalidateCollection(id)`, `revalidateBusiness`.
+
+### Add a Server Component data fetch
+
+```ts
+import { cacheTag, cacheLife } from "next/cache";
+import { getServerClient, tags } from "@cimplify/sdk/server";
+
+async function getX() {
+  "use cache";
+  cacheTag(tags.products());
+  cacheLife("hours");
+  const r = await getServerClient().catalogue.getProducts({ limit: 24 });
+  if (!r.ok) throw new Error(r.error.message);
+  return r.value.items;
+}
+```
+
+### Eject an SDK component for deeper customization
+
+Try `classNames`, `renderImage`, `renderLink`, slot props first. If those run out:
+
+```bash
+bunx @cimplify/sdk eject --list
+bunx @cimplify/sdk eject product-card --dir src/components/cimplify
+```
+
+Once ejected, the file is yours. Hooks/types still come from `@cimplify/sdk`.
+
+### Deploy
+
+```bash
+bunx @cimplify/sdk login
+bunx @cimplify/sdk projects create my-store
+bunx @cimplify/sdk link <project-id>
+bunx @cimplify/sdk env push
+bunx @cimplify/sdk deploy --prod
+bunx @cimplify/sdk logs --follow
+bunx @cimplify/sdk domains add my-store.com
+```
+
+## Pitfalls — explicit ❌ list
+
+- ❌ Hardcoding any visible string in a page or component. Always `brand.X`.
+- ❌ Disabling `cacheComponents: true` to silence a warning. Fix the warning by wrapping the dynamic call in `<Suspense>`.
+- ❌ Using `unstable_cache` — Next 16's canonical primitive is `'use cache'` + `cacheTag` + `cacheLife`.
+- ❌ Bypassing `getServerClient()` and calling `createCimplifyClient` directly in a Server Component — loses per-request memoization.
+- ❌ Mutating data without calling the matching `revalidate*` helper.
+- ❌ Adding an `app/error.tsx` handler that calls `reset()` without logging — silently swallowed errors hide bugs.
+- ❌ Running `bun test` and reporting failures. Use `bun run test:run` (vitest).
+- ❌ Editing the per-template `AGENTS.md` to remove notes about TODOs (contact form, newsletter fake submits) — they're real.
+
+## Where things live
+
+| Need | Look here |
+|---|---|
+| Which page reads which `brand.X` field | `AGENTS.md` at project root |
+| Architectural rules | `AGENTS.md` at project root + this skill |
+| Running locally | `bun dev` (boots mock + Next together) |
+| Switching mock seed | edit `dev:mock` in `package.json` and `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID` in `.env.local` |
+| Full SDK reference | `docs/sdk/storefronts.md` in the Cimplify repo |
+
+## What to do when the user asks something out-of-scope
+
+If the user asks for something the template doesn't support out of the box:
+
+1. **Check first** — is there an SDK component or hook that does it? `@cimplify/sdk/react` has 50+ components, 30+ hooks. Search `node_modules/@cimplify/sdk/dist/react.d.mts` if needed.
+2. **Compose from existing parts** before authoring new ones.
+3. **If genuinely missing** — build the new component, hoist its strings into `brand.ts`, document in `AGENTS.md`.
+
+Don't introduce competing patterns (a new caching strategy, a new auth flow, a new theming system). The template's opinions are intentional.

package/templates/storefront-fashion/.cursor/rules/cimplify-storefront.mdc

@@ -0,0 +1,25 @@
+---
+description: Cimplify storefront — architectural rules and rebrand contract for a project scaffolded from `bunx @cimplify/sdk init`. Triggers when files like lib/brand.ts, app/globals.css, components/header.tsx, or .cimplify/project.json are in the workspace.
+globs: ["lib/brand.ts", "app/**", "components/**", ".env.local", "next.config.ts"]
+alwaysApply: true
+---
+
+# Cimplify storefront
+
+This project was scaffolded from a Cimplify template. Read `AGENTS.md` at the project root for the file ↔ `brand.X` field map and `.claude/skills/cimplify-storefront/SKILL.md` for the full playbook.
+
+## The contract
+
+1. **`lib/brand.ts`** — every visible string. If something isn't there, add a field to the `Brand` interface; don't hardcode.
+2. **`app/globals.css` `@theme` block** — palette, radius, font references.
+3. **Server Components are cached** via `'use cache'` + `cacheTag(tags.X())` + `cacheLife("hours")`. Don't downgrade to client to silence a warning.
+4. **Client islands** behind `<Suspense>`.
+5. **`cacheComponents: true`** in `next.config.ts` is non-negotiable.
+6. Use **`bun run test:run`** (vitest), not `bun test`.
+
+## Don't
+
+- Hardcode visible strings in pages/components.
+- Use `unstable_cache` (Next 16 uses `'use cache'`).
+- Bypass `getServerClient()` (loses per-request memoization).
+- Mutate without calling the matching `revalidate*` helper from `@cimplify/sdk/server`.

package/templates/storefront-fashion/AGENTS.md

@@ -4,43 +4,97 @@ If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this store
 
 ## TL;DR for rebranding
 
-1. **Edit `lib/brand.ts`.** Every visible string reads from this file.
-2. **Edit `app/globals.css`** — the `@theme { … }` block holds the design tokens (palette, radius, font references). High-contrast neutrals + electric primary by default.
+1. **Edit `lib/brand.ts`** — every visible string lives here.
+2. **Edit `app/globals.css`** — `@theme { … }` for palette + radius + font references.
 3. **Edit `.env.local`** — `NEXT_PUBLIC_CIMPLIFY_API_URL`, `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`, `NEXT_PUBLIC_SITE_URL`.
 
 ## Aesthetic
 
-This template is built for streetwear / capsule fashion / lookbook-led brands (Nike, Aritzia, Highsnobiety, drop culture). Key design moves:
+Streetwear / lookbook-led brands (Nike, Aritzia, Highsnobiety, drop culture):
 
-- **Anton display typography** for hero + section titles (uppercase, condensed, heavy).
-- **Inter** for body and UI.
-- **High-contrast palette**: near-black foreground on near-white background, with one electric primary (default: `oklch(0.7 0.24 30)` — coral-orange).
-- **Sharp corners**: `--radius: 0.125rem` — minimal rounding, near-square inputs and buttons.
-- **Editorial full-bleed hero** with image gradient overlay (see `components/feature-hero.tsx`).
-- **Block-letter header** — no logo mark, just the shortName in display type with a microTag.
+- **Anton display + Inter** — uppercase condensed display, clean body sans.
+- **High-contrast palette** — near-black foreground on near-white background, electric primary (default coral, `oklch(0.7 0.24 30)`).
+- **Sharp corners**: `0.125rem` — minimal rounding.
+- **Editorial full-bleed hero** with image gradient overlay.
+- **Block-letter header** — no logo mark, just the shortName in display type.
+- Schema.org `@type` is `Store`.
 
-## Industry-specific copy patterns
+## Page surface
 
-The bundled brand presets:
-- `brand.hero.badge` is a "drop counter" (e.g. `"Drop 04 · Live now"`).
-- `brand.tradeIn` is repurposed as a "Studio collective" / membership programme.
-- `brand.brandStrip.headline` is `"Stocked at"` with editorial publication wordmarks (Vogue, Highsnobiety, etc.).
-- `brand.faq` covers sizing, drops/restocks, returns, customs.
-
-Replace these freely. The components render conditionally — set any optional block to `undefined` to hide it.
-
-## Rules
+```
+app/
+  page.tsx                       Multi-section home — full-bleed editorial hero,
+                                  trust bar, category tiles, promo banner,
+                                  "Just dropped" grid, brand strip, collections,
+                                  studio-collective CTA, best sellers, newsletter
+  shop/page.tsx                  SDK <CataloguePage/> with custom hero
+  search/page.tsx                Search
+  collections/[slug]/page.tsx    Collection landing (drops)
+  categories/[slug]/page.tsx     Category landing
+  products/[slug]/page.tsx       Full product detail page (Product JSON-LD)
+
+  size-guide/page.tsx            ⭐ Fashion-specific: chest/length/shoulder + waist/hip/inseam
+                                  tables, "how to measure" callout
+  lookbook/page.tsx              ⭐ Fashion-specific: editorial multi-drop lookbook —
+                                  hero + 3-up tile galleries per drop, "Shop Drop X" CTAs
+
+  cart/page.tsx, checkout/page.tsx, orders/[id]/page.tsx
+
+  account/page.tsx               <CimplifyAccount /> (iframe)
+  account/orders/page.tsx        <CimplifyAccount section="orders" />
+  account/addresses/page.tsx     <CimplifyAccount section="addresses" />
+  account/settings/page.tsx      <CimplifyAccount section="settings" />
+  login/page.tsx, signup/page.tsx  redirects → /account
+
+  contact/page.tsx, track-order/page.tsx
+
+  about/page.tsx, faq/page.tsx
+  shipping/page.tsx (DHL Express worldwide), returns/page.tsx (30 days),
+  accessibility/page.tsx, terms/page.tsx, privacy/page.tsx
+
+  sitemap-page/page.tsx, sitemap.ts, robots.ts, llms.txt/route.ts, opensearch.xml/route.ts
+  error.tsx, not-found.tsx
+```
 
-- ✅ All content edits → `lib/brand.ts`
-- ✅ All design-token edits → `app/globals.css` `@theme` block
-- ✅ Server Components stay cached via `'use cache'` + `cacheTag(tags.X())` + `cacheLife("hours")`
-- ✅ Client islands behind `<Suspense>`
-- ❌ Don't hardcode strings.
-- ❌ Don't disable `cacheComponents: true`.
+## File ↔ brand-field map
+
+| File | Reads from `brand` |
+|---|---|
+| `app/layout.tsx` | identity, contact, socials, Store JSON-LD |
+| `app/page.tsx` | `brand.hero`, `brand.trustItems`, `brand.brandStrip`, `brand.promo`, `brand.tradeIn` (= studio-collective copy), `brand.newsletter` |
+| `app/about/page.tsx` | `brand.about` |
+| `app/faq/page.tsx` | `brand.faq` (sizing, drops, returns, customs) |
+| `app/shipping/page.tsx` | `brand.shipping` (worldwide DHL, customs) |
+| `app/returns/page.tsx` | `brand.returns` (30 days, free US/UK/EU) |
+| `app/accessibility/page.tsx` | `brand.accessibility` |
+| `app/terms/page.tsx`, `app/privacy/page.tsx` | `brand.terms`, `brand.privacy` |
+| `app/contact/page.tsx` | `brand.contactPage`, `brand.contact` |
+| `app/track-order/page.tsx` | `brand.trackOrder` |
+| `app/account/*/page.tsx` | `brand.account` (iframe owns UI) |
+| `app/products/[slug]/page.tsx` | `brand.name`, `brand.currency` (Product JSON-LD) |
+| `app/size-guide/page.tsx` | currently has its size charts inlined — hoist to `brand.sizeGuide` if you want agents to edit them |
+| `app/lookbook/page.tsx` | currently has the lookbook entries inlined (image URLs + drop names) — hoist to `brand.lookbook` for agent editing |
+| `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
+| `components/header.tsx`, `footer.tsx` | `brand.header`, `brand.footer`, `brand.contact`, `brand.socials` |
+| `components/promo-banner.tsx`, `trade-in-cta.tsx`, `brand-marquee.tsx`, `trust-bar.tsx`, `newsletter.tsx` | corresponding optional sections in `brand` |
+
+## Fashion-specific notes
+
+- **Hero is full-bleed editorial.** Replace `HERO_FALLBACK_IMAGE` in `app/page.tsx` with the merchant's drop campaign shot for maximum impact.
+- **Drop badges and "limited run" copy** drive urgency. Keep `brand.hero.badge` and `brand.promo.badge` short and time-bounded.
+- **`brand.tradeIn`** is repurposed as the "Studio collective" / membership programme — three-step access flow.
+- **Product detail uses the page-driven model** (`/products/[slug]`) — fashion is a consideration purchase (sizing, fit, fabric details), not impulse.
+- **`brandStrip.headline` is `"Stocked at"`** with editorial publication wordmarks (Vogue, Highsnobiety, etc.) — typography-led, no logo licensing required.
+
+## Known TODOs
+
+- `app/size-guide/page.tsx` has its size charts inlined as constants. Move them to `brand.sizeGuide` (typed) so agents can edit per-merchant size charts in one file.
+- `app/lookbook/page.tsx` has its drop entries inlined. Move to `brand.lookbook` for agent editing — each drop becomes `{ drop, title, date, byline, hero, tiles[] }`.
+- Contact form + newsletter fake submits.
 
 ## Mock seed
 
-Wired to `--seed retail` (Currents Electronics catalogue). Replace with apparel data in production. To preview a different seed, edit `dev:mock` in `package.json`.
+Wired to `--seed retail` (Currents Electronics catalogue — the closest stand-in until an apparel seed ships). Replace with apparel data in production.
 
 ## Quick start
 

package/templates/storefront-fashion/CLAUDE.md

@@ -0,0 +1,22 @@
+# CLAUDE.md
+
+This project was scaffolded from a Cimplify storefront template (`bunx @cimplify/sdk init`).
+
+## Read these first
+
+- **`AGENTS.md`** at the project root — the file ↔ `brand.X` field map for *this template's* industry, plus the architectural rules.
+- **`.claude/skills/cimplify-storefront/SKILL.md`** — the playbook for common tasks (rebrand, add a section, wire a Server Action, deploy, eject a component). Invoke it whenever you're asked to change content, palette, copy, or routing.
+
+## The two-line summary
+
+1. **Edit `lib/brand.ts`** for any visible string.
+2. **Edit `app/globals.css` `@theme` block** for any palette / radius / font change.
+
+That covers ~95% of what merchants ask for. For anything else, follow the `cimplify-storefront` skill.
+
+## Don't do
+
+- Hardcode strings in pages or components.
+- Disable `cacheComponents: true` in `next.config.ts`.
+- Use `unstable_cache` — Next 16's canonical primitive is `'use cache'`.
+- Run `bun test` (Bun's `vi` shim is incomplete) — use `bun run test:run`.