@brainerce/mcp-server 3.6.0 → 3.8.0

package/dist/bin/http.js

@@ -924,6 +924,175 @@ function ProductPage({ product, storeInfo }: { product: Product; storeInfo: Stor
 }
 \`\`\`
 
+### Variant Attribute Selector with Swatches (color + size **mix**)
+
+The simple text-button picker above works, but loses the merchant-configured
+**swatch metadata**. A single product often mixes one attribute that should
+render as **color swatches** (e.g. \`Color\`) and another that should render
+as **text buttons** (e.g. \`Size\`). The product response includes everything
+you need:
+
+- \`product.productAttributeOptions[]\` \u2014 the swatch definitions: \`attribute.name\`,
+  \`attribute.displayType\` (the \`AttributeDisplayType\` enum: \`DEFAULT\` | \`COLOR_SWATCH\` | \`IMAGE_SWATCH\` | \`MIXED_SWATCH\`),
+  \`attributeOption.name\`, \`swatchColor\` (hex), \`swatchColor2\` (hex \u2014 used for dual-color swatches
+  like Black & White), \`swatchImageUrl\` (for fabric / pattern thumbnails).
+  \`MIXED_SWATCH\` means each option in the group can independently pick image OR color
+  (the merchant decides per option). Treat any unrecognized value as \`DEFAULT\`.
+- \`variant.attributes\` \u2014 the selected value per attribute on each variant.
+
+Use \`getProductSwatches(product)\` to get a render-ready, grouped structure:
+
+\`\`\`typescript
+import { getProductSwatches } from 'brainerce';
+
+const groups = getProductSwatches(product);
+// [
+//   { attributeName: 'color', displayType: 'COLOR_SWATCH', options: [
+//     { name: 'Full Color',    swatchColor: '#1D9435', swatchColor2: null,       swatchImageUrl: null },
+//     { name: 'Black & White', swatchColor: '#000000', swatchColor2: '#FFFFFF',  swatchImageUrl: null },
+//   ]},
+//   { attributeName: 'size', displayType: 'DEFAULT', options: [
+//     { name: '16" \xD7 20"' }, { name: '24" \xD7 32"' }, { name: '36" \xD7 48"' },
+//   ]},
+// ]
+\`\`\`
+
+Render one branch per \`displayType\`. The same loop handles all-swatch, all-text,
+and the mix case:
+
+\`\`\`typescript
+function VariantPicker({
+  product,
+  selections,
+  onSelect,
+}: {
+  product: Product;
+  selections: Record<string, string>;          // { color: 'Full Color', size: '24" \xD7 32"' }
+  onSelect: (attrName: string, value: string) => void;
+}) {
+  const groups = getProductSwatches(product);
+  if (groups.length === 0) return null;
+
+  return (
+    <div className="space-y-4">
+      {groups.map((group) => (
+        <div key={group.attributeName}>
+          <label className="block mb-2 text-sm font-medium">
+            {group.attributeName}: <span className="text-gray-500">{selections[group.attributeName] ?? ''}</span>
+          </label>
+          <div className="flex flex-wrap gap-2">
+            {group.options.map((opt) => {
+              const isSelected = selections[group.attributeName] === opt.name;
+
+              // COLOR_SWATCH \u2014 round button; dual-color uses a 50/50 gradient.
+              if (group.displayType === 'COLOR_SWATCH' && opt.swatchColor) {
+                const bg = opt.swatchColor2
+                  ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                  : opt.swatchColor;
+                return (
+                  <button
+                    key={opt.name}
+                    type="button"
+                    title={opt.name}
+                    aria-pressed={isSelected}
+                    onClick={() => onSelect(group.attributeName, opt.name)}
+                    className={\`h-9 w-9 rounded-full border-2 \${isSelected ? 'border-black ring-2 ring-black/30' : 'border-gray-300 hover:border-black'}\`}
+                    style={{ background: bg }}
+                  />
+                );
+              }
+
+              // IMAGE_SWATCH \u2014 square thumbnail (fabric/pattern preview).
+              if (group.displayType === 'IMAGE_SWATCH' && opt.swatchImageUrl) {
+                return (
+                  <button
+                    key={opt.name}
+                    type="button"
+                    aria-pressed={isSelected}
+                    onClick={() => onSelect(group.attributeName, opt.name)}
+                    className={\`h-10 w-10 overflow-hidden rounded border-2 \${isSelected ? 'border-black' : 'border-gray-300'}\`}
+                  >
+                    <img src={opt.swatchImageUrl} alt={opt.name} className="h-full w-full object-cover" />
+                  </button>
+                );
+              }
+
+              // MIXED_SWATCH \u2014 each option is independently image OR color (image wins if present).
+              if (group.displayType === 'MIXED_SWATCH') {
+                if (opt.swatchImageUrl) {
+                  return (
+                    <button
+                      key={opt.name}
+                      type="button"
+                      aria-pressed={isSelected}
+                      onClick={() => onSelect(group.attributeName, opt.name)}
+                      className={\`h-10 w-10 overflow-hidden rounded border-2 \${isSelected ? 'border-black' : 'border-gray-300'}\`}
+                    >
+                      <img src={opt.swatchImageUrl} alt={opt.name} className="h-full w-full object-cover" />
+                    </button>
+                  );
+                }
+                if (opt.swatchColor) {
+                  const bg = opt.swatchColor2
+                    ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                    : opt.swatchColor;
+                  return (
+                    <button
+                      key={opt.name}
+                      type="button"
+                      title={opt.name}
+                      aria-pressed={isSelected}
+                      onClick={() => onSelect(group.attributeName, opt.name)}
+                      className={\`h-9 w-9 rounded-full border-2 \${isSelected ? 'border-black ring-2 ring-black/30' : 'border-gray-300 hover:border-black'}\`}
+                      style={{ background: bg }}
+                    />
+                  );
+                }
+                // option has neither image nor color \u2192 fall through to text button below.
+              }
+
+              // DEFAULT (or any swatch type missing its data) \u2014 plain text button.
+              return (
+                <button
+                  key={opt.name}
+                  type="button"
+                  aria-pressed={isSelected}
+                  onClick={() => onSelect(group.attributeName, opt.name)}
+                  className={\`rounded border px-3 py-1.5 text-sm \${isSelected ? 'bg-black text-white border-black' : 'border-gray-300 hover:border-black'}\`}
+                >
+                  {opt.name}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+\`\`\`
+
+Wire it up in the product page: keep \`selections\` in state, find the matching
+variant after each pick, and update price / image / stock from it.
+
+\`\`\`typescript
+const [selections, setSelections] = useState<Record<string, string>>({});
+
+const matchedVariant = useMemo(() => (
+  product.variants?.find((v) =>
+    Object.entries(selections).every(([k, val]) => v.attributes?.[k] === val)
+  ) ?? null
+), [product.variants, selections]);
+
+// Greying-out unavailable combinations: for each candidate value, run
+// the same find() and check \`inventory.canPurchase\`. Disable the button
+// if no purchasable variant exists under that selection.
+\`\`\`
+
+**i18n:** \`getProductSwatches\` returns translated \`attributeName\` and
+\`option.name\` automatically when \`client.setLocale()\` is active. No
+client-side overlay needed. Swatch colors are language-agnostic.
+
 ### Description Rendering (handles HTML vs text)
 
 \`\`\`typescript
@@ -1558,17 +1727,28 @@ Allergens (informational chips), scheduled availability windows, nested combos (
 function getProductReviewsSection() {
   return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
 
-Reviews publish immediately on submit. Merchants hide individual reviews via the admin surface \u2014 no PENDING queue.
+**Purchaser-only.** Only authenticated customers who purchased the product can submit. Each customer writes one review per product and can edit/delete it. Reviews publish immediately \u2014 no PENDING queue.
 
 \`\`\`typescript
-// PDP \u2014 list visible reviews
-const { data, meta } = await client.listProductReviews(productId, { page: 1, limit: 20 });
-data.forEach(r => render(r.authorName, r.rating, r.body, r.verifiedPurchase));
+// PDP \u2014 list visible reviews (public)
+const { data } = await getClient().listProductReviews(productId, { page: 1, limit: 20 });
+
+// Decide which UI to render for the current customer
+getClient().setCustomerToken(authToken); // after login
+const { eligible, reason, myReview } = await getClient().getMyProductReview(productId);
+
+if (!eligible) {
+  // reason: 'no_eligible_order' | 'reviews_disabled' | 'product_not_found'
+  // \u2192 "only customers who purchased this product can leave a review"
+} else if (myReview) {
+  // \u2192 edit form prefilled with myReview.rating + myReview.body
+} else {
+  // \u2192 submit form (rating + body only \u2014 name/email come from customer profile)
+}
 
-// PDP \u2014 submit form
-await client.submitProductReview(productId, {
-  authorName, authorEmail, rating: 5, body,
-});
+await getClient().submitProductReview(productId, { rating: 5, body: 'Loved it!' });
+await getClient().updateMyProductReview(productId, { rating: 4, body: 'Updated.' });
+await getClient().deleteMyProductReview(productId); // can submit a new one after
 \`\`\`
 
 Each \`Product\` carries denormalized rollups: \`product.avgRating\`, \`product.reviewCount\`. Use these on PLP cards.
@@ -1597,9 +1777,10 @@ const productJsonLd = {
 
 ### Rules
 - Rating must be an integer 1-5 (DB constraint).
-- Duplicate from same email \u2192 409 Conflict.
-- Submit endpoint is throttled to 3 / 60s / IP \u2014 surface a friendly "please wait" on 429.
-- \`verifiedPurchase\` is derived server-side from DELIVERED orders \u2014 DO NOT try to set it.
+- Customer must be logged in AND have purchased the product (\`SHIPPED+\` for physical, \`PAID+\` for downloadable).
+- One review per (productId, customerId). Duplicate submit \u2192 409 \u2014 use updateMyProductReview instead.
+- Submit throttled 3 / 60s / IP; edit/delete 5 / 60s / IP.
+- \`verifiedPurchase\` is always true for customer-submitted reviews.
 - Stores with \`reviewsEnabled = false\` return 403 on storefront endpoints.`;
 }
 function getInventorySection() {
@@ -2021,9 +2202,12 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const client = getServerClient();
   client.setLocale(locale);
   const product = await client.getProductBySlug(slug);
+  // NEVER feed raw HTML into <meta name="description"> \u2014 product.description
+  // is often rich-text HTML. Strip tags first, then truncate on a word
+  // boundary. See buildMetaDescription() in lib/seo.ts.
   return {
     title: product.seoTitle || product.name,
-    description: product.seoDescription || product.description?.slice(0, 160),
+    description: product.seoDescription || buildMetaDescription(product.description) || product.name,
   };
 }
 \`\`\`
@@ -2139,11 +2323,25 @@ Because the backend already overlays everything, UI code is just:
 
 ### RTL handling
 
-For RTL locales (\`he\`, \`ar\`), set \`<html dir="rtl">\` in the root layout and
-let flexbox reverse automatically. Do NOT add \`flex-row-reverse\` on top of
-\`dir="rtl"\` \u2014 that's a double-swap. DO swap directional icons (chevrons,
-arrows) manually. Use logical CSS properties (\`ms-*\`/\`me-*\`) instead of
-\`ml-*\`/\`mr-*\`.
+Resolve direction with \`client.getStoreDirection(locale)\` \u2014 it returns
+\`'ltr' | 'rtl'\` for any BCP-47 tag (Arabic, Hebrew, Persian, Urdu, Yiddish
+today; future RTL locales added by the platform are picked up automatically).
+Do NOT maintain your own RTL locale set.
+
+\`\`\`tsx
+// app/[locale]/layout.tsx
+const dir = client.getStoreDirection(locale);
+return <html lang={locale} dir={dir}>...</html>;
+\`\`\`
+
+For static rendering, \`storeInfo.i18n.defaultDirection\` carries the store's
+default direction, and each entry in \`storeInfo.i18n.supportedLocaleObjects\`
+includes its own \`direction\`.
+
+Let flexbox reverse automatically once \`<html dir="rtl">\` is set. Do NOT add
+\`flex-row-reverse\` on top \u2014 that's a double-swap. DO swap directional icons
+(chevrons, arrows) manually. Use logical CSS properties (\`ms-*\`/\`me-*\`)
+instead of \`ml-*\`/\`mr-*\`.
 
 ### Language switcher
 
@@ -2520,6 +2718,141 @@ and a \`newsletter\` form embedded in the footer), render each form from its
 own \`contactForms.get(key, locale)\` call. The \`formKey\` you pass to
 \`createInquiry\` must match.`;
 }
+function getContentSection() {
+  return `## Content \u2014 typed merchant content store
+
+Brainerce ships a typed content store so merchants can edit site chrome, FAQ,
+static pages, and inline rich-text blocks in the dashboard \u2014 without
+re-prompting the AI that built their storefront. Every row has a \`type\` +
+\`key\` + typed \`data\` payload + free-form \`customFields\`.
+
+**Six content types.** Each one has a fixed \`data\` shape; the SDK's TypeScript
+generics keep them in lockstep:
+
+| Type           | Use for                                | \`data\` shape (abbreviated) |
+| -------------- | -------------------------------------- | --------------------------- |
+| \`FAQ\`         | Q/A accordions                         | \`{ items: { question, answer }[] }\` |
+| \`FOOTER\`      | Site footer (chrome)                   | \`{ columns, copyright?, social? }\` |
+| \`HEADER\`      | Top nav + logo + CTA (chrome)          | \`{ logo?, navItems, cta? }\` |
+| \`ANNOUNCEMENT\`| Banners; time-bound by \`startsAt/endsAt\` | \`{ message, severity, dismissible, ... }\` |
+| \`RICH_TEXT\`   | Free-form HTML blocks embedded inline  | \`{ html }\` |
+| \`PAGE\`        | Static pages with slug + SEO           | \`{ slug, title, html, seo? }\` |
+
+Run \`get-type-definitions\` with \`domain: 'content'\` for the full interfaces.
+
+### Default key
+
+Every type has \`'main'\` as its universal default key. \`client.content.faq.get()\`
+with no arguments resolves to \`key='main'\`. Topical keys (\`'shipping'\`,
+\`'holiday-2026'\`, \`'about'\`) are merchant-named.
+
+### Reading content (any SDK mode)
+
+Public reads work in vibe-coded mode, storefront mode, and admin mode. They
+return \`null\` on 404 \u2014 render hard-coded fallbacks so the page never crashes
+when the merchant hasn't seeded yet.
+
+\`\`\`ts
+// Single entry, default key 'main', resolved to a locale
+const faq = await client.content.faq.get('main', locale);
+if (faq) {
+  faq.data.items.forEach(({ question, answer }) => {
+    // Render question + sanitize(answer)
+  });
+}
+
+// All entries of a type
+const allFaqs = await client.content.faq.list(locale);
+
+// Page by URL slug \u2014 for app/[slug]/page.tsx
+const page = await client.content.page.getBySlug(slug, locale);
+if (!page) notFound();
+\`\`\`
+
+### Security \u2014 sanitize HTML before rendering
+
+\`FAQ.items[i].answer\`, \`RICH_TEXT.html\`, and \`PAGE.html\` carry
+MERCHANT-AUTHORED HTML. The server does NOT pre-sanitize \u2014 some merchants
+embed iframes (e.g. YouTube) which strict sanitizers would strip. ALWAYS
+sanitize on the storefront before injecting:
+
+\`\`\`ts
+// Recommended: isomorphic-dompurify
+import DOMPurify from 'isomorphic-dompurify';
+const safe = DOMPurify.sanitize(rawHtml);
+<div dangerouslySetInnerHTML={{ __html: safe }} />;
+\`\`\`
+
+Skipping this is XSS.
+
+### Custom fields
+
+Every Content row carries a free-form \`customFields: Record<string, string>\`.
+Merchants add arbitrary key-value extras (\`helpEmail\`, \`phoneNumber\`,
+\`foundedYear\`) that you can opt into reading:
+
+\`\`\`ts
+const faq = await client.content.faq.get('shipping');
+<a href={\`mailto:\${faq.customFields.helpEmail}\`}>Need help?</a>
+\`\`\`
+
+The shape is whatever the merchant entered. Read keys you expect; ignore the rest.
+
+### Locale resolution
+
+All public reads accept a \`locale\` argument. The server resolves
+\`translations[locale]\` server-side and returns the resolved \`data\` payload \u2014
+the storefront does NOT need to do its own overlay. Empty / missing translations
+fall through to the default-locale value.
+
+### Cache
+
+Public reads carry \`Cache-Control: public, max-age=300, stale-while-revalidate=60\`.
+Merchant edits propagate within ~5 minutes. Don't layer extra client-side
+caching beyond Next.js's default fetch cache.
+
+### Admin writes (apiKey mode)
+
+\`\`\`ts
+const adminClient = new BrainerceClient({ apiKey: process.env.BRAINERCE_API_KEY });
+
+// Create \u2014 always starts in DRAFT
+const faq = await adminClient.content.faq.create({
+  key: 'shipping',
+  name: 'Shipping FAQ',
+  data: { items: [{ question: 'How long?', answer: 'Most orders ship in 2 days.' }] },
+});
+
+// Update (data replaces wholesale; last-write-wins on the data field)
+await adminClient.content.update(faq.id, {
+  data: { items: [{ question: 'How long?', answer: 'Updated answer.' }] },
+});
+
+// Publish / unpublish
+await adminClient.content.publish(faq.id);
+await adminClient.content.unpublish(faq.id);
+
+// Hard delete
+await adminClient.content.remove(faq.id);
+\`\`\`
+
+Write operations throw if called from vibe-coded or storefront mode.
+
+### Reserved key convention
+
+\`'main'\` is reserved as the universal default. Don't use it for topical
+entries \u2014 pick a descriptive slug (\`'shipping'\`, \`'returns'\`, \`'about'\`,
+\`'holiday-2026'\`). The validation rule is \`^[a-z][a-z0-9-]*$\`, max 64 chars.
+
+### See also
+
+- \`get-business-flows\` with \`flow: 'content-bootstrap'\` for the full
+  layout / FAQ / page recipe.
+- \`get-required-features\` lists each Content surface (\`site-header\`,
+  \`site-footer\`, \`announcement-bar\`, \`faq-page\`, \`static-pages\`).
+- \`get-type-definitions\` with \`domain: 'content'\` for the TypeScript
+  interfaces.`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -2566,6 +2899,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getAdminApiSection();
     case "inquiries":
       return getContactInquiriesSection();
+    case "content":
+      return getContentSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -2654,10 +2989,14 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
-        getContactInquiriesSection()
+        getContactInquiriesSection(),
+        "",
+        "---",
+        "",
+        getContentSection()
       ].join("\n");
     default:
-      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, checkout-custom-fields, payment, auth, order-confirmation, inventory, discounts, recommendations, product-customization-fields, tax, i18n, critical-rules, type-reference, admin, inquiries, all`;
+      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, checkout-custom-fields, payment, auth, order-confirmation, inventory, discounts, recommendations, product-customization-fields, tax, i18n, critical-rules, type-reference, admin, inquiries, content, all`;
   }
 }
 
@@ -2685,6 +3024,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "i18n",
     "admin",
     "inquiries",
+    "content",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: import_zod.z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -2695,9 +3035,7 @@ var GET_SDK_DOCS_SCHEMA = {
 async function handleGetSdkDocs(args) {
   const id = args.salesChannelId ?? args.connectionId;
   if (!args.salesChannelId && args.connectionId) {
-    console.warn(
-      "get-sdk-docs: `connectionId` is deprecated \u2014 use `salesChannelId` instead"
-    );
+    console.warn("get-sdk-docs: `connectionId` is deprecated \u2014 use `salesChannelId` instead");
   }
   const content = getSectionByTopic(args.topic, id, args.currency);
   return {
@@ -3429,11 +3767,16 @@ interface ProductReviewAdmin extends ProductReview {
   updatedAt: string;
 }
 
-interface SubmitProductReviewInput {
-  authorName: string;
-  authorEmail?: string;              // recommended \u2014 used for guest dedupe + verified-purchase derivation
+interface WriteProductReviewInput {
   rating: number;                    // 1-5
-  body?: string;                     // optional
+  body?: string;                     // optional, max 5000 chars
+}
+
+interface MyProductReview {
+  eligible: boolean;
+  // Machine-readable reason when not eligible. null when eligible=true.
+  reason: 'no_eligible_order' | 'reviews_disabled' | 'product_not_found' | null;
+  myReview: ProductReview | null;
 }
 
 // Each Product carries denormalized review stats:
@@ -3674,6 +4017,156 @@ export interface ModifierValidationError {
 // The cart line then carries:
 //   cart.items[i].modifiers      \u2014 CartItemModifierLine[]
 //   cart.items[i].modifiersTotal \u2014 decimal string of the paid (non-free) deltas`;
+var CONTENT_TYPES = `// ---- Content (typed merchant content store) ----
+// Brainerce ships a typed content store so merchants can edit FAQ, footer,
+// header, announcements, rich text, and static pages in the dashboard
+// without re-prompting the AI that built the storefront. Every row has a
+// 'type' + 'key' + typed 'data' payload + free-form 'customFields'.
+//
+// SECURITY (read carefully):
+//   RICH_TEXT.html, PAGE.html, and FAQ answers are MERCHANT-AUTHORED HTML.
+//   ALWAYS sanitize with isomorphic-dompurify (or equivalent) before
+//   injecting via dangerouslySetInnerHTML. The server does NOT pre-sanitize
+//   because some merchants embed iframes (e.g. YouTube) which strict
+//   sanitizers would strip; the storefront chooses the policy.
+//
+// 404 contract: client.content.<type>.get(key) returns null when no
+// PUBLISHED row exists. Always render a hard-coded fallback on null so
+// the page never crashes when the merchant hasn't seeded yet.
+//
+// Default key: every type has 'main' as its universal default. Pass no
+// argument to fetch the main entry; pass a custom key ('shipping',
+// 'holiday-2026', 'about') for topical entries.
+
+export type ContentType = 'FAQ' | 'FOOTER' | 'HEADER' | 'ANNOUNCEMENT' | 'RICH_TEXT' | 'PAGE';
+export type ContentStatus = 'DRAFT' | 'PUBLISHED';
+
+export interface FaqItem {
+  question: string;
+  /** Sanitized HTML \u2014 sanitize before rendering. */
+  answer: string;
+}
+export interface FaqContent { items: FaqItem[] }
+
+export interface FooterLink { label: string; url: string }
+export interface FooterColumn { title: string; links: FooterLink[] }
+export interface FooterSocialLink { platform: string; url: string } // 'instagram' | 'facebook' | 'x' | ...
+export interface FooterContent {
+  columns: FooterColumn[];
+  copyright?: string;
+  social?: FooterSocialLink[];
+}
+
+export interface HeaderLogo { src: string; alt: string }
+export interface HeaderNavItem { label: string; url: string }
+export interface HeaderCta { label: string; url: string }
+export interface HeaderContent {
+  logo?: HeaderLogo;
+  navItems: HeaderNavItem[];
+  cta?: HeaderCta;
+}
+
+export type AnnouncementSeverity = 'info' | 'warning' | 'success';
+export interface AnnouncementContent {
+  message: string;
+  severity: AnnouncementSeverity;
+  dismissible: boolean;
+  /** ISO 8601 \u2014 filter client-side. */
+  startsAt?: string;
+  endsAt?: string;
+  ctaLabel?: string;
+  ctaHref?: string;
+}
+
+export interface RichTextContent {
+  /** Raw HTML \u2014 sanitize before rendering. */
+  html: string;
+}
+
+export interface PageSeo {
+  title?: string;
+  description?: string;
+  ogImage?: string;
+}
+export interface PageContent {
+  /** URL slug, lower-kebab. */
+  slug: string;
+  title: string;
+  /** Raw HTML \u2014 sanitize before rendering. */
+  html: string;
+  seo?: PageSeo;
+}
+
+export interface ContentSummary {
+  id: string;
+  type: ContentType;
+  key: string;
+  name: string;
+  status: ContentStatus;
+  position: number;
+  updatedAt: string;
+}
+
+export interface Content<T extends ContentType = ContentType> extends ContentSummary {
+  type: T;
+  data: T extends 'FAQ' ? FaqContent
+      : T extends 'FOOTER' ? FooterContent
+      : T extends 'HEADER' ? HeaderContent
+      : T extends 'ANNOUNCEMENT' ? AnnouncementContent
+      : T extends 'RICH_TEXT' ? RichTextContent
+      : T extends 'PAGE' ? PageContent
+      : never;
+  /** Free-form merchant-defined extras. Read keys the merchant told you to expect. */
+  customFields: Record<string, string>;
+  salesChannelIds: string[];
+}
+
+// ---- SDK usage examples ----
+//
+// FAQ \u2014 render an accordion from the main FAQ (or a topical one):
+//   const faq = await client.content.faq.get('main', locale);  // 'shipping', 'returns', ...
+//   if (faq) {
+//     faq.data.items.forEach(({ question, answer }) => {
+//       // Render question + sanitize(answer) \u2014 never inject raw HTML.
+//     });
+//   }
+//
+// Footer \u2014 server component in root layout:
+//   const footer = await client.content.footer.get('main', locale);
+//   if (!footer) return <Fallback />;
+//   // Render footer.data.columns, footer.data.social, footer.data.copyright
+//
+// Header \u2014 same pattern as footer:
+//   const header = await client.content.header.get('main', locale);
+//
+// Announcement \u2014 multiple may be active; filter by date client-side:
+//   const announcements = await client.content.announcement.list(locale);
+//   const now = Date.now();
+//   const active = announcements.filter((a) => {
+//     const startOk = !a.data.startsAt || new Date(a.data.startsAt).getTime() <= now;
+//     const endOk = !a.data.endsAt || new Date(a.data.endsAt).getTime() >= now;
+//     return startOk && endOk;
+//   });
+//
+// Rich text \u2014 inline block anywhere on a page:
+//   const block = await client.content.richText.get('about-intro', locale);
+//   <div dangerouslySetInnerHTML={{ __html: sanitize(block.data.html) }} />
+//
+// Page \u2014 catch-all route by slug (e.g. /about, /terms, /privacy):
+//   // app/[slug]/page.tsx
+//   const page = await client.content.page.getBySlug(params.slug, locale);
+//   if (!page) notFound();
+//   // page.data.title, page.data.html, page.data.seo
+//   return <article dangerouslySetInnerHTML={{ __html: sanitize(page.data.html) }} />;
+//
+// Custom fields \u2014 every Content row carries a free-form Record<string, string>:
+//   const faq = await client.content.faq.get('shipping');
+//   <a href={\`mailto:\${faq.customFields.helpEmail}\`}>Need help?</a>
+//
+// Cache \u2014 public reads carry Cache-Control: public, max-age=300,
+// stale-while-revalidate=60. Storefront changes propagate within ~5 min
+// of the merchant publishing. Do not add extra client-side caching
+// beyond Next.js's default fetch cache.`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -3684,7 +4177,8 @@ var TYPES_BY_DOMAIN = {
   helpers: HELPERS_TYPES,
   inquiries: INQUIRIES_TYPES,
   reviews: REVIEWS_TYPES,
-  "modifier-groups": MODIFIER_GROUPS_TYPES
+  "modifier-groups": MODIFIER_GROUPS_TYPES,
+  content: CONTENT_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -3715,9 +4209,10 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "helpers",
     "inquiries",
     "reviews",
+    "content",
     "all"
   ]).describe(
-    'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse.'
+    'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page.'
   )
 };
 async function handleGetTypeDefinitions(args) {
@@ -3736,6 +4231,7 @@ var GET_CODE_EXAMPLE_SCHEMA = {
     "sdk-init",
     "cart-read-and-mutate",
     "variant-selection",
+    "variant-selector-swatches",
     "checkout-address-and-shipping",
     "checkout-payment-providers",
     "checkout-stripe-confirm",
@@ -3805,28 +4301,148 @@ for (const item of cart.items) {
   const unitPrice = parseFloat(item.unitPrice); // prices are strings!
 }`,
   "variant-selection": `// Variant selection with live stock + price updates.
+// Variants expose attributes as a flat object: { color: 'Red', size: 'M' }.
+// NOT 'options' \u2014 that field does not exist on ProductVariant.
 import { getVariantPrice, getStockStatus, getVariantOptions } from 'brainerce';
 import type { Product, ProductVariant } from 'brainerce';
 
 function selectVariant(product: Product, selections: Record<string, string>) {
-  // selections = { Size: 'M', Color: 'Red' }
-  const variant = product.variants.find((v) =>
-    v.options.every((o) => selections[o.name] === o.value)
+  // selections = { size: 'M', color: 'Red' }  (keys match variant.attributes keys)
+  const variant = product.variants?.find((v) =>
+    Object.entries(selections).every(([k, val]) => v.attributes?.[k] === val)
   );
   if (!variant) return null;
 
-  const price = getVariantPrice(product, variant); // handles compare-at, currency
-  const stock = getStockStatus(variant); // 'IN_STOCK' | 'LOW_STOCK' | 'OUT_OF_STOCK'
-  const canPurchase = stock !== 'OUT_OF_STOCK';
+  const price = getVariantPrice(variant, product.basePrice); // string, fallback-aware
+  const stock = getStockStatus(variant.inventory); // 'in-stock' | 'low-stock' | 'out-of-stock' | 'unavailable'
+  const canPurchase = variant.inventory?.canPurchase !== false;
 
   // Switch the main product image to the variant's image if it has one
-  const image = variant.image ?? product.images[0];
+  const image = variant.image ?? product.images?.[0];
 
   return { variant, price, stock, canPurchase, image };
 }
 
-// Build the option picker from getVariantOptions(product) \u2014 returns
-// [{ name: 'Size', values: ['S','M','L'] }, ...]`,
+// Build the option picker by iterating product.variants and grouping
+// variant.attributes into { color: ['Red', 'Blue'], size: ['S','M','L'] }.
+// For each variant you can also call getVariantOptions(variant) which returns
+// the same key/value pairs as an array with translated names when setLocale() is active.
+// For swatch metadata (color hex, dual-color, image), use the
+// 'variant-selector-swatches' operation instead.`,
+  "variant-selector-swatches": `// Variant picker that mixes color swatches and text buttons in one product.
+// Uses product.productAttributeOptions[] \u2014 the merchant-configured swatch
+// metadata. displayType is the AttributeDisplayType Prisma enum, one of:
+//   'DEFAULT'       \u2014 plain text button
+//   'COLOR_SWATCH'  \u2014 swatchColor (+ optional swatchColor2 dual-color gradient)
+//   'IMAGE_SWATCH'  \u2014 swatchImageUrl thumbnail
+//   'MIXED_SWATCH'  \u2014 per-option hybrid: image if swatchImageUrl is set,
+//                     otherwise fall back to swatchColor
+// getProductSwatches() groups options by attribute name so you can render each
+// attribute with its own displayType \u2014 a single product can have Color as
+// swatches AND Size as text buttons.
+import { getProductSwatches } from 'brainerce';
+import type { Product } from 'brainerce';
+
+function VariantPicker({
+  product,
+  selections,
+  onSelect,
+}: {
+  product: Product;
+  selections: Record<string, string>;
+  onSelect: (attrName: string, value: string) => void;
+}) {
+  const groups = getProductSwatches(product);
+  // groups: [{ attributeName, displayType, options: [{ name, swatchColor, swatchColor2, swatchImageUrl }] }]
+
+  return (
+    <>
+      {groups.map((group) => (
+        <div key={group.attributeName}>
+          <label>{group.attributeName}: {selections[group.attributeName] ?? ''}</label>
+          <div style={{ display: 'flex', gap: 8 }}>
+            {group.options.map((opt) => {
+              const selected = selections[group.attributeName] === opt.name;
+              const onClick = () => onSelect(group.attributeName, opt.name);
+
+              // COLOR_SWATCH: round button. swatchColor2 = dual-color gradient.
+              if (group.displayType === 'COLOR_SWATCH' && opt.swatchColor) {
+                const bg = opt.swatchColor2
+                  ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                  : opt.swatchColor;
+                return (
+                  <button
+                    key={opt.name}
+                    type="button"
+                    title={opt.name}
+                    aria-pressed={selected}
+                    onClick={onClick}
+                    style={{
+                      width: 36,
+                      height: 36,
+                      borderRadius: '50%',
+                      background: bg,
+                      outline: selected ? '2px solid black' : 'none',
+                    }}
+                  />
+                );
+              }
+
+              // IMAGE_SWATCH: square thumbnail.
+              if (group.displayType === 'IMAGE_SWATCH' && opt.swatchImageUrl) {
+                return (
+                  <button key={opt.name} type="button" onClick={onClick} aria-pressed={selected}>
+                    <img src={opt.swatchImageUrl} alt={opt.name} width={40} height={40} />
+                  </button>
+                );
+              }
+
+              // MIXED_SWATCH: per-option hybrid (image wins if present).
+              if (group.displayType === 'MIXED_SWATCH') {
+                if (opt.swatchImageUrl) {
+                  return (
+                    <button key={opt.name} type="button" onClick={onClick} aria-pressed={selected}>
+                      <img src={opt.swatchImageUrl} alt={opt.name} width={40} height={40} />
+                    </button>
+                  );
+                }
+                if (opt.swatchColor) {
+                  const bg = opt.swatchColor2
+                    ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                    : opt.swatchColor;
+                  return (
+                    <button
+                      key={opt.name}
+                      type="button"
+                      title={opt.name}
+                      aria-pressed={selected}
+                      onClick={onClick}
+                      style={{ width: 36, height: 36, borderRadius: '50%', background: bg }}
+                    />
+                  );
+                }
+              }
+
+              // DEFAULT (or any swatch type missing its data): text button.
+              return (
+                <button key={opt.name} type="button" onClick={onClick} aria-pressed={selected}>
+                  {opt.name}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}
+
+// After the user picks a value, find the matching ProductVariant:
+//   product.variants?.find((v) =>
+//     Object.entries(selections).every(([k, val]) => v.attributes?.[k] === val)
+//   )
+// Then read variant.price, variant.image, variant.inventory.canPurchase
+// to update the rest of the PDP.`,
   "checkout-address-and-shipping": `// Step 1-3 of the checkout flow. Never reorder or skip.
 import { client } from './brainerce';
 
@@ -4143,8 +4759,10 @@ client.setLocale(locale);
 // order bumps, search suggestions, discount banners, nudges,
 // badges, order history.
 
-// For RTL locales (he, ar), set the document direction.
-// Framework-neutral: document.documentElement.setAttribute('dir', 'rtl');`,
+// For RTL direction, do not hardcode the locale list. Ask the SDK:
+//   const dir = client.getStoreDirection(currentLocale); // 'ltr' | 'rtl'
+//   document.documentElement.setAttribute('dir', dir);
+// (Or in React: <html dir={dir}>...</html>.)`,
   "order-history-full": `// Full "My Orders" account page. Render every piece of data the server
 // already returns \u2014 not just order number / total / status.
 //
@@ -4619,21 +5237,25 @@ function renderCartItem(item: CartItem): string {
 function lineTotal(item: CartItem): number {
   return item.unitPrice * item.quantity;
 }`,
-  "product-reviews": `// PDP: list visible reviews + submit form + JSON-LD aggregateRating
-import { client } from '@/lib/brainerce';
-import type { Product, ProductReview, SubmitProductReviewInput } from 'brainerce';
-
+  "product-reviews": `// Purchaser-only reviews. Customer must be logged in AND have purchased
+// the product. The component switches between sign-in CTA / not-eligible /
+// submit form / edit form based on getMyProductReview().
+import { getClient, getServerClient } from '@/lib/brainerce';
+import { checkAuthStatus } from '@/lib/auth';
+import type { Product, ProductReview, MyProductReview } from 'brainerce';
+
+// Server component \u2014 fetches existing reviews + emits JSON-LD aggregateRating.
 export async function ProductReviewsSection({ product }: { product: Product }) {
-  const { data } = await client.listProductReviews(product.id, { page: 1, limit: 20 });
+  const { data } = await getServerClient().listProductReviews(product.id, { page: 1, limit: 20 });
 
   return (
     <section>
       <h2>Reviews ({product.reviewCount ?? 0})</h2>
-      {data.length === 0 && <p>No reviews yet \u2014 be the first.</p>}
+      {data.length === 0 && <p>No reviews yet.</p>}
       {data.map((r) => (
         <article key={r.id}>
           <strong>{r.authorName}</strong>
-          {r.verifiedPurchase && <span> \xB7 Verified</span>}
+          {r.verifiedPurchase && <span> \xB7 Verified purchase</span>}
           <div>{'\u2605'.repeat(r.rating)}{'\u2606'.repeat(5 - r.rating)}</div>
           {r.body && <p>{r.body}</p>}
         </article>
@@ -4666,42 +5288,83 @@ function productJsonLd(product: Product, url: string) {
 
 // Client-side form
 'use client';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
+
+type Stage =
+  | { kind: 'loading' }
+  | { kind: 'signed_out' }
+  | { kind: 'not_eligible'; reason: MyProductReview['reason'] }
+  | { kind: 'submit' }
+  | { kind: 'edit'; review: ProductReview };
 
 function ReviewForm({ productId }: { productId: string }) {
+  const [stage, setStage] = useState<Stage>({ kind: 'loading' });
   const [rating, setRating] = useState(5);
   const [body, setBody] = useState('');
-  const [name, setName] = useState('');
-  const [email, setEmail] = useState('');
   const [error, setError] = useState<string | null>(null);
 
+  useEffect(() => {
+    (async () => {
+      const auth = await checkAuthStatus();
+      if (!auth.isLoggedIn) return setStage({ kind: 'signed_out' });
+      const me = await getClient().getMyProductReview(productId);
+      if (!me.eligible) return setStage({ kind: 'not_eligible', reason: me.reason });
+      if (me.myReview) {
+        setRating(me.myReview.rating);
+        setBody(me.myReview.body ?? '');
+        return setStage({ kind: 'edit', review: me.myReview });
+      }
+      setStage({ kind: 'submit' });
+    })();
+  }, [productId]);
+
+  if (stage.kind === 'loading') return <p>Loading\u2026</p>;
+  if (stage.kind === 'signed_out')
+    return <p><a href="/account/login">Sign in</a> to leave a review.</p>;
+  if (stage.kind === 'not_eligible')
+    return <p>Only customers who purchased this product can leave a review.</p>;
+
   async function submit(e: React.FormEvent) {
     e.preventDefault();
     setError(null);
+    const client = getClient();
+    const input = { rating, body: body || undefined };
     try {
-      await client.submitProductReview(productId, {
-        authorName: name,
-        authorEmail: email,
-        rating,
-        body: body || undefined,
-      });
+      if (stage.kind === 'edit') {
+        await client.updateMyProductReview(productId, input);
+      } else {
+        await client.submitProductReview(productId, input);
+      }
       window.location.reload();
     } catch (err: any) {
-      if (err?.status === 409) setError("You've already reviewed this product.");
+      if (err?.status === 403) setError('Only customers who purchased this product can leave a review.');
+      else if (err?.status === 409) setError('You already reviewed this product.');
       else if (err?.status === 429) setError('Too many submissions. Please wait a moment.');
-      else setError('Could not submit review. Please try again.');
+      else setError('Could not save your review. Please try again.');
     }
   }
 
+  async function remove() {
+    if (!confirm('Delete your review?')) return;
+    await getClient().deleteMyProductReview(productId);
+    window.location.reload();
+  }
+
   return (
     <form onSubmit={submit}>
-      <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Your name" required maxLength={100} />
-      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
-      <select value={rating} onChange={(e) => setRating(Number(e.target.value))}>
-        {[5,4,3,2,1].map(n => <option key={n} value={n}>{'\u2605'.repeat(n)}</option>)}
-      </select>
-      <textarea value={body} onChange={(e) => setBody(e.target.value)} maxLength={5000} placeholder="Tell us what you think (optional)" />
-      <button type="submit">Submit review</button>
+      <h3>{stage.kind === 'edit' ? 'Edit your review' : 'Write a review'}</h3>
+      <div>
+        {[1,2,3,4,5].map(n => (
+          <button type="button" key={n} onClick={() => setRating(n)}>
+            {n <= rating ? '\u2605' : '\u2606'}
+          </button>
+        ))}
+      </div>
+      <textarea value={body} onChange={(e) => setBody(e.target.value)} maxLength={5000} />
+      <button type="submit">{stage.kind === 'edit' ? 'Save changes' : 'Submit review'}</button>
+      {stage.kind === 'edit' && (
+        <button type="button" onClick={remove}>Delete review</button>
+      )}
       {error && <p role="alert">{error}</p>}
     </form>
   );
@@ -5191,7 +5854,7 @@ var RULES = {
     body: `- NEVER hardcode currency, locale, or language strings. Read them from \`get-store-info\` / \`get-store-capabilities\` and use the configured values.
 - NEVER format prices with \`toFixed(2)\` or custom logic. Use \`formatPrice()\` from the SDK \u2014 it honors the store's currency and locale.
 - When the store has i18n enabled (\`capabilities.store.i18n.enabled === true\`), you MUST call \`client.setLocale(locale)\` at app init and include a language switcher. All SDK reads will then return localized content automatically.
-- For RTL locales (\`he\`, \`ar\`), set the document direction to RTL. Do not manually reverse flex layouts \u2014 the platform's CSS reversal handles it.`
+- For RTL direction, do NOT maintain a local list of RTL locales. Call \`client.getStoreDirection(locale)\` \u2014 it returns \`'ltr' | 'rtl'\` for any BCP-47 tag (covers Arabic, Hebrew, Persian, Urdu, Yiddish, and any future RTL locales the platform adds). Set \`<html dir={...}>\` from this value. The platform's CSS reversal handles flex layouts \u2014 do not manually swap them.`
   },
   types: {
     title: "Type safety",
@@ -5239,6 +5902,7 @@ var GET_BUSINESS_FLOWS_SCHEMA = {
     "cart-persistence",
     "inventory-reservation",
     "product-customization",
+    "content-bootstrap",
     "all"
   ]).describe('Which flow to retrieve. Use "all" to get every flow.')
 };
@@ -5429,6 +6093,76 @@ Server-side guardrails that WILL reject bad requests (so validate client-side to
 - More than 10 uploads per IP per minute \u2192 429.
 
 Never render customization fields without also wiring the upload + metadata flow \u2014 a form that submits nothing is worse than no form at all.`
+  },
+  "content-bootstrap": {
+    title: "Content Bootstrap \u2014 site chrome & static content",
+    body: `Every Brainerce storefront should render merchant-defined site chrome (header, footer, announcements, FAQ, static pages) from the Content API. The merchant edits these in the Brainerce dashboard; storefronts pick up changes within ~5 minutes (public reads carry \`Cache-Control: public, max-age=300, stale-while-revalidate=60\`).
+
+1. **Fetch chrome at the root layout** (server component if Next.js). All three return \`null\` on 404 \u2014 render hard-coded fallbacks so the page never crashes when the merchant hasn't seeded yet.
+   \`\`\`ts
+   const [header, footer, announcements] = await Promise.all([
+     client.content.header.get('main', locale),
+     client.content.footer.get('main', locale),
+     client.content.announcement.list(locale),
+   ]);
+   \`\`\`
+
+2. **FAQ \u2014 fetch lazily on the FAQ page.** Default key is \`'main'\`; pass a topical key (\`'shipping'\`, \`'returns'\`) for sub-FAQs.
+   \`\`\`ts
+   const faq = await client.content.faq.get('main', locale);
+   if (faq) {
+     faq.data.items.forEach(({ question, answer }) => {
+       // sanitize(answer) \u2014 see step 4
+     });
+   }
+   \`\`\`
+
+3. **Static pages \u2014 catch-all route by slug:**
+   \`\`\`tsx
+   // app/[slug]/page.tsx
+   export default async function Page({ params }) {
+     const page = await client.content.page.getBySlug(params.slug, locale);
+     if (!page) notFound();
+     return (
+       <article dangerouslySetInnerHTML={{ __html: sanitize(page.data.html) }} />
+     );
+   }
+   \`\`\`
+
+4. **SECURITY \u2014 sanitize HTML before rendering.** \`FAQ.items[i].answer\`, \`PAGE.html\`, and \`RICH_TEXT.html\` are merchant-authored HTML. The server does NOT pre-sanitize because some merchants embed iframes (e.g. YouTube). Always sanitize at the edge of your render:
+   \`\`\`ts
+   import DOMPurify from 'isomorphic-dompurify';
+   const safe = DOMPurify.sanitize(rawHtml);
+   <div dangerouslySetInnerHTML={{ __html: safe }} />;
+   \`\`\`
+   Skipping this is XSS.
+
+5. **Announcements \u2014 multiple may be active; filter by date client-side:**
+   \`\`\`ts
+   const now = Date.now();
+   const visible = announcements.filter((a) => {
+     const startOk = !a.data.startsAt || new Date(a.data.startsAt).getTime() <= now;
+     const endOk = !a.data.endsAt || new Date(a.data.endsAt).getTime() >= now;
+     return startOk && endOk;
+   });
+   \`\`\`
+
+6. **RTL direction \u2014 call \`client.getStoreDirection(locale)\`:**
+   \`\`\`tsx
+   const dir = client.getStoreDirection(locale);
+   <html lang={locale} dir={dir}>...</html>
+   \`\`\`
+   Do NOT maintain a local RTL locale set \u2014 the SDK helper covers Arabic / Hebrew / Persian / Urdu / Yiddish today and picks up any future RTL locale automatically.
+
+7. **Custom fields \u2014 every Content row has free-form \`customFields: Record<string, string>\`.** Read keys the merchant told you to expect:
+   \`\`\`ts
+   const faq = await client.content.faq.get('shipping');
+   <a href={\`mailto:\${faq.customFields.helpEmail}\`}>Need help?</a>
+   \`\`\`
+
+8. **Cache:** public reads carry \`Cache-Control: public, max-age=300, stale-while-revalidate=60\`. Don't add extra client-side caching beyond Next.js's default fetch cache \u2014 merchants expect their edits to appear within ~5 minutes.
+
+**Translations.** All public reads accept a \`locale\` argument; the server resolves \`translations[locale]\` server-side. Empty / missing overlays fall through to the default-locale value. The storefront does NOT need to do its own per-field overlay \u2014 call with the active locale and render what comes back.`
   }
 };
 var FLOW_ORDER = [
@@ -5440,7 +6174,8 @@ var FLOW_ORDER = [
   "order-confirmation",
   "cart-persistence",
   "inventory-reservation",
-  "product-customization"
+  "product-customization",
+  "content-bootstrap"
 ];
 async function handleGetBusinessFlows(args) {
   const header = "# Brainerce Business Flows\n\nThese sequences are framework-neutral and non-negotiable. Your framework and file layout are your choice \u2014 the order of SDK calls and the error handling is not.";
@@ -5509,9 +6244,9 @@ var FEATURES = [
   },
   {
     id: "product-reviews",
-    title: "Display + collect product reviews with stars + JSON-LD",
-    description: 'On the PDP show a Reviews section: list of customer reviews with star rating, author name, verified-purchase badge, body, and date. Include a submit form (name + email + 1-5 stars + optional body). On PLP cards show \u2605 avgRating and (reviewCount). Emit Product JSON-LD with aggregateRating ONLY when product.reviewCount > 0 \u2014 this is what unlocks the star rich snippet in Google. Reviews publish immediately; the merchant moderates from the admin surface. Rate-limited to 3 submits / 60s / IP. Show a friendly "you already reviewed this" message on 409.',
-    sdk: "client.listProductReviews(productId), client.submitProductReview(productId, { authorName, authorEmail, rating, body }). Product.avgRating + Product.reviewCount are denormalized rollups returned on every product fetch.",
+    title: "Display + collect product reviews (purchaser-only) with stars + JSON-LD",
+    description: 'On the PDP show a Reviews section: list of customer reviews with star rating, author name (from customer profile), verified-purchase badge, body, and date \u2014 public, no login needed. Below the list, a form that adapts to the current customer: signed-in + purchased + no review yet \u2192 submit form (rating 1-5 + optional body, no name/email \u2014 those are derived from the customer profile); signed-in + purchased + already has review \u2192 edit form prefilled with rating/body plus a delete button; signed-in but did NOT purchase \u2192 "only customers who purchased this product can leave a review"; not signed in \u2192 sign-in CTA. Eligibility: physical products require an order in SHIPPED+; downloadable products additionally accept PAID/PROCESSING. On PLP cards show \u2605 avgRating and (reviewCount). Emit Product JSON-LD with aggregateRating ONLY when product.reviewCount > 0 \u2014 this is what unlocks the star rich snippet in Google. Reviews publish immediately; merchants moderate (hide/show) from the admin surface. Rate-limited 3 submits / 60s / IP.',
+    sdk: "client.listProductReviews(productId) for the public list; client.getMyProductReview(productId) for the form-state decision; client.submitProductReview / updateMyProductReview / deleteMyProductReview for the three customer actions. All four customer methods require setCustomerToken(...) after login. Product.avgRating + Product.reviewCount are denormalized rollups returned on every product fetch.",
     mandatory: "mandatory"
   },
   {
@@ -5652,11 +6387,57 @@ var FEATURES = [
   {
     id: "i18n",
     title: "Serve multiple languages with a language switcher",
-    description: "When i18n is enabled, the experience routes by locale, sets the SDK locale (client.setLocale), includes a language switcher in the header, and renders RTL locales (he, ar) with the correct document direction.",
-    sdk: "client.setLocale(locale). Read supported locales from get-store-capabilities.store.i18n.",
+    description: "When i18n is enabled, the experience routes by locale, sets the SDK locale (client.setLocale), includes a language switcher in the header, and renders the correct document direction by reading client.getStoreDirection(locale) \u2014 do not hardcode an RTL locale set.",
+    sdk: "client.setLocale(locale). client.getStoreDirection(locale) for <html dir>. Read supported locales from get-store-capabilities.store.i18n.",
     mandatory: "conditional",
     capabilityFlag: "i18n",
     whenDisabledNote: "This store is single-language. Do not build the language switcher."
+  },
+  {
+    id: "site-header",
+    title: "Site header from merchant content (logo + nav + CTA)",
+    description: 'Fetch client.content.header.get("main", locale) in the root layout. Returns null when the merchant has not seeded yet \u2014 render a hard-coded fallback so the page never crashes. Renders header.data.logo, header.data.navItems[], header.data.cta if present.',
+    sdk: 'client.content.header.get("main", locale)',
+    flowRef: "content-bootstrap",
+    mandatory: "mandatory"
+  },
+  {
+    id: "site-footer",
+    title: "Site footer from merchant content (columns + social + copyright)",
+    description: 'Fetch client.content.footer.get("main", locale) in the root layout. Returns null when unseeded \u2014 render a hard-coded fallback. Render footer.data.columns[].links, footer.data.social[], footer.data.copyright.',
+    sdk: 'client.content.footer.get("main", locale)',
+    flowRef: "content-bootstrap",
+    mandatory: "mandatory"
+  },
+  {
+    id: "announcement-bar",
+    title: "Announcement bar at the top of every page",
+    description: "Fetch client.content.announcement.list(locale) in the root layout. Filter by data.startsAt / data.endsAt client-side. Render a dismissible bar when data.dismissible=true. Build the UI anyway \u2014 it auto-hides when no announcements exist.",
+    sdk: "client.content.announcement.list(locale)",
+    flowRef: "content-bootstrap",
+    mandatory: "conditional",
+    capabilityFlag: "hasContent",
+    whenDisabledNote: "Store has no published Content rows yet. Build the announcement bar anyway \u2014 it auto-hides on empty."
+  },
+  {
+    id: "faq-page",
+    title: "FAQ page rendered from merchant content",
+    description: 'Build /faq as an accordion fed by client.content.faq.get("main", locale). For topical FAQs, use a key parameter (shipping, returns, ...). Always sanitize answer HTML before injecting via dangerouslySetInnerHTML. Build the page anyway \u2014 it auto-hides or 404s when no FAQ rows exist.',
+    sdk: 'client.content.faq.get("main", locale), client.content.faq.list(locale)',
+    flowRef: "content-bootstrap",
+    mandatory: "conditional",
+    capabilityFlag: "hasContent",
+    whenDisabledNote: "No FAQ content yet. Build /faq anyway \u2014 it auto-hides on empty."
+  },
+  {
+    id: "static-pages",
+    title: "Static pages from merchant content (About, Terms, Privacy, \u2026)",
+    description: "Mount a catch-all app/[slug]/page.tsx route. Inside, call client.content.page.getBySlug(params.slug, locale). On null \u2192 notFound(). On hit, sanitize page.data.html before injecting via dangerouslySetInnerHTML. Generate <Metadata> from page.data.seo. Build the route anyway \u2014 it 404s on unknown slugs.",
+    sdk: "client.content.page.getBySlug(slug, locale), client.content.page.list(locale)",
+    flowRef: "content-bootstrap",
+    mandatory: "conditional",
+    capabilityFlag: "hasContent",
+    whenDisabledNote: "No static pages yet. Build the catch-all route anyway \u2014 it 404s on unknown slugs."
   }
 ];
 function isFeatureActive(feature, caps) {
@@ -5707,6 +6488,7 @@ function renderCapabilitiesSummary(caps) {
   );
   lines.push(`- Downloadable products: ${caps.features.hasDownloadableProducts ? "yes" : "no"}`);
   lines.push(`- Checkout custom fields: ${caps.features.hasCheckoutCustomFields ? "yes" : "no"}`);
+  lines.push(`- Content (FAQ/footer/header/announcements/pages): ${caps.features.hasContent ? "seeded" : "none \u2014 build chrome UI with fallbacks"}`);
   lines.push(
     `- Email verification: ${caps.connection.requireEmailVerification ? "required" : "not required (still build the verify-email flow)"}`
   );