@cimplify/sdk 0.42.0 → 0.43.0

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

@@ -10,24 +10,69 @@ If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this store
 
 ## Aesthetic
 
-Approachable grocer — Trader Joe's / Whole Foods / abundant-feel:
-
 - **Inter sans only** (no serif) — friendly, readable for dense product grids.
-- **Fresh green + cream**: vibrant green primary, warm cream background.
+- **Fresh green + cream** — vibrant green primary, warm cream background.
 - **Generous radius**: `0.875rem` — softer than retail.
 - **Bold, slightly heavy** headings.
+- Schema.org `@type` is `GroceryStore`.
+
+## Page surface
+
+```
+app/
+  page.tsx                       Home — hero ("Free delivery over GH₵150"),
+                                  collection strips, category grid, newsletter
+  shop/page.tsx                  Aisle (SDK <CataloguePage/>)
+  search/page.tsx                Search
+  collections/[slug]/page.tsx    Collection landing (e.g. weekly box, deals)
+  categories/[slug]/page.tsx     Category landing
+
+  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 (delivery + slots), returns/page.tsx (quality guarantee),
+  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, GroceryStore JSON-LD |
+| `app/page.tsx` | `brand.hero` (free-delivery badge) |
+| `app/about/page.tsx` | `brand.about` |
+| `app/faq/page.tsx` | `brand.faq` (delivery slots, sourcing, subscription boxes) |
+| `app/shipping/page.tsx` | `brand.shipping` (delivery slots + free-over threshold) |
+| `app/returns/page.tsx` | `brand.returns` (quality guarantee) |
+| `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/llms.txt/route.ts` | `brand.llms`, contact, currency |
+| `components/header.tsx`, `footer.tsx` | `brand.header`, `brand.footer`, `brand.contact`, `brand.socials` |
 
-## Industry-specific copy patterns
+## Grocery-specific notes
 
-- `brand.hero.badge` is `"Free delivery over GH₵150"` — pricing-led trust signal.
-- `brand.hero.primaryCtaLabel` is `"Shop the aisle"`.
-- `brand.tradeIn` is omitted.
-- `brand.faq` covers delivery slots, sourcing/quality, subscription boxes.
-- Schema.org type is `GroceryStore`.
+- **Subscription boxes** are modelled as products with `billing_plans` (renders the SubscriptionCard variant). The basket-box landing lives at `/categories/baskets`.
+- **Weight-based pricing**: SDK supports `quantity_pricing` tiers per product, but most grocery products are sold by unit/kg. Real weight-at-pack pricing happens on the backend pricing rule.
+- Mock seed: `--seed grocery` (FreshMart).
 
-## Mock seed
+## Known TODOs
 
-Wired to `--seed grocery` (FreshMart).
+- Contact + newsletter fake submits.
+- Hero / category / product imagery is Unsplash placeholder — replace with merchant photography.
 
 ## Quick start
 

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

@@ -10,24 +10,75 @@ If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this store
 
 ## Aesthetic
 
-Boutique restaurant — Sweetgreen / chef-table feel:
+- **Lora serif + Inter** — warm, food-friendly headings + clean body.
+- **Forest green + cream** — deep sage primary, warm cream background.
+- **Mid radius**: `0.625rem`.
+- Schema.org `@type` is `Restaurant`.
 
-- **Lora serif** for headings (warm, food-leaning).
-- **Inter** for body and UI.
-- **Forest green + cream**: deep sage primary, warm cream background, subtle warm accents.
-- **Mid-radius**: `0.625rem` — softer than retail, tighter than spa.
+## Page surface
 
-## Industry-specific copy patterns
+```
+app/
+  page.tsx                       Home — hero with daily-special badge,
+                                  collection strips, category grid
+  shop/page.tsx                  Full menu (SDK <CataloguePage/>)
+  search/page.tsx                Search
+  collections/[slug]/page.tsx    Collection landing (e.g. brunch, mains)
+  categories/[slug]/page.tsx     Category landing
+
+  reservations/page.tsx          ⭐ Restaurant-specific: reservation widget
+                                  (date + lunch/dinner slot + party size)
+                                  backed by service-type "seating" products
+
+  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 (delivery), returns/page.tsx (refunds), 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, Restaurant JSON-LD |
+| `app/page.tsx` | `brand.hero` (daily-special badge) |
+| `app/about/page.tsx` | `brand.about` |
+| `app/faq/page.tsx` | `brand.faq` (reservations, dietary, delivery) |
+| `app/shipping/page.tsx` | `brand.shipping` (delivery + pickup) |
+| `app/returns/page.tsx` | `brand.returns` (refund + cancellation) |
+| `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 the UI) |
+| `app/reservations/*` | derives seating from service-type products in the catalogue |
+| `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
+| `components/header.tsx`, `footer.tsx` | `brand.header`, `brand.footer`, `brand.contact`, `brand.socials` |
+
+## Restaurant-specific notes
 
-- `brand.hero.badge` is `"Tonight's special · Banku & Tilapia"` — a daily-special call-out.
-- `brand.hero.primaryCtaLabel` is `"Reserve a table"`.
-- `brand.tradeIn` is omitted.
-- `brand.faq` covers reservations, dietary, delivery, allergens.
-- Schema.org type is `Restaurant`.
+- **Reservations are service-type products.** Add seating options like "Two-top", "Four-top", "Long table for 12" to the catalogue with `type: "service"`. The `/reservations` page filters them in.
+- The reservation widget adds the chosen seating to cart with the date, time, party size, and notes as cart-item notes; checkout finalises the booking via Cimplify's order pipeline.
+- Schema.org `@type` is `Restaurant`. `servesCuisine` etc. can be added to the JSON-LD object in `app/layout.tsx` if needed.
+- Mock seed: `--seed restaurant` (Mama's Kitchen).
 
-## Mock seed
+## Known TODOs
 
-Wired to `--seed restaurant` (Mama's Kitchen).
+- `/reservations` widget assumes every slot is bookable. For production, wire `useAvailableSlots({ serviceId, date })` from `@cimplify/sdk/react` to filter to actually-free windows.
+- Contact form + newsletter fake their submits.
+- Hero / dish photography is Unsplash — replace with merchant photos.
 
 ## Quick start
 

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