@cimplify/sdk 0.42.1 → 0.44.0

package/dist/mock/msw.mjs

@@ -7990,6 +7990,442 @@ function seedGrocery(registry) {
   return { businessId };
 }
 
+// src/mock/seeds/fashion.ts
+var ISO8 = "2026-01-01T00:00:00.000Z";
+var img3 = (id) => `https://images.unsplash.com/photo-${id}?w=900&h=1200&fit=crop&auto=format&q=80`;
+var PHOTO2 = {
+  "heavyweight-hoodie-charcoal": "1556905055-8f358a7a47b2",
+  "heavyweight-hoodie-cream": "1576566588028-4147f3842f27",
+  "heavyweight-hoodie-cobalt": "1542838686-37da4a9fd1b3",
+  "studio-tee-black": "1521572163474-6864f9cf17ab",
+  "studio-tee-natural": "1485518882345-15568b007407",
+  "graphic-tee-frx-mark": "1521223890158-f9f7c3d5d504",
+  "carbon-bomber": "1591047139829-d91aecb6caea",
+  "field-jacket-olive": "1564859228273-274232fdb516",
+  "wide-leg-trouser": "1542272604-787c3835535d",
+  "track-pant-charcoal": "1604176354204-9268737828e4",
+  "studio-cap": "1620799140408-edc6dcb6d633",
+  "tote-natural": "1591195853828-11db59a44f6b",
+  "knit-beanie": "1542838132-92c53300491e",
+  "studio-sock-3pack": "1602810318383-e386cc2a3ccf"
+};
+var photoFor2 = (slug) => img3(PHOTO2[slug] ?? "1556905055-8f358a7a47b2");
+var SIZES = ["XS", "S", "M", "L", "XL", "2XL"];
+function seedFashion(registry) {
+  const businessId = "bus_studio_frx";
+  const business = {
+    id: businessId,
+    name: "Studio FRX",
+    handle: "studiofrx",
+    business_type: "retail",
+    email: "hello@studiofrx.test",
+    default_currency: "GHS",
+    default_phone: "+233244000000",
+    default_address: "Osu Oxford Street, Accra",
+    default_offers_table_service: false,
+    default_accepts_online_orders: true,
+    image: img3("1490481651871-ab68de25d43d"),
+    status: "active",
+    created_at: ISO8,
+    updated_at: ISO8,
+    created_by: "seed",
+    preferences: {
+      tagline: "Limited-run streetwear from Accra",
+      description: "Heavyweight cotton, garment-dyed in Tema, hand-screened. Each drop is a closed run \u2014 when it's gone, it's gone.",
+      instagram: "https://instagram.com/studiofrx",
+      theme: "monochrome",
+      checkout: { allow_guest: true }
+    },
+    is_online_only: false,
+    enabled_payment_types: ["card", "mobile_money"],
+    default_location_settings: {},
+    country_code: "GH",
+    timezone: "Africa/Accra"
+  };
+  registry.businesses.put(businessId, business);
+  const categories = [
+    { slug: "new-arrivals", name: "New Arrivals", description: "Just dropped \u2014 the latest from the studio." },
+    { slug: "hoodies", name: "Hoodies", description: "Heavyweight 500gsm, garment-dyed in Tema." },
+    { slug: "tees", name: "Tees", description: "14oz cotton, oversized cut, hand-screened." },
+    { slug: "outerwear", name: "Outerwear", description: "Bombers, field jackets, made for layering." },
+    { slug: "bottoms", name: "Bottoms", description: "Wide-leg trousers and track pants." },
+    { slug: "accessories", name: "Accessories", description: "Caps, totes, beanies, socks." }
+  ];
+  const catIds = /* @__PURE__ */ new Map();
+  for (const c of categories) {
+    const id = `cat_${c.slug}`;
+    catIds.set(c.slug, id);
+    const cat = {
+      id,
+      business_id: businessId,
+      name: c.name,
+      slug: c.slug,
+      description: c.description,
+      product_ids: [],
+      display_order: 0,
+      is_active: true,
+      created_at: ISO8,
+      updated_at: ISO8
+    };
+    registry.categories.put(id, cat);
+  }
+  const products = [
+    // Hoodies
+    {
+      slug: "heavyweight-hoodie-charcoal",
+      name: "Heavyweight Hoodie \xB7 Charcoal",
+      price: "650.00",
+      category: "hoodies",
+      description: "500gsm garment-dyed cotton, hand-screened FRX seal at chest. Numbered run of 600. Oversized fit; size down for regular cut.",
+      tags: ["hoodie", "signature", "drop-04"],
+      isSignature: true
+    },
+    {
+      slug: "heavyweight-hoodie-cream",
+      name: "Heavyweight Hoodie \xB7 Cream",
+      price: "650.00",
+      category: "hoodies",
+      description: "500gsm garment-dyed cotton in natural cream. Numbered run of 600.",
+      tags: ["hoodie", "drop-04"],
+      isNew: true
+    },
+    {
+      slug: "heavyweight-hoodie-cobalt",
+      name: "Heavyweight Hoodie \xB7 Cobalt",
+      price: "650.00",
+      category: "hoodies",
+      description: "Limited cobalt-blue colourway. 500gsm garment-dyed cotton. Numbered run of 200.",
+      tags: ["hoodie", "limited", "drop-04"],
+      isNew: true
+    },
+    // Tees
+    {
+      slug: "studio-tee-black",
+      name: "Studio Tee \xB7 Black",
+      price: "220.00",
+      category: "tees",
+      description: "14oz heavyweight cotton, garment-dyed. Dropped shoulder, oversized fit. The everyday FRX.",
+      tags: ["tee", "signature"],
+      isSignature: true
+    },
+    {
+      slug: "studio-tee-natural",
+      name: "Studio Tee \xB7 Natural",
+      price: "220.00",
+      category: "tees",
+      description: "14oz heavyweight cotton in undyed natural. Softens beautifully with wear.",
+      tags: ["tee"]
+    },
+    {
+      slug: "graphic-tee-frx-mark",
+      name: "Graphic Tee \xB7 FRX Mark",
+      price: "260.00",
+      category: "tees",
+      description: "Hand-screened FRX seal, oversized fit. 14oz cotton. Numbered run of 400.",
+      tags: ["tee", "graphic", "drop-04"],
+      isNew: true
+    },
+    // Outerwear
+    {
+      slug: "carbon-bomber",
+      name: "Carbon Bomber",
+      price: "1200.00",
+      category: "outerwear",
+      description: "Waxed cotton outer, ribbed cuffs, two-way zip. Cut for layering over a hoodie.",
+      tags: ["outerwear", "premium"],
+      isSignature: true
+    },
+    {
+      slug: "field-jacket-olive",
+      name: "Field Jacket \xB7 Olive",
+      price: "1450.00",
+      category: "outerwear",
+      description: "Garment-dyed military canvas, four utility pockets, drawcord hem. A workhorse.",
+      tags: ["outerwear", "premium", "drop-04"],
+      isNew: true
+    },
+    // Bottoms
+    {
+      slug: "wide-leg-trouser",
+      name: "Wide-Leg Trouser",
+      price: "480.00",
+      category: "bottoms",
+      description: "Heavy twill cotton, pleated front, side pockets. Cut for an oversized silhouette.",
+      tags: ["bottom"]
+    },
+    {
+      slug: "track-pant-charcoal",
+      name: "Track Pant \xB7 Charcoal",
+      price: "380.00",
+      category: "bottoms",
+      description: "Heavyweight loopback fleece, tapered leg, elasticated cuffs. The bottom half of the hoodie set.",
+      tags: ["bottom"]
+    },
+    // Accessories
+    {
+      slug: "studio-cap",
+      name: "Studio Cap",
+      price: "120.00",
+      category: "accessories",
+      description: "Brushed cotton 6-panel, embroidered FRX. Adjustable strap.",
+      tags: ["accessory"]
+    },
+    {
+      slug: "tote-natural",
+      name: "Studio Tote \xB7 Natural",
+      price: "150.00",
+      category: "accessories",
+      description: "12oz natural canvas, screen-printed FRX seal. Roomy.",
+      tags: ["accessory"]
+    },
+    {
+      slug: "knit-beanie",
+      name: "Knit Beanie",
+      price: "140.00",
+      category: "accessories",
+      description: "Merino wool blend, woven label. Two colourways.",
+      tags: ["accessory"]
+    },
+    {
+      slug: "studio-sock-3pack",
+      name: "Studio Sock \xB7 3-pack",
+      price: "180.00",
+      category: "accessories",
+      description: "Heavy-cuff crew socks, 3-pack. Cotton-rich blend.",
+      tags: ["accessory"]
+    }
+  ];
+  for (const p of products) {
+    const id = `prod_${p.slug}`;
+    const catId = catIds.get(p.category);
+    const product = {
+      id,
+      business_id: businessId,
+      name: p.name,
+      slug: p.slug,
+      description: p.description,
+      product_type: "product",
+      base_price: p.price,
+      currency: "GHS",
+      image: photoFor2(p.slug),
+      images: [photoFor2(p.slug)],
+      is_available: true,
+      category_ids: [catId],
+      collection_ids: [],
+      add_on_ids: [],
+      variant_ids: [],
+      tags: p.tags ?? [],
+      is_signature: p.isSignature ?? false,
+      is_new: p.isNew ?? false,
+      render_hint: "physical",
+      created_at: ISO8,
+      updated_at: ISO8
+    };
+    registry.products.put(id, product);
+    const cat = registry.categories.get(catId);
+    cat.product_ids.push(id);
+    registry.categories.put(catId, cat);
+  }
+  for (const p of products) {
+    const productId = `prod_${p.slug}`;
+    const axis = {
+      id: `axis_${p.slug}_size`,
+      business_id: businessId,
+      product_id: productId,
+      name: "Size",
+      display_order: 0,
+      affects_recipe: false,
+      values: SIZES.map((s, i) => ({
+        id: `axv_${p.slug}_size_${s.toLowerCase()}`,
+        business_id: businessId,
+        axis_id: `axis_${p.slug}_size`,
+        name: s,
+        display_order: i,
+        created_at: ISO8,
+        updated_at: ISO8
+      })),
+      created_at: ISO8,
+      updated_at: ISO8
+    };
+    registry.variantAxes.put(axis.id, axis);
+    const variantIds = [];
+    let firstVariant = true;
+    for (const sz of axis.values) {
+      const variantId = `var_${p.slug}_size_${sz.name.toLowerCase()}`;
+      const variant = {
+        id: variantId,
+        product_id: productId,
+        business_id: businessId,
+        name: sz.name,
+        sku: `${p.slug.toUpperCase()}-${sz.name}`,
+        price_adjustment: "0.00",
+        component_multiplier: "1.00",
+        is_default: firstVariant,
+        is_active: true,
+        axis_value_ids: [sz.id],
+        created_at: ISO8,
+        updated_at: ISO8
+      };
+      registry.variants.put(variantId, variant);
+      variantIds.push(variantId);
+      firstVariant = false;
+    }
+    const product = registry.products.get(productId);
+    product.variant_ids = variantIds;
+    registry.products.put(productId, product);
+  }
+  const drop04 = {
+    id: "col_drop_04",
+    business_id: businessId,
+    name: "Drop 04",
+    slug: "drop-04",
+    description: "Spring 2026 capsule. 412 pieces left.",
+    product_ids: [
+      "prod_heavyweight-hoodie-charcoal",
+      "prod_heavyweight-hoodie-cream",
+      "prod_heavyweight-hoodie-cobalt",
+      "prod_graphic-tee-frx-mark",
+      "prod_field-jacket-olive"
+    ],
+    is_active: true,
+    created_at: ISO8,
+    updated_at: ISO8
+  };
+  const bestSellers = {
+    id: "col_best_sellers",
+    business_id: businessId,
+    name: "Best Sellers",
+    slug: "best-sellers",
+    description: "What everyone's buying.",
+    product_ids: [
+      "prod_studio-tee-black",
+      "prod_heavyweight-hoodie-charcoal",
+      "prod_carbon-bomber",
+      "prod_studio-cap",
+      "prod_track-pant-charcoal"
+    ],
+    is_active: true,
+    created_at: ISO8,
+    updated_at: ISO8
+  };
+  registry.collections.put(drop04.id, drop04);
+  registry.collections.put(bestSellers.id, bestSellers);
+  for (const col of [drop04, bestSellers]) {
+    for (const pid of col.product_ids) {
+      const p = registry.products.get(pid);
+      if (p) {
+        p.collection_ids.push(col.id);
+        registry.products.put(pid, p);
+      }
+    }
+  }
+  const tags = [
+    { id: "tag_signature", business_id: businessId, name: "Signature", slug: "signature", color: "#0a0a0a", sort_order: 0, usage_count: 3, created_at: ISO8, updated_at: ISO8 },
+    { id: "tag_drop_04", business_id: businessId, name: "Drop 04", slug: "drop-04", color: "#dc2626", sort_order: 1, usage_count: 5, created_at: ISO8, updated_at: ISO8 },
+    { id: "tag_limited", business_id: businessId, name: "Limited", slug: "limited", color: "#dc2626", sort_order: 2, usage_count: 1, created_at: ISO8, updated_at: ISO8 },
+    { id: "tag_premium", business_id: businessId, name: "Premium", slug: "premium", color: "#7c3aed", sort_order: 3, usage_count: 2, created_at: ISO8, updated_at: ISO8 }
+  ];
+  for (const t of tags) registry.tags.put(t.id, t);
+  const apparel = {
+    id: "tax_apparel",
+    business_id: businessId,
+    name: "Apparel",
+    slug: "apparel",
+    path: ["Apparel"],
+    attribute_template_ids: ["attr_fabric", "attr_country_of_origin"],
+    created_at: ISO8,
+    updated_at: ISO8
+  };
+  registry.taxonomies.put(apparel.id, apparel);
+  const attrs = [
+    {
+      id: "attr_fabric",
+      business_id: businessId,
+      namespace: "core",
+      name: "Fabric",
+      slug: "fabric",
+      description: 'Material composition (e.g. "100% cotton, 500gsm").',
+      attribute_type: "text",
+      is_required: false,
+      is_filterable: true,
+      visibility: "public",
+      display_order: 0,
+      applies_to: "product",
+      created_at: ISO8,
+      updated_at: ISO8
+    },
+    {
+      id: "attr_country_of_origin",
+      business_id: businessId,
+      namespace: "core",
+      name: "Country of origin",
+      slug: "country-of-origin",
+      attribute_type: "text",
+      is_required: false,
+      is_filterable: true,
+      visibility: "public",
+      display_order: 1,
+      applies_to: "product",
+      created_at: ISO8,
+      updated_at: ISO8
+    },
+    {
+      id: "attr_fit",
+      business_id: businessId,
+      namespace: "core",
+      name: "Fit",
+      slug: "fit",
+      attribute_type: "single_select",
+      options: ["regular", "oversized", "relaxed", "slim"],
+      is_required: false,
+      is_filterable: true,
+      visibility: "public",
+      display_order: 2,
+      applies_to: "product",
+      created_at: ISO8,
+      updated_at: ISO8
+    }
+  ];
+  for (const a of attrs) registry.attributeDefs.put(a.id, a);
+  const articles = [
+    {
+      id: "kb_sizing",
+      business_id: businessId,
+      title: "Sizing & fit",
+      slug: "sizing",
+      content: "Our pieces are cut for an oversized, dropped-shoulder fit. Order true to size for the intended fit; size down for a regular cut. Charts on every product page.",
+      category: "products",
+      tags: ["sizing", "fit"],
+      created_at: ISO8,
+      updated_at: ISO8
+    },
+    {
+      id: "kb_drops",
+      business_id: businessId,
+      title: "Drops & restocks",
+      slug: "drops",
+      content: "Each drop is a closed, numbered run. We don't restock. The FRX list gets a 24-hour head start before each drop opens to the public.",
+      category: "general",
+      tags: ["drops", "restocks"],
+      created_at: ISO8,
+      updated_at: ISO8
+    },
+    {
+      id: "kb_returns",
+      business_id: businessId,
+      title: "Returns",
+      slug: "returns",
+      content: "Free returns within 30 days from the US, UK, and EU. Item must be unworn with original tags. Underwear and final-sale items aren't returnable.",
+      category: "logistics",
+      tags: ["returns"],
+      created_at: ISO8,
+      updated_at: ISO8
+    }
+  ];
+  for (const a of articles) registry.knowledgeArticles.put(a.id, a);
+  return { businessId };
+}
+
 // src/mock/seeds/registry.ts
 var SEEDS = {
   default: seedDefault,
@@ -7998,7 +8434,8 @@ var SEEDS = {
   restaurant: seedRestaurant,
   retail: seedRetail,
   services: seedServices,
-  grocery: seedGrocery
+  grocery: seedGrocery,
+  fashion: seedFashion
 };
 function applySeed(registry, name) {
   const fn = SEEDS[name];

package/dist/{server-CVEsjECc.d.mts → server-DD-Cd1Ob.d.mts}

@@ -883,7 +883,7 @@ interface LiteService {
     getMenuCategory(categoryId: string): unknown;
 }
 
-type SeedName = "default" | "empty" | "reesa-storefront" | "restaurant" | "retail" | "services" | "grocery";
+type SeedName = "default" | "empty" | "reesa-storefront" | "restaurant" | "retail" | "services" | "grocery" | "fashion";
 declare function applySeed(registry: StateRegistry, name: SeedName): {
     businessId: string;
 };

package/dist/{server-CVEsjECc.d.ts → server-DD-Cd1Ob.d.ts}

@@ -883,7 +883,7 @@ interface LiteService {
     getMenuCategory(categoryId: string): unknown;
 }
 
-type SeedName = "default" | "empty" | "reesa-storefront" | "restaurant" | "retail" | "services" | "grocery";
+type SeedName = "default" | "empty" | "reesa-storefront" | "restaurant" | "retail" | "services" | "grocery" | "fashion";
 declare function applySeed(registry: StateRegistry, name: SeedName): {
     businessId: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/sdk",
-  "version": "0.42.1",
+  "version": "0.44.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/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`.