@cimplify/sdk 0.42.0 → 0.43.0

package/templates/storefront-retail/.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-retail/.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-retail/AGENTS.md

@@ -4,39 +4,75 @@ If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this store
 
 ## TL;DR for rebranding
 
-To rebrand this storefront end-to-end as a different merchant:
+1. **Edit `lib/brand.ts`** — every visible string lives here.
+2. **Edit `app/globals.css`** — `@theme { … }` block 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`.
 
-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.
-3. **Edit `.env.local`** — set `NEXT_PUBLIC_CIMPLIFY_API_URL`, `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`, `NEXT_PUBLIC_SITE_URL`.
+## Aesthetic
 
-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`.
+- **Inter + JetBrains Mono** — clean modern sans, mono-spaced labels for spec-feel.
+- **Cool navy + electric blue**: dark foreground, electric primary.
+- **Sharp corners**: `0.5rem` — modern retail.
+- **Section heroes** in dark with mono-spaced eyebrow labels.
 
-## Rules
+## Page surface
 
-- ✅ 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 (header active link, cart pill, product card link) live behind `<Suspense>`
-- ❌ Don't hardcode strings. If a string isn't in `brand`, add a new field to the `Brand` interface.
-- ❌ Don't disable `cacheComponents: true` in `next.config.ts`.
-- ❌ Don't use `unstable_cache` — Next 16 uses the `'use cache'` directive.
+```
+app/
+  page.tsx                       Multi-section home — split hero, trust bar, category tiles,
+                                  promo banner, "Just dropped" grid, brand strip, collections,
+                                  trade-in CTA, best sellers, newsletter
+  shop/page.tsx                  SDK <CataloguePage/> with custom hero
+  search/page.tsx                Search (SDK <SearchPage/>)
+  collections/[slug]/page.tsx    Collection landing
+  categories/[slug]/page.tsx     Category landing
+  products/[slug]/page.tsx       Full product detail page (Product JSON-LD)
+
+  cart/page.tsx                  SDK <CartPage/>
+  checkout/page.tsx              SDK <CheckoutPage/>
+  orders/[id]/page.tsx           Post-checkout confirmation
+
+  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               Branded contact form
+  track-order/page.tsx           Guest lookup → /orders/[id]
+
+  about/page.tsx, faq/page.tsx   Brand pages
+  shipping/page.tsx, returns/page.tsx, accessibility/page.tsx  Standalone policies
+  terms/page.tsx, privacy/page.tsx
+
+  sitemap-page/page.tsx          HTML sitemap
+  sitemap.ts, robots.ts          XML sitemap, robots.txt
+  llms.txt/route.ts              LLM-friendly site index
+  opensearch.xml/route.ts        Browser search description
+  error.tsx, not-found.tsx       Global boundaries
+```
 
-## File map (what reads from where)
+## File ↔ brand-field map
 
 | File | Reads from `brand` |
 |---|---|
-| `app/layout.tsx` | metadata, OpenGraph, Organization JSON-LD |
+| `app/layout.tsx` | identity, contact, socials, schemaType (Store JSON-LD) |
 | `app/page.tsx` | `brand.hero`, `brand.trustItems`, `brand.brandStrip`, `brand.promo`, `brand.tradeIn`, `brand.newsletter` |
 | `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/products/[slug]/page.tsx` | `brand.name`, `brand.currency` (Product JSON-LD) |
+| `app/shipping/page.tsx` | `brand.shipping` (warranty + returns + same-day delivery copy) |
+| `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` (Cimplify Link iframe owns the UI) |
+| `app/products/[slug]/page.tsx` | `brand.name`, `brand.currency` (Product JSON-LD: brand, offer, availability) |
 | `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
-| `app/not-found.tsx` | `brand.name` (page title) |
+| `app/opensearch.xml/route.ts` | `brand.shortName`, `brand.name` |
 | `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` |
 | `components/promo-banner.tsx` | `brand.promo` (renders nothing if absent) |
 | `components/trade-in-cta.tsx` | `brand.tradeIn` (renders nothing if absent) |
 | `components/brand-marquee.tsx` | `brand.brandStrip` |
@@ -45,20 +81,25 @@ That is the entire rebrand. Do not modify any `.tsx` file in `app/` or `componen
 
 ## Retail-specific notes
 
-- Product detail is a **full `/products/[slug]` page** with image gallery, customizer, related products rail, and Product JSON-LD. This fits consideration-purchase electronics UX (specs, reviews, warranty). Do not replace with a modal.
-- Schema.org type is `Store`. Change in `lib/brand.ts` (`schemaType`) for a different industry.
-- Optional sections render conditionally: `brand.promo`, `brand.tradeIn`, `brand.trustItems`, `brand.brandStrip` — set to `undefined` to hide.
-- `app/page.tsx` uses Unsplash fallback hero image (`HERO_FALLBACK_IMAGE`) — replace with your own asset URL.
+- Product detail is a **full `/products/[slug]` page** with image gallery, customizer, related products rail, and Product JSON-LD. Consideration purchases (phones, laptops, headphones) need real estate. Don't replace with a modal.
+- Schema.org `@type` is `Store`.
+- Optional sections render conditionally: set `brand.promo`, `brand.tradeIn`, `brand.trustItems`, or `brand.brandStrip` to `undefined` to hide them.
+- `app/page.tsx` uses an Unsplash fallback hero (`HERO_FALLBACK_IMAGE`) — replace with the merchant's own product photography.
+
+## Known TODOs
+
+- Contact form + newsletter signup currently fake their submit. Wire `client.support.sendMessage(...)` for contact and a real list provider for newsletter.
+- Trust-bar / brand-marquee imagery / wordmarks are placeholders — swap for the merchant's real partners.
 
 ## Mock seed
 
-Wired to `--seed retail` (Currents Electronics) via `package.json` `dev:mock`. To preview another seed, change the flag or run `bunx @cimplify/sdk --seed services` directly and update `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID` in `.env.local`.
+Wired to `--seed retail` (Currents Electronics). Edit `dev:mock` in `package.json` to preview another seed.
 
 ## Quick start
 
 ```bash
 bun install
-bun dev                 # boots mock + Next dev server
+bun dev
 ```
 
 Open <http://localhost:3000>.

package/templates/storefront-retail/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-services/.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-services/.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-services/AGENTS.md

@@ -5,31 +5,79 @@ 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 lives here.
-2. **Edit `app/globals.css`** — the `@theme { … }` block holds the palette + radius.
+2. **Edit `app/globals.css`** — `@theme { … }` for palette + radius.
 3. **Edit `.env.local`** — `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_serene_spa` for the bundled seed.
 
 ## Aesthetic
 
-Calm, refined wellness — Booksy / Mindbody / boutique-spa territory:
+- **Fraunces serif + Inter** — warm, slightly editorial headings.
+- **Sand + sage palette** — warm cream background, deep sage primary.
+- **Generous radius**: `1rem` — calm, soft.
+- Lower-contrast than retail / fashion.
+- Schema.org `@type` is `BeautySalon`.
 
-- **Fraunces serif** for headings (warm, slightly editorial).
-- **Inter** for body and UI.
-- **Sand + sage palette**: warm cream background, deep sage primary.
-- **Soft corners**: `--radius: 1rem` — generous rounding throughout.
-- **Lower-contrast** than retail / fashion; calm-feeling.
+## Page surface
 
-## Industry-specific copy patterns
+```
+app/
+  page.tsx                       Home — hero ("Now booking"), service strips,
+                                  category grid, newsletter
+  shop/page.tsx                  Treatment menu (SDK <CataloguePage/>)
+  search/page.tsx                Search
+  collections/[slug]/page.tsx    Collection landing
+  categories/[slug]/page.tsx     Category landing (e.g. memberships, packages)
+
+  book/page.tsx                  ⭐ Services-specific: full booking widget
+                                  (treatment + 14-day date + 30-min slot grid)
+                                  → adds to cart with slot as note → /checkout
+
+  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 (find a booking)
+
+  about/page.tsx, faq/page.tsx
+  shipping/page.tsx (what to expect at the studio), returns/page.tsx (cancellations),
+  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
+```
+
+## File ↔ brand-field map
+
+| File | Reads from `brand` |
+|---|---|
+| `app/layout.tsx` | identity, contact, socials, BeautySalon JSON-LD |
+| `app/page.tsx` | `brand.hero` ("Now booking") |
+| `app/about/page.tsx` | `brand.about` |
+| `app/faq/page.tsx` | `brand.faq` (booking, contraindications, memberships) |
+| `app/shipping/page.tsx` | `brand.shipping` (what to expect at the studio) |
+| `app/returns/page.tsx` | `brand.returns` (cancellation policy) |
+| `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` ("find a booking") |
+| `app/account/*/page.tsx` | `brand.account` (iframe owns UI) |
+| `app/book/*` | derives bookable services from product list (`type: "service"`) |
+| `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
+| `components/header.tsx`, `footer.tsx` | `brand.header`, `brand.footer`, `brand.contact`, `brand.socials` |
+
+## Services-specific notes
 
-The bundled brand presets:
-- `brand.hero.badge` reads `"Now booking · April"` — month-based availability.
-- `brand.hero.primaryCtaLabel` is `"Book a treatment"`.
-- `brand.tradeIn` is omitted (irrelevant for services).
-- `brand.faq` covers booking, cancellation, contraindications, memberships.
-- Schema.org type is `BeautySalon`.
+- **Bookable services are `type: "service"` products.** The `/book` page filters the product list to type=service and treats them as treatments. Their `duration_minutes` is shown on the chip.
+- Cart-item notes carry the booked time slot — checkout sends them through Cimplify's order pipeline. The merchant's downstream system reads the note to schedule the appointment.
+- Mock seed: `--seed services` (Serene Spa).
 
-## Mock seed
+## Known TODOs
 
-Wired to `--seed services` (Serene Spa). Products in this seed are *services* (`type: "service"`), so the SDK's variant cards render `StandardServiceCard` automatically.
+- `/book` widget shows every slot as available. For production, wire `useAvailableSlots({ serviceId, date })` from `@cimplify/sdk/react` to filter to genuinely-free windows.
+- Contact + newsletter fake submits.
 
 ## Quick start
 

package/templates/storefront-services/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`.