@cimplify/cli 0.7.18 → 0.7.19

package/dist/dispatcher.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { TEMPLATES } from './chunk-HWHV62KB.mjs';
-import { package_default } from './chunk-GAN7PG6N.mjs';
+import { TEMPLATES } from './chunk-VG6K7O6Q.mjs';
+import { package_default } from './chunk-HOOY5QBI.mjs';
 
 // src/dispatcher.ts
 var VERSION = package_default.version ?? "unknown";
@@ -138,16 +138,16 @@ var COMMANDS = {
   logs: () => import('./logs-YNN2PQ24.mjs'),
   status: () => import('./status-JSYXM5RT.mjs'),
   dev: () => import('./dev-ONW2S77K.mjs'),
-  introspect: () => import('./introspect-ZS6I46OO.mjs'),
+  introspect: () => import('./introspect-VUTR3NSR.mjs'),
   inspect: () => import('./inspect-CGYX4DDF.mjs'),
-  doctor: () => import('./doctor-IGQNPWUY.mjs'),
-  explain: () => import('./explain-IK2FYBB7.mjs'),
+  doctor: () => import('./doctor-JOC3TBGJ.mjs'),
+  explain: () => import('./explain-P5WRAUZ6.mjs'),
   assets: () => import('./assets-74SK63TR.mjs'),
   repo: () => import('./repo-KNQMSPVV.mjs'),
-  list: () => import('./list-P74FSKQR.mjs'),
-  add: () => import('./add-UXXUPBKR.mjs'),
-  update: () => import('./update-E6Q3KV3B.mjs'),
-  upgrade: () => import('./update-E6Q3KV3B.mjs'),
+  list: () => import('./list-KLDTK2H3.mjs'),
+  add: () => import('./add-NGRXXN3X.mjs'),
+  update: () => import('./update-MDBLCCQ2.mjs'),
+  upgrade: () => import('./update-MDBLCCQ2.mjs'),
   "auth-step-up": () => import('./auth-step-up-BIUYQJP6.mjs')
 };
 var COMMAND_PREFIXES = {

package/dist/{doctor-IGQNPWUY.mjs → doctor-JOC3TBGJ.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { gatherIntrospection } from './chunk-MR3Q43SU.mjs';
+import { gatherIntrospection } from './chunk-DAEUJO35.mjs';
 import './chunk-K5464A3L.mjs';
 import './chunk-DBZ3UOQ2.mjs';
-import './chunk-GAN7PG6N.mjs';
+import './chunk-HOOY5QBI.mjs';
 import { parseArgs, flagBool } from './chunk-C4M3DXKC.mjs';
 import { ApiClient } from './chunk-MAOO6ZZ5.mjs';
 import { readAuthOrNull } from './chunk-UBAI443T.mjs';

package/dist/{explain-IK2FYBB7.mjs → explain-P5WRAUZ6.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { package_default } from './chunk-GAN7PG6N.mjs';
+import { package_default } from './chunk-HOOY5QBI.mjs';
 import { parseArgs } from './chunk-C4M3DXKC.mjs';
 import { bold, dim, info, result, CliError, CLI_ERROR_CODE } from './chunk-E2T2SBP5.mjs';
 
@@ -17,7 +17,7 @@ var TOPICS = [
     "title": "Customizing a template",
     "description": "When and how to eject SDK components into your project",
     "source_url": "https://cimplify.dev/docs/templates/customizing",
-    "body": '## The customisation tiers\n\n      \n        \n\n| Tier | When | Cost |\n| --- | --- | --- |\n| Edit `brand.ts` | Copy, links, contact, hero, FAQ, policies | Free updates from the SDK forever |\n| Edit `globals.css @theme` | Palette, radius, fonts | Free updates from the SDK forever |\n| `classNames` overrides | Restyle a slot inside an SDK component | Free updates; no fork |\n| Eject a component | Restructure JSX, change behaviour, add merchant logic | You own the file; no auto-updates |\n| Extend `BrandSchema` | Industry-specific fields (lookbook, booking policy) | Type-checked, validated, schema co-evolves |\n\n      \n\n      \n\n## Edit content via `brand.ts`\n\n      \n\nHardcoding a string in a page or component is the wrong move. Hoist it into the brand object first; everything that reads from `brand` stays consistent across pages, sitemap, and metadata.\n\n      \n        \n\n```tsx\n// \u274C wrong: hardcoded in a component\n<h1>Akua\'s Bakery</h1>\n\n// \u2705 right: sourced from the brand contract\n<h1>{brand.hero.title}</h1>\n```\n\n      \n\n      \n\n## Eject a component\n\n      \n\nThe SDK ships ~67 ejectable components in its registry (cards, selectors, full pages, primitives). Eject when a `classNames` override can\'t reach the part you need to change, or when you\'re restructuring beyond what the component\'s props support.\n\n      \n        \n\n```bash\n# Browse the registry\ncimplify list\n\n# Eject one\ncimplify add cart-summary\n# \u2192 writes ./components/cart-summary.tsx, owned by you\n\n# Replace the SDK import in your page\n# import { CartSummary } from "@cimplify/sdk/react"\n# import { CartSummary } from "@/components/cart-summary"\n```\n\n      \n      \n\nOnce ejected, the file is yours. SDK upgrades won\'t touch it; you trade off auto-bugfixes for full control.\n\n      \n        \n\n**Don\'t reinvent the customizer.** Variant selection, add-on math, bundle pricing, and composite mode-switching took many iterations to get right. Eject `variant-selector`, `composite-selector`, `bundle-selector`, or `add-on-selector` and re-style; don\'t rewrite the cart payload contract. See `AGENTS.md` for the full doctrine.\n\n      \n\n      \n\n## Extend the brand schema\n\n      \n\nIndustry-specific fields belong on the schema, not in scattered component props. Use `BrandSchema.extend` so your additions get the same boot-time validation as the canonical fields.\n\n      \n        \n\n```ts title="lib/schema.ts (services template)"\n\nexport const ServicesBrandSchema = BrandSchema.extend({\n  bookingPolicy: z.object({\n    cancellationWindowHours: z.number().int().positive(),\n    depositPercent: z.number().int().min(0).max(100),\n    rescheduleNoticeHours: z.number().int().positive(),\n  }),\n});\n\nexport type ServicesBrand = z.infer<typeof ServicesBrandSchema>;\n```\n\n      \n      \n        \n\n```ts title="lib/brand.ts"\n\nexport const brand: ServicesBrand = {\n  // \u2026all the standard Brand fields\u2026\n  bookingPolicy: {\n    cancellationWindowHours: 24,\n    depositPercent: 25,\n    rescheduleNoticeHours: 12,\n  },\n};\n```\n\n      \n      \n        \n\n```ts title="__tests__/brand.test.ts: assert against the extended schema"\n\ndescribe("brand", () => {\n  it("conforms to the services brand contract", () => {\n    expect(ServicesBrandSchema.safeParse(brand).success).toBe(true);\n  });\n});\n```\n\n      \n\n      \n\n## Add a new section\n\n      \n\n1. Build the section as a Server Component in `components/`.\n2. Read merchant-specific copy from `brand`; extend the schema if the field isn\'t there.\n3. Wrap any client interactivity in a `*-client.tsx` island behind `<Suspense>` to keep the chrome cached.\n4. Compose into the page (`app/page.tsx`, `app/products/[slug]/page.tsx`, \u2026).\n5. Run `bun run check`.\n\n      \n\n## Wire a Server Action\n\n      \n        \n\n```ts\n"use server";\n\nexport async function cancelMyOrder(orderId: string) {\n  const r = await getServerClient().orders.cancel(orderId, "customer requested");\n  if (!r.ok) return { ok: false as const, message: r.error.message };\n\n  await revalidateOrders();\n  return { ok: true as const };\n}\n```\n\n      \n\n      \n\n## Don\'ts\n\n      \n\n- Hardcode strings in pages or components.\n- Enable `cacheComponents: true` in `next.config.ts`. Cache Components (the `\'use cache\'` directive) is still experimental and its runtime constraints don\'t suit hosted storefronts. Stay on the ISR Previous Model the templates ship with.\n- Use `\'use cache\'` / `cacheTag` / `cacheLife` directives. Same reason \u2014 they require Cache Components, which we don\'t enable. Use `export const revalidate` per page + `cacheOptions: { revalidate, tags }` on SDK reads.\n- Bypass `getServerClient()` by instantiating `createCimplifyClient` directly in a Server Component; you\'ll lose per-request memoisation.\n\n      \n\n## Next\n\n      \n        \n- [**Brand schema**](/docs/templates/brand)\n  Field reference and a full example\n\n        \n- [**Testing**](/docs/testing)\n  Catch ejections that broke the contract\n'
+    "body": '## The customisation tiers\n\n      \n        \n\n| Tier | When | Cost |\n| --- | --- | --- |\n| Edit `brand.ts` | Copy, links, contact, hero, FAQ, policies | Free updates from the SDK forever |\n| Edit `globals.css @theme` | Palette, radius, fonts | Free updates from the SDK forever |\n| `classNames` overrides | Restyle a slot inside an SDK component | Free updates; no fork |\n| Eject a component | Restructure JSX, change behaviour, add merchant logic | You own the file; no auto-updates |\n| Extend `BrandSchema` | Industry-specific fields (lookbook, booking policy) | Type-checked, validated, schema co-evolves |\n\n      \n\n      \n\n## Edit content via `brand.ts`\n\n      \n\nHardcoding a string in a page or component is the wrong move. Hoist it into the brand object first; everything that reads from `brand` stays consistent across pages, sitemap, and metadata.\n\n      \n        \n\n```tsx\n// \u274C wrong: hardcoded in a component\n<h1>Akua\'s Bakery</h1>\n\n// \u2705 right: sourced from the brand contract\n<h1>{brand.hero.title}</h1>\n```\n\n      \n\n      \n\n## Eject a component\n\n      \n\nThe SDK ships ~67 ejectable components in its registry (cards, selectors, full pages, primitives). Eject when a `classNames` override can\'t reach the part you need to change, or when you\'re restructuring beyond what the component\'s props support.\n\n      \n        \n\n```bash\n# Browse the registry\ncimplify list\n\n# Eject one\ncimplify add cart-summary\n# \u2192 writes ./components/cart-summary.tsx, owned by you\n\n# Replace the SDK import in your page\n# import { CartSummary } from "@cimplify/sdk/react"\n# import { CartSummary } from "@/components/cart-summary"\n```\n\n      \n      \n\nOnce ejected, the file is yours. SDK upgrades won\'t touch it; you trade off auto-bugfixes for full control.\n\n      \n        \n\n**Don\'t reinvent the customizer.** Variant selection, add-on math, bundle pricing, and composite mode-switching took many iterations to get right. Eject `variant-selector`, `composite-selector`, `bundle-selector`, or `add-on-selector` and re-style; don\'t rewrite the cart payload contract. See `AGENTS.md` for the full doctrine.\n\n      \n\n      \n\n## Extend the brand schema\n\n      \n\nIndustry-specific fields belong on the schema, not in scattered component props. Use `BrandSchema.extend` so your additions get the same boot-time validation as the canonical fields.\n\n      \n        \n\n```ts title="lib/schema.ts (services template)"\n\nexport const ServicesBrandSchema = BrandSchema.extend({\n  bookingPolicy: z.object({\n    cancellationWindowHours: z.number().int().positive(),\n    depositPercent: z.number().int().min(0).max(100),\n    rescheduleNoticeHours: z.number().int().positive(),\n  }),\n});\n\nexport type ServicesBrand = z.infer<typeof ServicesBrandSchema>;\n```\n\n      \n      \n        \n\n```ts title="lib/brand.ts"\n\nexport const brand: ServicesBrand = {\n  // \u2026all the standard Brand fields\u2026\n  bookingPolicy: {\n    cancellationWindowHours: 24,\n    depositPercent: 25,\n    rescheduleNoticeHours: 12,\n  },\n};\n```\n\n      \n      \n        \n\n```ts title="__tests__/brand.test.ts: assert against the extended schema"\n\ndescribe("brand", () => {\n  it("conforms to the services brand contract", () => {\n    expect(ServicesBrandSchema.safeParse(brand).success).toBe(true);\n  });\n});\n```\n\n      \n\n      \n\n## Add a new section\n\n      \n\n1. Build the section as a Server Component in `components/`.\n2. Read merchant-specific copy from `brand`; extend the schema if the field isn\'t there.\n3. Wrap any client interactivity in a `*-client.tsx` island behind `<Suspense>` to keep the chrome cached.\n4. Compose into the page (`app/page.tsx`, `app/products/[slug]/page.tsx`, \u2026).\n5. Run `bun run check`.\n\n      \n\n## Wire a Server Action\n\n      \n        \n\n```ts\n"use server";\n\nexport async function cancelMyOrder(orderId: string) {\n  const r = await getServerClient().orders.cancel(orderId, "customer requested");\n  if (!r.ok) return { ok: false as const, message: r.error.message };\n\n  await revalidateOrders();\n  return { ok: true as const };\n}\n```\n\n      \n\n      \n\n## Don\'ts\n\n      \n\n- Hardcode strings in pages or components.\n- Enable `cacheComponents: true` in `next.config.ts`. Cache Components (the `\'use cache\'` directive) is still experimental and its runtime constraints don\'t suit hosted storefronts. Stay on the ISR Previous Model the templates ship with.\n- Use `\'use cache\'` / `cacheTag` / `cacheLife` directives. Same reason: they require Cache Components, which we don\'t enable. Use `export const revalidate` per page + `cacheOptions: { revalidate, tags }` on SDK reads.\n- Bypass `getServerClient()` by instantiating `createCimplifyClient` directly in a Server Component; you\'ll lose per-request memoisation.\n\n      \n\n## Next\n\n      \n        \n- [**Brand schema**](/docs/templates/brand)\n  Field reference and a full example\n\n        \n- [**Testing**](/docs/testing)\n  Catch ejections that broke the contract\n'
   },
   {
     "name": "products",
@@ -87,7 +87,7 @@ var TOPICS = [
     "title": "Orders",
     "description": "Order shape and status flow",
     "source_url": "https://cimplify.dev/docs/sdk/orders",
-    "body": "`client.orders.list()` returns different results depending on how the\nclient was constructed:\n\n- **Guest client** (`getServerClient()` with no `accessToken`, or the\n  browser `cimplify` client with no signed-in shopper): returns nothing\n  by default \u2014 the API has no customer to scope to. `client.orders.get()`\n  still works on the same browser session that placed the order via the\n  cached `bill_token`.\n- **Authenticated client** (`getAuthenticatedServerClient()` from the\n  templates, or `getServerClient({ accessToken })` from a custom integration):\n  returns *that customer's* orders at *this merchant*.\n\nSee [Sign in with Cimplify \u2192 Personalized server-side reads](/docs/sdk/auth#personalized-server-side-reads)\nfor the full setup.\n\n## Render orders for the signed-in shopper\n\n```tsx title=\"app/account/orders/page.tsx\"\n\nexport const revalidate = 0; // personalized; do not ISR-cache\n\nexport default async function OrdersPage() {\n  const client = await getAuthenticatedServerClient();\n  const r = await client.orders.list({ limit: 20 });\n  if (!r.ok) throw new Error(r.error.message);\n\n  if (r.value.length === 0) {\n    return <p>No orders yet.</p>;\n  }\n  return (\n    <ul>\n      {r.value.map((o) => (\n        <li key={o.id}>#{o.order_number} \u2014 {o.status} \u2014 {o.total_price}</li>\n      ))}\n    </ul>\n  );\n}\n```\n\nIf `cimplify_access` is missing (signed-out shopper), `client.orders.list()`\nreturns the empty guest view. Branch on `getSession()` from `lib/auth.ts`\nif you want to redirect to sign-in instead.\n\n## List orders\n\n      \n        \n\n```ts\nconst r = await client.orders.list({ limit: 20 })\nif (!r.ok) {\n  console.error(r.error.code, r.error.message)\n  return\n}\n\nconsole.log(r.value.length)\nfor (const order of r.value) {\n  console.log(order.id, order.order_number, order.status)\n}\n```\n\n      \n\n      \n\n## Filter by status\n\n      \n        \n\n```ts\nconst pending = await client.orders.list({ status: 'pending' })\nconst completed = await client.orders.list({ status: 'completed', limit: 50 })\n\n// Convenience wrappers\nconst recent = await client.orders.getRecent(5)             // last 5\nconst cancelled = await client.orders.getByStatus('cancelled')\n```\n\n      \n\n      \n\n## Get a single order\n\n      \n\nFor guest orders the SDK appends the cached `bill_token` automatically; the lookup works in the same browser session that placed the order, with no auth.\n\n      \n        \n\n```ts\n\nconst r = await client.orders.get('ord_xxx')\nif (!r.ok) return\n\nconst order = r.value\nconsole.log(order.status)\nconsole.log(order.items.length)\nconsole.log(order.total_price)                       // Money string\nconsole.log(formatPrice(parsePrice(order.total_price), order.currency))\n```\n\n      \n\n      \n\n## Cancel an order\n\n      \n        \n\n```ts\nconst cancelled = await client.orders.cancel('ord_xxx', 'changed_mind')\nif (!cancelled.ok) {\n  // Codes you'll see: ORDER_NOT_CANCELLABLE, ORDER_ALREADY_FULFILLED\n  console.error(cancelled.error.code, cancelled.error.message)\n}\n\n// Idempotent retry: same key, same outcome on the server\nawait client.orders.cancel('ord_xxx', 'changed_mind', {\n  idempotencyKey: 'cancel-ord_xxx-once',\n})\n```\n\n      \n\n      \n\n## Order status values\n\n      \n        \n\n| Status | Meaning |\n| --- | --- |\n| `pending` | Created, awaiting payment confirmation |\n| `confirmed` | Accepted by the business |\n| `preparing` | Being assembled or fulfilled |\n| `ready` | Ready for pickup or delivery dispatch |\n| `completed` | Fulfilled; terminal state |\n| `cancelled` | Cancelled; terminal state |\n| `refunded` | Payment refunded |\n\n      \n\n      \n\n## Poll until terminal\n\n      \n        \n\n```ts\nasync function pollUntilTerminal(orderId: string, intervalMs = 5000) {\n  for (;;) {\n    const r = await client.orders.get(orderId)\n    if (!r.ok) return r\n\n    const status = r.value.status\n    if (status === 'completed' || status === 'cancelled' || status === 'refunded') {\n      return r\n    }\n\n    await new Promise((resolve) => setTimeout(resolve, intervalMs))\n  }\n}\n```\n\n      \n\n      \n\n## Method reference\n\n      \n        \n\n| Method | Returns |\n| --- | --- |\n| `list({ status?, limit?, offset? })` | `Result<Order[]>` |\n| `get(orderId)` | `Result<Order>` |\n| `cancel(orderId, reason?, opts?)` | `Result<Order>` |\n| `getRecent(limit?)` | `Result<Order[]>` |\n| `getByStatus(status)` | `Result<Order[]>` |\n\n      \n\n      \n\n## Related\n\n      \n        \n- [**Checkout**](/docs/sdk/checkout)\n  Create the orders that this page lists\n\n        \n- [**Subscriptions**](/docs/sdk/subscriptions)\n  For recurring orders, see the subscription surface\n\n        \n- [**Scheduling**](/docs/sdk/scheduling)\n  Reschedule or cancel a booking line item\n\n        \n- [**Error handling**](/docs/sdk/errors)\n  Cancellation guards and retryable errors\n"
+    "body": "`client.orders.list()` returns different results depending on how the\nclient was constructed:\n\n- **Guest client** (`getServerClient()` with no `accessToken`, or the\n  browser `cimplify` client with no signed-in shopper): returns nothing\n  by default; the API has no customer to scope to. `client.orders.get()`\n  still works on the same browser session that placed the order via the\n  cached `bill_token`.\n- **Authenticated client** (`getAuthenticatedServerClient()` from the\n  templates, or `getServerClient({ accessToken })` from a custom integration):\n  returns *that customer's* orders at *this merchant*.\n\nSee [Sign in with Cimplify \u2192 Personalized server-side reads](/docs/sdk/auth#personalized-server-side-reads)\nfor the full setup.\n\n## Render orders for the signed-in shopper\n\n```tsx title=\"app/account/orders/page.tsx\"\n\nexport const revalidate = 0; // personalized; do not ISR-cache\n\nexport default async function OrdersPage() {\n  const client = await getAuthenticatedServerClient();\n  const r = await client.orders.list({ limit: 20 });\n  if (!r.ok) throw new Error(r.error.message);\n\n  if (r.value.length === 0) {\n    return <p>No orders yet.</p>;\n  }\n  return (\n    <ul>\n      {r.value.map((o) => (\n        <li key={o.id}>#{o.order_number} \xB7 {o.status} \xB7 {o.total_price}</li>\n      ))}\n    </ul>\n  );\n}\n```\n\nIf `cimplify_access` is missing (signed-out shopper), `client.orders.list()`\nreturns the empty guest view. Branch on `getSession()` from `lib/auth.ts`\nif you want to redirect to sign-in instead.\n\n## List orders\n\n      \n        \n\n```ts\nconst r = await client.orders.list({ limit: 20 })\nif (!r.ok) {\n  console.error(r.error.code, r.error.message)\n  return\n}\n\nconsole.log(r.value.length)\nfor (const order of r.value) {\n  console.log(order.id, order.order_number, order.status)\n}\n```\n\n      \n\n      \n\n## Filter by status\n\n      \n        \n\n```ts\nconst pending = await client.orders.list({ status: 'pending' })\nconst completed = await client.orders.list({ status: 'completed', limit: 50 })\n\n// Convenience wrappers\nconst recent = await client.orders.getRecent(5)             // last 5\nconst cancelled = await client.orders.getByStatus('cancelled')\n```\n\n      \n\n      \n\n## Get a single order\n\n      \n\nFor guest orders the SDK appends the cached `bill_token` automatically; the lookup works in the same browser session that placed the order, with no auth.\n\n      \n        \n\n```ts\n\nconst r = await client.orders.get('ord_xxx')\nif (!r.ok) return\n\nconst order = r.value\nconsole.log(order.status)\nconsole.log(order.items.length)\nconsole.log(order.total_price)                       // Money string\nconsole.log(formatPrice(parsePrice(order.total_price), order.currency))\n```\n\n      \n\n      \n\n## Cancel an order\n\n      \n        \n\n```ts\nconst cancelled = await client.orders.cancel('ord_xxx', 'changed_mind')\nif (!cancelled.ok) {\n  // Codes you'll see: ORDER_NOT_CANCELLABLE, ORDER_ALREADY_FULFILLED\n  console.error(cancelled.error.code, cancelled.error.message)\n}\n\n// Idempotent retry: same key, same outcome on the server\nawait client.orders.cancel('ord_xxx', 'changed_mind', {\n  idempotencyKey: 'cancel-ord_xxx-once',\n})\n```\n\n      \n\n      \n\n## Order status values\n\n      \n        \n\n| Status | Meaning |\n| --- | --- |\n| `pending` | Created, awaiting payment confirmation |\n| `confirmed` | Accepted by the business |\n| `preparing` | Being assembled or fulfilled |\n| `ready` | Ready for pickup or delivery dispatch |\n| `completed` | Fulfilled; terminal state |\n| `cancelled` | Cancelled; terminal state |\n| `refunded` | Payment refunded |\n\n      \n\n      \n\n## Poll until terminal\n\n      \n        \n\n```ts\nasync function pollUntilTerminal(orderId: string, intervalMs = 5000) {\n  for (;;) {\n    const r = await client.orders.get(orderId)\n    if (!r.ok) return r\n\n    const status = r.value.status\n    if (status === 'completed' || status === 'cancelled' || status === 'refunded') {\n      return r\n    }\n\n    await new Promise((resolve) => setTimeout(resolve, intervalMs))\n  }\n}\n```\n\n      \n\n      \n\n## Method reference\n\n      \n        \n\n| Method | Returns |\n| --- | --- |\n| `list({ status?, limit?, offset? })` | `Result<Order[]>` |\n| `get(orderId)` | `Result<Order>` |\n| `cancel(orderId, reason?, opts?)` | `Result<Order>` |\n| `getRecent(limit?)` | `Result<Order[]>` |\n| `getByStatus(status)` | `Result<Order[]>` |\n\n      \n\n      \n\n## Related\n\n      \n        \n- [**Checkout**](/docs/sdk/checkout)\n  Create the orders that this page lists\n\n        \n- [**Subscriptions**](/docs/sdk/subscriptions)\n  For recurring orders, see the subscription surface\n\n        \n- [**Scheduling**](/docs/sdk/scheduling)\n  Reschedule or cancel a booking line item\n\n        \n- [**Error handling**](/docs/sdk/errors)\n  Cancellation guards and retryable errors\n"
   },
   {
     "name": "subscriptions",
@@ -129,7 +129,7 @@ var TOPICS = [
     "title": "Assets",
     "description": "Storefront brand assets \u2014 upload to CDN, build URLs, render through next/image",
     "source_url": "https://cimplify.dev/docs/sdk/assets",
-    "body": 'The asset surface on the SDK is **read-side only** \u2014 building URLs for images you\'ve already uploaded via [`cimplify assets upload`](/docs/cli/assets). Customer-runtime uploads still go through `client.uploads.upload(file)`.\n\n## `assetUrl(path, opts?)`\n\nPure URL builder. Prepends the CDN base for relative paths, passes absolute URLs through with the transform query contract appended.\n\n```ts\n\nassetUrl("hero/main.jpg")\n// "https://storefrontassetscdn.cimplify.io/hero/main.jpg"\n\nassetUrl("hero/main.jpg", { w: 1200, format: "webp", quality: 80 })\n// "https://storefrontassetscdn.cimplify.io/hero/main.jpg?w=1200&format=webp&quality=80"\n\nassetUrl("hero/main.jpg", { base: "http://localhost:8787/storage" })\n// "http://localhost:8787/storage/hero/main.jpg"\n\nassetUrl("https://res.cloudinary.com/foo/bar.jpg")\n// "https://res.cloudinary.com/foo/bar.jpg"   (absolute \u2192 passthrough)\n```\n\n### Options\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `base` | `string` | Override the CDN base. Defaults to `DEFAULT_CDN_BASE_URL`. |\n| `w` / `h` | `number` | Width / height in pixels (on-the-fly resizing) |\n| `quality` | `number` | 0\u2013100 |\n| `format` | `"auto" \\| "webp" \\| "avif" \\| "jpeg"` | `"auto"` lets the CDN pick by `Accept` header |\n\nThe transform query is only meaningful when the URL terminates on the Cimplify storefront CDN (which supports on-the-fly resizing). For external hosts, unknown params are typically ignored \u2014 the image still loads at its original size.\n\n## `isCimplifyAsset(src, base?)`\n\nDecides whether `src` is hosted on a Cimplify CDN. Used by the storefront\'s `next/image` loader to skip transforms for external URLs.\n\n```ts\n\nisCimplifyAsset("hero/main.jpg")                                      // true (relative \u2192 ours)\nisCimplifyAsset("/img/seed/bakery/x.jpg")                             // true (dev mock passthrough)\nisCimplifyAsset("https://storefrontassetscdn.cimplify.io/x.jpg")     // true\nisCimplifyAsset("https://cdn.cimplify.io/x.jpg")                     // true\nisCimplifyAsset("https://static-tmp.cimplify.io/seed/x.jpg")         // true\nisCimplifyAsset("https://res.cloudinary.com/demo/upload/x.jpg")      // false\nisCimplifyAsset("https://images.unsplash.com/photo-xyz")             // false\n```\n\n## Built-in `next/image` loader\n\nEvery storefront template scaffolded by `cimplify init` ships `lib/cimplify-loader.ts` and points `images.loaderFile` at it. The loader:\n\n```ts\n\nconst cdnBase = process.env.NEXT_PUBLIC_CIMPLIFY_CDN_URL?.trim() || undefined;\n\nconst cimplifyImageLoader: ImageLoader = ({ src, width, quality }) => {\n  if (isCimplifyAsset(src, cdnBase)) {\n    return assetUrl(src, { base: cdnBase, w: width, quality, format: "auto" });\n  }\n  return src;\n};\n\nexport default cimplifyImageLoader;\n```\n\n**Cloudinary URLs from `client.catalogue.getProducts()` flow through untouched.** Cimplify-hosted URLs get the transform query. The result: every `<Image>` works regardless of where its asset lives, and Cimplify-hosted ones get edge-optimized.\n\nTo point the loader at a different CDN (for testing, multi-CDN setups, etc.) set `NEXT_PUBLIC_CIMPLIFY_CDN_URL` in your `.env.local`:\n\n```\nNEXT_PUBLIC_CIMPLIFY_CDN_URL=http://localhost:8787/storage\n```\n\n## `useImage(path, opts?)` \u2014 React\n\nThin hook that returns `{ src, loader }` for `<Image>`:\n\n```tsx\n\nexport function Hero() {\n  const { src, loader } = useImage("hero/main.jpg", { format: "webp", quality: 85 });\n  return <Image src={src} loader={loader} alt="..." width={1200} height={800} />;\n}\n```\n\nIf `images.loaderFile` is already set globally in your `next.config.ts`, you typically don\'t need `useImage` \u2014 just `<Image src={assetUrl("hero/main.jpg")} />` works. `useImage` is useful when you want per-component transform overrides on a project that doesn\'t use a global loader.\n\n### Options\n\n| Field | Notes |\n| --- | --- |\n| `base` | Per-call CDN base override |\n| `w`, `h` | Default transform values; per-image `width` from `<Image>` still wins |\n| `format`, `quality` | Default transform values |\n\n`useImage` is `useMemo`-stable across renders when the path + opts don\'t change.\n\n## Constants\n\n```ts\n\nDEFAULT_CDN_BASE_URL // "https://storefrontassetscdn.cimplify.io"\nCIMPLIFY_CDN_HOSTS   // readonly ["storefrontassetscdn.cimplify.io", "cdn.cimplify.io", "static-tmp.cimplify.io"]\n```\n\n## What\'s not in v1\n\n- **`useUpload` hook** \u2014 runtime customer-facing uploads with progress + cancel. Deferred to v1.1. Customer uploads today go through `client.uploads.upload(file)` (no progress, no cancel \u2014 just `await`).\n- **`SEED_IDS` typed const tree** \u2014 demo-only convenience for referencing seed-image slugs in code. Generate-from-seed-source step deferred to v1.1; today demos use `seedImage(industry, slug)` from the SDK\'s mock module.\n- **Cloudinary / S3 path-transform support** \u2014 the loader passes external hosts through unchanged; Cloudinary\'s `c_fill,w_500/` path transforms aren\'t synthesized.\n- **`assets rm` server-side delete** \u2014 CLI removes manifest entries; the remote blob stays until v1.1\'s media-manager `DELETE` wiring.\n\n## Where it lives in the platform\n\n- Wire format: `POST /v1/businesses/{id}/assets/{init,confirm}` \u2014 see the management API reference\n- Backend service: `crate::uploads::service::UploadService::init_storefront_asset`\n- Served from the Cimplify asset CDN at `storefrontassetscdn.cimplify.io`\n- Storage key: `assets/{business_id}/{folder}/{filename}` \u2014 deterministic, idempotent, agent-predictable\n\n## Related\n\n- [`cimplify assets`](/docs/cli/assets) \u2014 CLI surface for upload/ls/rm\n- [Uploads (customer-runtime)](/docs/sdk/uploads) \u2014 `client.uploads.upload(file)` for private 7-day-presigned uploads\n'
+    "body": 'The asset surface on the SDK is **read-side only**: building URLs for images you\'ve already uploaded via [`cimplify assets upload`](/docs/cli/assets). Customer-runtime uploads still go through `client.uploads.upload(file)`.\n\n## `assetUrl(path, opts?)`\n\nPure URL builder. Prepends the CDN base for relative paths, passes absolute URLs through with the transform query contract appended.\n\n```ts\n\nassetUrl("hero/main.jpg")\n// "https://storefrontassetscdn.cimplify.io/hero/main.jpg"\n\nassetUrl("hero/main.jpg", { w: 1200, format: "webp", quality: 80 })\n// "https://storefrontassetscdn.cimplify.io/hero/main.jpg?w=1200&format=webp&quality=80"\n\nassetUrl("hero/main.jpg", { base: "http://localhost:8787/storage" })\n// "http://localhost:8787/storage/hero/main.jpg"\n\nassetUrl("https://res.cloudinary.com/foo/bar.jpg")\n// "https://res.cloudinary.com/foo/bar.jpg"   (absolute \u2192 passthrough)\n```\n\n### Options\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `base` | `string` | Override the CDN base. Defaults to `DEFAULT_CDN_BASE_URL`. |\n| `w` / `h` | `number` | Width / height in pixels (on-the-fly resizing) |\n| `quality` | `number` | 0\u2013100 |\n| `format` | `"auto" \\| "webp" \\| "avif" \\| "jpeg"` | `"auto"` lets the CDN pick by `Accept` header |\n\nThe transform query is only meaningful when the URL terminates on the Cimplify storefront CDN (which supports on-the-fly resizing). For external hosts, unknown params are typically ignored; the image still loads at its original size.\n\n## `isCimplifyAsset(src, base?)`\n\nDecides whether `src` is hosted on a Cimplify CDN. Used by the storefront\'s `next/image` loader to skip transforms for external URLs.\n\n```ts\n\nisCimplifyAsset("hero/main.jpg")                                      // true (relative \u2192 ours)\nisCimplifyAsset("/img/seed/bakery/x.jpg")                             // true (dev mock passthrough)\nisCimplifyAsset("https://storefrontassetscdn.cimplify.io/x.jpg")     // true\nisCimplifyAsset("https://cdn.cimplify.io/x.jpg")                     // true\nisCimplifyAsset("https://static-tmp.cimplify.io/seed/x.jpg")         // true\nisCimplifyAsset("https://res.cloudinary.com/demo/upload/x.jpg")      // false\nisCimplifyAsset("https://images.unsplash.com/photo-xyz")             // false\n```\n\n## Built-in `next/image` loader\n\nEvery storefront template scaffolded by `cimplify init` ships `lib/cimplify-loader.ts` and points `images.loaderFile` at it. The loader:\n\n```ts\n\nconst cdnBase = process.env.NEXT_PUBLIC_CIMPLIFY_CDN_URL?.trim() || undefined;\n\nconst cimplifyImageLoader: ImageLoader = ({ src, width, quality }) => {\n  if (isCimplifyAsset(src, cdnBase)) {\n    return assetUrl(src, { base: cdnBase, w: width, quality, format: "auto" });\n  }\n  return src;\n};\n\nexport default cimplifyImageLoader;\n```\n\n**Cloudinary URLs from `client.catalogue.getProducts()` flow through untouched.** Cimplify-hosted URLs get the transform query. The result: every `<Image>` works regardless of where its asset lives, and Cimplify-hosted ones get edge-optimized.\n\nTo point the loader at a different CDN (for testing, multi-CDN setups, etc.) set `NEXT_PUBLIC_CIMPLIFY_CDN_URL` in your `.env.local`:\n\n```\nNEXT_PUBLIC_CIMPLIFY_CDN_URL=http://localhost:8787/storage\n```\n\n## `useImage(path, opts?)` (React)\n\nThin hook that returns `{ src, loader }` for `<Image>`:\n\n```tsx\n\nexport function Hero() {\n  const { src, loader } = useImage("hero/main.jpg", { format: "webp", quality: 85 });\n  return <Image src={src} loader={loader} alt="..." width={1200} height={800} />;\n}\n```\n\nIf `images.loaderFile` is already set globally in your `next.config.ts`, you typically don\'t need `useImage`; just `<Image src={assetUrl("hero/main.jpg")} />` works. `useImage` is useful when you want per-component transform overrides on a project that doesn\'t use a global loader.\n\n### Options\n\n| Field | Notes |\n| --- | --- |\n| `base` | Per-call CDN base override |\n| `w`, `h` | Default transform values; per-image `width` from `<Image>` still wins |\n| `format`, `quality` | Default transform values |\n\n`useImage` is `useMemo`-stable across renders when the path + opts don\'t change.\n\n## Constants\n\n```ts\n\nDEFAULT_CDN_BASE_URL // "https://storefrontassetscdn.cimplify.io"\nCIMPLIFY_CDN_HOSTS   // readonly ["storefrontassetscdn.cimplify.io", "cdn.cimplify.io", "static-tmp.cimplify.io"]\n```\n\n## What\'s not in v1\n\n- **`useUpload` hook**: runtime customer-facing uploads with progress + cancel. Deferred to v1.1. Customer uploads today go through `client.uploads.upload(file)` (no progress, no cancel; just `await`).\n- **`SEED_IDS` typed const tree**: demo-only convenience for referencing seed-image slugs in code. Generate-from-seed-source step deferred to v1.1; today demos use `seedImage(industry, slug)` from the SDK\'s mock module.\n- **Cloudinary / S3 path-transform support**: the loader passes external hosts through unchanged; Cloudinary\'s `c_fill,w_500/` path transforms aren\'t synthesized.\n- **`assets rm` server-side delete**: CLI removes manifest entries; the remote blob stays until v1.1\'s media-manager `DELETE` wiring.\n\n## Where it lives in the platform\n\n- Wire format: `POST /v1/businesses/{id}/assets/{init,confirm}`; see the management API reference\n- Backend service: `crate::uploads::service::UploadService::init_storefront_asset`\n- Served from the Cimplify asset CDN at `storefrontassetscdn.cimplify.io`\n- Storage key: `assets/{business_id}/{folder}/{filename}`: deterministic, idempotent, agent-predictable\n\n## Related\n\n- [`cimplify assets`](/docs/cli/assets): CLI surface for upload/ls/rm\n- [Uploads (customer-runtime)](/docs/sdk/uploads): `client.uploads.upload(file)` for private 7-day-presigned uploads\n'
   },
   {
     "name": "exit-codes",
@@ -157,21 +157,21 @@ var TOPICS = [
     "title": "Revalidation",
     "description": "Canonical cimplify:* cache-tag vocabulary + revalidate helpers",
     "source_url": "https://cimplify.dev/docs/sdk/revalidation",
-    "body": "Cimplify storefronts cache catalogue reads with Next 16's ISR (`export const revalidate = N` + `next.tags` via the SDK's `cacheOptions`). When a merchant edits a product, collection, or brand asset, Cimplify invalidates the matching caches for your storefront automatically \u2014 no `/api/revalidate` webhook round-trip required.\n\nThis page is the canonical contract between Cimplify and your storefront. Use the typed helpers \u2014 never hand-write tag strings \u2014 so the scheme stays in one place.\n\n## Why ISR, not Cache Components\n\nCimplify templates use Next 16's [Previous Model](https://nextjs.org/docs/app/guides/caching-without-cache-components): `export const revalidate` at the page level, `cacheOptions: { revalidate, tags }` on SDK reads (forwarded as `fetch().next.{revalidate,tags}`), and `revalidateTag` for invalidation. The `'use cache'` directive (Cache Components) is still experimental and its runtime constraints don't suit hosted storefronts. The Previous Model is stable, fully supported, and what every Cimplify template ships with. Keep `cacheComponents` **off** in `next.config.ts`.\n\n## Tags\n\nAll tags are namespaced under `cimplify:` so they can't collide with consumer tags. Build them via `tags` from `@cimplify/sdk/server`:\n\n```ts\n\nexport const revalidate = 3600;\n\nasync function getProducts() {\n  const r = await getServerClient().catalogue.getProducts(\n    { limit: 24 },\n    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },\n  );\n  return r.ok ? r.value.items : [];\n}\n```\n\n### Catalogue\n\n| Helper | Tag |\n| --- | --- |\n| `tags.products()` | `cimplify:products` |\n| `tags.product(id)` | `cimplify:product:{id}` |\n| `tags.categories()` | `cimplify:categories` |\n| `tags.category(id)` | `cimplify:category:{id}` |\n| `tags.categoryProducts(id)` | `cimplify:category:{id}:products` |\n| `tags.collections()` | `cimplify:collections` |\n| `tags.collection(id)` | `cimplify:collection:{id}` |\n| `tags.collectionProducts(id)` | `cimplify:collection:{id}:products` |\n| `tags.tag(name)` | `cimplify:tag:{name}` (product tag, e.g. \"vegan\") |\n| `tags.addons()` | `cimplify:addons` |\n| `tags.addon(id)` | `cimplify:addon:{id}` |\n| `tags.stock()` | `cimplify:stock` |\n| `tags.stockFor(productId)` | `cimplify:stock:{productId}` |\n\n### Brand / business\n\n| Helper | Tag |\n| --- | --- |\n| `tags.business()` | `cimplify:business` |\n| `tags.brand()` | `cimplify:brand` |\n| `tags.locations()` | `cimplify:locations` |\n| `tags.location(id)` | `cimplify:location:{id}` |\n| `tags.locale()` | `cimplify:locale` |\n\n### Pricing / subscriptions\n\n| Helper | Tag |\n| --- | --- |\n| `tags.pricing()` | `cimplify:pricing` |\n| `tags.subscriptions()` | `cimplify:subscriptions` |\n| `tags.subscription(id)` | `cimplify:subscription:{id}` |\n\n### Customer-scoped (Server Actions only)\n\n| Helper | Tag |\n| --- | --- |\n| `tags.orders(customerId)` | `cimplify:orders:{customerId}` |\n| `tags.order(id)` | `cimplify:order:{id}` |\n\n## Granularity\n\nTag with **both** a broad and a precise tag on every read so either-flavour invalidation works:\n\n```ts\ncacheOptions: { revalidate: 3600, tags: [tags.products(), tags.product(id)] }\n```\n\nThe broad tag (`products`) catches \"I changed something product-related, invalidate everything.\" The precise tag (`product:{id}`) catches \"I changed exactly this one product, invalidate only its entries.\"\n\n## Revalidating from a Server Action\n\n```ts\n\nexport async function saveProduct(id: string, data: ProductInput) {\n  await client.catalogue.updateProduct(id, data);\n  await revalidateProduct(id);\n}\n```\n\nHelpers:\n\n| Helper | Invalidates |\n| --- | --- |\n| `revalidateProducts()` | `products` |\n| `revalidateProduct(id)` | `product:{id}` + `products` |\n| `revalidateCategories()` | `categories` |\n| `revalidateCategory(id)` | `category:{id}` + `category:{id}:products` + `categories` |\n| `revalidateCollections()` | `collections` |\n| `revalidateCollection(id)` | `collection:{id}` + `collection:{id}:products` + `collections` |\n| `revalidateBusiness()` | `business` |\n| `revalidateBrand()` | `brand` |\n| `revalidateLocations()` | `locations` |\n| `revalidateLocation(id)` | `location:{id}` + `locations` |\n| `revalidatePricing()` | `pricing` + `products` |\n| `revalidateAddOns()` | `addons` |\n| `revalidateAddOn(id)` | `addon:{id}` + `addons` |\n| `revalidateSubscriptions()` | `subscriptions` |\n| `revalidateSubscription(id)` | `subscription:{id}` + `subscriptions` |\n| `revalidateStock(productId?)` | `stock:{productId}` + `stock` (or just `stock` if no id) |\n| `revalidateByTag(tag)` | escape hatch for a raw tag |\n\n## The Cimplify \u2192 storefront eviction contract\n\nWhen a merchant edits something in the dashboard, Cimplify automatically invalidates the matching caches for every storefront serving that business \u2014 **globally, in ~1\u20133 seconds**, with no webhook round-trip into your storefront. You don't wire anything up; tagging your reads correctly is the whole contract.\n\nThe tags Cimplify dispatches use the **exact strings** from the tables above, keyed by database ID. If you've tagged your `cacheOptions.tags` with the helpers above, your storefront stays in sync automatically.\n\n## Dynamic routes \u2014 tag by **ID**, never by slug\n\nCimplify dispatches revalidation tags **keyed by database ID**, not by URL slug. A `/products/[slug]` page that caches itself under `tags.product(slug)` will never be invalidated by an edit \u2014 the tag the storefront wrote doesn't match the tag Cimplify fires.\n\nResolve the slug to a record first, then tag with `record.id`:\n\n```ts title=\"app/products/[slug]/page.tsx \u2014 correct\"\n\nexport const revalidate = 3600;\n\nexport async function generateStaticParams() {\n  const r = await getServerClient().catalogue.getProducts({ limit: 10_000 });\n  if (!r.ok || r.value.items.length === 0) return [{ slug: \"__placeholder__\" }];\n  return r.value.items.map((p) => ({ slug: p.slug ?? p.id }));\n}\n\nexport default async function Page({ params }: { params: Promise<{ slug: string }> }) {\n  const { slug } = await params;\n\n  // First resolve slug \u2192 product. Tag the resolution read with the\n  // collection-level tag so adds/removes invalidate it. This call hits the\n  // SDK with a fallback-broad tag.\n  const r = await getServerClient().catalogue.getProductBySlug(\n    slug,\n    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },\n  );\n  if (!r.ok) notFound();\n\n  // Now re-fetch with the resolved ID so the per-product tag is keyed on the\n  // stable identifier \u2014 revalidateProduct(id) from Cimplify will hit this\n  // entry on the next mutation.\n  const detailed = await getServerClient().catalogue.getProduct(\n    r.value.id,\n    { cacheOptions: { revalidate: 3600, tags: [tags.product(r.value.id), tags.products()] } },\n  );\n\n  if (!detailed.ok) notFound();\n  return <ProductDetail product={detailed.value} />;\n}\n```\n\nThe same pattern applies to `[slug]` routes for categories, collections, addons, locations, and so on \u2014 always tag with the resolved `record.id`, never with the URL slug.\n\n### Why this matters\n\n- **Renames don't orphan.** The cache key includes the slug (path-based), so a renamed product gets a fresh cache entry under the new slug. The old slug-keyed entry is invalidated via the `tags.products()` collection tag and will 404 naturally.\n- **IDs are stable.** Cimplify's bus emits `ProductUpdated { id }` events; the slug isn't on the event payload, and adding it would create races with concurrent rename. Keeping the tag scheme ID-only keeps the contract simple.\n- **You get instant freshness.** With Cimplify's automatic eviction, a 1-hour `revalidate` entry can sit cached and still flip fresh within ~3s of an edit \u2014 but only if the tag actually matches.\n\n## SDK timeout\n\nThe SDK's default per-call timeout is **5 seconds**. Picked so a single slow upstream call can't exhaust the page render budget \u2014 a hung `getCollections()` would otherwise take the entire page render with it. With the 5s default, a slow call fails fast, `Result.ok` becomes `false`, the page renders with empty data, and the result is cached so subsequent hits are instant.\n\nOverride only for genuinely-large bulk reads (admin tooling, batch jobs):\n\n```ts\n\nconst adminClient = createCimplifyClient({\n  secretKey: process.env.CIMPLIFY_SECRET_KEY,\n  timeout: 30_000, // 30s for a 10k-row export\n});\n```\n\n## Don't cache empty responses as if they were real\n\nIf a render produces empty results because of a transient backend hiccup, that empty render gets cached for the full `revalidate` window \u2014 and every visitor sees an empty storefront until someone manually invalidates.\n\nTwo defences:\n\n**1.** The SDK's 5s timeout above stops a slow call from hanging the whole render, but the result is still `Result.ok = false`. Branch on that and short-circuit to a not-found / soft state rather than committing the empty render to cache:\n\n```ts title=\"app/categories/[slug]/page.tsx\"\nasync function getCategory(slug: string) {\n  const r = await getServerClient().catalogue.getCategoryBySlug(\n    slug,\n    { cacheOptions: { revalidate: 3600, tags: [tags.categories()] } },\n  );\n  // Distinguish a real 404 from a transient SDK error. Only `notFound()` on\n  // the real 404; for transient errors, render a soft loading state so the\n  // cache doesn't lock in an incorrect \"page couldn't load\" for an hour.\n  if (!r.ok) {\n    if (r.error.code === \"NOT_FOUND\") notFound();\n    return { soft: true as const };\n  }\n  return { soft: false as const, category: r.value };\n}\n```\n\n**2.** Use the eviction-pipeline path for catalogue invalidation rather than relying on `revalidate` window expiry. A real edit in the dashboard purges the cache within seconds; the `revalidate` value is a backstop, not the primary refresh mechanism.\n\n## Tag taxonomy is locked\n\nThe vocabulary above is the v1 contract. Adding new tag helpers is non-breaking; removing or renaming any of them bumps the SDK major version. Agents that bake these strings into prompts can pin to v0.x of `@cimplify/sdk`.\n"
+    "body": "Cimplify storefronts cache catalogue reads with Next 16's ISR (`export const revalidate = N` + `next.tags` via the SDK's `cacheOptions`). When a merchant edits a product, collection, or brand asset, Cimplify invalidates the matching caches for your storefront automatically, with no `/api/revalidate` webhook round-trip required.\n\nThis page is the canonical contract between Cimplify and your storefront. Use the typed helpers (never hand-write tag strings) so the scheme stays in one place.\n\n## Why ISR, not Cache Components\n\nCimplify templates use Next 16's [Previous Model](https://nextjs.org/docs/app/guides/caching-without-cache-components): `export const revalidate` at the page level, `cacheOptions: { revalidate, tags }` on SDK reads (forwarded as `fetch().next.{revalidate,tags}`), and `revalidateTag` for invalidation. The `'use cache'` directive (Cache Components) is still experimental and its runtime constraints don't suit hosted storefronts. The Previous Model is stable, fully supported, and what every Cimplify template ships with. Keep `cacheComponents` **off** in `next.config.ts`.\n\n## Tags\n\nAll tags are namespaced under `cimplify:` so they can't collide with consumer tags. Build them via `tags` from `@cimplify/sdk/server`:\n\n```ts\n\nexport const revalidate = 3600;\n\nasync function getProducts() {\n  const r = await getServerClient().catalogue.getProducts(\n    { limit: 24 },\n    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },\n  );\n  return r.ok ? r.value.items : [];\n}\n```\n\n### Catalogue\n\n| Helper | Tag |\n| --- | --- |\n| `tags.products()` | `cimplify:products` |\n| `tags.product(id)` | `cimplify:product:{id}` |\n| `tags.categories()` | `cimplify:categories` |\n| `tags.category(id)` | `cimplify:category:{id}` |\n| `tags.categoryProducts(id)` | `cimplify:category:{id}:products` |\n| `tags.collections()` | `cimplify:collections` |\n| `tags.collection(id)` | `cimplify:collection:{id}` |\n| `tags.collectionProducts(id)` | `cimplify:collection:{id}:products` |\n| `tags.tag(name)` | `cimplify:tag:{name}` (product tag, e.g. \"vegan\") |\n| `tags.addons()` | `cimplify:addons` |\n| `tags.addon(id)` | `cimplify:addon:{id}` |\n| `tags.stock()` | `cimplify:stock` |\n| `tags.stockFor(productId)` | `cimplify:stock:{productId}` |\n\n### Brand / business\n\n| Helper | Tag |\n| --- | --- |\n| `tags.business()` | `cimplify:business` |\n| `tags.brand()` | `cimplify:brand` |\n| `tags.locations()` | `cimplify:locations` |\n| `tags.location(id)` | `cimplify:location:{id}` |\n| `tags.locale()` | `cimplify:locale` |\n\n### Pricing / subscriptions\n\n| Helper | Tag |\n| --- | --- |\n| `tags.pricing()` | `cimplify:pricing` |\n| `tags.subscriptions()` | `cimplify:subscriptions` |\n| `tags.subscription(id)` | `cimplify:subscription:{id}` |\n\n### Customer-scoped (Server Actions only)\n\n| Helper | Tag |\n| --- | --- |\n| `tags.orders(customerId)` | `cimplify:orders:{customerId}` |\n| `tags.order(id)` | `cimplify:order:{id}` |\n\n## Granularity\n\nTag with **both** a broad and a precise tag on every read so either-flavour invalidation works:\n\n```ts\ncacheOptions: { revalidate: 3600, tags: [tags.products(), tags.product(id)] }\n```\n\nThe broad tag (`products`) catches \"I changed something product-related, invalidate everything.\" The precise tag (`product:{id}`) catches \"I changed exactly this one product, invalidate only its entries.\"\n\n## Revalidating from a Server Action\n\n```ts\n\nexport async function saveProduct(id: string, data: ProductInput) {\n  await client.catalogue.updateProduct(id, data);\n  await revalidateProduct(id);\n}\n```\n\nHelpers:\n\n| Helper | Invalidates |\n| --- | --- |\n| `revalidateProducts()` | `products` |\n| `revalidateProduct(id)` | `product:{id}` + `products` |\n| `revalidateCategories()` | `categories` |\n| `revalidateCategory(id)` | `category:{id}` + `category:{id}:products` + `categories` |\n| `revalidateCollections()` | `collections` |\n| `revalidateCollection(id)` | `collection:{id}` + `collection:{id}:products` + `collections` |\n| `revalidateBusiness()` | `business` |\n| `revalidateBrand()` | `brand` |\n| `revalidateLocations()` | `locations` |\n| `revalidateLocation(id)` | `location:{id}` + `locations` |\n| `revalidatePricing()` | `pricing` + `products` |\n| `revalidateAddOns()` | `addons` |\n| `revalidateAddOn(id)` | `addon:{id}` + `addons` |\n| `revalidateSubscriptions()` | `subscriptions` |\n| `revalidateSubscription(id)` | `subscription:{id}` + `subscriptions` |\n| `revalidateStock(productId?)` | `stock:{productId}` + `stock` (or just `stock` if no id) |\n| `revalidateByTag(tag)` | escape hatch for a raw tag |\n\n## The Cimplify \u2192 storefront eviction contract\n\nWhen a merchant edits something in the dashboard, Cimplify automatically invalidates the matching caches for every storefront serving that business, **globally, in ~1\u20133 seconds**, with no webhook round-trip into your storefront. You don't wire anything up; tagging your reads correctly is the whole contract.\n\nThe tags Cimplify dispatches use the **exact strings** from the tables above, keyed by database ID. If you've tagged your `cacheOptions.tags` with the helpers above, your storefront stays in sync automatically.\n\n## Dynamic routes: tag by **ID**, never by slug\n\nCimplify dispatches revalidation tags **keyed by database ID**, not by URL slug. A `/products/[slug]` page that caches itself under `tags.product(slug)` will never be invalidated by an edit; the tag the storefront wrote doesn't match the tag Cimplify fires.\n\nResolve the slug to a record first, then tag with `record.id`:\n\n```ts title=\"app/products/[slug]/page.tsx (correct)\"\n\nexport const revalidate = 3600;\n\nexport async function generateStaticParams() {\n  const r = await getServerClient().catalogue.getProducts({ limit: 10_000 });\n  if (!r.ok || r.value.items.length === 0) return [{ slug: \"__placeholder__\" }];\n  return r.value.items.map((p) => ({ slug: p.slug ?? p.id }));\n}\n\nexport default async function Page({ params }: { params: Promise<{ slug: string }> }) {\n  const { slug } = await params;\n\n  // First resolve slug \u2192 product. Tag the resolution read with the\n  // collection-level tag so adds/removes invalidate it. This call hits the\n  // SDK with a fallback-broad tag.\n  const r = await getServerClient().catalogue.getProductBySlug(\n    slug,\n    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },\n  );\n  if (!r.ok) notFound();\n\n  // Now re-fetch with the resolved ID so the per-product tag is keyed on the\n  // stable identifier; revalidateProduct(id) from Cimplify will hit this\n  // entry on the next mutation.\n  const detailed = await getServerClient().catalogue.getProduct(\n    r.value.id,\n    { cacheOptions: { revalidate: 3600, tags: [tags.product(r.value.id), tags.products()] } },\n  );\n\n  if (!detailed.ok) notFound();\n  return <ProductDetail product={detailed.value} />;\n}\n```\n\nThe same pattern applies to `[slug]` routes for categories, collections, addons, locations, and so on: always tag with the resolved `record.id`, never with the URL slug.\n\n### Why this matters\n\n- **Renames don't orphan.** The cache key includes the slug (path-based), so a renamed product gets a fresh cache entry under the new slug. The old slug-keyed entry is invalidated via the `tags.products()` collection tag and will 404 naturally.\n- **IDs are stable.** Cimplify's bus emits `ProductUpdated { id }` events; the slug isn't on the event payload, and adding it would create races with concurrent rename. Keeping the tag scheme ID-only keeps the contract simple.\n- **You get instant freshness.** With Cimplify's automatic eviction, a 1-hour `revalidate` entry can sit cached and still flip fresh within ~3s of an edit, but only if the tag actually matches.\n\n## SDK timeout\n\nThe SDK's default per-call timeout is **5 seconds**. Picked so a single slow upstream call can't exhaust the page render budget; a hung `getCollections()` would otherwise take the entire page render with it. With the 5s default, a slow call fails fast, `Result.ok` becomes `false`, the page renders with empty data, and the result is cached so subsequent hits are instant.\n\nOverride only for genuinely-large bulk reads (admin tooling, batch jobs):\n\n```ts\n\nconst adminClient = createCimplifyClient({\n  secretKey: process.env.CIMPLIFY_SECRET_KEY,\n  timeout: 30_000, // 30s for a 10k-row export\n});\n```\n\n## Don't cache empty responses as if they were real\n\nIf a render produces empty results because of a transient backend hiccup, that empty render gets cached for the full `revalidate` window, and every visitor sees an empty storefront until someone manually invalidates.\n\nTwo defences:\n\n**1.** The SDK's 5s timeout above stops a slow call from hanging the whole render, but the result is still `Result.ok = false`. Branch on that and short-circuit to a not-found / soft state rather than committing the empty render to cache:\n\n```ts title=\"app/categories/[slug]/page.tsx\"\nasync function getCategory(slug: string) {\n  const r = await getServerClient().catalogue.getCategoryBySlug(\n    slug,\n    { cacheOptions: { revalidate: 3600, tags: [tags.categories()] } },\n  );\n  // Distinguish a real 404 from a transient SDK error. Only `notFound()` on\n  // the real 404; for transient errors, render a soft loading state so the\n  // cache doesn't lock in an incorrect \"page couldn't load\" for an hour.\n  if (!r.ok) {\n    if (r.error.code === \"NOT_FOUND\") notFound();\n    return { soft: true as const };\n  }\n  return { soft: false as const, category: r.value };\n}\n```\n\n**2.** Use the eviction-pipeline path for catalogue invalidation rather than relying on `revalidate` window expiry. A real edit in the dashboard purges the cache within seconds; the `revalidate` value is a backstop, not the primary refresh mechanism.\n\n## Tag taxonomy is locked\n\nThe vocabulary above is the v1 contract. Adding new tag helpers is non-breaking; removing or renaming any of them bumps the SDK major version. Agents that bake these strings into prompts can pin to v0.x of `@cimplify/sdk`.\n"
   },
   {
     "name": "inspect-suggestions",
     "title": "Inspect \u2014 `suggestions[].kind` vocabulary",
     "description": "The canonical suggestions[].kind vocabulary for cimplify inspect",
     "source_url": "https://cimplify.dev/docs/cli/inspect#suggestionskind-vocabulary",
-    "body": '## `suggestions[].kind` vocabulary\nEach entry is a stable `kind` + typed payload. Copy lives here (and in `cimplify explain inspect-suggestions`) so agents don\'t invent phrasing.\n\n| Kind | Payload | Implied prompt |\n| --- | --- | --- |\n| `add_first_product` | `{}` | Catalogue is empty \u2014 seed or add a product. |\n| `add_first_collection` | `{}` | Products exist but no collections \u2014 group some. |\n| `fix_no_image` | `{ count }` | N products without images \u2014 add placeholders. |\n| `fix_no_description` | `{ count }` | N products lack descriptions \u2014 generate copy. |\n| `fix_no_price` | `{ count }` | N products have no price \u2014 open the editor. |\n| `fix_no_collection` | `{ count }` | N products not in any collection \u2014 suggest "Featured". |\n| `fix_no_tags` | `{ count }` | N untagged products \u2014 suggest tags from name/category. |\n| `merchandise_empty_collection` | `{ collection_id, name }` | Collection "X" is empty \u2014 pick products to feature. |\n| `merchandise_empty_category` | `{ category_id, name }` | Category "X" has no products \u2014 fill or remove. |\n| `tag_uncategorized_products` | `{ count }` | Majority untagged \u2014 bulk-tag from category. |\n| `enable_search_ui` | `{ product_count }` | Large catalogue \u2014 add search + filters. |\n'
+    "body": '## `suggestions[].kind` vocabulary\nEach entry is a stable `kind` + typed payload. Copy lives here (and in `cimplify explain inspect-suggestions`) so agents don\'t invent phrasing.\n\n| Kind | Payload | Implied prompt |\n| --- | --- | --- |\n| `add_first_product` | `{}` | Catalogue is empty; seed or add a product. |\n| `add_first_collection` | `{}` | Products exist but no collections; group some. |\n| `fix_no_image` | `{ count }` | N products without images; add placeholders. |\n| `fix_no_description` | `{ count }` | N products lack descriptions; generate copy. |\n| `fix_no_price` | `{ count }` | N products have no price; open the editor. |\n| `fix_no_collection` | `{ count }` | N products not in any collection; suggest "Featured". |\n| `fix_no_tags` | `{ count }` | N untagged products; suggest tags from name/category. |\n| `merchandise_empty_collection` | `{ collection_id, name }` | Collection "X" is empty; pick products to feature. |\n| `merchandise_empty_category` | `{ category_id, name }` | Category "X" has no products; fill or remove. |\n| `tag_uncategorized_products` | `{ count }` | Majority untagged; bulk-tag from category. |\n| `enable_search_ui` | `{ product_count }` | Large catalogue; add search + filters. |\n'
   },
   {
     "name": "agent-prompts",
     "title": "Agent prompts",
     "description": "Copy-paste prompts for common Cimplify workflows",
     "source_url": "https://cimplify.dev/docs/agent-prompts",
-    "body": 'These prompts are deliberately terse. Each one names the canonical doc the agent should read first, the exact commands or [MCP tools](/docs/mcp) to call, and the exit condition. Replace `<angle-bracket>` placeholders before running.\n\nEvery prompt assumes the agent has either:\n\n- the [Cimplify CLI](/docs/cli) installed and `cimplify login` complete, **or**\n- an MCP connection to `https://api.cimplify.io/mcp` ([setup](/docs/mcp#connect))\n\n## Ship a new storefront end-to-end\n\n```text title="Scaffold \u2192 deploy \u2192 custom domain"\nSet up a Cimplify <retail> storefront called <my-store> and deploy it to <shop.example.com>.\n\nSource of truth: https://cimplify.dev/docs/tldr\n- Use the MCP tools at api.cimplify.io/mcp when available; otherwise shell `cimplify <cmd> --json`.\n- After every command, echo the JSON envelope.\n- Stop on the first non-zero exit code and name it from https://cimplify.dev/docs/cli#exit-codes.\n- Poll deployment status with cimplify_get_deployment_status (or `cimplify status --json`); never `sleep`.\n- Idempotent \u2014 re-running any step is safe.\n```\n\n## Rebrand an existing storefront\n\n```text title="Apply a new brand to a scaffolded template"\nRebrand the storefront in <./my-store> to match these tokens:\n  name: <Acme Coffee>\n  primary: <#0F172A>\n  accent: <#F59E0B>\n  fontDisplay: <"Playfair Display">\n  fontBody: <"Inter">\n\nRules (https://cimplify.dev/docs/templates/brand):\n- Single source of truth is `lib/brand.ts`. Update it first.\n- Mirror color tokens into `app/globals.css` `@theme` block. Do not hard-code colors elsewhere.\n- Do not edit ejected SDK components; they pick up tokens automatically.\n- Run `bun run check:brand` after edits; fix any schema errors it reports.\n- Verify by opening `http://localhost:3000` (start `bun dev` if not running).\n- Commit with message `brand: <name>`. Do not deploy.\n```\n\n## Add a homepage section\n\n```text title="New Server Component section, cache-tagged"\nAdd a `<Stories>` section to the homepage of the storefront in <./my-store>.\n\nPattern (mirrors the Server Component sections under `app/_sections/` in the scaffolded template):\n- Create `app/_sections/stories.tsx` as an async Server Component. Pass `cacheOptions: { revalidate: 3600, tags: [tags.collections()] }` to the SDK read (from `@cimplify/sdk/server`). Do NOT use `\'use cache\'` / `cacheTag` / `cacheLife` \u2014 Cimplify storefronts run on CF Workers where Cache Components is broken; use the ISR Previous Model.\n- Source data from `client.catalogue.getCollection({ slug: "stories" })`.\n- Render with the existing `<SectionHeader>` and `<ProductCard>` SDK components (do not eject).\n- Insert into `app/page.tsx` between the hero and the featured collection.\n- Run `bun run check` \u2014 must pass typecheck, lint, brand, cart-flow, contract.\n- Do not modify `lib/brand.ts` or any file under `components/ui/`.\n```\n\n## Migrate to a new SDK version\n\n```text title="SDK upgrade with breaking-change scan"\nUpgrade the storefront in <./my-store> from `@cimplify/sdk@<0.44.x>` to `@cimplify/sdk@<latest>`.\n\nProcess:\n- Read the release notes for the target range (`npm view @cimplify/sdk versions --json` to list, then `npm view @cimplify/sdk@<version>` per release).\n- Bump the pin in `package.json`, run `bun install`.\n- For each breaking change called out in the changelog, grep the project for the old symbol and apply the documented replacement.\n- Run `bun run check`. If `check:contract` fails, the SDK \u2194 mock contract drifted \u2014 stop and report.\n- Do not run `cimplify deploy`. End by printing a summary of every file you changed and every breaking change you applied.\n```\n\n## Add a custom checkout payment method\n\n```text title="Wire an additional payment option"\nAdd <mobile_money> as a checkout payment option in the storefront at <./my-store>.\n\nReference: https://cimplify.dev/docs/api-reference/checkout (flat ProcessArgs body \u2014 top-level fields, not nested).\n- The body shape is the contract \u2014 never wrap fields.\n- Eject the existing `<PaymentMethodPicker>` component with `cimplify add payment-method-picker`.\n- Add the option in the ejected picker, wiring the provider-specific body (e.g. `mobile_money_details: { phone_number, provider }`).\n- Validate the body against the typed `ProcessArgs` from `@cimplify/sdk`.\n- Run `bun run check:cart` \u2014 the add\u2192checkout flow must still pass.\n```\n\n## Provision a CI deploy key\n\n```text title="One-time setup for headless deploys"\nCreate a CI-scoped API key for the Cimplify project linked at <./my-store>, and write the GitHub Actions snippet that uses it.\n\nSteps:\n- Confirm `.cimplify/project.json` exists; if not, fail with NOT_LINKED (exit 4).\n- Print the dashboard URL the human needs to visit to create the key (https://app.cimplify.io/settings/developer).\n- Once the user provides `dk_live_\u2026`, store it as a repo secret named `CIMPLIFY_API_KEY` (instruct, do not perform).\n- Write `.github/workflows/deploy.yml` that runs on push to main: install CLI via the curl one-liner, `cimplify deploy --prod --api-key "$CIMPLIFY_API_KEY" --yes --json`.\n- Print the exit-code legend from https://cimplify.dev/docs/cli#exit-codes so the workflow can map failures.\n```\n\n## Diagnose a deploy that didn\'t go live\n\n```text title="Triage a failed or stuck deployment"\nThe latest deploy of the project at <./my-store> isn\'t live. Find out why.\n\nTriage path:\n- `cimplify status --json` \u2014 what\'s the latest deployment_id and status?\n- If status is `failed`, `cimplify logs --deployment <id> --json | tail -200`. Quote the first error line you see.\n- If status is `queued` or `building` for >5 minutes, the build is stuck \u2014 try `cimplify rollback <previous-deploy-id>`.\n- If status is `superseded` (exit 2), a newer push raced it; usually fine \u2014 confirm with `cimplify status` again.\n- If domains misroute, `cimplify domains ls --json` \u2014 confirm the verified+attached domain.\n- Report: deployment_id, status, the failing log line (if any), and the recommended next action. Do not auto-rollback without confirming.\n```\n\n## Add a hero image and reference it in the homepage\n\n```text title="Upload brand assets \u2192 use them in source"\nAdd the image at <./Downloads/hero.jpg> as the homepage hero for the storefront in <./my-store>.\n\nReference: https://cimplify.dev/docs/cli/assets\n- `cp <./Downloads/hero.jpg> public/hero/main.jpg`\n- `cimplify assets upload public/hero/ --folder hero --json` \u2014 captures the manifest entry for `hero/main.jpg`.\n- Edit `app/page.tsx`: replace the hero `<Image>` `src` with `assetUrl("hero/main.jpg")` from `@cimplify/sdk`.\n- Do NOT touch existing `<Image>` calls that point at Cloudinary or other external hosts \u2014 the loader passes them through unchanged.\n- Run `bun run check`. Open `http://localhost:3000`; verify the hero image renders.\n- Commit `cimplify-assets.json` along with the source change so the manifest is reviewable.\n```\n\n## Audit caching and asset delivery\n\n```text title="Find caching and asset regressions on a live storefront"\nAudit the live storefront at <https://my-store.mycimplify.com> for caching and asset-delivery regressions.\n\nSources of truth:\n- https://cimplify.dev/docs/sdk/optimization (page + asset caching)\n- https://cimplify.dev/docs/templates/seo-and-resource-hints (responsive images)\n\n- Page cache: curl /, /shop, and a PDP 2\u20133\xD7 each; `X-Cimplify-Edge-Cache` must warm to HIT and `Cache-Control` must carry `s-maxage`. A BYPASS or missing `s-maxage` means the page lost its `revalidate` or carries a Cookie.\n- Asset cache: pull a `/_next/static/*` chunk \u2014 it must be `public, max-age=31536000, immutable`.\n- Images: flag raw `<img>` from a third-party CDN, and Cloudinary URLs with no `/upload/<transform>/` segment (full-resolution originals).\n- Report a table (route/asset, observed header, expected, severity). Do not change source unless asked.\n```\n\n## Reset a sandbox storefront to a clean state\n\n```text title="Wipe and re-seed for repeatable demos"\nReset the local mock state for the storefront in <./my-store>.\n\n- Stop any running `bun dev` process.\n- `cimplify mock reset` (clears the in-process mock backing store).\n- `cimplify mock seed <retail>` (re-seeds with the chosen industry fixture).\n- `bun dev` to restart both servers.\n- Verify: `curl localhost:8787/v1/catalogue/products | jq \'.data | length\'` returns the expected seed count (~24 for retail).\n- Do not touch the linked cloud project; this is local-only.\n```\n\n## How these are built\n\nEvery prompt above is structured the same way so you can adapt them:\n\n1. **Goal** \u2014 one sentence, with `<angle-bracket>` placeholders for the moving parts.\n2. **Source of truth** \u2014 the canonical doc URL the agent reads first.\n3. **Rules** \u2014 operational guardrails: which tools to call, what to echo, when to stop.\n4. **Exit condition** \u2014 what counts as success, what counts as a halt.\n\nIf you build a prompt that should live here, open a PR against `content/docs/agent-prompts.mdx`. Keep them under ~12 lines; if a workflow needs more, it belongs in a dedicated doc page and the prompt should link to it.\n'
+    "body": 'These prompts are deliberately terse. Each one names the canonical doc the agent should read first, the exact commands or [MCP tools](/docs/mcp) to call, and the exit condition. Replace `<angle-bracket>` placeholders before running.\n\nEvery prompt assumes the agent has either:\n\n- the [Cimplify CLI](/docs/cli) installed and `cimplify login` complete, **or**\n- an MCP connection to `https://api.cimplify.io/mcp` ([setup](/docs/mcp#connect))\n\n## Ship a new storefront end-to-end\n\n```text title="Scaffold \u2192 deploy \u2192 custom domain"\nSet up a Cimplify <retail> storefront called <my-store> and deploy it to <shop.example.com>.\n\nSource of truth: https://cimplify.dev/docs/tldr\n- Use the MCP tools at api.cimplify.io/mcp when available; otherwise shell `cimplify <cmd> --json`.\n- After every command, echo the JSON envelope.\n- Stop on the first non-zero exit code and name it from https://cimplify.dev/docs/cli#exit-codes.\n- Poll deployment status with cimplify_get_deployment_status (or `cimplify status --json`); never `sleep`.\n- Idempotent: re-running any step is safe.\n```\n\n## Rebrand an existing storefront\n\n```text title="Apply a new brand to a scaffolded template"\nRebrand the storefront in <./my-store> to match these tokens:\n  name: <Acme Coffee>\n  primary: <#0F172A>\n  accent: <#F59E0B>\n  fontDisplay: <"Playfair Display">\n  fontBody: <"Inter">\n\nRules (https://cimplify.dev/docs/templates/brand):\n- Single source of truth is `lib/brand.ts`. Update it first.\n- Mirror color tokens into `app/globals.css` `@theme` block. Do not hard-code colors elsewhere.\n- Do not edit ejected SDK components; they pick up tokens automatically.\n- Run `bun run check:brand` after edits; fix any schema errors it reports.\n- Verify by opening `http://localhost:3000` (start `bun dev` if not running).\n- Commit with message `brand: <name>`. Do not deploy.\n```\n\n## Add a homepage section\n\n```text title="New Server Component section, cache-tagged"\nAdd a `<Stories>` section to the homepage of the storefront in <./my-store>.\n\nPattern (mirrors the Server Component sections under `app/_sections/` in the scaffolded template):\n- Create `app/_sections/stories.tsx` as an async Server Component. Pass `cacheOptions: { revalidate: 3600, tags: [tags.collections()] }` to the SDK read (from `@cimplify/sdk/server`). Do NOT use `\'use cache\'` / `cacheTag` / `cacheLife`. Cimplify storefronts run on CF Workers where Cache Components is broken; use the ISR Previous Model.\n- Source data from `client.catalogue.getCollection({ slug: "stories" })`.\n- Render with the existing `<SectionHeader>` and `<ProductCard>` SDK components (do not eject).\n- Insert into `app/page.tsx` between the hero and the featured collection.\n- Run `bun run check`. It must pass typecheck, lint, brand, cart-flow, contract.\n- Do not modify `lib/brand.ts` or any file under `components/ui/`.\n```\n\n## Migrate to a new SDK version\n\n```text title="SDK upgrade with breaking-change scan"\nUpgrade the storefront in <./my-store> from `@cimplify/sdk@<0.44.x>` to `@cimplify/sdk@<latest>`.\n\nProcess:\n- Read the release notes for the target range (`npm view @cimplify/sdk versions --json` to list, then `npm view @cimplify/sdk@<version>` per release).\n- Bump the pin in `package.json`, run `bun install`.\n- For each breaking change called out in the changelog, grep the project for the old symbol and apply the documented replacement.\n- Run `bun run check`. If `check:contract` fails, the SDK \u2194 mock contract drifted; stop and report.\n- Do not run `cimplify deploy`. End by printing a summary of every file you changed and every breaking change you applied.\n```\n\n## Add a custom checkout payment method\n\n```text title="Wire an additional payment option"\nAdd <mobile_money> as a checkout payment option in the storefront at <./my-store>.\n\nReference: https://cimplify.dev/docs/api-reference/checkout (flat ProcessArgs body: top-level fields, not nested).\n- The body shape is the contract; never wrap fields.\n- Eject the existing `<PaymentMethodPicker>` component with `cimplify add payment-method-picker`.\n- Add the option in the ejected picker, wiring the provider-specific body (e.g. `mobile_money_details: { phone_number, provider }`).\n- Validate the body against the typed `ProcessArgs` from `@cimplify/sdk`.\n- Run `bun run check:cart`; the add\u2192checkout flow must still pass.\n```\n\n## Provision a CI deploy key\n\n```text title="One-time setup for headless deploys"\nCreate a CI-scoped API key for the Cimplify project linked at <./my-store>, and write the GitHub Actions snippet that uses it.\n\nSteps:\n- Confirm `.cimplify/project.json` exists; if not, fail with NOT_LINKED (exit 4).\n- Print the dashboard URL the human needs to visit to create the key (https://app.cimplify.io/settings/developer).\n- Once the user provides `dk_live_\u2026`, store it as a repo secret named `CIMPLIFY_API_KEY` (instruct, do not perform).\n- Write `.github/workflows/deploy.yml` that runs on push to main: install CLI via the curl one-liner, `cimplify deploy --prod --api-key "$CIMPLIFY_API_KEY" --yes --json`.\n- Print the exit-code legend from https://cimplify.dev/docs/cli#exit-codes so the workflow can map failures.\n```\n\n## Diagnose a deploy that didn\'t go live\n\n```text title="Triage a failed or stuck deployment"\nThe latest deploy of the project at <./my-store> isn\'t live. Find out why.\n\nTriage path:\n- `cimplify status --json`: what\'s the latest deployment_id and status?\n- If status is `failed`, `cimplify logs --deployment <id> --json | tail -200`. Quote the first error line you see.\n- If status is `queued` or `building` for >5 minutes, the build is stuck; try `cimplify rollback <previous-deploy-id>`.\n- If status is `superseded` (exit 2), a newer push raced it; usually fine, so confirm with `cimplify status` again.\n- If domains misroute, `cimplify domains ls --json`: confirm the verified+attached domain.\n- Report: deployment_id, status, the failing log line (if any), and the recommended next action. Do not auto-rollback without confirming.\n```\n\n## Add a hero image and reference it in the homepage\n\n```text title="Upload brand assets \u2192 use them in source"\nAdd the image at <./Downloads/hero.jpg> as the homepage hero for the storefront in <./my-store>.\n\nReference: https://cimplify.dev/docs/cli/assets\n- `cp <./Downloads/hero.jpg> public/hero/main.jpg`\n- `cimplify assets upload public/hero/ --folder hero --json`: captures the manifest entry for `hero/main.jpg`.\n- Edit `app/page.tsx`: replace the hero `<Image>` `src` with `assetUrl("hero/main.jpg")` from `@cimplify/sdk`.\n- Do NOT touch existing `<Image>` calls that point at Cloudinary or other external hosts; the loader passes them through unchanged.\n- Run `bun run check`. Open `http://localhost:3000`; verify the hero image renders.\n- Commit `cimplify-assets.json` along with the source change so the manifest is reviewable.\n```\n\n## Audit caching and asset delivery\n\n```text title="Find caching and asset regressions on a live storefront"\nAudit the live storefront at <https://my-store.mycimplify.com> for caching and asset-delivery regressions.\n\nSources of truth:\n- https://cimplify.dev/docs/sdk/optimization (page + asset caching)\n- https://cimplify.dev/docs/templates/seo-and-resource-hints (responsive images)\n\n- Page cache: curl /, /shop, and a PDP 2\u20133\xD7 each; `X-Cimplify-Edge-Cache` must warm to HIT and `Cache-Control` must carry `s-maxage`. A BYPASS or missing `s-maxage` means the page lost its `revalidate` or carries a Cookie.\n- Asset cache: pull a `/_next/static/*` chunk; it must be `public, max-age=31536000, immutable`.\n- Images: flag raw `<img>` from a third-party CDN, and Cloudinary URLs with no `/upload/<transform>/` segment (full-resolution originals).\n- Report a table (route/asset, observed header, expected, severity). Do not change source unless asked.\n```\n\n## Reset a sandbox storefront to a clean state\n\n```text title="Wipe and re-seed for repeatable demos"\nReset the local mock state for the storefront in <./my-store>.\n\n- Stop any running `bun dev` process.\n- `cimplify mock reset` (clears the in-process mock backing store).\n- `cimplify mock seed <retail>` (re-seeds with the chosen industry fixture).\n- `bun dev` to restart both servers.\n- Verify: `curl localhost:8787/v1/catalogue/products | jq \'.data | length\'` returns the expected seed count (~24 for retail).\n- Do not touch the linked cloud project; this is local-only.\n```\n\n## How these are built\n\nEvery prompt above is structured the same way so you can adapt them:\n\n1. **Goal**: one sentence, with `<angle-bracket>` placeholders for the moving parts.\n2. **Source of truth**: the canonical doc URL the agent reads first.\n3. **Rules**: operational guardrails for which tools to call, what to echo, and when to stop.\n4. **Exit condition**: what counts as success, what counts as a halt.\n\nIf you build a prompt that should live here, open a PR against `content/docs/agent-prompts.mdx`. Keep them under ~12 lines; if a workflow needs more, it belongs in a dedicated doc page and the prompt should link to it.\n'
   },
   {
     "name": "seeds",

package/dist/{introspect-ZS6I46OO.mjs → introspect-VUTR3NSR.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-export { run as default, extractMockSeed, gatherIntrospection, renderIntrospection } from './chunk-MR3Q43SU.mjs';
+export { run as default, extractMockSeed, gatherIntrospection, renderIntrospection } from './chunk-DAEUJO35.mjs';
 import './chunk-K5464A3L.mjs';
 import './chunk-DBZ3UOQ2.mjs';
-import './chunk-GAN7PG6N.mjs';
+import './chunk-HOOY5QBI.mjs';
 import './chunk-C4M3DXKC.mjs';
 import './chunk-UBAI443T.mjs';
 import './chunk-E2T2SBP5.mjs';

package/dist/{list-P74FSKQR.mjs → list-KLDTK2H3.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { REGISTRY_INDEX } from './chunk-HWHV62KB.mjs';
+import { REGISTRY_INDEX } from './chunk-VG6K7O6Q.mjs';
 import { parseArgs, flagBool } from './chunk-C4M3DXKC.mjs';
 import { CliError, CLI_ERROR_CODE, info, bold, dim, green, result } from './chunk-E2T2SBP5.mjs';
 

package/dist/{update-E6Q3KV3B.mjs → update-MDBLCCQ2.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { package_default } from './chunk-GAN7PG6N.mjs';
+import { package_default } from './chunk-HOOY5QBI.mjs';
 import { promptYesNo } from './chunk-ITAFAORS.mjs';
 import { parseArgs, flagBool, flagString } from './chunk-C4M3DXKC.mjs';
 import { success, bold, info, dim, result, failure, CliError, CLI_ERROR_CODE, step, isJsonMode } from './chunk-E2T2SBP5.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/cli",
-  "version": "0.7.18",
+  "version": "0.7.19",
   "description": "Cimplify CLI — deploy, manage env vars, link projects, and scaffold storefronts",
   "keywords": [
     "cimplify",
@@ -45,6 +45,6 @@
     "vitest": "^4.1.5"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0"
+    "@cimplify/sdk": "^0.78.0"
   }
 }

package/templates/storefront-auto/package.json

@@ -17,7 +17,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/storefront-bakery/package.json

@@ -17,7 +17,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/storefront-fashion/package.json

@@ -19,7 +19,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/storefront-grocery/package.json

@@ -17,7 +17,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/storefront-pharmacy/package.json

@@ -17,7 +17,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/storefront-restaurant/package.json

@@ -17,7 +17,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/storefront-retail/package.json

@@ -17,7 +17,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/storefront-services/package.json

@@ -17,7 +17,7 @@
     "check": "bun run typecheck && bun run test:run"
   },
   "dependencies": {
-    "@cimplify/sdk": "^0.72.0",
+    "@cimplify/sdk": "^0.78.0",
     "next": "^16.2.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"