@cimplify/cli 0.2.0

package/dist/rollback-XO7RIG2A.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { pollDeployment } from './chunk-TAMGCHIL.mjs';
+import { DEPLOYMENT_STATUS, DEPLOY_TRIGGER } from './chunk-MQMNWLMU.mjs';
+import { parseArgs, flagBool } from './chunk-D7D75ONX.mjs';
+import { ApiClient } from './chunk-4ZVTPMUZ.mjs';
+import { readAuth, readProjectLink, writeProjectState } from './chunk-JJYWETGA.mjs';
+import { CliError, CLI_ERROR_CODE, step, success, info, dim, result, EXIT_CODE } from './chunk-NZ4RG62Z.mjs';
+
+// src/commands/rollback.ts
+var FLAG_NO_POLL = "no-poll";
+function deploymentsEndpoint(businessId, projectId) {
+  return `/v1/businesses/${encodeURIComponent(businessId)}/projects/${encodeURIComponent(projectId)}/deployments`;
+}
+function deployEndpoint(businessId, projectId) {
+  return `/v1/businesses/${encodeURIComponent(businessId)}/projects/${encodeURIComponent(projectId)}/deploy`;
+}
+async function run(argv) {
+  const args = parseArgs(argv);
+  const targetId = args.positional[0];
+  if (!targetId) {
+    throw new CliError(
+      CLI_ERROR_CODE.INVALID_INPUT,
+      "Usage: cimplify rollback <deployment-id>\nList past deployments via the dashboard or API."
+    );
+  }
+  const auth = await readAuth();
+  const link = await readProjectLink();
+  const client = ApiClient.fromAuth(auth);
+  const deployments = await client.get(
+    deploymentsEndpoint(link.businessId, link.projectId)
+  );
+  const target = deployments.find((d) => d.id === targetId);
+  if (!target) {
+    throw new CliError(
+      CLI_ERROR_CODE.PROJECT_NOT_FOUND,
+      `Deployment ${targetId} not found in project history.`
+    );
+  }
+  if (!target.git_sha) {
+    throw new CliError(
+      CLI_ERROR_CODE.INVALID_INPUT,
+      `Deployment ${targetId} has no git_sha to roll back to.`
+    );
+  }
+  const currentActive = deployments.find(
+    (d) => d.status === DEPLOYMENT_STATUS.ACTIVE && d.environment === target.environment
+  );
+  const body = {
+    git_ref: target.git_sha,
+    env_scope: target.environment,
+    trigger: DEPLOY_TRIGGER.ROLLBACK,
+    parent_id: currentActive?.id
+  };
+  step(`Rolling back ${target.environment} to ${target.git_sha.slice(0, 12)}`);
+  const enqueued = await client.post(
+    deployEndpoint(link.businessId, link.projectId),
+    body
+  );
+  await writeProjectState({
+    lastDeploymentId: enqueued.deployment_id,
+    lastDeploymentSha: enqueued.git_sha,
+    lastDeploymentEnv: target.environment,
+    lastDeploymentAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  success(`Enqueued rollback ${enqueued.deployment_id}`);
+  if (flagBool(args, FLAG_NO_POLL)) {
+    info(dim(`Track via: cimplify deployments status ${enqueued.deployment_id}`));
+    result({
+      deployment: {
+        id: enqueued.deployment_id,
+        git_sha: enqueued.git_sha,
+        environment: target.environment,
+        status: "queued",
+        rolled_back_from: target.id
+      }
+    });
+    return;
+  }
+  const final = await pollDeployment(
+    client,
+    link.businessId,
+    link.projectId,
+    enqueued.deployment_id
+  );
+  result({
+    deployment: {
+      id: enqueued.deployment_id,
+      git_sha: enqueued.git_sha,
+      environment: target.environment,
+      status: final.status,
+      url: final.url ?? null,
+      error_message: final.error_message ?? null,
+      rolled_back_from: target.id
+    }
+  });
+  if (final.status === DEPLOYMENT_STATUS.ACTIVE) {
+    process.exitCode = EXIT_CODE.OK;
+    return;
+  }
+  if (final.status === DEPLOYMENT_STATUS.SUPERSEDED) {
+    process.exitCode = EXIT_CODE.SUPERSEDED;
+    return;
+  }
+  process.exitCode = EXIT_CODE.ERROR;
+}
+
+export { run as default };

package/dist/status-7CMVLD54.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { DEPLOYMENT_STATUS } from './chunk-MQMNWLMU.mjs';
+import { parseArgs } from './chunk-D7D75ONX.mjs';
+import { ApiClient } from './chunk-4ZVTPMUZ.mjs';
+import { readAuth, readProjectLink, readProjectState } from './chunk-JJYWETGA.mjs';
+import { bold, dim, info, result } from './chunk-NZ4RG62Z.mjs';
+
+// src/commands/status.ts
+var QUERY_LIMIT = "limit";
+var LATEST_DEPLOYMENT_LIMIT = 1;
+var SECONDS_PER_MINUTE = 60;
+var SECONDS_PER_HOUR = 3600;
+var SECONDS_PER_DAY = 86400;
+var SHA_DISPLAY_LEN = 7;
+function deploymentsEndpoint(businessId, projectId) {
+  return `/v1/businesses/${encodeURIComponent(businessId)}/projects/${encodeURIComponent(projectId)}/deployments`;
+}
+function deploymentProgressEndpoint(businessId, projectId, deploymentId) {
+  return `/v1/businesses/${encodeURIComponent(businessId)}/projects/${encodeURIComponent(projectId)}/deployments/${encodeURIComponent(deploymentId)}/progress`;
+}
+function relativeTime(fromIso, now = /* @__PURE__ */ new Date()) {
+  if (!fromIso) return "unknown";
+  const then = new Date(fromIso);
+  if (Number.isNaN(then.getTime())) return fromIso;
+  const diffSec = Math.floor((now.getTime() - then.getTime()) / 1e3);
+  if (diffSec < SECONDS_PER_MINUTE) return `${diffSec} second${diffSec === 1 ? "" : "s"} ago`;
+  if (diffSec < SECONDS_PER_HOUR) {
+    const m = Math.floor(diffSec / SECONDS_PER_MINUTE);
+    return `${m} minute${m === 1 ? "" : "s"} ago`;
+  }
+  if (diffSec < SECONDS_PER_DAY) {
+    const h = Math.floor(diffSec / SECONDS_PER_HOUR);
+    return `${h} hour${h === 1 ? "" : "s"} ago`;
+  }
+  const d = Math.floor(diffSec / SECONDS_PER_DAY);
+  return `${d} day${d === 1 ? "" : "s"} ago`;
+}
+function renderStatus(link, row, now = /* @__PURE__ */ new Date()) {
+  const out = [];
+  out.push(`${bold("Project:")}  ${link.projectId}${link.framework ? dim(` (${link.framework})`) : ""}`);
+  if (link.remoteUrl) {
+    const branch = link.defaultBranch ? ` @ ${link.defaultBranch}` : "";
+    out.push(`${bold("Linked:")}   ${link.remoteUrl}${branch}`);
+  }
+  out.push("");
+  if (!row) {
+    out.push(dim("No deployments yet. Run `cimplify deploy`."));
+    return out;
+  }
+  out.push(bold("Latest deployment:"));
+  out.push(`  ID:       ${row.id}`);
+  out.push(`  Status:   ${row.status}`);
+  if (row.environment) out.push(`  Env:      ${row.environment}`);
+  if (row.trigger) out.push(`  Trigger:  ${row.trigger}`);
+  if (row.sha) out.push(`  SHA:      ${row.sha.slice(0, SHA_DISPLAY_LEN)}`);
+  if (row.url) out.push(`  URL:      ${row.url}`);
+  if (row.startedAt) out.push(`  Started:  ${relativeTime(row.startedAt, now)}`);
+  return out;
+}
+async function run(argv) {
+  parseArgs(argv);
+  const auth = await readAuth();
+  const link = await readProjectLink();
+  const client = ApiClient.fromAuth(auth);
+  const state = await readProjectState();
+  let row = null;
+  if (state?.lastDeploymentId) {
+    const progress = await client.get(
+      deploymentProgressEndpoint(link.businessId, link.projectId, state.lastDeploymentId)
+    );
+    row = {
+      id: state.lastDeploymentId,
+      status: progress.status ?? DEPLOYMENT_STATUS.QUEUED,
+      sha: state.lastDeploymentSha,
+      url: progress.url ?? void 0,
+      startedAt: state.lastDeploymentAt,
+      environment: state.lastDeploymentEnv
+    };
+  } else {
+    const recent = await client.get(
+      deploymentsEndpoint(link.businessId, link.projectId),
+      { query: { [QUERY_LIMIT]: LATEST_DEPLOYMENT_LIMIT } }
+    );
+    const latest = recent[0];
+    if (latest) {
+      row = {
+        id: latest.id,
+        status: latest.status,
+        trigger: latest.trigger,
+        sha: latest.git_sha ?? void 0,
+        url: latest.url ?? void 0,
+        startedAt: latest.created_at,
+        environment: latest.environment
+      };
+    }
+  }
+  for (const line of renderStatus(
+    {
+      projectId: link.projectId,
+      remoteUrl: link.remoteUrl,
+      defaultBranch: link.defaultBranch,
+      framework: link.framework
+    },
+    row
+  )) {
+    info(line);
+  }
+  result({
+    project: {
+      id: link.projectId,
+      framework: link.framework ?? null,
+      remote_url: link.remoteUrl ?? null,
+      default_branch: link.defaultBranch ?? null
+    },
+    deployment: row ? {
+      id: row.id,
+      status: row.status,
+      environment: row.environment ?? null,
+      trigger: row.trigger ?? null,
+      git_sha: row.sha ?? null,
+      url: row.url ?? null,
+      started_at: row.startedAt ?? null
+    } : null
+  });
+}
+
+export { run as default, relativeTime, renderStatus };

package/dist/unlink-5ABCT7B6.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { clearProjectLink } from './chunk-JJYWETGA.mjs';
+import { success, info, result } from './chunk-NZ4RG62Z.mjs';
+
+// src/commands/unlink.ts
+async function run(_argv) {
+  const removed = await clearProjectLink();
+  if (removed) {
+    success("Unlinked project.");
+  } else {
+    info("No project link to remove.");
+  }
+  result({ unlinked: removed });
+}
+
+export { run as default };

package/dist/whoami-INHDUHWA.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { ApiClient } from './chunk-4ZVTPMUZ.mjs';
+import { readAuth } from './chunk-JJYWETGA.mjs';
+import { info, bold, dim, result } from './chunk-NZ4RG62Z.mjs';
+
+// src/commands/whoami.ts
+var ENDPOINT_AUTH_ME = "/v1/auth/me";
+async function run(_argv) {
+  const auth = await readAuth();
+  const client = ApiClient.fromAuth(auth);
+  const me = await client.get(ENDPOINT_AUTH_ME);
+  info(`${bold("Account")}    ${me.id}`);
+  if (me.email) info(`${bold("Email")}      ${me.email}`);
+  if (me.name) info(`${bold("Name")}       ${me.name}`);
+  info(`${bold("Business")}   ${me.business_id}`);
+  info(`${bold("API")}        ${dim(auth.apiBaseUrl)}`);
+  result({
+    account: { id: me.id, email: me.email ?? null, name: me.name ?? null },
+    business: { id: me.business_id },
+    api_base_url: auth.apiBaseUrl
+  });
+}
+
+export { run as default };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cimplify/cli",
+  "version": "0.2.0",
+  "description": "Cimplify CLI — deploy, manage env vars, link projects, and scaffold storefronts",
+  "keywords": [
+    "cimplify",
+    "cli",
+    "deploy",
+    "storefront"
+  ],
+  "license": "MIT",
+  "bin": {
+    "cimplify": "dist/dispatcher.mjs"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "bundle-assets": "bun scripts/bundle-assets.ts",
+    "prebuild": "bun run bundle-assets",
+    "build": "tsup",
+    "build:binary": "bun run bundle-assets && bun scripts/build-binaries.ts",
+    "build:binary:local": "bun run bundle-assets && bun scripts/build-binaries.ts --local",
+    "sync:template-pins": "bun scripts/sync-template-pins.ts",
+    "version": "bun scripts/sync-template-pins.ts && git add templates/*/package.json",
+    "prepublishOnly": "bun scripts/sync-template-pins.ts && bun run build",
+    "dev": "bun run bundle-assets && tsup --watch",
+    "typecheck": "bun run bundle-assets && tsgo --noEmit -p tsconfig.json",
+    "clean": "rm -rf dist bin src/embedded-assets.ts",
+    "lint:ox": "oxlint --fix .",
+    "format": "oxfmt . --write",
+    "format:check": "oxfmt . --check",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260503.1",
+    "tsup": "^8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.5"
+  }
+}

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/.env.example

@@ -0,0 +1,16 @@
+# Cimplify API base URL.
+# Dev: leave empty so the SDK uses the current origin (localhost:3000),
+# which Next.js rewrites to the mock at 127.0.0.1:8787 (see next.config.ts).
+# Production: set to your Cimplify host (e.g. https://api.cimplify.io).
+NEXT_PUBLIC_CIMPLIFY_API_URL=
+
+# Tenant public key. The mock accepts any value.
+NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=mock-dev
+
+# Business id used by the mock seed (default: Akua's Bakery).
+NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_default_akua_bakery
+
+# Canonical public site URL — used by sitemap.xml, robots.txt, llms.txt,
+# and OpenGraph metadata. Set this on production deploys (Vercel auto-injects
+# via VERCEL_URL but Next prefers an explicit value).
+NEXT_PUBLIC_SITE_URL=https://example.com

package/templates/storefront-bakery/AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md — Bakery storefront template
+
+If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this storefront, **start here.**
+
+## TL;DR for rebranding
+
+To rebrand this storefront end-to-end as a different merchant:
+
+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`.
+
+## Rules
+
+- ✅ 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 modal) 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.
+
+## 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` | 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/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`, `brand.contact`, `brand.socials` |
+
+## Bakery-specific notes
+
+- 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`.
+
+## Known TODOs (not blocking, but worth knowing)
+
+- `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.
+
+## Customizing SDK components
+
+For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for product customization** (variants, add-ons, bundles, composites, services with scheduling) — the SDK already gets price math, axis matching, and cart payload contracts right. Default to ejecting and restyling:
+
+```bash
+bunx @cimplify/sdk add cart-drawer
+bunx @cimplify/sdk add variant-selector
+bunx @cimplify/sdk add product-page
+```
+
+Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".
+
+## Quick start
+
+```bash
+bun install
+bun dev                 # boots mock + Next dev server
+```
+
+Open <http://localhost:3000>.

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`.