@cimplify/cli 0.5.2 → 0.5.4

package/templates/storefront-restaurant/app/opensearch.xml/route.ts

@@ -1,7 +1,5 @@
 import { brand } from "@/lib/brand";
-
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
+import { getSiteUrl } from "@/lib/site-url";
 
 /**
  * OpenSearch description document — lets browsers add this site to the
@@ -9,14 +7,15 @@ const SITE_URL =
  * domain, they get an inline search box that hits /search?q=...
  */
 export async function GET(): Promise<Response> {
+  const siteUrl = await getSiteUrl();
   const xml = `<?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
   <ShortName>${escapeXml(brand.shortName)}</ShortName>
   <Description>Search ${escapeXml(brand.name)}</Description>
   <InputEncoding>UTF-8</InputEncoding>
-  <Url type="text/html" method="get" template="${SITE_URL}/search?q={searchTerms}" />
-  <Url type="application/opensearchdescription+xml" rel="self" template="${SITE_URL}/opensearch.xml" />
-  <moz:SearchForm>${SITE_URL}/search</moz:SearchForm>
+  <Url type="text/html" method="get" template="${siteUrl}/search?q={searchTerms}" />
+  <Url type="application/opensearchdescription+xml" rel="self" template="${siteUrl}/opensearch.xml" />
+  <moz:SearchForm>${siteUrl}/search</moz:SearchForm>
 </OpenSearchDescription>
 `;
   return new Response(xml, {

package/templates/storefront-restaurant/app/robots.ts

@@ -1,9 +1,8 @@
 import type { MetadataRoute } from "next";
+import { getSiteUrl } from "@/lib/site-url";
 
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
-
-export default function robots(): MetadataRoute.Robots {
+export default async function robots(): Promise<MetadataRoute.Robots> {
+  const siteUrl = await getSiteUrl();
   return {
     rules: [
       {
@@ -12,7 +11,7 @@ export default function robots(): MetadataRoute.Robots {
         disallow: ["/cart", "/checkout", "/orders/", "/api/"],
       },
     ],
-    sitemap: `${SITE_URL}/sitemap.xml`,
-    host: SITE_URL,
+    sitemap: `${siteUrl}/sitemap.xml`,
+    host: siteUrl,
   };
 }

package/templates/storefront-restaurant/app/sitemap.ts

@@ -1,8 +1,6 @@
 import type { MetadataRoute } from "next";
 import { getServerClient, type Product } from "@cimplify/sdk/server";
-
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
+import { getSiteUrl } from "@/lib/site-url";
 
 const STATIC_ROUTES: { path: string; priority: number; changeFrequency: "daily" | "weekly" | "monthly" }[] = [
   { path: "/", priority: 1.0, changeFrequency: "daily" },
@@ -15,6 +13,7 @@ const STATIC_ROUTES: { path: string; priority: number; changeFrequency: "daily"
 
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const now = new Date();
+  const siteUrl = await getSiteUrl();
   const client = getServerClient();
 
   const [productsRes, categoriesRes, collectionsRes] = await Promise.all([
@@ -28,7 +27,7 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const collections = collectionsRes.ok ? collectionsRes.value : [];
 
   const staticEntries: MetadataRoute.Sitemap = STATIC_ROUTES.map((r) => ({
-    url: `${SITE_URL}${r.path}`,
+    url: `${siteUrl}${r.path}`,
     lastModified: now,
     changeFrequency: r.changeFrequency,
     priority: r.priority,
@@ -38,21 +37,21 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   // shop pages). Emit those as deep-linkable URLs so search engines and LLMs
   // can index each product canonically.
   const productEntries: MetadataRoute.Sitemap = products.map((p: Product) => ({
-    url: `${SITE_URL}/shop?product=${encodeURIComponent(p.slug ?? p.id)}`,
+    url: `${siteUrl}/shop?product=${encodeURIComponent(p.slug ?? p.id)}`,
     lastModified: p.updated_at ? new Date(p.updated_at) : now,
     changeFrequency: "weekly",
     priority: 0.7,
   }));
 
   const categoryEntries: MetadataRoute.Sitemap = categories.map((c) => ({
-    url: `${SITE_URL}/categories/${c.slug}`,
+    url: `${siteUrl}/categories/${c.slug}`,
     lastModified: now,
     changeFrequency: "weekly",
     priority: 0.6,
   }));
 
   const collectionEntries: MetadataRoute.Sitemap = collections.map((c) => ({
-    url: `${SITE_URL}/collections/${c.slug}`,
+    url: `${siteUrl}/collections/${c.slug}`,
     lastModified: now,
     changeFrequency: "weekly",
     priority: 0.6,

package/templates/storefront-restaurant/lib/site-url.ts

@@ -0,0 +1,29 @@
+import { headers } from "next/headers";
+
+/**
+ * Canonical absolute URL for this storefront, derived at request time.
+ *
+ * Resolution order:
+ *   1. `NEXT_PUBLIC_SITE_URL` — set when you need a fixed canonical
+ *      (multiple domains, www-vs-apex preference, etc.).
+ *   2. The request `Host` header — works automatically on every deploy,
+ *      including preview URLs and custom domains.
+ *   3. `https://example.com` — only ever returned during prerender of
+ *      a page that has no live request (rare in App Router).
+ */
+export async function getSiteUrl(): Promise<string> {
+  const explicit = process.env.NEXT_PUBLIC_SITE_URL?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const h = await headers();
+    const host = h.get("host");
+    if (host) {
+      const isLocal = host.startsWith("localhost") || host.startsWith("127.");
+      return `${isLocal ? "http" : "https"}://${host}`;
+    }
+  } catch {
+    // `headers()` is unavailable in some build contexts — fall through.
+  }
+  return "https://example.com";
+}

package/templates/storefront-retail/.claude/skills/cimplify-storefront/SKILL.md

@@ -49,7 +49,7 @@ mock:            { seed, businessId }
 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`.
+4. Set `.env.local`: `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` (optional: `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.
 
@@ -131,7 +131,7 @@ cimplify domains add my-store.com
 | 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` |
+| Switching mock seed | edit `dev:mock` in `package.json` |
 | Full SDK reference | `docs/sdk/storefronts.md` in the Cimplify repo |
 
 ## What to do when the user asks something out-of-scope

package/templates/storefront-retail/.env.example

@@ -1,26 +1,8 @@
-# Tenant public key. Get yours from the desk Developers tab. The mock
-# accepts any value, so leave the placeholder during local dev.
+# Your tenant public key. Get it from the desk's Developers tab in
+# production; the mock accepts any value during local dev.
 NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=mock-dev
 
-# Business id used by the mock seed (default: Currents Electronics).
-NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_currents_electronics
-
-# Canonical public site URL — used by sitemap.xml, robots.txt, llms.txt,
-# and OpenGraph metadata. Set this on production deploys; `cimplify env push`
-# wires it into your linked project.
-NEXT_PUBLIC_SITE_URL=https://example.com
-
-# Business handle (human-readable slug, e.g. "akua-bakery"). Used by the
-# UCP manifest endpoint at /.well-known/ucp so AI agents (Claude / ChatGPT /
-# Gemini) can discover this storefront's commerce capabilities. Set this
-# on production deploys; leave empty in dev unless you're testing UCP.
-NEXT_PUBLIC_CIMPLIFY_BUSINESS_HANDLE=
-
-# ── Escape hatches (rarely needed) ────────────────────────────────────
-# Override the storefront API host (where /api/v1/catalogue, /api/v1/orders
-# live). Defaults to https://storefronts.cimplify.io in production,
-# 127.0.0.1:8787 in dev. Set only for self-hosted Cimplify or staging.
-# NEXT_PUBLIC_CIMPLIFY_STOREFRONT_URL=
-
-# Override the management/UCP host. Defaults to https://api.cimplify.io.
-# NEXT_PUBLIC_CIMPLIFY_API_URL=
+# Optional. Forces a fixed canonical URL for sitemap.xml, robots.txt,
+# OpenGraph, and llms.txt. Leave unset and the storefront derives the
+# canonical from the request `Host` header automatically.
+# NEXT_PUBLIC_SITE_URL=

package/templates/storefront-retail/AGENTS.md

@@ -6,7 +6,7 @@ If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this store
 
 1. **Edit `lib/brand.ts`** — every visible string lives here.
 2. **Edit `app/globals.css`** — `@theme { … }` block for palette + radius + font references.
-3. **Edit `.env.local`** — `NEXT_PUBLIC_CIMPLIFY_API_URL`, `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`, `NEXT_PUBLIC_SITE_URL`.
+3. **Edit `.env.local`** — `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` (optional: `NEXT_PUBLIC_SITE_URL`).
 
 ## Aesthetic
 

package/templates/storefront-retail/README.md

@@ -51,8 +51,6 @@ cimplify-mock --seed services     # Serene Spa
 cimplify-mock --seed grocery      # FreshMart
 ```
 
-Update `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID` in `.env.local` to match the seeded business.
-
 For a fresh scaffold with another design altogether:
 
 ```bash
@@ -68,8 +66,6 @@ cimplify init my-store --template grocery    # coming soon
 # .env.local
 - NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=mock-dev
 + NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=<your tenant key>
-- NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_currents_electronics
-+ NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=<your business id>
 ```
 
 Deploy with `cimplify deploy --prod` after linking the project. See [`cimplify` CLI docs](https://www.cimplify.dev/docs/cli). `next.config.ts` already whitelists the SDK image hosts under `images.remotePatterns`.

package/templates/storefront-retail/app/.well-known/ucp/route.ts

@@ -5,44 +5,70 @@ import { NextResponse } from "next/server";
  *
  * Agents — Claude, ChatGPT, Gemini, MCP clients — probe
  * `https://<your-domain>/.well-known/ucp` to learn what commerce
- * capabilities your storefront supports. We forward to Cimplify, which
- * returns the canonical manifest. Edge-cached for an hour because
- * capabilities change rarely.
+ * capabilities your storefront supports. We resolve the business's
+ * UCP handle from the public key (via the storefront API), then forward
+ * to Cimplify for the canonical manifest. Edge-cached for an hour
+ * because capabilities change rarely.
  */
 const UCP_API_BASE = "https://api.cimplify.io";
-
+const STOREFRONT_API_BASE =
+  process.env.NODE_ENV === "production"
+    ? "https://storefronts.cimplify.io"
+    : "http://127.0.0.1:8787";
 
 export async function GET() {
-  const businessHandle = process.env.NEXT_PUBLIC_CIMPLIFY_BUSINESS_HANDLE;
-
-  if (!businessHandle) {
+  const publicKey = process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY;
+  if (!publicKey) {
     return NextResponse.json(
       {
-        error: "NEXT_PUBLIC_CIMPLIFY_BUSINESS_HANDLE not set",
+        error: "NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY not set",
         remediation:
-          "Set NEXT_PUBLIC_CIMPLIFY_BUSINESS_HANDLE in .env.local (and your deployment env) to your business handle.",
+          "Set NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY in .env.local (and your deployment env).",
       },
       { status: 500 },
     );
   }
 
   try {
-    const response = await fetch(
-      `${UCP_API_BASE}/ucp/v1/${businessHandle}/manifest`,
+    // Step 1 — resolve the business handle from the public key.
+    const businessResp = await fetch(`${STOREFRONT_API_BASE}/api/v1/business`, {
+      headers: { "X-API-Key": publicKey, "Content-Type": "application/json" },
+      next: { revalidate: 3600 },
+    });
+
+    if (!businessResp.ok) {
+      return NextResponse.json(
+        { error: `Failed to resolve business: ${businessResp.status}` },
+        { status: businessResp.status },
+      );
+    }
+
+    const businessJson = await businessResp.json();
+    const handle: string | undefined = businessJson?.data?.handle;
+    if (!handle) {
+      return NextResponse.json(
+        { error: "Business has no handle configured" },
+        { status: 500 },
+      );
+    }
+
+    // Step 2 — fetch the canonical UCP manifest.
+    const manifestResp = await fetch(
+      `${UCP_API_BASE}/ucp/v1/${handle}/manifest`,
       {
         headers: { "Content-Type": "application/json" },
         next: { revalidate: 3600 },
       },
     );
 
-    if (!response.ok) {
+    if (!manifestResp.ok) {
       return NextResponse.json(
-        { error: `Upstream UCP manifest fetch failed: ${response.status}` },
-        { status: response.status },
+        { error: `Upstream UCP manifest fetch failed: ${manifestResp.status}` },
+        { status: manifestResp.status },
       );
     }
 
-    const manifest = await response.json();
+    const manifest = await manifestResp.json();
     return NextResponse.json(manifest, {
       headers: {
         "Content-Type": "application/json",

package/templates/storefront-retail/app/layout.tsx

@@ -6,6 +6,7 @@ import { Header } from "@/components/header";
 import { Footer } from "@/components/footer";
 import { CartDrawer } from "@/components/cart-drawer";
 import { brand } from "@/lib/brand";
+import { getSiteUrl } from "@/lib/site-url";
 
 const inter = Inter({
   subsets: ["latin"],
@@ -19,42 +20,46 @@ const mono = JetBrains_Mono({
   display: "swap",
 });
 
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
-
-export const metadata: Metadata = {
-  metadataBase: new URL(SITE_URL),
-  title: {
+export async function generateMetadata(): Promise<Metadata> {
+  const siteUrl = await getSiteUrl();
+  return {
+    metadataBase: new URL(siteUrl),
+    title: {
     default: brand.name,
     template: `%s — ${brand.name}`,
-  },
-  description: brand.description,
-  openGraph: {
+    },
+    description: brand.description,
+    openGraph: {
     type: "website",
     siteName: brand.name,
     locale: brand.locale,
-  },
-  twitter: { card: "summary_large_image" },
-};
+    },
+    twitter: { card: "summary_large_image" },
+  };
+}
 
-const ORGANIZATION_LD = {
-  "@context": "https://schema.org",
-  "@type": brand.schemaType,
-  name: brand.name,
-  url: SITE_URL,
-  description: brand.description,
-  email: brand.contact.email,
-  telephone: brand.contact.phoneTel,
-  address: {
+async function organizationLd() {
+  const siteUrl = await getSiteUrl();
+  return {
+    "@context": "https://schema.org",
+    "@type": brand.schemaType,
+    name: brand.name,
+    url: siteUrl,
+    description: brand.description,
+    email: brand.contact.email,
+    telephone: brand.contact.phoneTel,
+    address: {
     "@type": "PostalAddress",
     streetAddress: brand.contact.streetAddress,
     addressLocality: brand.contact.city,
     addressCountry: brand.contact.countryCode,
-  },
-  sameAs: brand.socials.map((s) => s.href),
-};
+    },
+    sameAs: brand.socials.map((s) => s.href),
+  };
+}
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const ld = await organizationLd();
   return (
     <html lang="en" suppressHydrationWarning className={`${inter.variable} ${mono.variable}`}>
       <body
@@ -63,7 +68,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
       >
         <script
           type="application/ld+json"
-          dangerouslySetInnerHTML={{ __html: JSON.stringify(ORGANIZATION_LD) }}
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(ld) }}
         />
         <Providers>
           <Header />

package/templates/storefront-retail/app/llms.txt/route.ts

@@ -1,11 +1,9 @@
 import { cacheTag, cacheLife } from "next/cache";
 import { getServerClient, tags, type Product } from "@cimplify/sdk/server";
 import { brand } from "@/lib/brand";
+import { getSiteUrl } from "@/lib/site-url";
 
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
-
-async function buildLlmsTxt(): Promise<string> {
+async function buildLlmsTxt(SITE_URL: string): Promise<string> {
   "use cache";
   cacheTag(tags.products(), tags.categories(), tags.collections());
   cacheLife("hours");
@@ -84,7 +82,7 @@ async function buildLlmsTxt(): Promise<string> {
  * into context windows.
  */
 export async function GET(): Promise<Response> {
-  const body = await buildLlmsTxt();
+  const body = await buildLlmsTxt(await getSiteUrl());
   return new Response(body, {
     headers: {
       "Content-Type": "text/plain; charset=utf-8",

package/templates/storefront-retail/app/opensearch.xml/route.ts

@@ -1,7 +1,5 @@
 import { brand } from "@/lib/brand";
-
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
+import { getSiteUrl } from "@/lib/site-url";
 
 /**
  * OpenSearch description document — lets browsers add this site to the
@@ -9,14 +7,15 @@ const SITE_URL =
  * domain, they get an inline search box that hits /search?q=...
  */
 export async function GET(): Promise<Response> {
+  const siteUrl = await getSiteUrl();
   const xml = `<?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
   <ShortName>${escapeXml(brand.shortName)}</ShortName>
   <Description>Search ${escapeXml(brand.name)}</Description>
   <InputEncoding>UTF-8</InputEncoding>
-  <Url type="text/html" method="get" template="${SITE_URL}/search?q={searchTerms}" />
-  <Url type="application/opensearchdescription+xml" rel="self" template="${SITE_URL}/opensearch.xml" />
-  <moz:SearchForm>${SITE_URL}/search</moz:SearchForm>
+  <Url type="text/html" method="get" template="${siteUrl}/search?q={searchTerms}" />
+  <Url type="application/opensearchdescription+xml" rel="self" template="${siteUrl}/opensearch.xml" />
+  <moz:SearchForm>${siteUrl}/search</moz:SearchForm>
 </OpenSearchDescription>
 `;
   return new Response(xml, {

package/templates/storefront-retail/app/products/[slug]/page.tsx

@@ -11,11 +11,9 @@ import {
 } from "@cimplify/sdk/server";
 import { ProductDetail } from "./product-detail";
 import { brand } from "@/lib/brand";
+import { getSiteUrl } from "@/lib/site-url";
 
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
-
-function productLd(product: ProductWithDetails) {
+function productLd(product: ProductWithDetails, SITE_URL: string) {
   const image = product.image_url ?? product.images?.[0];
   const inStock = product.inventory_status?.in_stock !== false;
   return {
@@ -74,6 +72,7 @@ export async function generateMetadata({
   params: Promise<{ slug: string }>;
 }): Promise<Metadata> {
   const { slug } = await params;
+  const siteUrl = await getSiteUrl();
   const data = await getProduct(slug);
   if (!data) return {};
   const { product } = data;
@@ -108,6 +107,7 @@ async function ProductContent({
   params: Promise<{ slug: string }>;
 }) {
   const { slug } = await params;
+  const siteUrl = await getSiteUrl();
   const data = await getProduct(slug);
   if (!data) notFound();
 
@@ -115,7 +115,7 @@ async function ProductContent({
     <>
       <script
         type="application/ld+json"
-        dangerouslySetInnerHTML={{ __html: JSON.stringify(productLd(data.product)) }}
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(productLd(data.product, siteUrl)) }}
       />
       <nav
         aria-label="Breadcrumb"

package/templates/storefront-retail/app/robots.ts

@@ -1,9 +1,8 @@
 import type { MetadataRoute } from "next";
+import { getSiteUrl } from "@/lib/site-url";
 
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
-
-export default function robots(): MetadataRoute.Robots {
+export default async function robots(): Promise<MetadataRoute.Robots> {
+  const siteUrl = await getSiteUrl();
   return {
     rules: [
       {
@@ -12,7 +11,7 @@ export default function robots(): MetadataRoute.Robots {
         disallow: ["/cart", "/checkout", "/orders/", "/api/"],
       },
     ],
-    sitemap: `${SITE_URL}/sitemap.xml`,
-    host: SITE_URL,
+    sitemap: `${siteUrl}/sitemap.xml`,
+    host: siteUrl,
   };
 }

package/templates/storefront-retail/app/sitemap.ts

@@ -1,8 +1,6 @@
 import type { MetadataRoute } from "next";
 import { getServerClient, type Product } from "@cimplify/sdk/server";
-
-const SITE_URL =
-  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
+import { getSiteUrl } from "@/lib/site-url";
 
 const STATIC_ROUTES: { path: string; priority: number; changeFrequency: "daily" | "weekly" | "monthly" }[] = [
   { path: "/", priority: 1.0, changeFrequency: "daily" },
@@ -15,6 +13,7 @@ const STATIC_ROUTES: { path: string; priority: number; changeFrequency: "daily"
 
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const now = new Date();
+  const siteUrl = await getSiteUrl();
   const client = getServerClient();
 
   const [productsRes, categoriesRes, collectionsRes] = await Promise.all([
@@ -28,28 +27,28 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const collections = collectionsRes.ok ? collectionsRes.value : [];
 
   const staticEntries: MetadataRoute.Sitemap = STATIC_ROUTES.map((r) => ({
-    url: `${SITE_URL}${r.path}`,
+    url: `${siteUrl}${r.path}`,
     lastModified: now,
     changeFrequency: r.changeFrequency,
     priority: r.priority,
   }));
 
   const productEntries: MetadataRoute.Sitemap = products.map((p: Product) => ({
-    url: `${SITE_URL}/products/${p.slug ?? p.id}`,
+    url: `${siteUrl}/products/${p.slug ?? p.id}`,
     lastModified: p.updated_at ? new Date(p.updated_at) : now,
     changeFrequency: "weekly",
     priority: 0.7,
   }));
 
   const categoryEntries: MetadataRoute.Sitemap = categories.map((c) => ({
-    url: `${SITE_URL}/categories/${c.slug}`,
+    url: `${siteUrl}/categories/${c.slug}`,
     lastModified: now,
     changeFrequency: "weekly",
     priority: 0.6,
   }));
 
   const collectionEntries: MetadataRoute.Sitemap = collections.map((c) => ({
-    url: `${SITE_URL}/collections/${c.slug}`,
+    url: `${siteUrl}/collections/${c.slug}`,
     lastModified: now,
     changeFrequency: "weekly",
     priority: 0.6,

package/templates/storefront-retail/lib/site-url.ts

@@ -0,0 +1,29 @@
+import { headers } from "next/headers";
+
+/**
+ * Canonical absolute URL for this storefront, derived at request time.
+ *
+ * Resolution order:
+ *   1. `NEXT_PUBLIC_SITE_URL` — set when you need a fixed canonical
+ *      (multiple domains, www-vs-apex preference, etc.).
+ *   2. The request `Host` header — works automatically on every deploy,
+ *      including preview URLs and custom domains.
+ *   3. `https://example.com` — only ever returned during prerender of
+ *      a page that has no live request (rare in App Router).
+ */
+export async function getSiteUrl(): Promise<string> {
+  const explicit = process.env.NEXT_PUBLIC_SITE_URL?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const h = await headers();
+    const host = h.get("host");
+    if (host) {
+      const isLocal = host.startsWith("localhost") || host.startsWith("127.");
+      return `${isLocal ? "http" : "https"}://${host}`;
+    }
+  } catch {
+    // `headers()` is unavailable in some build contexts — fall through.
+  }
+  return "https://example.com";
+}

package/templates/storefront-services/.claude/skills/cimplify-storefront/SKILL.md

@@ -49,7 +49,7 @@ mock:            { seed, businessId }
 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`.
+4. Set `.env.local`: `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` (optional: `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.
 
@@ -131,7 +131,7 @@ cimplify domains add my-store.com
 | 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` |
+| Switching mock seed | edit `dev:mock` in `package.json` |
 | Full SDK reference | `docs/sdk/storefronts.md` in the Cimplify repo |
 
 ## What to do when the user asks something out-of-scope

package/templates/storefront-services/.env.example

@@ -1,26 +1,8 @@
-# Tenant public key. Get yours from the desk Developers tab. The mock
-# accepts any value, so leave the placeholder during local dev.
+# Your tenant public key. Get it from the desk's Developers tab in
+# production; the mock accepts any value during local dev.
 NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=mock-dev
 
-# Business id used by the mock seed (default: Serene Spa).
-NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_serene_spa
-
-# Canonical public site URL — used by sitemap.xml, robots.txt, llms.txt,
-# and OpenGraph metadata. Set this on production deploys; `cimplify env push`
-# wires it into your linked project.
-NEXT_PUBLIC_SITE_URL=https://example.com
-
-# Business handle (human-readable slug, e.g. "akua-bakery"). Used by the
-# UCP manifest endpoint at /.well-known/ucp so AI agents (Claude / ChatGPT /
-# Gemini) can discover this storefront's commerce capabilities. Set this
-# on production deploys; leave empty in dev unless you're testing UCP.
-NEXT_PUBLIC_CIMPLIFY_BUSINESS_HANDLE=
-
-# ── Escape hatches (rarely needed) ────────────────────────────────────
-# Override the storefront API host (where /api/v1/catalogue, /api/v1/orders
-# live). Defaults to https://storefronts.cimplify.io in production,
-# 127.0.0.1:8787 in dev. Set only for self-hosted Cimplify or staging.
-# NEXT_PUBLIC_CIMPLIFY_STOREFRONT_URL=
-
-# Override the management/UCP host. Defaults to https://api.cimplify.io.
-# NEXT_PUBLIC_CIMPLIFY_API_URL=
+# Optional. Forces a fixed canonical URL for sitemap.xml, robots.txt,
+# OpenGraph, and llms.txt. Leave unset and the storefront derives the
+# canonical from the request `Host` header automatically.
+# NEXT_PUBLIC_SITE_URL=

package/templates/storefront-services/AGENTS.md

@@ -6,8 +6,7 @@ If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this store
 
 1. **Edit `lib/brand.ts`** — every visible string lives here.
 2. **Edit `app/globals.css`** — `@theme { … }` for palette + radius.
-3. **Edit `.env.local`** — `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_serene_spa` for the bundled seed.
-
+3. **Edit `.env.local`** — set `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` (the only required var).
 ## Aesthetic
 
 - **Fraunces serif + Inter** — warm, slightly editorial headings.