@brainerce/mcp-server 3.1.0 → 3.2.0

package/dist/bin/stdio.js

@@ -65,7 +65,7 @@ function getTypeQuickReference() {
 | OAuth | \`provider.name\` | \`provider\` | it IS the string: \`'GOOGLE' | 'FACEBOOK' | 'GITHUB'\` |
 | OAuth | \`oauth.url\` | \`oauth.authorizationUrl\` | |
 | Description | \`getDescriptionContent()\` | \`{ html } | { text } | null\` | check \`'html' in content\` before use |
-| \`smartGetCart()\` | always use \`.id\` | check \`'id' in cart\` | returns \`Cart | LocalCart\` |
+| \`smartGetCart()\` | N/A | \`cart.id\` | returns \`CartWithIncludes\` (extends \`Cart\`); pass \`{ include: [...] }\` for extras |
 | \`startGuestCheckout()\` | always use \`.checkoutId\` | check \`result.tracked\` | discriminated union |
 
 **Rules:**
@@ -73,8 +73,8 @@ function getTypeQuickReference() {
 - CartItem/CheckoutLineItem = **NESTED** (\`item.product.name\`, \`item.unitPrice\`)
 - OrderItem = **FLAT** (\`item.name\`, \`item.price\`, \`item.totalPrice\`, \`item.image\`)
 - Cart has NO \`.total\` \u2014 use \`getCartTotals(cart)\`
-- \`getCartTotals()\` only works with server \`Cart\`, NOT \`LocalCart\`
-- \`smartGetCart()\` returns \`Cart | LocalCart\` \u2014 check \`'id' in cart\` before using Cart fields
+- \`getCartTotals()\` works with server \`Cart\` (all carts are server-side now)
+- \`smartGetCart()\` returns \`CartWithIncludes\` \u2014 always a server cart; pass \`{ include: ['recommendations', 'upgrades', 'bundles'] }\` for extras
 - \`startGuestCheckout()\` returns discriminated union \u2014 check \`result.tracked\` before \`.checkoutId\`
 - \`SetShippingAddressDto.email\` is **required** \u2014 always include email
 
@@ -202,7 +202,7 @@ async function startCheckout() {
 6. Select shipping method \u2192 \`selectShippingMethod()\`
 6b. (Optional) Set checkout custom fields \u2192 \`setCheckoutCustomFields()\` \u2014 surcharges auto-calculated
 7. Create payment intent \u2192 \`createPaymentIntent()\` \u2192 returns \`{ clientSecret, provider }\`
-8. Branch on \`provider\`: \`'stripe'\` \u2192 Stripe Elements, \`'grow'\` \u2192 iframe, \`'paypal'\` \u2192 PayPal Buttons
+8. Branch on the **\`clientSdk.renderType\`** returned by \`createPaymentIntent()\` \u2014 NEVER hard-code by provider name. Values: \`'sdk-widget'\` (Stripe, PayPal, Grow), \`'iframe'\` (Cardcom hosted or Brainerce-hosted embed \u2014 detect via URL path), \`'redirect'\`, \`'sandbox'\`, \`'embedded-fields'\` (reserved).
 9. **Order is created AUTOMATICALLY after payment succeeds (via webhook) \u2014 for ALL providers!**
 
 ### Checkout Page Component
@@ -305,8 +305,8 @@ function CheckoutPage() {
       </div>
     );
   }
-  if (paymentData.provider === 'grow') {
-    return <GrowPaymentForm paymentUrl={paymentData.clientSecret} checkoutId={paymentData.checkoutId} />;
+  if (paymentData.clientSdk?.renderType === 'iframe') {
+    return <PaymentIframe clientSecret={paymentData.clientSecret} checkoutId={paymentData.checkoutId} />;
   }
   if (paymentData.provider === 'paypal' && paypalClientId) {
     return <PayPalPaymentForm clientId={paypalClientId} orderId={paymentData.clientSecret} checkoutId={paymentData.checkoutId} />;
@@ -362,26 +362,82 @@ function StripePaymentForm({ checkoutId }: { checkoutId: string }) {
 }
 \`\`\`
 
-### Grow Payment Form (Israeli stores \u2014 iframe based, no SDK needed)
+### Iframe-Based Providers (Cardcom, legacy Grow, etc.)
+
+When \`clientSdk.renderType === 'iframe'\`, the payment intent returns a \`clientSecret\` which is a URL to load in an iframe. There are TWO flavors of iframe rendering you must handle:
+
+**Flavor A \u2014 Brainerce-hosted embed (URL path contains \`/embed/\`):** The iframe loads a Brainerce-branded compact form (e.g. Cardcom OpenFields). Render it **INLINE** inside your checkout flow (next to the order summary) \u2014 NO modal, NO dark overlay. The embed page posts messages to resize itself and to request top-level navigation (e.g. for Bit express-pay buttons).
+
+**Flavor B \u2014 Provider-hosted page (any other URL):** The iframe loads a full provider-branded page with its own header/chrome. Render inside a **modal overlay** so it doesn't fight your checkout layout.
+
+Detect flavor by URL path \u2014 works across localhost/staging/prod without a domain list:
 
 \`\`\`typescript
-function GrowPaymentForm({ paymentUrl, checkoutId }: { paymentUrl: string; checkoutId: string }) {
-  const [iframeLoaded, setIframeLoaded] = useState(false);
+function PaymentIframe({ clientSecret, checkoutId }: { clientSecret: string; checkoutId: string }) {
+  const [height, setHeight] = useState(540); // default before resize message arrives
+  const isBrainerceEmbed = (() => {
+    try { return new URL(clientSecret).pathname.includes('/embed/'); }
+    catch { return false; }
+  })();
+
+  useEffect(() => {
+    function handleMessage(e: MessageEvent) {
+      const data = e.data as { type?: string; height?: number; url?: string };
+      if (data?.type === 'brainerce:resize' && typeof data.height === 'number') {
+        setHeight(data.height);
+      }
+      if (data?.type === 'brainerce:redirect' && typeof data.url === 'string') {
+        // Top-level navigation (e.g. Bit). ALWAYS validate against an allowlist
+        // before navigating \u2014 never trust the URL blindly.
+        if (isTrustedPaymentUrl(data.url)) { window.top!.location.href = data.url; }
+      }
+      if (data?.type === 'brainerce:payment-complete') {
+        // Payment done \u2014 redirect to confirmation page which verifies server-side
+        window.location.href = \`/order-confirmation?checkout_id=\${checkoutId}\`;
+      }
+    }
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, [checkoutId]);
+
+  if (isBrainerceEmbed) {
+    // Inline: part of the checkout flow, no overlay
+    return (
+      <div className="w-full">
+        <iframe
+          src={clientSecret}
+          style={{ width: '100%', height, border: 0, transition: 'height 0.2s ease-out' }}
+          title="Payment"
+          allow="payment"
+        />
+      </div>
+    );
+  }
+
+  // Provider-hosted page: modal overlay
   return (
-    <div className="w-full">
-      {!iframeLoaded && <div className="flex items-center justify-center py-12"><span>Loading payment form...</span></div>}
-      <iframe
-        src={paymentUrl}
-        onLoad={() => setIframeLoaded(true)}
-        style={{ width: '100%', minHeight: '600px', border: 'none', display: iframeLoaded ? 'block' : 'none' }}
-        allow="payment"
-      />
-      <p className="text-center text-sm text-gray-500 mt-4">
-        Having trouble? <a href={paymentUrl} target="_blank" rel="noopener noreferrer" className="text-blue-600 underline">Open payment in new tab</a>
-      </p>
+    <div className="fixed inset-0 z-50 flex items-start justify-center bg-black/50 py-6 overflow-y-auto">
+      <div className="bg-white rounded-2xl shadow-2xl w-full max-w-4xl mx-4">
+        <iframe
+          src={clientSecret}
+          style={{ width: '100%', height: '90vh', minHeight: 700, border: 0 }}
+          title="Payment"
+          allow="payment"
+        />
+      </div>
     </div>
   );
 }
+
+// Allowlist of origins you trust for top-level payment redirects.
+function isTrustedPaymentUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') return false;
+    // Add your provider hostnames here. Example: Cardcom for Bit express-pay.
+    return u.hostname === 'cardcom.solutions' || u.hostname.endsWith('.cardcom.solutions');
+  } catch { return false; }
+}
 \`\`\`
 
 ### PayPal Payment Form
@@ -651,12 +707,23 @@ const growProvider = providers.find(p => p.provider === 'grow');
 const paypalProvider = providers.find(p => p.provider === 'paypal');
 \`\`\`
 
-Each provider has: \`id\`, \`provider\` ('stripe'|'grow'|'paypal'|'sandbox'), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
+Each provider has: \`id\`, \`provider\` (flexible string \u2014 \`'stripe'\`, \`'grow'\`, \`'paypal'\`, \`'cardcom'\`, \`'sandbox'\`, and future providers), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
+
+The payment intent returned from \`createPaymentIntent()\` includes a \`clientSdk\` object whose \`renderType\` tells you exactly how to render \u2014 **branch on THAT, not on the provider name**:
 
+- \`renderType: 'sdk-widget'\` \u2014 load \`clientSdk.scriptUrl\`, mount into \`<div id={clientSdk.containerId}>\`. Used by Stripe, PayPal, Grow. The SDK paints its own form in your DOM.
+- \`renderType: 'iframe'\` \u2014 render \`<iframe src={clientSecret}>\`. Two flavors detected by URL path:
+  - Path contains \`/embed/\` \u2192 Brainerce-hosted embed. Render **INLINE** (no modal). Listen for \`brainerce:resize\` / \`brainerce:redirect\` postMessages. Used by Cardcom (embedded mode).
+  - Any other URL \u2192 provider-hosted page. Render inside a **modal**. Used by Cardcom (hosted mode), legacy Grow iframe.
+- \`renderType: 'redirect'\` \u2014 \`window.location.href = URL\`. Customer completes payment off-site and returns via SuccessRedirectUrl.
+- \`renderType: 'sandbox'\` \u2014 show a "Complete Test Order" button; call \`completeGuestCheckout(checkoutId)\`. Orders are \`isTestOrder: true\`. Appears when \`sandboxPaymentsEnabled\` is true.
+- \`renderType: 'embedded-fields'\` \u2014 reserved for future Stripe-Elements-style pattern (PCI micro-iframes for card/CVV mounted directly into the merchant form). **No provider ships this today** \u2014 handle via a "not supported yet" fallback.
+
+Provider-specific install notes:
 - **Stripe:** \`npm install @stripe/stripe-js @stripe/react-stripe-js\` \u2014 \`loadStripe(publicKey, { stripeAccount })\`
-- **Grow:** No SDK \u2014 uses iframe with payment URL. Supports credit cards, Bit, Apple Pay, Google Pay.
 - **PayPal:** \`npm install @paypal/react-paypal-js\` \u2014 \`PayPalScriptProvider\` + \`PayPalButtons\`
-- **Sandbox:** No SDK needed \u2014 when \`sandboxPaymentsEnabled\` is true, \`getPaymentProviders()\` includes a sandbox provider with \`renderType: 'sandbox'\`. Show a "Complete Test Order" button. Call \`completeGuestCheckout(checkoutId)\` to finalize. Orders are marked \`isTestOrder: true\`.`;
+- **Grow:** No SDK needed \u2014 JS SDK loaded via \`clientSdk.scriptUrl\`. Supports credit cards, Bit, Apple Pay, Google Pay.
+- **Cardcom:** No SDK needed \u2014 rendering driven by \`renderType: 'iframe'\` + the inline/modal branch above. Supports credit cards, Bit (when terminal provisions it), installments, 3D Secure.`;
 }
 function getProductsSection(_currency) {
   return `## Products & Variants
@@ -687,10 +754,12 @@ When \`storeInfo.i18n.enabled\` is true, call \`client.setLocale(locale)\` once
 \`{ locale }\` params needed. Translated fields include: \`name\`,
 \`description\`, \`slug\`, \`seoTitle\`, \`seoDescription\`, plus
 \`categories[].name\`, \`brands[].name\`, \`tags[].name\`, \`variants[].name\`,
-\`productAttributeOptions[].attribute.name\`/\`attributeOption.name\`, and
-\`metafields[].value\`. No client-side overlay. See the full \`i18n\` section
-(\`get-sdk-docs\` topic \`i18n\`) for the \`[locale]\` route pattern, SDK setup,
-and the brand/tag badge examples.
+\`variant.attributes\` keys and values (so \`getVariantOptions()\` returns
+translated attribute/option names), \`productAttributeOptions[].attribute.name\`/
+\`attributeOption.name\`, \`metafields[].value\`, cart item product/variant names,
+and recommendation/bundle/bump product names. No client-side overlay. See the
+full \`i18n\` section (\`get-sdk-docs\` topic \`i18n\`) for the \`[locale]\` route
+pattern, SDK setup, and the brand/tag badge examples.
 
 ### Price Display (Use SDK Helper!)
 
@@ -827,6 +896,8 @@ const material = getProductMetafieldValue(product, 'material');
 
 Some products allow customers to provide input at purchase time (e.g., text on a cake, upload a logo). Check \`product.customizationFields\` and render input fields accordingly.
 
+Merchants can also flag a \`MetafieldDefinition\` as \`appliesToAllProducts: true\` \u2014 those fields are folded into every product's \`customizationFields\` array automatically by the backend. Client code does not need to merge or union anything: always render exactly what's in \`product.customizationFields\`.
+
 \`\`\`typescript
 import { getProductCustomizationFields } from 'brainerce';
 import type { ProductCustomizationField } from 'brainerce';
@@ -885,7 +956,7 @@ function getCartSection(_currency) {
 ### Smart Cart Methods (RECOMMENDED)
 
 \`\`\`typescript
-const cart = await client.smartGetCart();  // Returns Cart | LocalCart
+const cart = await client.smartGetCart();  // Returns CartWithIncludes (extends Cart)
 await client.smartAddToCart({
   productId: product.id,
   variantId: selectedVariant?.id,
@@ -1016,7 +1087,19 @@ const recs = (product as any).recommendations as ProductRecommendationsResponse
 
 ### Cart Page Features
 
-**Cross-sell recommendations** (existing products the customer might also want):
+**Consolidated include** (fetch recommendations, upgrades, and bundles in one request):
+\`\`\`typescript
+import type { CartWithIncludes } from 'brainerce';
+const cart = await client.getCart(cartId, {
+  include: ['recommendations', 'upgrades', 'bundles'],
+});
+// cart.recommendations \u2014 cross-sell recommendations
+// cart.upgrades \u2014 upgrade suggestions keyed by source product ID
+// cart.bundles \u2014 bundle offers
+// Also works with smartGetCart: client.smartGetCart({ include: ['recommendations', 'upgrades', 'bundles'] })
+\`\`\`
+
+**Cross-sell recommendations** (or fetch individually for targeted refresh):
 \`\`\`typescript
 import type { CartRecommendationsResponse } from 'brainerce';
 const cartRecs = await client.getCartRecommendations(cartId, 4);
@@ -1108,6 +1191,110 @@ Always check the flag before rendering: \`if (storeInfo?.upsell?.featureName !==
 ProductRecommendation: \`id\`, \`name\`, \`slug\`, \`basePrice\`, \`salePrice\`, \`images\`, \`type\`, \`inventory\`, \`relationType\`, \`variants?\` (when variant selection needed).
 OrderBump/CartBundleOffer: includes \`requiresVariantSelection\` (boolean) and \`lockedVariant?\` (\`{ id, name, attributes }\`).`;
 }
+function getProductCustomizationFieldsSection() {
+  return `## Product Customization Fields (buyer input on product page)
+
+Some products let the buyer personalize them before adding to cart \u2014 engraving text, a photo upload, a color pick, a multi-select add-on list. The merchant defines these fields in the Brainerce dashboard; the storefront renders them, collects values, uploads any images, and passes everything as \`metadata\` on add-to-cart.
+
+### Where the fields come from
+
+They arrive **embedded on the product response** \u2014 no extra API call:
+
+\`\`\`typescript
+import type { Product, ProductCustomizationField, MetafieldType } from 'brainerce';
+
+const product = await client.getProductBySlug(slug);
+const fields: ProductCustomizationField[] = product.customizationFields ?? [];
+// fields is sorted by position. If empty, render the product page normally.
+\`\`\`
+
+Each field has:
+\`\`\`typescript
+{
+  definitionId: string;
+  key: string;              // stable identifier \u2014 use this as the metadata key
+  name: string;             // display label (may be localized)
+  description?: string | null;
+  type: MetafieldType;      // 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' |
+                            // 'JSON' | 'URL' | 'COLOR' | 'DIMENSION' | 'WEIGHT' |
+                            // 'IMAGE' | 'GALLERY' | 'SELECT' | 'MULTI_SELECT'
+  required: boolean;
+  minLength?: number | null;       // chars for TEXT/TEXTAREA; array size for MULTI_SELECT
+  maxLength?: number | null;
+  minValue?: number | null;        // NUMBER / DIMENSION / WEIGHT
+  maxValue?: number | null;
+  enumValues?: string[];           // required for SELECT / MULTI_SELECT
+  defaultValue?: string | null;
+  position: number;
+}
+\`\`\`
+
+### Render one control per type
+
+| type            | Render as                                                  | Collected value              |
+| --------------- | ---------------------------------------------------------- | ---------------------------- |
+| \`TEXT\`        | \`<input type="text">\`                                    | \`string\`                   |
+| \`TEXTAREA\`    | \`<textarea>\`                                             | \`string\`                   |
+| \`NUMBER\`      | \`<input type="number">\`                                  | \`number\`                   |
+| \`BOOLEAN\`     | checkbox / switch                                          | \`boolean\`                  |
+| \`DATE\`        | \`<input type="date">\`                                    | \`string\` (YYYY-MM-DD)      |
+| \`DATETIME\`    | \`<input type="datetime-local">\`                          | \`string\` (ISO 8601)        |
+| \`URL\`         | \`<input type="url">\`                                     | \`string\`                   |
+| \`COLOR\`       | \`<input type="color">\`                                   | \`string\` (#RRGGBB)         |
+| \`SELECT\`      | \`<select>\` or radio group (use \`enumValues\`)           | \`string\` (in enumValues)   |
+| \`MULTI_SELECT\`| checkbox group (use \`enumValues\`)                        | \`string[]\` (every in enum) |
+| \`IMAGE\`       | file input + upload via \`uploadCustomizationFile\`        | \`string\` (URL)             |
+| \`GALLERY\`     | multi-file input + one upload per file                     | \`string[]\` (URLs)          |
+| \`JSON\`        | textarea; validate is parseable                            | \`string\` (JSON)            |
+
+### Upload buyer-submitted images
+
+\`IMAGE\` and \`GALLERY\` require uploading before add-to-cart:
+
+\`\`\`typescript
+const { url } = await client.uploadCustomizationFile(file);
+// Server rules: image/* only, max 5 MB, 10 uploads/min per IP.
+// Files are retained for at least 7 days; after that, if the cart never
+// became an order, they are automatically deleted.
+\`\`\`
+
+### Add to cart with customization metadata
+
+\`\`\`typescript
+// Collect values keyed by field.key \u2014 NOT by field.name or field.definitionId.
+const metadata: Record<string, unknown> = {
+  engraving_text: 'Happy Birthday!',       // TEXT
+  frame_color: 'Gold',                     // SELECT (must be in enumValues)
+  upload_photo: url,                       // IMAGE (URL from uploadCustomizationFile)
+  addons: ['Gift wrap'],                   // MULTI_SELECT (always an array)
+};
+
+await client.addToCart(cart.id, {
+  productId: product.id,
+  quantity: 1,
+  metadata,
+});
+\`\`\`
+
+Server validation (rejected with HTTP 400 on failure):
+- \`required: true\` \u2192 must be present and non-empty
+- \`TEXT\` / \`TEXTAREA\` \u2192 string; \`minLength\` / \`maxLength\` enforced as character count
+- \`NUMBER\` \u2192 \`minValue\` / \`maxValue\` enforced
+- \`SELECT\` \u2192 value must be one of \`enumValues\`
+- \`MULTI_SELECT\` \u2192 array; each element in \`enumValues\`; duplicates removed; \`minLength\` / \`maxLength\` enforced as array size
+- \`IMAGE\` / \`GALLERY\` \u2192 URL(s) must be from \`/customization-upload\` on this store
+
+### Order snapshot
+
+When the order is created, each line's customization values are snapshotted onto the order item with \`{ key, name, type, value }\` \u2014 so later edits to the field definition don't orphan old orders. The merchant dashboard shows the values on the order detail page.
+
+### Common mistakes
+
+- Passing values keyed by \`field.name\` instead of \`field.key\` \u2192 silently ignored (unknown key)
+- Sending a \`MULTI_SELECT\` as a string instead of \`string[]\` \u2192 HTTP 400
+- Using a raw external URL (not from \`/customization-upload\`) for \`IMAGE\` / \`GALLERY\` \u2192 HTTP 400
+- Assuming \`enumValues\` is present for all types \u2014 only \`SELECT\` / \`MULTI_SELECT\` require it`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -1364,7 +1551,50 @@ const { data: orders } = await client.getMyOrders({ page: 1, limit: 10 }); // Re
 // \u274C WRONG \u2014 these methods don't exist!
 client.getCustomerProfile();
 client.getCustomerOrders();
-\`\`\``;
+\`\`\`
+
+### Order history should show more than just totals
+
+A useful order card includes ALL of the following when the data is present. Each section is conditional \u2014 render nothing if the field is empty.
+
+| Section | Source field | Notes |
+|---|---|---|
+| Header (number, status badge, date, total) | \`order.orderNumber\`, \`order.status\`, \`order.createdAt\`, \`order.totalAmount\` | Always present. |
+| Line items | \`order.items[]\` | Render image, name, qty, price. |
+| **Per-item customizations** | \`order.items[i].customizations\` | Map of { label, value, type }. Render by \`type\` \u2014 see table below. |
+| **Status timeline** | \`order.statusHistory\` | \`OrderStatusChange[]\`: \`{ status, at, note? }\`. Render as a vertical list. |
+| **Shipping address** | \`order.shippingAddress\` | Standard \`OrderAddress\` shape. |
+| **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
+| **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
+| Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
+| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. |
+
+#### Rendering \`order.items[i].customizations\` by type
+
+The map key is the metafield slug; the value is \`{ label, value, type }\`. Dispatch by \`type\`:
+
+| Type | Value | Render |
+|---|---|---|
+| \`TEXT\`, \`TEXTAREA\`, \`URL\`, \`NUMBER\`, \`SELECT\` | string | Plain text (\`URL\` \u2192 anchor). |
+| \`BOOLEAN\` | \`"yes"\` / \`"no"\` | \u2713 / \u2717 |
+| \`MULTI_SELECT\` | \`string[]\` | Comma-separated. |
+| \`IMAGE\` | asset URL (string) | Thumbnail linking to full-size asset. |
+| \`GALLERY\` | \`string[]\` of URLs | Grid of thumbnails. |
+| \`COLOR\` | hex string | Swatch + hex text. |
+| \`DATE\` | ISO-8601 | \`toLocaleDateString()\` |
+| \`DATETIME\` | ISO-8601 | \`toLocaleString()\` |
+| Unknown | any | Plain text (defensive default). |
+
+The storefront scaffolded by \`create-brainerce-store\` already implements this. See \`src/components/account/order-history.tsx\` + the sibling \`order-customizations.tsx\`, \`order-status-timeline.tsx\`, \`order-shipping-block.tsx\`, \`order-payment-block.tsx\` \u2014 mirror that structure.
+
+### Do NOT render
+
+These fields are NOT returned to buyers by \`/customers/me/orders\`. If you see them in older examples, ignore them \u2014 they are for merchant/admin views only.
+
+- \`order.accountId\`, \`order.storeId\`, \`order.customerId\` (already known on the request)
+- \`order.notes\` (internal merchant notes)
+- \`order.customFieldValues\` (order-level checkout fields \u2014 merchant concept; buyers see \`items[i].customizations\`)
+- \`order.appliedSurcharges\`, \`order.surchargeAmount\`, \`order.appliedRuleIds\`, \`order.downloadMeta\`, \`order.pickupLocationData\``;
 }
 function getOrderConfirmationSection() {
   return `## Order Confirmation Page (/order-confirmation) \u2014 REQUIRED!
@@ -1534,7 +1764,8 @@ overlay needed:
 - \`brands[].name\`
 - \`tags[].name\`
 - \`variants[].name\`
-- \`productAttributeOptions[].attribute.name\`, \`attributeOption.name\`/\`value\`
+- \`variant.attributes\` keys and values \u2014 \`getVariantOptions(variant)\` returns translated attribute names and option values automatically
+- \`productAttributeOptions[].attribute.name\`, \`attributeOption.name\`
 - \`metafields[].value\`
 
 **Taxonomy (\`getCategories\`, \`getBrands\`, \`getTags\`):**
@@ -1543,6 +1774,10 @@ overlay needed:
 **Cart:**
 - \`items[].product.name\`, \`items[].variant.name\`
 
+**Bundles & Order Bumps:**
+- \`bundleProduct.name\`, \`bundleProduct.slug\`, \`bumpProduct.name\`, \`bumpProduct.slug\`
+- Variant names inside bundles/bumps
+
 **Checkout:**
 - Line items: \`items[].product.name\`, \`items[].variant.name\`
 - Discount banners, nudges, badges
@@ -1653,6 +1888,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getDiscountsSection();
     case "recommendations":
       return getRecommendationsSection();
+    case "product-customization-fields":
+      return getProductCustomizationFieldsSection();
     case "tax":
       return getTaxDisplaySection(cur);
     case "i18n":
@@ -1727,6 +1964,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductCustomizationFieldsSection(),
+        "",
+        "---",
+        "",
         getTaxDisplaySection(cur),
         "",
         "---",
@@ -1738,7 +1979,7 @@ function getSectionByTopic(topic, connectionId, currency) {
         getAdminApiSection()
       ].join("\n");
     default:
-      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, checkout-custom-fields, payment, auth, order-confirmation, inventory, discounts, recommendations, tax, i18n, critical-rules, type-reference, admin, 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, all`;
   }
 }
 
@@ -1758,6 +1999,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "product-customization-fields",
     "tax",
     "critical-rules",
     "type-reference",
@@ -1802,6 +2044,7 @@ interface Product {
   brands?: Array<{ id: string; name: string }>;
   tags?: string[];
   metafields?: ProductMetafield[];
+  customizationFields?: ProductCustomizationField[];  // Buyer input fields \u2014 render on PDP, send values in cart metadata. Account-wide fields (MetafieldDefinition.appliesToAllProducts=true) are folded in here automatically; no client-side merging.
   productAttributeOptions?: Array<{
     id: string;
     attributeId: string;
@@ -1860,6 +2103,32 @@ interface ProductMetafield {
   variantId?: string | null;
 }
 
+// Metafield type enum \u2014 used by ProductCustomizationField.type
+type MetafieldType =
+  | 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME'
+  | 'URL' | 'COLOR' | 'DIMENSION' | 'WEIGHT' | 'JSON'
+  | 'IMAGE' | 'GALLERY'
+  | 'SELECT' | 'MULTI_SELECT';
+
+// Customer-facing input assigned per product. Render on the PDP in the order of \`position\`.
+// Submit values keyed by \`key\` inside AddToCartDto.metadata.
+// Upload files via \`uploadCustomizationFile()\` first, then place the returned \`url\` in metadata.
+interface ProductCustomizationField {
+  definitionId: string;
+  name: string;                 // Label to show buyers
+  key: string;                  // Use as metadata key in AddToCartDto.metadata
+  description?: string | null;  // Help text
+  type: MetafieldType;
+  required: boolean;
+  minLength?: number | null;    // TEXT/TEXTAREA char bounds; MULTI_SELECT array bounds
+  maxLength?: number | null;
+  minValue?: number | null;     // NUMBER bounds
+  maxValue?: number | null;
+  enumValues?: string[];        // REQUIRED for SELECT / MULTI_SELECT
+  defaultValue?: string | null;
+  position: number;             // Render order
+}
+
 interface ProductQueryParams {
   page?: number;
   limit?: number;
@@ -1943,6 +2212,7 @@ interface CartItem {
     sku?: string | null;
     image?: ProductImage | string | null;
   } | null;
+  metadata?: Record<string, unknown> | null;  // Buyer-submitted customization values, keyed by ProductCustomizationField.key
   createdAt: string;
   updatedAt: string;
 }
@@ -2007,6 +2277,9 @@ interface Checkout {
   taxAmount: string;
   taxBreakdown?: TaxBreakdown | null;
   total: string;
+  surchargeAmount: string;
+  appliedSurcharges?: Array<{ key: string; name: string; value: unknown; amount: string }> | null;
+  customFieldValues?: Record<string, unknown> | null;
   couponCode?: string | null;
   lineItems: CheckoutLineItem[];  // Use THIS for order summary, NOT cart.items!
   itemCount: number;
@@ -2025,6 +2298,7 @@ interface CheckoutLineItem {
   discountAmount: string;
   product: { id: string; name: string; sku: string; images?: ProductImage[]; };
   variant?: { id: string; name?: string | null; sku?: string | null; image?: ProductImage | string | null; } | null;
+  metadata?: Record<string, unknown> | null;  // Copied from CartItem.metadata \u2014 buyer customization values
 }
 
 interface CheckoutAddress {
@@ -2106,6 +2380,27 @@ interface Order {
   billingAddress?: OrderAddress;
   hasDownloads?: boolean;
   createdAt: string;
+
+  // Payment + fulfillment
+  paymentMethod?: string | null;
+  financialStatus?: string | null;       // "pending" | "paid" | "refunded" | "partially_refunded" | "voided"
+  fulfillmentStatus?: string | null;     // "unfulfilled" | "partial" | "fulfilled"
+
+  // Tracking
+  trackingNumber?: string | null;
+  trackingUrl?: string | null;
+  carrier?: string | null;
+  shippedAt?: string | null;             // ISO-8601
+  deliveredAt?: string | null;           // ISO-8601
+
+  // Timeline of status transitions, chronological
+  statusHistory?: OrderStatusChange[] | null;
+}
+
+interface OrderStatusChange {
+  status: OrderStatus;
+  at: string;                            // ISO-8601
+  note?: string | null;
 }
 
 // \u26A0\uFE0F OrderItem is FLAT \u2014 unlike CartItem which is NESTED
@@ -2119,6 +2414,9 @@ interface OrderItem {
   unitPrice?: string;    // alias
   totalPrice?: string;
   image?: string;        // FLAT: item.image (NOT nested)
+  // Snapshot of buyer-submitted customization values captured at checkout.
+  // Keyed by metafield slug. \`value\` is string[] for MULTI_SELECT / GALLERY, string otherwise.
+  customizations?: Record<string, { label: string; value: string | string[]; type: string }>;
 }
 
 interface OrderCustomer {
@@ -2340,6 +2638,32 @@ interface ProductRecommendationsResponse {
 }
 interface CartRecommendationsResponse {
   recommendations: ProductRecommendation[];
+}
+
+// Cart include types (for consolidated getCart requests)
+type CartIncludeOption = 'recommendations' | 'upgrades' | 'bundles';
+interface CartIncludeOptions {
+  include?: CartIncludeOption[];
+}
+interface CartWithIncludes extends Cart {
+  recommendations?: { recommendations: ProductRecommendation[] };
+  upgrades?: { upgrades: Record<string, CartUpgradeSuggestion> };
+  bundles?: { bundles: CartBundleOffer[] };
+}
+interface CartUpgradeSuggestion {
+  targetProduct: ProductRecommendation;
+  priceDelta: string;
+  deltaPercent: number;
+}
+interface CartBundleOffer {
+  id: string;
+  bundleProduct: ProductRecommendation;
+  originalPrice: string;
+  discountedPrice: string;
+  discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
+  discountValue: number;
+  requiresVariantSelection: boolean;
+  lockedVariant?: { id: string; name?: string };
 }`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
@@ -2403,7 +2727,8 @@ var GET_CODE_EXAMPLE_SCHEMA = {
     "coupon-apply-and-remove",
     "reservation-countdown",
     "search-autocomplete-debounce",
-    "i18n-set-locale"
+    "i18n-set-locale",
+    "order-history-full"
   ]).describe("The SDK operation to get a snippet for.")
 };
 var SNIPPETS = {
@@ -2498,23 +2823,51 @@ const checkout = await client.getCheckout(checkoutId);
   "checkout-payment-providers": `// Fetch configured payment providers for this checkout.
 import { client } from './brainerce';
 
-const providers = await client.getPaymentProviders(checkoutId);
-// providers = [{ provider, name, renderType, config }, ...]
-// renderType tells you how to render:
-//   'stripe-elements' \u2014 render Stripe Elements form and call stripe.confirmCardPayment
-//   'redirect'         \u2014 render a button that navigates to provider.authorizationUrl
-//   'paypal'           \u2014 render PayPal SDK button
-//   'sandbox'          \u2014 render a "complete test order" button (no real charge)
+const { providers, hasPayments, defaultProvider } = await client.getPaymentProviders();
+// each provider: { id, provider, name, publicKey, supportedMethods, testMode, isDefault, clientSdk? }
+//
+// After createPaymentIntent, the response carries a clientSdk.renderType that
+// tells your UI how to render the payment step. The 5 possible values:
+//
+//   'sdk-widget'       \u2014 Load the provider's JS SDK (scriptUrl), then mount
+//                        into a <div id={containerId}>. Used by Stripe,
+//                        PayPal, Grow. The SDK paints its own form inside
+//                        your DOM. You control layout/placement.
+//
+//   'iframe'           \u2014 Render <iframe src={clientSecret}>. Two flavors:
+//                          a) URL path contains "/embed/" \u2192 Brainerce-hosted
+//                             embed page. Render INLINE in your checkout
+//                             flow. Listen for postMessage:
+//                             - 'brainerce:resize' \u2192 update iframe height
+//                             - 'brainerce:redirect' \u2192 validated top-level
+//                               navigation (e.g. Bit express-pay)
+//                          b) Any other URL \u2192 provider-hosted page. Render
+//                             inside a modal overlay (it carries its own
+//                             branding/chrome).
+//
+//   'redirect'         \u2014 Full-page navigate: window.location.href = URL.
+//                        Customer leaves your site, pays on provider page,
+//                        returns via SuccessRedirectUrl.
+//
+//   'sandbox'          \u2014 Test mode. Render a "Complete Test Order" button;
+//                        call completeGuestCheckout(checkoutId). Orders are
+//                        flagged isTestOrder: true. No real charge.
+//
+//   'embedded-fields'  \u2014 (Reserved \u2014 not yet shipped in any provider.) PCI
+//                        micro-iframes for sensitive fields (card number,
+//                        CVV) mounted directly into the merchant form. Full
+//                        control of surrounding layout, like Stripe
+//                        Elements. Requires the provider to ship a client
+//                        SDK that exposes mount points.
+//
+// Always branch on clientSdk.renderType \u2014 NEVER hard-code by provider name.
+// New providers can be added without storefront changes.
 
-// Pick the first configured provider by default (or let the user pick if
-// multiple are configured).
-const active = providers[0];
-
-// If providers is empty, NO payment provider is configured and customers
-// cannot pay. Display a clear error \u2014 do not try to fake a checkout.
 if (providers.length === 0) {
   throw new Error('No payment provider configured for this store');
-}`,
+}
+
+const active = providers[0];`,
   "checkout-stripe-confirm": `// Stripe confirm flow. Requires @stripe/stripe-js and @stripe/react-stripe-js
 // (or the vanilla Stripe.js browser SDK).
 import { loadStripe } from '@stripe/stripe-js';
@@ -2728,12 +3081,82 @@ const locale = 'he'; // e.g., from the /[locale] route segment
 client.setLocale(locale);
 
 // ALL content comes back translated: products, categories, brands,
-// tags, variants, metafields, cart items, checkout line items,
-// recommendations, search suggestions, discount banners, nudges,
+// tags, variants (name + attributes keys/values), metafields,
+// cart items, checkout line items, recommendations, bundles,
+// 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');`
+// Framework-neutral: document.documentElement.setAttribute('dir', 'rtl');`,
+  "order-history-full": `// Full "My Orders" account page. Render every piece of data the server
+// already returns \u2014 not just order number / total / status.
+//
+// Data you get from client.getMyOrders() (already on the wire today):
+//   - items[].customizations          \u2014 buyer's custom-field entries
+//   - statusHistory                   \u2014 status timeline
+//   - shippingAddress                 \u2014 name + address lines + country
+//   - trackingNumber / trackingUrl / carrier / shippedAt / deliveredAt
+//   - paymentMethod / financialStatus / fulfillmentStatus
+//   - appliedDiscounts                \u2014 shaped buyer-facing view
+//   - hasDownloads                    \u2014 call /orders/:id/downloads to fetch
+//
+// Do NOT render: accountId, storeId, customerId, notes, customFieldValues
+// (merchant-internal, order-level), appliedRuleIds, appliedSurcharges,
+// surchargeAmount, downloadMeta (raw), pickupLocationData. The backend
+// does not return these to buyers \u2014 if you see them in a type, they're
+// an oversight; still skip them.
+import { client } from './brainerce';
+import type { Order, OrderItem, OrderStatusChange } from 'brainerce';
+
+const { data: orders } = await client.getMyOrders({ page: 1, limit: 10 });
+
+for (const order of orders) {
+  // Line items + per-item customizations
+  for (const item of order.items) {
+    // item.image, item.productName, item.quantity, item.price
+    if (item.customizations) {
+      for (const [fieldId, entry] of Object.entries(item.customizations)) {
+        // entry = { label, value, type }
+        // Type-aware render (see account-page section in get-sdk-docs):
+        //   TEXT / TEXTAREA / URL / NUMBER / SELECT        \u2014 plain text
+        //   BOOLEAN                                         \u2014 \u2713 / \u2717
+        //   MULTI_SELECT                                    \u2014 comma-separated
+        //   IMAGE                                           \u2014 <img src={value}>
+        //   GALLERY                                         \u2014 wrap grid of <img>
+        //   COLOR                                           \u2014 swatch + hex
+        //   DATE / DATETIME                                 \u2014 localized format
+      }
+    }
+  }
+
+  // Status timeline \u2014 skip silently when null/empty
+  if (order.statusHistory?.length) {
+    for (const entry of order.statusHistory as OrderStatusChange[]) {
+      // entry = { status, at, note? }
+      // Render a dot + localized status label + new Date(entry.at).toLocaleString()
+    }
+  }
+
+  // Shipping + tracking
+  if (order.shippingAddress) {
+    // Render firstName lastName \xB7 line1 \xB7 line2 \xB7 city, region \xB7 postalCode \xB7 country
+  }
+  if (order.trackingNumber) {
+    // Render carrier \xB7 trackingNumber, shippedAt/deliveredAt dates,
+    // and an anchor to order.trackingUrl when present.
+  }
+
+  // Payment
+  if (order.paymentMethod || order.financialStatus) {
+    // paymentMethod: 'card' | 'paypal' | 'bank_transfer' | 'cash_on_delivery' | ...
+    // financialStatus: 'pending' | 'paid' | 'refunded' | 'partially_refunded' | 'voided'
+    // Map financialStatus \u2192 a colored badge.
+  }
+}
+
+// All sections above are conditional. Absent data = section not rendered \u2014
+// never show empty placeholders. The create-brainerce-store template's
+// src/components/account/order-history.tsx is the reference implementation.`
 };
 async function handleGetCodeExample(args) {
   const snippet = SNIPPETS[args.operation];
@@ -3199,7 +3622,7 @@ var RULES = {
 - All prices are STRINGS in the SDK. \`parseFloat\` them before math or comparisons.
 - CartItem and CheckoutLineItem are NESTED (\`item.product.name\`, \`item.unitPrice\`). OrderItem is FLAT (\`item.name\`, \`item.price\`). They are not interchangeable.
 - Cart has no \`.total\` field \u2014 call \`getCartTotals(cart)\` to get \`{ subtotal, tax, shipping, discount, total }\`.
-- \`smartGetCart()\` returns a discriminated union (\`Cart | LocalCart\`). Check \`'id' in cart\` before using server-only fields.
+- \`smartGetCart()\` returns \`CartWithIncludes\` (extends \`Cart\`). Pass \`{ include: ['recommendations', 'upgrades', 'bundles'] }\` to fetch extras in one request.
 - \`startGuestCheckout()\` is also a discriminated union. Check \`result.tracked\` before reading \`result.checkoutId\`.`
   }
 };
@@ -3237,6 +3660,7 @@ var GET_BUSINESS_FLOWS_SCHEMA = {
     "order-confirmation",
     "cart-persistence",
     "inventory-reservation",
+    "product-customization",
     "all"
   ]).describe('Which flow to retrieve. Use "all" to get every flow.')
 };
@@ -3356,7 +3780,7 @@ Build the OAuth button region AND the callback handler even when no providers ar
 - **Reads:** \`client.getCart()\` returns the current cart. Call it on mount in your cart UI and on any page that shows a cart count (header).
 - **Writes:** use \`client.addToCart\`, \`client.updateCartItem\`, \`client.removeCartItem\`, \`client.applyCoupon\`, \`client.removeCoupon\`. After each mutation the SDK returns the updated cart.
 - **Totals:** call \`getCartTotals(cart)\` \u2014 do NOT read \`cart.total\`. The helper understands taxes, shipping, and discounts.
-- **\`smartGetCart()\`** returns \`Cart | LocalCart\` (guest users have no server cart until they add an item). Check \`'id' in cart\` before using server-only fields.
+- **\`smartGetCart()\`** returns \`CartWithIncludes\` (extends \`Cart\`). All carts are server-side. Pass \`{ include: ['recommendations', 'upgrades', 'bundles'] }\` to fetch extras in one request.
 - **NEVER mutate cart state outside SDK helpers.** Any hand-rolled cart update risks desync with the reservation timer and the checkout flow.`
   },
   "inventory-reservation": {
@@ -3370,6 +3794,54 @@ Build the OAuth button region AND the callback handler even when no providers ar
 - **On the cart page:** show per-item availability \u2014 items that can no longer be purchased (because their reservation expired or the stock dropped) should display an "out of stock" badge and the "proceed to checkout" action should be disabled until they are removed.
 
 The reservation strategy (\`HARD\` vs \`SOFT\`) is exposed via \`get-store-capabilities\`. A HARD reservation means the stock is physically held; a SOFT reservation just tracks intent. Your UI behaves identically either way \u2014 the SDK hides the difference.`
+  },
+  "product-customization": {
+    title: "Product customization (buyer input)",
+    body: `Products can ship with \`customizationFields: ProductCustomizationField[]\` \u2014 buyer-filled inputs (engraving text, uploaded photo, pick-a-color, etc.). If you ignore them, merchants lose the data they need to fulfill the order.
+
+1. **Read the fields** from the product payload. Sort by \`position\`. If the array is empty, nothing to render.
+2. **Render one control per field** based on \`type\`:
+   - \`TEXT\` / \`URL\` / \`COLOR\` / \`DIMENSION\` / \`WEIGHT\` \u2192 \`<input type="text">\` (honour \`minLength\`/\`maxLength\`)
+   - \`TEXTAREA\` \u2192 \`<textarea>\`
+   - \`NUMBER\` \u2192 \`<input type="number">\` (honour \`minValue\`/\`maxValue\`)
+   - \`BOOLEAN\` \u2192 checkbox (value \`true\`/\`false\`)
+   - \`DATE\` \u2192 \`<input type="date">\` (ISO \`YYYY-MM-DD\`)
+   - \`DATETIME\` \u2192 \`<input type="datetime-local">\` (ISO timestamp)
+   - \`SELECT\` \u2192 \`<select>\` populated from \`enumValues\` (value = one string)
+   - \`MULTI_SELECT\` \u2192 checkbox group from \`enumValues\` (value = \`string[]\`)
+   - \`IMAGE\` \u2192 file input + preview (value = one URL string)
+   - \`GALLERY\` \u2192 multi-file input (value = \`string[]\` of URLs)
+   - \`JSON\` \u2192 advanced; render an admin-style editor or skip unless you control the data
+3. **For IMAGE / GALLERY types: upload FIRST, then attach the URL.** Call \`client.uploadCustomizationFile(file)\` \u2014 it returns \`{ url }\`. Put that \`url\` string into the field value. NEVER put a \`File\` object in cart metadata.
+4. **Enforce \`required: true\` client-side** before add-to-cart \u2014 show a red hint, block submit. The server re-validates; you want the user to fix it before the request fails.
+5. **Add to cart with metadata keyed by \`field.key\`:**
+   \`\`\`ts
+   await client.addToCart({
+     productId,
+     quantity: 1,
+     metadata: {
+       engraving_text: 'For Mom',
+       frame_color: 'Gold',
+       upload_photo: photoUrl,      // from uploadCustomizationFile()
+       addons: ['Gift wrap'],       // MULTI_SELECT
+     },
+   });
+   \`\`\`
+6. **On cart / checkout UIs, surface the metadata.** \`CartItem.metadata\` and \`CheckoutLineItem.metadata\` carry the values the buyer submitted. Show them in the line-item row so the buyer can verify before paying (especially uploaded image thumbnails).
+7. **After the order is placed, values live on \`OrderItem.customizations\`** \u2014 a \`Record<string, { label, value, type }>\` keyed by field key. Definitions may be renamed/deleted after the order; the snapshot preserves what the buyer saw at purchase time.
+
+**Apply-to-all fields.** A merchant can flag a \`MetafieldDefinition\` with \`appliesToAllProducts: true\` \u2014 the backend then includes it in every product's \`customizationFields\` array automatically, including products created after the flag was set. Your client code reads \`product.customizationFields\` as-is and never merges or unions anything \u2014 just render what's there.
+
+Server-side guardrails that WILL reject bad requests (so validate client-side to avoid round-trips):
+- Unknown keys \u2192 rejected. Only use keys that appear in \`product.customizationFields\`.
+- Missing \`required\` fields \u2192 rejected.
+- \`SELECT\` value not in \`enumValues\` \u2192 rejected.
+- \`MULTI_SELECT\` value not \`string[]\` OR containing values outside \`enumValues\` \u2192 rejected.
+- \`IMAGE\` / \`GALLERY\` values must be URLs returned from \`/customization-upload\` on this store \u2014 pasting an external URL is rejected.
+- Upload > 5MB or non-image MIME \u2192 rejected by upload endpoint.
+- 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.`
   }
 };
 var FLOW_ORDER = [
@@ -3380,7 +3852,8 @@ var FLOW_ORDER = [
   "oauth",
   "order-confirmation",
   "cart-persistence",
-  "inventory-reservation"
+  "inventory-reservation",
+  "product-customization"
 ];
 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.";
@@ -3445,6 +3918,14 @@ var FEATURES = [
     sdk: "client.getProductBySlug(slug). Helpers: getProductPriceInfo, getVariantPrice, getStockStatus, getVariantOptions, getProductSwatches, getDescriptionContent, getProductMetafieldValue.",
     mandatory: "mandatory"
   },
+  {
+    id: "product-customization-fields",
+    title: "Render buyer-input customization fields on the product page",
+    description: "When a product ships with `customizationFields` (engraving text, uploaded photo, picked color, date, select / multi-select), render one control per field sorted by `position`. Enforce required + enumValues + min/max client-side. For IMAGE / GALLERY, upload via client.uploadCustomizationFile() and place the returned URL in the value. Submit all values keyed by `field.key` inside addToCart({ metadata }). Show the metadata on cart / checkout rows so the buyer can verify. Build the UI anyway \u2014 it auto-hides when a product has no customization fields. NOTE: merchants can flag a definition with `appliesToAllProducts: true`; the backend folds those into every product's `customizationFields` array automatically \u2014 the client never merges or unions anything, just reads `product.customizationFields` as-is.",
+    sdk: "product.customizationFields, client.uploadCustomizationFile(file), client.addToCart({ productId, quantity, metadata })",
+    flowRef: "product-customization",
+    mandatory: "mandatory"
+  },
   {
     id: "cart",
     title: "Manage a cart with quantity, removal, and totals",