@brainerce/mcp-server 3.4.0 → 3.5.1

package/dist/bin/stdio.js

@@ -93,7 +93,7 @@ npm install brainerce
 import { BrainerceClient } from 'brainerce';
 
 export const client = new BrainerceClient({
-  connectionId: '${connectionId}',
+  salesChannelId: '${connectionId}',
 });
 
 // Cart helpers \u2014 save cart ID to localStorage
@@ -195,7 +195,7 @@ async function startCheckout() {
 ### Full Checkout Flow (Multi-Provider)
 
 1. Customer fills cart
-2. Customer optionally applies coupon (cart page)
+2. Customer optionally applies coupon on cart page \u2192 \`applyCoupon(cartId, code)\`
 3. Detect payment providers \u2192 \`getPaymentProviders()\`
 4. Start checkout session (\`startGuestCheckout()\` or \`createCheckout()\`)
 5. Set shipping address (includes required email) \u2192 \`setShippingAddress()\`
@@ -213,7 +213,7 @@ import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-
 
 function CheckoutPage() {
   const [paymentData, setPaymentData] = useState<{
-    clientSecret: string; provider: string; checkoutId: string;
+    clientSecret: string; provider: string; checkoutId: string; clientSdk?: { renderType: string };
   } | null>(null);
   const [stripePromise, setStripePromise] = useState<ReturnType<typeof loadStripe> | null>(null);
   const [paypalClientId, setPaypalClientId] = useState<string | null>(null);
@@ -265,12 +265,17 @@ function CheckoutPage() {
       }
 
       // Step 4: Create payment intent \u2014 returns provider type!
+      // Pass saveCard: true when the customer ticked "save my card for next time" \u2014
+      // only honored for logged-in customers (not guests). The vaulted card then
+      // appears in client.listSavedPaymentMethods(storeId, customerId) and can be
+      // charged off-session via subscription / one-click checkout flows.
       const paymentIntent = await client.createPaymentIntent(checkoutId, {
         successUrl: \`\${window.location.origin}/order-confirmation?checkout_id=\${checkoutId}\`,
         cancelUrl: \`\${window.location.origin}/checkout?error=payment_cancelled\`,
+        // saveCard: customerOptedIn,  // optional opt-in
       });
 
-      setPaymentData({ clientSecret: paymentIntent.clientSecret, provider: paymentIntent.provider, checkoutId });
+      setPaymentData({ clientSecret: paymentIntent.clientSecret, provider: paymentIntent.provider, checkoutId, clientSdk: paymentIntent.clientSdk });
 
       // Step 5: Initialize the correct payment provider
       if (paymentIntent.provider === 'stripe' && stripeProvider) {
@@ -388,8 +393,10 @@ function PaymentIframe({ clientSecret, checkoutId }: { clientSecret: string; che
       }
       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; }
+        // before navigating \u2014 never trust the URL blindly. The SDK ships with
+        // a maintained list of payment-provider hosts; prefer it over a local
+        // copy so 'npm update brainerce' picks up new providers automatically.
+        if (isAllowedPaymentUrl(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
@@ -429,15 +436,10 @@ function PaymentIframe({ clientSecret, checkoutId }: { clientSecret: string; che
   );
 }
 
-// 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; }
-}
+// Allowlist check is provided by the SDK \u2014 covers Stripe, PayPal, Cardcom,
+// Meshulam, Grow, CreditGuard, plus Brainerce-hosted embed shells. To extend
+// for a self-hosted PSP, pass { extraHosts: ['my-psp.example.com'] }.
+import { isAllowedPaymentUrl } from 'brainerce';
 \`\`\`
 
 ### PayPal Payment Form
@@ -725,6 +727,80 @@ Provider-specific install notes:
 - **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 getSavedPaymentMethodsSection() {
+  return `## Saved Payment Methods (vaulted cards)
+
+When a logged-in customer ticks "save my card for next time", the platform vaults the
+card with the underlying provider and stores a reference. Vaulted cards can later be
+charged off-session \u2014 typically via subscription / one-click checkout features built
+on top of this foundation.
+
+### Opt-in at checkout
+
+Pass \`saveCard: true\` to \`createPaymentIntent\` when the customer chose to save.
+**Only honored for logged-in customers** \u2014 anonymous (guest) checkouts silently
+skip vaulting because there's no Customer record to attach the resulting saved
+method to.
+
+\`\`\`typescript
+const intent = await client.createPaymentIntent(checkoutId, {
+  successUrl,
+  cancelUrl,
+  saveCard: true,  // optional \u2014 only when customer ticked the box AND is logged in
+});
+\`\`\`
+
+After a successful charge, the saved card appears in the customer's profile.
+
+### Listing saved cards (storefront / customer account page)
+
+Show the customer their saved cards on a "Manage Payment Methods" page in their
+account. The platform returns display-only metadata \u2014 last4, brand, expiry,
+default flag, status. The underlying provider token is encrypted at rest and
+NEVER returned through the SDK.
+
+\`\`\`typescript
+const methods = await client.listSavedPaymentMethods(storeId, customerId);
+
+methods.forEach((m) => {
+  console.log(\`\${m.brand} ending in \${m.last4} (expires \${m.expMonth}/\${m.expYear})\`);
+  if (m.isDefault) console.log('  \u21B3 default');
+  if (m.status === 'expired') console.log('  \u21B3 expired \u2014 please add a new card');
+});
+\`\`\`
+
+### Removing a saved card
+
+\`\`\`typescript
+await client.removeSavedPaymentMethod(storeId, customerId, methodId);
+\`\`\`
+
+Hard-deletes the row from the platform DB. The provider may still hold the
+underlying token internally \u2014 we don't issue a delete-at-provider call because
+not every provider supports it. From the platform's perspective the token is
+gone; subsequent charges fail.
+
+### Provider support matrix
+
+| Provider | Save card on first charge | Charge saved card off-session |
+|---|---|---|
+| Cardcom  | \u2705 (Operation: ChargeAndCreateToken) | \u2705 |
+| PayPal   | \u2705 (Vault API: store_in_vault) | \u2705 |
+| Stripe   | (separate workstream \u2014 Brainerce doesn't ship a Stripe payment app yet) | \u2014 |
+| Grow     | \u274C \u2014 returns 501 \`token_storage_unavailable\` | \u274C |
+
+When a provider doesn't support tokenization, the platform surfaces a 409 with
+\`code: 'token_storage_unavailable'\`. Storefronts should hide the "save card"
+checkbox when the active provider doesn't support it.
+
+### Charging off-session
+
+Charging a saved card from the storefront is **not** part of this foundation \u2014
+that's the job of the Subscription / one-click checkout features built on top.
+For now, charges run through the standard \`createPaymentIntent\` flow. The
+saved-method foundation makes those features possible without further platform
+changes.`;
+}
 function getProductsSection(_currency) {
   return `## Products & Variants
 
@@ -745,6 +821,18 @@ const filtered = await client.getProducts({
   categories: ['cat_123'], minPrice: 10, maxPrice: 100,
   sortBy: 'price', sortOrder: 'asc',
 });
+
+// Filter by custom fields (metafields). Only fields the merchant marked
+// \`filterable: true\` are honored; supported types are SELECT, MULTI_SELECT,
+// BOOLEAN. AND across keys, OR within a key.
+const byCustom = await client.getProducts({
+  metafields: { color: ['red', 'blue'], in_stock: ['true'] },
+});
+
+// Discover which custom fields are filterable for the current store:
+const { definitions } = await client.getPublicMetafieldDefinitions();
+const facets = definitions.filter(d => d.filterable);
+// Render a checkbox group per SELECT/MULTI_SELECT, a switch per BOOLEAN.
 \`\`\`
 
 ### i18n \u2014 translated fields come back on every request
@@ -797,6 +885,10 @@ function ProductPage({ product, storeInfo }: { product: Product; storeInfo: Stor
     ? getVariantPrice(selectedVariant, product.basePrice).toString()
     : product.salePrice || product.basePrice;
 
+  // \u2705 For catalog cards: use pre-computed priceMin/priceMax instead of iterating variants
+  // product.priceMin / product.priceMax are always set for VARIABLE products with explicit variant prices.
+  // product.priceVaries is true when the range should be shown as "\u20AA49 \u2013 \u20AA199".
+
   // Build attribute buttons (size, color, etc.)
   const allOptions = product.variants?.map(v => getVariantOptions(v)) || [];
   const attrNames = [...new Set(allOptions.flatMap(opts => opts.map(o => o.name)))];
@@ -1011,6 +1103,7 @@ const total = cart.total;
 
 ### Coupons
 
+**On the cart page** (before checkout is created):
 \`\`\`typescript
 // Apply coupon \u2014 returns updated Cart with discountAmount
 const updatedCart = await client.applyCoupon(cartId, 'SAVE20');
@@ -1018,13 +1111,24 @@ console.log(updatedCart.discountAmount); // "10.00"
 console.log(updatedCart.couponCode);     // "SAVE20"
 
 // Remove coupon
-const updatedCart = await client.removeCoupon(cartId);
+await client.removeCoupon(cartId);
 
 // Calculate totals including discount
 const totals = getCartTotals(cart); // { subtotal, discount, shipping, total }
 \`\`\`
 
-Add a coupon code input on the cart page. Coupons only work on server \`Cart\` (has \`id\` field). Checkout inherits the coupon \u2014 show \`checkout.discountAmount\` and \`checkout.couponCode\` in checkout order summary.
+**On the checkout page** (after checkout session exists \u2014 ALWAYS use this when checkoutId is available):
+\`\`\`typescript
+// Applies to cart AND updates checkout totals in one call
+const checkout = await client.applyCheckoutCoupon(checkoutId, 'SAVE20');
+console.log(checkout.discountAmount); // "10.00"
+console.log(checkout.total);          // correctly updated total
+
+// Remove coupon from checkout
+await client.removeCheckoutCoupon(checkoutId);
+\`\`\`
+
+> \u26A0\uFE0F **Critical:** if a checkout session already exists, ALWAYS use \`applyCheckoutCoupon(checkoutId, code)\`. Using \`applyCoupon(cartId, code)\` after checkout creation does NOT update the checkout total \u2014 payment will charge the original amount. Show \`checkout.discountAmount\` and \`checkout.couponCode\` in the order summary.
 
 ### \u26A0\uFE0F Checkout Order Summary \u2014 Use checkout.lineItems, NOT cart.items!
 
@@ -1114,22 +1218,24 @@ const { upgrades } = await client.getCartUpgrades(cartId);
 // Show inline banner per cart item if upgrade exists
 \`\`\`
 
-**Bundle offers** (discounted complementary products configured by the store owner):
+**Bundle offers** (N-product bundles configured by the store owner \u2014 productIds[0] triggers the offer, productIds[1..] are offered together at a discount):
 \`\`\`typescript
 import type { CartBundlesResponse } from 'brainerce';
 const { bundles } = await client.getCartBundles(cartId);
-// bundles[].bundleProduct \u2014 the product to offer
-// bundles[].originalPrice / bundles[].discountedPrice \u2014 prices
+// bundles[].triggerProductId \u2014 already in cart, activates the offer
+// bundles[].productIds \u2014 full bundle composition (length >= 2)
+// bundles[].offeredProducts[] \u2014 products customer hasn't added yet
+//   each with originalPrice + discountedPrice
+// bundles[].totalOriginalPrice / totalDiscountedPrice \u2014 sums across offeredProducts
 // bundles[].discountType ('PERCENTAGE' | 'FIXED_AMOUNT') + discountValue
-// bundles[].requiresVariantSelection \u2014 true if customer must pick a variant
-// bundles[].lockedVariant \u2014 set if admin pre-selected a specific variant
-// bundles[].bundleProduct.variants \u2014 available variants (only when requiresVariantSelection)
 
-// Add a bundle to cart (applies the discount automatically):
+// Accept a bundle (adds every offered product not yet in cart at the discount):
 await client.addBundleToCart(cartId, bundleOfferId);
-// For products with variants \u2014 pass the selected variantId:
-await client.addBundleToCart(cartId, bundleOfferId, selectedVariantId);
-// Remove a bundle from cart:
+// If some offered products have variants, pass per-product variant selections:
+await client.addBundleToCart(cartId, bundleOfferId, {
+  [variantProductId]: selectedVariantId,
+});
+// Remove an accepted bundle (removes every cart item linked to that bundle):
 await client.removeBundleFromCart(cartId, bundleOfferId);
 // Detect already-added bundles: check cart.items for metadata?.isBundleItem === true
 \`\`\`
@@ -1185,11 +1291,12 @@ Always check the flag before rendering: \`if (storeInfo?.upsell?.featureName !==
 | CartRecommendationSection | products/ | Cross-sell grid at bottom of cart page |
 | FreeShippingBar | cart/ | Progress bar toward free shipping threshold |
 | CartUpgradeBanner | cart/ | Inline "Upgrade to X for +$Y" per cart item |
-| CartBundleOfferCard | cart/ | Discounted bundle offer card in cart (with inline variant selector for variable products) |
+| CartBundleOfferCard | cart/ | N-product bundle offer card in cart \u2014 lists every offered product with its discounted price and an "Add bundle" button |
 | OrderBumpCard | checkout/ | Checkbox add-on card in checkout sidebar (with inline variant selector for variable products) |
 
 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 }\`).`;
+OrderBump: includes \`requiresVariantSelection\` (boolean) and \`lockedVariant?\` (\`{ id, name, attributes }\`).
+CartBundleOffer: \`productIds\` (length \\>= 2; index 0 = trigger), \`offeredProducts\` (per-product discounted prices), \`totalOriginalPrice\` / \`totalDiscountedPrice\`. Variant selection for offered products is passed per-call via \`variantSelections\` on \`addBundleToCart\`.`;
 }
 function getProductCustomizationFieldsSection() {
   return `## Product Customization Fields (buyer input on product page)
@@ -1295,6 +1402,157 @@ When the order is created, each line's customization values are snapshotted onto
 - 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 getModifierGroupsSection() {
+  return `## Modifier Groups (toppings, sauce, build-your-own)
+
+Modifier groups are merchant-defined option blocks attached to a product \u2014 the canonical example is "Toppings" on a pizza, where the customer picks 0\u20138 options with the first 3 free. They differ from \`customizationFields\` (which are arbitrary buyer input \u2014 text, photos, color picks): modifier groups are a **structured selection with priced options**, validated and priced server-side.
+
+If \`product.modifierGroups\` is empty or missing, render the product page normally and skip everything below.
+
+### Wire shape on \`GET /products/:id\`
+
+\`\`\`typescript
+import type { Product, ModifierGroup, Modifier, ModifierSelection } from 'brainerce';
+
+const product = await client.getProductBySlug(slug);
+const groups: ModifierGroup[] = product.modifierGroups ?? [];
+
+// Each group looks like:
+// {
+//   id: 'mg_toppings',
+//   attachmentId: 'pmg_01',           // ProductModifierGroup row \u2014 used for attach updates
+//   name: 'Toppings',                 // customer-facing
+//   internalName?: string,            // ADMIN ONLY \u2014 never present in storefront responses
+//   selectionType: 'SINGLE' | 'MULTIPLE',
+//   min: number,                      // effective (overrides already applied)
+//   max: number | null,               // null = unlimited; **0 = group hidden for this variant**
+//   freeQuantity: number,             // first N picks at no extra cost
+//   required: boolean,
+//   freeAllocationPolicy: 'EXPENSIVE_FREE' | 'CHEAPEST_FREE' | 'SELECTION_ORDER',
+//   defaultModifierIds: string[],     // pre-checked on first render
+//   modifiers: Array<{
+//     id: 'm_olive',
+//     name: 'Olives',
+//     priceDelta: '5.00',             // DECIMAL STRING \u2014 never JSON Number
+//     position: 0,
+//     isDefault: false,               // pre-check this option even if not in defaultModifierIds
+//     available: true,                // false \u2192 "sold out", disabled in UI
+//     referencedProductId?: string,   // nested-combo target (depth \u2264 3)
+//   }>,
+// }
+\`\`\`
+
+**Money fields are strings.** \`priceDelta\` is \`"5.00"\` (or \`"-2.00"\` for downsell modifiers \u2014 see below). Use \`parseFloat()\` for display arithmetic; never compute the line total client-side \u2014 the server runs the free-allocation policy and returns the final \`unitPrice\` snapshot on the cart line.
+
+### Render: SINGLE \u2192 radio, MULTIPLE \u2192 checkbox
+
+Walk \`groups\` and pick the input type by \`selectionType\`. Sort modifiers by \`position\`.
+
+\`\`\`typescript
+for (const group of groups) {
+  if (group.max === 0) continue; // disabled-for-variant convention \u2014 skip entirely
+  const inputType = group.selectionType === 'SINGLE' ? 'radio' : 'checkbox';
+  const sorted = [...group.modifiers].sort((a, b) => a.position - b.position);
+  // Render fieldset \u2192 legend with name + " *" if required \u2192 list of sorted options.
+  // Each option: input(type=inputType, name=group.id, value=modifier.id),
+  // disabled when modifier.available === false, with a "Sold out" badge.
+}
+\`\`\`
+
+When \`group.freeQuantity > 0\`, show a running counter so the customer understands the rule:
+\`\`\`
+{Math.min(picks.length, group.freeQuantity)} of {group.freeQuantity} free
+\`\`\`
+
+Note: individual modifiers may have \`excludeFromFree: true\` \u2014 these are "premium" options that always charge their \`priceDelta\` and are never consumed by a free slot. Render them with a label like "premium" so customers know they are not eligible for the free allocation.
+
+### Initial state
+
+Honor \`defaultModifierIds\` first (per-attach defaults set by the merchant for this product/variant), falling back to \`modifier.isDefault\` flags when the group has no per-attach defaults. Filter sold-out modifiers out of the initial picks. For SINGLE groups, cap to one.
+
+### Pass selections on add-to-cart
+
+\`\`\`typescript
+const selections: ModifierSelection[] = [
+  { modifierGroupId: 'mg_bread',    modifierIds: ['m_thick'] },
+  { modifierGroupId: 'mg_toppings', modifierIds: ['m_olive', 'm_mushroom', 'm_bacon', 'm_egg'] },
+];
+
+await client.smartAddToCart({
+  productId: product.id,
+  variantId: selectedVariant?.id,
+  quantity: 1,
+  selections,
+});
+\`\`\`
+
+\`modifierIds\` is in **click-order** \u2014 the server uses this for the \`SELECTION_ORDER\` free-allocation policy. The cart response surfaces a per-line snapshot:
+
+\`\`\`typescript
+// cart.items[i].modifiers \u2014 same shape as ModifierSelection but with snapshot data
+[
+  { modifierId: 'm_olive',    name: 'Olives',     priceDelta: '5.00', freeApplied: true  },
+  { modifierId: 'm_mushroom', name: 'Mushrooms',  priceDelta: '5.00', freeApplied: true  },
+  { modifierId: 'm_bacon',    name: 'Bacon',      priceDelta: '7.00', freeApplied: true  },
+  { modifierId: 'm_egg',      name: 'Egg',        priceDelta: '6.00', freeApplied: false },
+]
+// + cart.items[i].modifiersTotal \u2014 sum of paid (non-free) deltas as a decimal string
+\`\`\`
+
+\`freeApplied: true\` means the modifier consumed a free slot \u2014 render with a "free" badge in the cart UI.
+
+### Editing selections after add-to-cart (idempotent)
+
+\`PATCH /cart/items/:id\` with a fresh \`selections\` array **replaces** the line's modifiers atomically \u2014 the server deletes old \`CartItemModifier\` rows and recreates them inside the same transaction. Omit \`selections\` from the body to leave them unchanged (e.g., quantity-only update).
+
+\`\`\`typescript
+await client.updateCartItem(cart.id, itemId, {
+  quantity: 1,
+  selections: [{ modifierGroupId: 'mg_toppings', modifierIds: ['m_olive', 'm_mushroom'] }],
+});
+\`\`\`
+
+### Validation envelope
+
+When the payload is invalid the server returns HTTP 400 with a structured envelope. The SDK exposes it on \`BrainerceError.details\`:
+
+\`\`\`typescript
+try {
+  await client.smartAddToCart({ productId, quantity: 1, selections });
+} catch (err) {
+  const e = err as { statusCode?: number; details?: { code?: string; errors?: Array<{ code: string; message: string; modifierGroupId?: string; modifierId?: string }> } };
+  if (e.statusCode === 400 && e.details?.code === 'MODIFIER_VALIDATION_FAILED') {
+    for (const issue of e.details.errors ?? []) {
+      // issue.code is one of: REQUIRED_GROUP_MISSING | MIN_SELECTIONS_NOT_MET |
+      // MAX_SELECTIONS_EXCEEDED | SINGLE_GROUP_MULTIPLE_PICKS | UNKNOWN_MODIFIER |
+      // UNKNOWN_GROUP | MODIFIER_DISABLED_FOR_VARIANT | MODIFIER_NOT_AVAILABLE |
+      // NESTED_DEPTH_EXCEEDED | NESTED_REQUIRES_PRODUCT_REF | INVALID_PRICE_DELTA |
+      // MODIFIER_PRICE_FLOOR_VIOLATED
+      console.error(issue.message);
+    }
+  }
+}
+\`\`\`
+
+Special case: \`MODIFIER_PRICE_FLOOR_VIOLATED\` fires when downsell modifiers (negative \`priceDelta\`) would push \`unitPrice\` below \`0\`. The server reports a generic message \u2014 internals never leak \u2014 so show a friendly "Cannot apply more discounts on this item" and let the customer remove a downsell.
+
+### Disable-for-variant convention (PRD \xA77.2.2)
+
+The merchant can hide a group entirely for one variant by setting \`maxOverride: 0\` on a per-variant attachment. The product response then returns the group with \`max: 0\` for that variant. **Skip it entirely** \u2014 do not render, do not include in selections. The validator silently skips groups with \`effectiveMax === 0\` on the cart side.
+
+### Common mistakes
+
+- Treating \`priceDelta\` as a number \u2192 arithmetic precision bugs. Always strings; use \`parseFloat\` only at display time.
+- Computing the line total client-side \u2192 diverges from the server's free-allocation. Render the server's \`unitPrice\` / \`modifiers[]\` / \`modifiersTotal\` instead.
+- Rendering a group with \`max: 0\` \u2192 it's the variant-disable signal; treat as absent.
+- Showing \`internalName\` on a public storefront \u2192 it is **never** present in storefront responses; if your code is reading it, you're using an admin endpoint by accident.
+- Building \`selections\` keyed by \`modifier.name\` \u2192 must be \`modifierGroupId\` + \`modifierIds[]\` (the IDs, not names).
+- Sending \`modifiers\` instead of \`selections\` on add-to-cart \u2192 \`modifiers\` is the response field; the request key is \`selections\`.
+
+### Restaurant features (advanced)
+
+Allergens (informational chips), scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -1690,7 +1948,7 @@ subsequent SDK call sends the \`Accept-Language\` header automatically:
 \`\`\`typescript
 import { BrainerceClient } from 'brainerce';
 
-const client = new BrainerceClient({ connectionId: 'vc_...' });
+const client = new BrainerceClient({ salesChannelId: 'vc_...' });
 client.setLocale('he'); // done \u2014 all calls are now in Hebrew
 \`\`\`
 
@@ -1860,7 +2118,40 @@ const admin = new BrainerceClient({ apiKey: 'brainerce_...' });
 // Email: getEmailTemplates(), createEmailTemplate()
 // Conflicts: getSyncConflicts(), resolveSyncConflict()
 // OAuth: getOAuthProviders(), configureOAuthProvider()
-\`\`\``;
+\`\`\`
+
+### Per-Channel Publishing
+
+Categories, tags, brands, and metafield definitions are gated to specific
+vibe-coded sites \u2014 same control already exposed for products and coupons.
+**Explicit opt-in:** an entity is visible to a vibe-coded site only if it
+has been explicitly published to that connection. Entities with no publish
+rows are invisible to every site (the merchant must publish them via the
+dashboard or the admin SDK).
+
+\`\`\`typescript
+// Publish to a specific vibe-coded site (admin mode):
+await admin.publishCategoryToVibeCodedSite('cat_id', 'conn_id');
+await admin.publishTagToVibeCodedSite('tag_id', 'conn_id');
+await admin.publishBrandToVibeCodedSite('brand_id', 'conn_id');
+await admin.publishMetafieldDefinitionToVibeCodedSite('def_id', 'conn_id');
+
+// Unpublish (entity stays visible to other sites unless they also have publishes):
+await admin.unpublishCategoryFromVibeCodedSite('cat_id', 'conn_id');
+// ...same for tag/brand/metafield definition.
+
+// Read which sites an entity is published to via list/get responses:
+const cat = await admin.getCategory('cat_id');
+cat.vibeCodedPublishes; // [{ connection: { id, name, connectionId } }, ...]
+\`\`\`
+
+Cross-account isolation is enforced server-side: a publish call only
+succeeds when entity and connection belong to the same account. Cross-account
+calls fail with \`404 Not Found\`.
+
+The vibe-coded read endpoints (used by storefront SDK calls in \`connectionId\`
+mode) automatically filter by these junction tables, so storefronts never see
+entities that weren't published to their site.`;
 }
 function getContactInquiriesSection() {
   return `## Contact Inquiries & Forms (optional)
@@ -1935,7 +2226,7 @@ const form = await brainerce.contactForms.get('main', 'en');
 // \u2192 {
 //     id, key, name, description?, submitButton, successMessage,
 //     fields: [{ key, type, label, placeholder?, helpText?, isRequired,
-//                enumValues?, validation?, defaultValue? }, ...]
+//                enumValues?, validation?, defaultValue?, width? }, ...]
 //   }
 
 // Submit a keyed payload. Unknown keys are stripped, required fields are
@@ -1961,6 +2252,20 @@ stripped server-side.
 Render every field type the merchant can pick. Keep this as a \`<DynamicField>\`
 component so the form is fully driven by \`schema.fields\`.
 
+**Layout.** Each field carries an optional \`width\` hint:
+
+| \`field.width\` | Meaning | Grid style (6-column grid) |
+| ------------- | ------- | -------------------------- |
+| \`'FULL'\` (default) | Full row | \`grid-column: span 6\` |
+| \`'HALF'\` | Half row | \`grid-column: span 3\` |
+| \`'THIRD'\` | One-third row | \`grid-column: span 2\` |
+
+Stack fields to full width on small screens (< ~640 px).
+
+**Required fields.** Show a red asterisk on required labels, validate
+**client-side** before calling \`createInquiry()\`, and show inline error
+messages. Do NOT rely only on the server returning 400.
+
 \`\`\`tsx
 import type { ContactFormPublic, ContactFormPublicField } from 'brainerce';
 
@@ -1978,13 +2283,24 @@ function isEmpty(v: FieldValue): boolean {
   return v === false;
 }
 
+// Map width \u2192 CSS grid column span (6-column grid)
+function widthClass(w?: string): string {
+  switch (w) {
+    case 'HALF':  return 'grid-col-half';   // grid-column: span 3; on sm+, full on mobile
+    case 'THIRD': return 'grid-col-third';  // grid-column: span 2; on sm+, full on mobile
+    default:      return 'grid-col-full';   // grid-column: span 6
+  }
+}
+
 function DynamicField({
   field,
   value,
+  error,
   onChange,
 }: {
   field: ContactFormPublicField;
   value: FieldValue;
+  error?: string;
   onChange: (v: FieldValue) => void;
 }) {
   const id = \`contact-\${field.key}\`;
@@ -1999,37 +2315,40 @@ function DynamicField({
     </label>
   );
   const help = field.helpText ? <p className="mt-1 text-xs opacity-70">{field.helpText}</p> : null;
+  const errorEl = error ? <p className="mt-1 text-xs text-red-500">{error}</p> : null;
 
+  // Outer div uses widthClass to control grid-column span
   switch (field.type) {
     case 'TEXTAREA':
-      return (<div>{label}<textarea id={id} required={field.isRequired} maxLength={maxLength} minLength={minLength} rows={6} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<textarea id={id} required={field.isRequired} maxLength={maxLength} minLength={minLength} rows={6} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}{errorEl}</div>);
     case 'EMAIL':
-      return (<div>{label}<input id={id} type="email" required={field.isRequired} autoComplete="email" placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<input id={id} type="email" required={field.isRequired} autoComplete="email" placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}{errorEl}</div>);
     case 'PHONE':
-      return (<div>{label}<input id={id} type="tel" required={field.isRequired} autoComplete="tel" placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<input id={id} type="tel" required={field.isRequired} autoComplete="tel" placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}{errorEl}</div>);
     case 'URL':
-      return (<div>{label}<input id={id} type="url" required={field.isRequired} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<input id={id} type="url" required={field.isRequired} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}{errorEl}</div>);
     case 'NUMBER':
-      return (<div>{label}<input id={id} type="number" required={field.isRequired} min={min} max={max} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<input id={id} type="number" required={field.isRequired} min={min} max={max} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}{errorEl}</div>);
     case 'DATE':
-      return (<div>{label}<input id={id} type="date" required={field.isRequired} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<input id={id} type="date" required={field.isRequired} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}{errorEl}</div>);
     case 'SELECT':
-      return (<div>{label}<select id={id} required={field.isRequired} value={strVal} onChange={(e) => onChange(e.target.value)}><option value="">\u2014</option>{field.enumValues?.map((o) => (<option key={o.value} value={o.value}>{o.label}</option>))}</select>{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<select id={id} required={field.isRequired} value={strVal} onChange={(e) => onChange(e.target.value)}><option value="">\u2014</option>{field.enumValues?.map((o) => (<option key={o.value} value={o.value}>{o.label}</option>))}</select>{help}{errorEl}</div>);
     case 'MULTI_SELECT': {
       const arr = Array.isArray(value) ? value : [];
-      return (<div>{label}<div>{field.enumValues?.map((o) => { const checked = arr.includes(o.value); return (<label key={o.value}><input type="checkbox" checked={checked} onChange={(e) => onChange(e.target.checked ? [...arr, o.value] : arr.filter((v) => v !== o.value))} /><span>{o.label}</span></label>); })}</div>{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<div>{field.enumValues?.map((o) => { const checked = arr.includes(o.value); return (<label key={o.value}><input type="checkbox" checked={checked} onChange={(e) => onChange(e.target.checked ? [...arr, o.value] : arr.filter((v) => v !== o.value))} /><span>{o.label}</span></label>); })}</div>{help}{errorEl}</div>);
     }
     case 'CHECKBOX':
-      return (<div><label htmlFor={id}><input id={id} type="checkbox" required={field.isRequired} checked={value === true} onChange={(e) => onChange(e.target.checked)} /><span>{field.label}</span></label>{help}</div>);
+      return (<div className={widthClass(field.width)}><label htmlFor={id}><input id={id} type="checkbox" required={field.isRequired} checked={value === true} onChange={(e) => onChange(e.target.checked)} /><span>{field.label}</span></label>{help}{errorEl}</div>);
     case 'TEXT':
     default:
-      return (<div>{label}<input id={id} type="text" required={field.isRequired} maxLength={maxLength} minLength={minLength} pattern={pattern} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}</div>);
+      return (<div className={widthClass(field.width)}>{label}<input id={id} type="text" required={field.isRequired} maxLength={maxLength} minLength={minLength} pattern={pattern} placeholder={field.placeholder} value={strVal} onChange={(e) => onChange(e.target.value)} />{help}{errorEl}</div>);
   }
 }
 
 export function ContactPage() {
   const [schema, setSchema] = useState<ContactFormPublic | null>(null);
   const [values, setValues] = useState<Record<string, FieldValue>>({});
+  const [errors, setErrors] = useState<Record<string, string>>({});
   const [honeypot, setHoneypot] = useState('');
   const [sent, setSent] = useState(false);
   const [loading, setLoading] = useState(false);
@@ -2053,6 +2372,19 @@ export function ContactPage() {
     if (loading) return;
     if (honeypot.trim().length > 0) { setSent(true); return; } // bot \u2192 silent success
 
+    // \u2500\u2500 Client-side required-field validation \u2500\u2500
+    const newErrors: Record<string, string> = {};
+    for (const f of schema.fields) {
+      if (f.isRequired && isEmpty(values[f.key] ?? defaultValueFor(f))) {
+        newErrors[f.key] = \`\${f.label} is required\`;  // or pull from your i18n system
+      }
+    }
+    if (Object.keys(newErrors).length > 0) {
+      setErrors(newErrors);
+      return; // block submission
+    }
+    setErrors({});
+
     setLoading(true);
     try {
       const payload: Record<string, unknown> = {};
@@ -2085,11 +2417,15 @@ export function ContactPage() {
           value={honeypot} onChange={(e) => setHoneypot(e.target.value)} />
       </div>
 
-      {schema.fields.map((field) => (
-        <DynamicField key={field.key} field={field}
-          value={values[field.key] ?? defaultValueFor(field)}
-          onChange={(v) => setValues((p) => ({ ...p, [field.key]: v }))} />
-      ))}
+      {/* CSS grid \u2014 6 columns on sm+, 1 column on mobile */}
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(6, 1fr)', gap: '1rem' }}>
+        {schema.fields.map((field) => (
+          <DynamicField key={field.key} field={field}
+            value={values[field.key] ?? defaultValueFor(field)}
+            error={errors[field.key]}
+            onChange={(v) => setValues((p) => ({ ...p, [field.key]: v }))} />
+        ))}
+      </div>
 
       <button type="submit" disabled={loading}>
         {loading ? '\u2026' : schema.submitButton}
@@ -2099,13 +2435,27 @@ export function ContactPage() {
 }
 \`\`\`
 
+CSS for the grid column helpers (or use the equivalent Tailwind / inline styles):
+
+\`\`\`css
+.grid-col-full  { grid-column: span 6; }
+.grid-col-half  { grid-column: span 6; }
+.grid-col-third { grid-column: span 6; }
+
+@media (min-width: 640px) {
+  .grid-col-half  { grid-column: span 3; }
+  .grid-col-third { grid-column: span 2; }
+}
+\`\`\`
+
 ### Rules
 
 - **Rate limit:** 3 submissions / 60s per IP \u2014 show a friendly "try again later" message on HTTP 429.
 - **Honeypot:** always render a hidden field named \`honeypot\` and **never send** it. Bots fill every input; the server rejects submissions carrying a non-empty \`honeypot\`.
 - **Built-in keys:** \`name\`, \`email\`, \`phone\`, \`subject\`, \`message\` always exist on the default form; the legacy \`createInquiry\` shape keeps working forever.
 - **Max values:** each field value is capped at 10 000 chars server-side. Validate client-side before submitting using \`field.validation.maxLength\`.
-- **Required fields:** respect \`field.isRequired\`. The server validates too, but show \`required\` on the input for browser-level UX.
+- **Required fields:** respect \`field.isRequired\`. Show a red asterisk (\`*\`) next to the label. **Validate client-side before submission** \u2014 iterate over \`schema.fields\`, check \`isEmpty(values[f.key])\` for each required field, and block the submit with inline error messages. The server validates too, but the user should never see a raw 400 error.
+- **Width (layout):** respect \`field.width\`. Use a CSS grid with 6 columns: \`FULL\` = span 6 (default), \`HALF\` = span 3, \`THIRD\` = span 2. Stack to full width on small screens. If \`width\` is missing, treat as \`FULL\`.
 - **Validation:** when \`field.validation.pattern\` is present, pass it as the input's \`pattern\` attribute; the server also enforces it. Likewise \`minLength\`/\`maxLength\`/\`min\`/\`max\`.
 - **Enum values:** SELECT and MULTI_SELECT always return \`enumValues\` (non-empty array). Render from \`enumValues\`, never a hardcoded list.
 - **Visibility:** the server strips fields with \`isVisible=false\`, so \`schema.fields\` only contains things to render.
@@ -2137,6 +2487,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getCheckoutCustomFieldsSection();
     case "payment":
       return getPaymentProvidersSection();
+    case "saved-payment-methods":
+      return getSavedPaymentMethodsSection();
     case "auth":
       return getCustomerAuthSection();
     case "order-confirmation":
@@ -2149,6 +2501,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getRecommendationsSection();
     case "product-customization-fields":
       return getProductCustomizationFieldsSection();
+    case "modifier-groups":
+      return getModifierGroupsSection();
     case "tax":
       return getTaxDisplaySection(cur);
     case "i18n":
@@ -2229,6 +2583,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getModifierGroupsSection(),
+        "",
+        "---",
+        "",
         getTaxDisplaySection(cur),
         "",
         "---",
@@ -2273,11 +2631,19 @@ var GET_SDK_DOCS_SCHEMA = {
     "inquiries",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
-  connectionId: import_zod.z.string().optional().describe("Vibe-coded connection ID (starts with vc_). Used to personalize setup code."),
+  salesChannelId: import_zod.z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
+  /** @deprecated alias of salesChannelId */
+  connectionId: import_zod.z.string().optional().describe("Deprecated alias of salesChannelId \u2014 kept for backwards compat"),
   currency: import_zod.z.string().optional().describe("Store currency code (e.g., USD, ILS, EUR). Used in price formatting examples.")
 };
 async function handleGetSdkDocs(args) {
-  const content = getSectionByTopic(args.topic, args.connectionId, args.currency);
+  const id = args.salesChannelId ?? args.connectionId;
+  if (!args.salesChannelId && args.connectionId) {
+    console.warn(
+      "get-sdk-docs: `connectionId` is deprecated \u2014 use `salesChannelId` instead"
+    );
+  }
+  const content = getSectionByTopic(args.topic, id, args.currency);
   return {
     content: [{ type: "text", text: content }]
   };
@@ -2299,6 +2665,9 @@ interface Product {
   basePrice: string;   // Use parseFloat() for calculations
   salePrice?: string | null;
   costPrice?: string | null;
+  priceMin?: string | null;  // Lowest variant price (VARIABLE products). Use for catalog/JSON-LD range display.
+  priceMax?: string | null;  // Highest variant price (VARIABLE products).
+  priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
   status: string;
   type: 'SIMPLE' | 'VARIABLE';
   isDownloadable?: boolean;
@@ -2316,7 +2685,7 @@ interface Product {
     attributeId: string;
     attributeOptionId: string;
     platform: string;
-    attribute: { id: string; name: string; displayType?: 'DEFAULT' | 'COLOR_SWATCH' | 'IMAGE_SWATCH' } | null;
+    attribute: { id: string; name: string; displayType?: 'DEFAULT' | 'COLOR_SWATCH' | 'IMAGE_SWATCH' | 'MIXED_SWATCH' } | null;
     attributeOption: { id: string; name: string; value?: string | null; swatchColor?: string | null; swatchColor2?: string | null; swatchImageUrl?: string | null } | null;
   }>;
   createdAt: string;
@@ -2325,6 +2694,8 @@ interface Product {
 
 // Use getProductSwatches(product) to get grouped swatch data for storefront rendering.
 // Returns Array<{ attributeName, displayType, options: Array<{ name, swatchColor?, swatchColor2?, swatchImageUrl? }> }>
+// displayType rendering: COLOR_SWATCH \u2192 color circle (swatchColor/swatchColor2); IMAGE_SWATCH \u2192 image thumbnail (swatchImageUrl);
+// MIXED_SWATCH \u2192 per-option: render swatchImageUrl if set, else swatchColor if set, else text only.
 
 interface ProductImage {
   url: string;
@@ -2405,6 +2776,10 @@ interface ProductQueryParams {
   tags?: string | string[];
   minPrice?: number;
   maxPrice?: number;
+  // Filter by custom-field (metafield) values. Keys = definition.key,
+  // values = accepted values. Only definitions with filterable=true and
+  // type SELECT/MULTI_SELECT/BOOLEAN are honored. AND across keys, OR within.
+  metafields?: Record<string, string | string[]>;
   sortBy?: 'name' | 'price' | 'createdAt';
   sortOrder?: 'asc' | 'desc';
 }
@@ -2822,6 +3197,36 @@ interface PaymentStatus {
   error?: string;
 }
 
+// ---- Saved Payment Methods (vaulted cards) ----
+// Display-only summary of a customer's vaulted payment method. The
+// underlying provider token is encrypted at rest in the platform DB
+// and NEVER returned through the SDK.
+//
+// To opt into vaulting at checkout, pass saveCard: true to
+// createPaymentIntent (only honored for logged-in customers).
+//
+// To list / remove saved methods, see:
+//   client.listSavedPaymentMethods(storeId, customerId)
+//   client.removeSavedPaymentMethod(storeId, customerId, methodId)
+
+interface SavedPaymentMethodSummary {
+  id: string;
+  customerId: string;
+  appInstallationId: string;
+  paymentMethod: string;          // 'credit_card' | 'paypal' | 'bank_account'
+  brand: string | null;
+  last4: string | null;
+  expMonth: number | null;
+  expYear: number | null;
+  isDefault: boolean;
+  status: string;                 // 'active' | 'expired' | 'invalid'
+  failureReason: string | null;
+  lastUsedAt: string | null;
+  expiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
 interface WaitForOrderResult {
   success: boolean;
   status: PaymentStatus;   // Access: result.status.orderNumber
@@ -2833,9 +3238,9 @@ var HELPERS_TYPES = `// ---- Helper Functions (import from 'brainerce') ----
 // Price helpers
 function formatPrice(priceString: string | number | undefined | null, options?: { currency?: string; locale?: string; }): string;
 function getProductPrice(product: Pick<Product, 'basePrice' | 'salePrice'>): number;
-function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice'>): {
+function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice' | 'discount' | 'priceMin' | 'priceVaries'>): {
   price: number; originalPrice: number; isOnSale: boolean; discountAmount: number; discountPercent: number;
-};
+}; // Falls back to priceMin when basePrice=0 (VARIABLE products)
 function getVariantPrice(variant: Pick<ProductVariant, 'price' | 'salePrice'>, productBasePrice: string): number;
 
 // Cart helpers
@@ -2921,15 +3326,32 @@ interface CartUpgradeSuggestion {
   priceDelta: string;
   deltaPercent: number;
 }
-interface CartBundleOffer {
+interface CartBundleOfferOfferedProduct {
   id: string;
-  bundleProduct: ProductRecommendation;
+  name: string;
+  slug: string | null;
+  basePrice: string;
+  salePrice: string | null;
+  images: Array<{ url: string }>;
+  type: string;
   originalPrice: string;
   discountedPrice: string;
+}
+interface CartBundleOffer {
+  id: string;
+  name: string;
+  description: string | null;
+  // productIds[0] = trigger product (must be in cart for the bundle to surface);
+  // productIds[1..] = offered together at the bundle discount.
+  triggerProductId: string;
+  productIds: string[];
+  // offeredProducts = productIds[1..] minus those already in cart, each with
+  // its own original/discounted price applied.
+  offeredProducts: CartBundleOfferOfferedProduct[];
   discountType: 'PERCENTAGE' | 'FIXED_AMOUNT';
-  discountValue: number;
-  requiresVariantSelection: boolean;
-  lockedVariant?: { id: string; name?: string };
+  discountValue: string;
+  totalOriginalPrice: string;
+  totalDiscountedPrice: string;
 }`;
 var INQUIRIES_TYPES = `// ---- Contact Inquiries & Forms ----
 
@@ -2984,6 +3406,7 @@ interface ContactFormPublicField {
   enumValues?: { value: string; label: string }[]; // present (non-empty) for SELECT / MULTI_SELECT
   validation?: ContactFormFieldValidation;
   defaultValue?: string;
+  width?: 'FULL' | 'HALF' | 'THIRD';           // layout hint \u2014 FULL = full row, HALF = half row, THIRD = one-third row
 }
 
 interface ContactFormPublic {
@@ -3015,6 +3438,19 @@ interface ContactFormSummary {
 //   MULTI_SELECT  \u2192 multiple <input type="checkbox">, value is string[]
 //   CHECKBOX      \u2192 single <input type="checkbox">, value is boolean
 // ------------------------------------------------------------------
+//
+// Layout: render fields inside a CSS grid container.
+//   width='FULL'  (default) \u2192 span entire row
+//   width='HALF'            \u2192 span half the row (two HALF fields sit side-by-side)
+//   width='THIRD'           \u2192 span one-third of the row (three THIRD fields sit side-by-side)
+// Use a 6-column grid for clean divisibility:
+//   FULL  \u2192 col-span-6 | HALF \u2192 col-span-3 | THIRD \u2192 col-span-2
+// Stack to full width on small screens (< sm breakpoint).
+//
+// Required fields: show a red asterisk (*) next to the label, validate
+// client-side before submission, and display inline error messages for
+// any empty required field. Do NOT rely only on the server returning 400.
+// ------------------------------------------------------------------
 
 // SDK methods
 //   await brainerce.createInquiry(input)              \u2192 POST /stores/{storeId}/inquiries
@@ -3027,6 +3463,130 @@ interface ContactFormSummary {
 // - Always pass \`locale\` \u2014 inbox filters inquiries by language, and schema labels come back translated
 // - Render \`schema.name\` / \`description\` / \`submitButton\` / \`successMessage\` directly \u2014 do NOT hardcode copy
 // - Unknown field keys are stripped server-side \u2014 safe to send extras during dev`;
+var MODIFIER_GROUPS_TYPES = `// ---- Modifier Groups (Restaurant / Build-Your-Own) ----
+// Modifier groups are merchant-defined option blocks attached to a product
+// (toppings, sauce, bread type, \u2026). They differ from product.customizationFields:
+// modifier groups are STRUCTURED priced choices validated server-side, while
+// customizationFields are arbitrary buyer input (text/photo/color).
+//
+// Money fields are decimal STRINGS on the wire \u2014 "5.00", "-2.00" (downsell).
+// Never JSON Number. Use parseFloat() only at display time. Do not compute
+// the line total client-side; the server runs free-allocation and returns
+// cart.items[i].unitPrice + .modifiers[] + .modifiersTotal.
+
+export type ModifierSelectionType = 'SINGLE' | 'MULTIPLE';
+
+export type FreeAllocationPolicy = 'EXPENSIVE_FREE' | 'CHEAPEST_FREE' | 'SELECTION_ORDER';
+
+export interface Modifier {
+  id: string;
+  name: string;
+  description?: string;
+  /** Decimal string. Negative values = downsell modifiers ("-2.00"). */
+  priceDelta: string;
+  sku?: string;
+  image?: { url: string; thumbnailUrl?: string; alt?: string };
+  position: number;
+  /** Pre-checked on first render. */
+  isDefault: boolean;
+  /** false = sold out \u2014 disable in UI with a "Sold out" badge. */
+  available: boolean;
+  /** When true, never applied as a free selection \u2014 always charges priceDelta even when freeQuantity > 0 on the group. */
+  excludeFromFree?: boolean;
+  /** Nested combo: opens a sub-flow; depth \u2264 3 enforced server-side. */
+  referencedProductId?: string;
+  translations?: Record<string, { name?: string; description?: string }>;
+}
+
+export interface ModifierGroup {
+  id: string;
+  /**
+   * Set when fetched in a product context (the ProductModifierGroup row id).
+   * Use this to update or detach the attachment without reattaching the group.
+   */
+  attachmentId?: string;
+  /** Customer-facing canonical name. */
+  name: string;
+  /**
+   * Admin-only disambiguator \u2014 NEVER present in storefront responses.
+   * If your client code reads this, you're hitting an admin endpoint by mistake.
+   */
+  internalName?: string;
+  description?: string;
+  selectionType: ModifierSelectionType;
+  /** Effective minimum after any per-attach / per-variant overrides. */
+  min: number;
+  /** Effective maximum; null = unlimited. **0 = group hidden for this variant** (PRD \xA77.2.2). */
+  max?: number | null;
+  freeQuantity: number;
+  required: boolean;
+  freeAllocationPolicy: FreeAllocationPolicy;
+  modifiers: Modifier[];
+  /** Effective default selections (after attachment-level overrides). */
+  defaultModifierIds: string[];
+  translations?: Record<string, { name?: string; description?: string }>;
+}
+
+/** Customer-side selection payload \u2014 modifierIds in click-order. */
+export interface ModifierSelection {
+  modifierGroupId: string;
+  modifierIds: string[];
+}
+
+/** Per-line modifier breakdown surfaced on cart.items[i] / order.items[i]. */
+export interface CartItemModifierLine {
+  modifierId: string;
+  /** Snapshot of the modifier's name at the time the line was added. */
+  name: string;
+  /** Decimal string snapshot of the priceDelta at the time the line was added. */
+  priceDelta: string;
+  /** True if this modifier consumed one of the group's free slots. */
+  freeApplied: boolean;
+}
+
+/**
+ * Stable error codes returned in the structured 400 envelope when a cart
+ * payload fails server-side validation. The SDK exposes the envelope on
+ * BrainerceError.details \u2014 switch on details.code === 'MODIFIER_VALIDATION_FAILED'
+ * first, then iterate details.errors[].
+ */
+export type ModifierValidationCode =
+  | 'REQUIRED_GROUP_MISSING'
+  | 'MIN_SELECTIONS_NOT_MET'
+  | 'MAX_SELECTIONS_EXCEEDED'
+  | 'SINGLE_GROUP_MULTIPLE_PICKS'
+  | 'UNKNOWN_MODIFIER'
+  | 'UNKNOWN_GROUP'
+  | 'MODIFIER_DISABLED_FOR_VARIANT'
+  | 'MODIFIER_NOT_AVAILABLE'
+  | 'NESTED_DEPTH_EXCEEDED'
+  | 'NESTED_REQUIRES_PRODUCT_REF'
+  | 'INVALID_PRICE_DELTA'
+  | 'MODIFIER_PRICE_FLOOR_VIOLATED';
+
+export interface ModifierValidationError {
+  code: ModifierValidationCode;
+  message: string;
+  modifierGroupId?: string;
+  modifierId?: string;
+}
+
+// Cart DTOs gain optional selections + nestedByModifierId \u2014 see CART_TYPES above.
+// Add to cart with selections:
+//
+//   await client.smartAddToCart({
+//     productId,
+//     variantId,
+//     quantity: 1,
+//     selections: [
+//       { modifierGroupId: 'mg_bread',    modifierIds: ['m_thick'] },
+//       { modifierGroupId: 'mg_toppings', modifierIds: ['m_olive', 'm_bacon'] },
+//     ],
+//   });
+//
+// 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 TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -3035,7 +3595,8 @@ var TYPES_BY_DOMAIN = {
   customers: CUSTOMERS_TYPES,
   payments: PAYMENTS_TYPES,
   helpers: HELPERS_TYPES,
-  inquiries: INQUIRIES_TYPES
+  inquiries: INQUIRIES_TYPES,
+  "modifier-groups": MODIFIER_GROUPS_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -3101,7 +3662,12 @@ var GET_CODE_EXAMPLE_SCHEMA = {
     "reservation-countdown",
     "search-autocomplete-debounce",
     "i18n-set-locale",
-    "order-history-full"
+    "order-history-full",
+    "modifier-groups-render",
+    "cart-add-with-selections",
+    "modifier-validation-error-handling",
+    "checkout-price-drift",
+    "cart-item-modifier-display"
   ]).describe("The SDK operation to get a snippet for.")
 };
 var SNIPPETS = {
@@ -3109,7 +3675,10 @@ var SNIPPETS = {
 import { BrainerceClient } from 'brainerce';
 
 export const client = new BrainerceClient({
-  connectionId: process.env.BRAINERCE_CONNECTION_ID!, // vc_*
+  // Read either env var name (the new one is preferred; the old one is a soft
+  // alias kept for backwards compatibility \u2014 both are accepted by the SDK).
+  salesChannelId:
+    process.env.BRAINERCE_SALES_CHANNEL_ID! ?? process.env.BRAINERCE_CONNECTION_ID!, // vc_*
 });
 
 // If the store has i18n enabled, set the locale at app start based on
@@ -3173,7 +3742,7 @@ function selectVariant(product: Product, selections: Record<string, string>) {
 import { client } from './brainerce';
 
 // 1. Submit the address + email. Email is REQUIRED on the DTO.
-const { shippingRates } = await client.setShippingAddress(checkoutId, {
+const { checkout, rates } = await client.setShippingAddress(checkoutId, {
   email,
   firstName,
   lastName,
@@ -3184,10 +3753,11 @@ const { shippingRates } = await client.setShippingAddress(checkoutId, {
   postalCode,
   country,
 });
+// rates = available shipping rates; checkout = updated checkout object
 
 // 2. Let the customer pick one of the returned rates.
-const chosen = shippingRates[0]; // user selection
-await client.setShippingMethod(checkoutId, chosen.id);
+const chosen = rates[0]; // user selection
+await client.selectShippingMethod(checkoutId, chosen.id);
 
 // 3. Re-fetch the checkout to get updated totals (tax may change after address).
 const checkout = await client.getCheckout(checkoutId);
@@ -3241,21 +3811,21 @@ if (providers.length === 0) {
 }
 
 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).
+  "checkout-stripe-confirm": `// Stripe confirm flow. Requires @stripe/stripe-js.
 import { loadStripe } from '@stripe/stripe-js';
 import { client } from './brainerce';
 
 const stripe = await loadStripe(stripePublicKey);
 if (!stripe) throw new Error('Stripe failed to load');
 
-// The SDK returns a clientSecret via the provider's config after setPaymentMethod.
-const { clientSecret } = await client.setPaymentMethod(checkoutId, {
-  providerId: stripeProvider.id,
+// Create a payment intent \u2014 returns clientSecret for Stripe Elements.
+const intent = await client.createPaymentIntent(checkoutId, {
+  successUrl: \`\${window.location.origin}/order-confirmation?checkoutId=\${checkoutId}\`,
+  cancelUrl: \`\${window.location.origin}/checkout?error=cancelled\`,
 });
 
-// Use Stripe Elements to collect the card, then confirm:
-const result = await stripe.confirmCardPayment(clientSecret, {
+// Use Stripe Elements to confirm:
+const result = await stripe.confirmCardPayment(intent.clientSecret, {
   payment_method: { card: cardElement },
 });
 
@@ -3264,21 +3834,21 @@ if (result.error) {
   return;
 }
 
-// Success \u2014 redirect to your confirmation page with checkoutId in the URL.
+// Success \u2014 redirect to confirmation page.
 // The confirmation page runs handlePaymentSuccess + waitForOrder.
 window.location.assign(\`/order-confirmation?checkoutId=\${checkoutId}\`);`,
   "checkout-paypal-confirm": `// PayPal confirm flow. Use the PayPal JS SDK (render a PayPal button component).
 import { client } from './brainerce';
 
-// When the PayPal button's onApprove fires with the PayPal order ID:
-async function onPayPalApprove(paypalOrderId: string) {
-  await client.setPaymentMethod(checkoutId, {
-    providerId: paypalProvider.id,
-    providerData: { paypalOrderId },
-  });
+// Create a payment intent first \u2014 for PayPal this returns the PayPal order ID.
+const intent = await client.createPaymentIntent(checkoutId, {
+  successUrl: \`\${window.location.origin}/order-confirmation?checkoutId=\${checkoutId}\`,
+  cancelUrl: \`\${window.location.origin}/checkout?error=cancelled\`,
+});
 
-  // PayPal confirmation \u2014 the SDK captures the order server-side.
-  // After this resolves, redirect to confirmation.
+// Render a PayPal button using intent.clientSdk (provider SDK config).
+// When the PayPal button's onApprove fires, redirect to confirmation:
+function onPayPalApprove() {
   window.location.assign(\`/order-confirmation?checkoutId=\${checkoutId}\`);
 }`,
   "checkout-sandbox-confirm": `// Sandbox payment \u2014 store has sandboxPaymentsEnabled=true. No real charge.
@@ -3321,7 +3891,7 @@ async function registerAndMaybeVerify(input: {
   firstName: string;
   lastName: string;
 }) {
-  const result = await client.register(input);
+  const result = await client.registerCustomer(input);
   if (result.requiresVerification) {
     // Route the user to your verify-email UI. Do NOT treat them as logged in.
     return { state: 'needs-verification' as const };
@@ -3342,7 +3912,7 @@ async function resendCode() {
 import { client } from './brainerce';
 
 async function login(email: string, password: string) {
-  const result = await client.login({ email, password });
+  const result = await client.loginCustomer(email, password);
   if (result.requiresVerification) {
     return { state: 'needs-verification' as const };
   }
@@ -3377,25 +3947,37 @@ async function submitReset(token: string, newPassword: string) {
   "oauth-redirect-and-callback": `// OAuth sign-in. Redirect flow, NOT popup.
 import { client } from './brainerce';
 
-// On your login / register UI:
-const providers = await client.getAvailableOAuthProviders();
-// Render one button per provider. On click, redirect the browser:
-for (const p of providers) {
-  // button.onclick = () => window.location.assign(p.authorizationUrl)
+// Step 1: Get available provider names (strings: 'GOOGLE', 'FACEBOOK', 'GITHUB')
+const { providers } = await client.getAvailableOAuthProviders();
+
+// Step 2: For each provider, fetch the authorization URL, then redirect.
+// Call this when the user clicks a provider button:
+async function redirectToOAuth(provider: string) {
+  const { authorizationUrl } = await client.getOAuthAuthorizeUrl(provider, {
+    redirectUrl: \`\${window.location.origin}/auth/callback\`,
+  });
+  window.location.href = authorizationUrl; // full-page redirect, NOT a popup
 }
 
-// On your OAuth callback route (SERVER-SIDE / BFF):
-// 1. Read token + oauth_success (or oauth_error) from query params.
-// 2. If oauth_error: redirect to login with the error message.
-// 3. If oauth_success: exchange the token for a session cookie (your BFF),
-//    then redirect the browser to /account or wherever.
-// Do NOT allow the token to land in browser history as a query param.`,
+// Step 3: On your /auth/callback route, read token from URL params:
+const params = new URLSearchParams(window.location.search);
+const oauthError = params.get('oauth_error');
+const token = params.get('token');
+if (oauthError) {
+  window.location.href = '/login?error=' + encodeURIComponent(oauthError);
+} else if (token) {
+  client.setCustomerToken(token);
+  window.location.href = '/account';
+}`,
   "coupon-apply-and-remove": `// Coupon input. Build the UI even if no coupons exist today \u2014 it auto-hides.
+// IMPORTANT: use applyCheckoutCoupon when a checkoutId is available (checkout page).
+// Using applyCoupon after checkout creation does NOT update the checkout total.
 import { client } from './brainerce';
 
-async function applyCoupon(code: string) {
+// On cart page (no checkout session yet)
+async function applyCouponToCart(cartId: string, code: string) {
   try {
-    const cart = await client.applyCoupon(code);
+    const cart = await client.applyCoupon(cartId, code);
     return { ok: true, cart };
   } catch (err) {
     // Invalid / expired / minimum not met. Surface the specific error.
@@ -3403,17 +3985,30 @@ async function applyCoupon(code: string) {
   }
 }
 
-async function removeCoupon() {
-  const cart = await client.removeCoupon();
-  return cart;
+async function removeCouponFromCart(cartId: string) {
+  return client.removeCoupon(cartId);
+}
+
+// On checkout page (checkout session already exists \u2014 always prefer this)
+async function applyCouponToCheckout(checkoutId: string, code: string) {
+  try {
+    const checkout = await client.applyCheckoutCoupon(checkoutId, code);
+    return { ok: true, checkout }; // checkout.total is already updated
+  } catch (err) {
+    return { ok: false, error: (err as Error).message };
+  }
+}
+
+async function removeCouponFromCheckout(checkoutId: string) {
+  return client.removeCheckoutCoupon(checkoutId);
 }`,
   "reservation-countdown": `// Reservation countdown. Use the SDK's expiry timestamp \u2014 do NOT invent
 // your own timer state.
 import { client } from './brainerce';
 
-function getRemainingMs(cart: { reservationExpiresAt?: string | null }): number {
-  if (!cart.reservationExpiresAt) return 0;
-  const expiry = new Date(cart.reservationExpiresAt).getTime();
+function getRemainingMs(cart: { reservation?: { expiresAt?: string } }): number {
+  if (!cart.reservation?.expiresAt) return 0;
+  const expiry = new Date(cart.reservation.expiresAt).getTime();
   return Math.max(0, expiry - Date.now());
 }
 
@@ -3440,8 +4035,8 @@ function onSearchChange(query: string, onResults: (items: unknown[]) => void) {
     return;
   }
   searchTimer = setTimeout(async () => {
-    const results = await client.searchProducts(query);
-    onResults(results);
+    const { products } = await client.getSearchSuggestions(query);
+    onResults(products);
   }, 300);
 }`,
   "i18n-set-locale": `// i18n \u2014 only if get-store-capabilities reports i18n.enabled.
@@ -3529,7 +4124,412 @@ for (const order of orders) {
 
 // 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.`
+// src/components/account/order-history.tsx is the reference implementation.`,
+  "modifier-groups-render": `// Render modifier groups on the product detail page (toppings / sauce /
+// build-your-own). The data lives on product.modifierGroups \u2014 only present
+// for restaurant / customizable products.
+import { useState } from 'react';
+import type { ModifierGroup, Product } from 'brainerce';
+
+function ModifierGroups({ product }: { product: Product }) {
+  const groups: ModifierGroup[] = product.modifierGroups ?? [];
+  if (groups.length === 0) return null; // not a customizable product
+
+  // Local state: selected modifier IDs per group, in click-order.
+  const [selections, setSelections] = useState<Record<string, string[]>>(() =>
+    buildInitialSelections(groups)
+  );
+
+  return (
+    <>
+      {groups.map((group) => {
+        // PRD \xA77.2.2: max === 0 means "hidden for this variant" \u2014 skip entirely.
+        if (group.max === 0) return null;
+
+        const isSingle = group.selectionType === 'SINGLE';
+        const inputType = isSingle ? 'radio' : 'checkbox';
+        const sorted = [...group.modifiers].sort((a, b) => a.position - b.position);
+        const picks = selections[group.id] ?? [];
+        const usedFree = Math.min(picks.length, group.freeQuantity);
+
+        const toggle = (modifierId: string, checked: boolean) => {
+          setSelections((prev) => {
+            const cur = prev[group.id] ?? [];
+            if (isSingle) return { ...prev, [group.id]: checked ? [modifierId] : [] };
+            if (checked) {
+              if (group.max != null && cur.length >= group.max) return prev; // at cap
+              return { ...prev, [group.id]: [...cur, modifierId] };
+            }
+            return { ...prev, [group.id]: cur.filter((id) => id !== modifierId) };
+          });
+        };
+
+        return (
+          <fieldset key={group.id}>
+            <legend>
+              {group.name}{group.required && ' *'}
+            </legend>
+            {group.freeQuantity > 0 && (
+              <p>{usedFree} of {group.freeQuantity} free</p>
+            )}
+            {sorted.map((m) => (
+              <label key={m.id}>
+                <input
+                  type={inputType}
+                  name={\`mg-\${group.id}\`}
+                  value={m.id}
+                  checked={picks.includes(m.id)}
+                  disabled={!m.available}
+                  onChange={(e) => toggle(m.id, e.target.checked)}
+                />
+                {m.name}
+                {parseFloat(m.priceDelta) !== 0 && (
+                  <span> {parseFloat(m.priceDelta) > 0 ? '+' : ''}{m.priceDelta}</span>
+                )}
+                {!m.available && <span> (Sold out)</span>}
+              </label>
+            ))}
+          </fieldset>
+        );
+      })}
+    </>
+  );
+}
+
+// Initial state: prefer per-attach defaultModifierIds; fall back to
+// modifier.isDefault flags. Filter sold-out modifiers.
+function buildInitialSelections(groups: ModifierGroup[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const group of groups) {
+    if (group.max === 0) continue;
+    const fromAttach = group.defaultModifierIds ?? [];
+    const fromIsDefault = group.modifiers
+      .filter((m) => m.isDefault && m.available)
+      .map((m) => m.id);
+    const merged =
+      fromAttach.length > 0
+        ? fromAttach.filter((id) => group.modifiers.some((m) => m.id === id && m.available))
+        : fromIsDefault;
+    const capped = group.selectionType === 'SINGLE' ? merged.slice(0, 1) : merged;
+    if (capped.length > 0) out[group.id] = capped;
+  }
+  return out;
+}
+
+// PRICE-DELTA RULES:
+// - "5.00"  \u2192 +$5 added to unit price
+// - "-2.00" \u2192 downsell: subtracts $2; never consumes a free slot
+// - "0.00"  \u2192 free option; render no price label
+// Server enforces unitPrice >= 0; rejects negative deltas combined with
+// referencedProductId. Do NOT compute the line total client-side \u2014 the
+// server runs free-allocation and returns cart.items[i].unitPrice.
+
+`,
+  "cart-add-with-selections": `// Pass modifier-group selections on add-to-cart. The server validates
+// against the effective rules and computes the final unitPrice (base +
+// paid modifiers, after the free-allocation policy runs).
+import { client } from './brainerce';
+import type { ModifierSelection } from 'brainerce';
+
+async function addPizzaToCart(
+  productId: string,
+  variantId: string,
+  selectionsByGroup: Record<string, string[]>
+) {
+  // Adapter: shape used in component state \u2192 wire format the SDK accepts.
+  const selections: ModifierSelection[] = Object.entries(selectionsByGroup)
+    .filter(([, modifierIds]) => modifierIds.length > 0)
+    .map(([modifierGroupId, modifierIds]) => ({ modifierGroupId, modifierIds }));
+
+  // modifierIds is in CLICK-ORDER \u2014 used by the SELECTION_ORDER free-allocation
+  // policy. Don't sort it; preserve the order the customer clicked.
+
+  const cart = await client.smartAddToCart({
+    productId,
+    variantId,
+    quantity: 1,
+    selections,
+  });
+
+  // Read the snapshot back off the new cart line.
+  const line = cart.items[cart.items.length - 1];
+  // line.modifiers  \u2192 CartItemModifierLine[] with { modifierId, name, priceDelta, freeApplied }
+  // line.modifiersTotal \u2192 decimal string of paid (non-free) deltas
+  // line.unitPrice  \u2192 final unit price including all paid modifiers
+  console.log('Free applied:', line.modifiers?.filter((m) => m.freeApplied).map((m) => m.name));
+}
+
+// EDITING SELECTIONS LATER (PRD \xA77.2.3 \u2014 idempotent replacement):
+// PATCH the cart item with a fresh selections array. The server deletes ALL
+// existing CartItemModifier rows and recreates them in the same transaction.
+// To leave selections untouched (e.g., quantity-only update), omit them.
+async function changeToppings(cartId: string, itemId: string, newToppingIds: string[]) {
+  await client.updateCartItem(cartId, itemId, {
+    quantity: 1,
+    selections: [{ modifierGroupId: 'mg_toppings', modifierIds: newToppingIds }],
+  });
+}
+
+// NESTED COMBOS (depth \u2264 3): when a picked modifier carries
+// referencedProductId, fetch that product's own modifierGroups, collect the
+// nested selections, and pass them keyed by the PARENT modifier id.
+async function addCombo(productId: string, mainBurger: string) {
+  await client.smartAddToCart({
+    productId,
+    quantity: 1,
+    selections: [
+      { modifierGroupId: 'mg_main',  modifierIds: [mainBurger] }, // the burger
+      { modifierGroupId: 'mg_drink', modifierIds: ['m_cola'] },
+    ],
+    nestedByModifierId: {
+      [mainBurger]: [
+        { modifierGroupId: 'mg_doneness', modifierIds: ['m_medium'] },
+        { modifierGroupId: 'mg_cheese',   modifierIds: ['m_cheddar'] },
+      ],
+    },
+  });
+}`,
+  "modifier-validation-error-handling": `// Surface MODIFIER_VALIDATION_FAILED to the user. The SDK throws
+// BrainerceError on HTTP 400; the structured envelope is on .details.
+import { client } from './brainerce';
+import type { ModifierSelection } from 'brainerce';
+
+interface ModifierValidationError {
+  code:
+    | 'REQUIRED_GROUP_MISSING'
+    | 'MIN_SELECTIONS_NOT_MET'
+    | 'MAX_SELECTIONS_EXCEEDED'
+    | 'SINGLE_GROUP_MULTIPLE_PICKS'
+    | 'UNKNOWN_MODIFIER'
+    | 'UNKNOWN_GROUP'
+    | 'MODIFIER_DISABLED_FOR_VARIANT'
+    | 'MODIFIER_NOT_AVAILABLE'
+    | 'NESTED_DEPTH_EXCEEDED'
+    | 'NESTED_REQUIRES_PRODUCT_REF'
+    | 'INVALID_PRICE_DELTA'
+    | 'MODIFIER_PRICE_FLOOR_VIOLATED';
+  message: string;
+  modifierGroupId?: string;
+  modifierId?: string;
+}
+
+async function tryAddToCart(productId: string, selections: ModifierSelection[]) {
+  try {
+    await client.smartAddToCart({ productId, quantity: 1, selections });
+    return { ok: true as const };
+  } catch (err) {
+    const e = err as {
+      statusCode?: number;
+      details?: { code?: string; errors?: ModifierValidationError[] };
+    };
+
+    if (e.statusCode === 400 && e.details?.code === 'MODIFIER_VALIDATION_FAILED') {
+      // Surface each issue inline. groupId / modifierId let you highlight the
+      // specific control the customer needs to fix.
+      const issues = e.details.errors ?? [];
+      const messages = issues.map((i) => formatIssue(i));
+      return { ok: false as const, issues, messages };
+    }
+
+    // Some other error (network, 500, etc.) \u2014 re-throw to a generic handler.
+    throw err;
+  }
+}
+
+function formatIssue(issue: ModifierValidationError): string {
+  switch (issue.code) {
+    case 'REQUIRED_GROUP_MISSING':
+      return 'Please pick at least one option from this group.';
+    case 'MIN_SELECTIONS_NOT_MET':
+    case 'MAX_SELECTIONS_EXCEEDED':
+    case 'SINGLE_GROUP_MULTIPLE_PICKS':
+      return issue.message; // server's message already says "Pick at least N" / "Pick at most N"
+    case 'UNKNOWN_MODIFIER':
+    case 'UNKNOWN_GROUP':
+    case 'MODIFIER_DISABLED_FOR_VARIANT':
+    case 'MODIFIER_NOT_AVAILABLE':
+      // The catalog moved under us \u2014 refetch the product and ask the customer
+      // to re-pick. These codes mean the option simply isn't valid anymore.
+      return 'This option is no longer available \u2014 please refresh.';
+    case 'NESTED_DEPTH_EXCEEDED':
+    case 'NESTED_REQUIRES_PRODUCT_REF':
+      return issue.message; // bug in your renderer \u2014 never go past 3 levels
+    case 'INVALID_PRICE_DELTA':
+      return issue.message; // shouldn't happen for SDK callers \u2014 server-validated on save
+    case 'MODIFIER_PRICE_FLOOR_VIOLATED':
+      // The server reports a generic message \u2014 internals never leak. Show a
+      // friendly error and let the customer remove a downsell.
+      return 'Cannot apply more discounts on this item.';
+  }
+}
+
+// CLIENT-SIDE PRE-FLIGHT (UX):
+// You can mirror these checks before calling addToCart to give faster
+// feedback, but the SERVER is authoritative. Always treat the 400 envelope
+// as the source of truth.
+function preflightSelections(
+  groups: { id: string; name: string; min: number; max?: number | null; required: boolean; selectionType: 'SINGLE' | 'MULTIPLE'; }[],
+  selections: Record<string, string[]>
+): string | null {
+  for (const g of groups) {
+    if (g.max === 0) continue; // disabled-for-variant
+    const picks = selections[g.id] ?? [];
+    if (g.required && picks.length === 0) return \`\${g.name} is required\`;
+    if (picks.length < g.min) return \`Pick at least \${g.min} from \${g.name}\`;
+    if (g.max != null && picks.length > g.max) return \`Pick at most \${g.max} from \${g.name}\`;
+    if (g.selectionType === 'SINGLE' && picks.length > 1) return \`Only one option allowed in \${g.name}\`;
+  }
+  return null;
+}`,
+  "checkout-price-drift": `// PRICE_DRIFT \u2014 a product's price changed between add-to-cart and checkout.
+// The server returns HTTP 400 with code "PRICE_DRIFT" when it detects that
+// the stored unitPrice no longer matches the live price.
+//
+// Strategy: catch the error \u2192 show "prices updated" dialog \u2192
+// call refreshCartSnapshots() to re-snapshot all live prices \u2192
+// retry createCheckout once.
+
+import { client } from './brainerce-client';
+
+interface CheckoutOptions {
+  cartId: string;
+}
+
+async function createCheckoutSafe(opts: CheckoutOptions) {
+  try {
+    // createCheckout only takes cartId (+ optional customerId, selectedItemIds).
+    // Shipping address, shipping method, and payment are set via separate calls.
+    return await client.createCheckout({ cartId: opts.cartId });
+  } catch (err: unknown) {
+    if (!isApiError(err, 'PRICE_DRIFT')) throw err;
+
+    // Prices changed \u2014 refresh snapshots then retry once.
+    // refreshCartSnapshots updates every cart item's unitPrice to the current
+    // live price (base price + any modifier deltas) so the next checkout call
+    // will pass the drift guard.
+    await client.refreshCartSnapshots(opts.cartId);
+
+    // After refreshing, re-fetch the cart so your UI shows the updated prices
+    // before you retry, giving the customer a chance to review.
+    const updatedCart = await client.getCart(opts.cartId);
+
+    // Signal to the UI layer that prices changed so it can show a dialog.
+    throw Object.assign(new Error('PRICES_UPDATED'), {
+      code: 'PRICES_UPDATED',
+      updatedCart,
+    });
+  }
+}
+
+function isApiError(err: unknown, code: string): boolean {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'code' in err &&
+    (err as { code: string }).code === code
+  );
+}
+
+// --- UI integration example (framework-neutral) ---
+//
+// async function handlePlaceOrder() {
+//   try {
+//     const checkout = await createCheckoutSafe({ cartId, ... });
+//     router.push(\`/order-confirmation?checkoutId=\${checkout.id}\`);
+//   } catch (err: unknown) {
+//     if (isApiError(err, 'PRICES_UPDATED')) {
+//       const { updatedCart } = err as { updatedCart: Cart };
+//       showPricesUpdatedDialog(updatedCart); // show diff, let user confirm
+//       return;
+//     }
+//     showGenericError(err);
+//   }
+// }
+//
+// The dialog should:
+//   1. Show which items changed price (compare old vs new unitPrice)
+//   2. Offer "Continue with new prices" (calls createCheckoutSafe again)
+//      and "Go back to cart" (returns to cart page)
+//   3. NOT silently retry \u2014 the customer must acknowledge the price change.`,
+  "cart-item-modifier-display": `// Rendering cart items that have modifier selections.
+// Each cart item has a \`modifiers\` array \u2014 each entry records the modifier
+// name, the price delta at time of add-to-cart, and whether it was free
+// (inside the group's freeQuantity allowance).
+//
+// Typical display:
+//   Margherita                         \u20AA45.00
+//     Extra cheese +\u20AA5.00
+//     Mushrooms     free
+//     No onions     \u2014
+//   \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+//   Base \u20AA45.00 + Modifiers \u20AA5.00 = \u20AA50.00
+
+import { formatPrice } from 'brainerce';
+
+interface CartItemModifier {
+  modifierId: string;
+  name: string;
+  priceDeltaAtTime: number; // in store currency units, e.g. 5.00
+  freeApplied: boolean;     // true when inside the group's freeQuantity
+}
+
+interface CartItem {
+  id: string;
+  name: string;
+  unitPrice: number;        // base + all chargeable modifier deltas, as stored
+  quantity: number;
+  modifiers?: CartItemModifier[];
+  currency: string;         // e.g. 'ILS', 'USD'
+}
+
+function renderCartItem(item: CartItem): string {
+  const currency = item.currency;
+  const lines: string[] = [];
+
+  lines.push(\`\${item.name}  \${formatPrice(item.unitPrice, { currency })}\`);
+
+  const chargeableModifiers = (item.modifiers ?? []).filter(
+    (m) => !m.freeApplied && m.priceDeltaAtTime !== 0
+  );
+  const freeModifiers = (item.modifiers ?? []).filter((m) => m.freeApplied);
+  const zeroModifiers = (item.modifiers ?? []).filter(
+    (m) => !m.freeApplied && m.priceDeltaAtTime === 0
+  );
+
+  for (const m of chargeableModifiers) {
+    const sign = m.priceDeltaAtTime > 0 ? '+' : '';
+    lines.push(\`  \${m.name}  \${sign}\${formatPrice(m.priceDeltaAtTime, { currency })}\`);
+  }
+  for (const m of freeModifiers) {
+    lines.push(\`  \${m.name}  free\`);
+  }
+  for (const m of zeroModifiers) {
+    lines.push(\`  \${m.name}  \u2014\`);
+  }
+
+  // Price breakdown: only show when there are chargeable modifiers
+  const modifiersTotal = chargeableModifiers.reduce(
+    (sum, m) => sum + m.priceDeltaAtTime,
+    0
+  );
+  if (modifiersTotal !== 0) {
+    // unitPrice already includes modifiers \u2014 derive base for display only
+    const basePrice = item.unitPrice - modifiersTotal;
+    const base = formatPrice(basePrice, { currency }) as string;
+    const mods = formatPrice(modifiersTotal, { currency }) as string;
+    const total = formatPrice(item.unitPrice, { currency }) as string;
+    lines.push(\`Base \${base} + Modifiers \${mods} = \${total}\`);
+  }
+
+  return lines.join('\\n');
+}
+
+// IMPORTANT: unitPrice already includes all chargeable modifier deltas.
+// Do NOT add modifier prices on top of unitPrice when computing line totals \u2014
+// multiply unitPrice \xD7 quantity directly.
+function lineTotal(item: CartItem): number {
+  return item.unitPrice * item.quantity;
+}`
 };
 async function handleGetCodeExample(args) {
   const snippet = SNIPPETS[args.operation];
@@ -3645,13 +4645,27 @@ function getCandidateApiUrls() {
 
 // src/tools/get-store-info.ts
 var GET_STORE_INFO_NAME = "get-store-info";
-var GET_STORE_INFO_DESCRIPTION = "Fetch live store information from the Brainerce API using a connection ID. Returns the channel display name (what the user sees in their dashboard), parent store name, currency, and language. Use this to personalize the store being built \u2014 prefer the channel name for user-facing text since a single Brainerce store can have multiple sales channels.";
+var GET_STORE_INFO_DESCRIPTION = "Fetch live store information from the Brainerce API using a sales channel ID. Returns the channel display name (what the user sees in their dashboard), parent store name, currency, and language. Use this to personalize the store being built \u2014 prefer the channel name for user-facing text since a single Brainerce store can have multiple sales channels.";
 var GET_STORE_INFO_SCHEMA = {
-  connectionId: import_zod4.z.string().describe("Vibe-coded connection ID (starts with vc_)")
+  salesChannelId: import_zod4.z.string().optional().describe("Sales channel ID (starts with vc_)"),
+  /** @deprecated alias of salesChannelId */
+  connectionId: import_zod4.z.string().optional().describe("Deprecated alias of salesChannelId \u2014 kept for backwards compat")
 };
 async function handleGetStoreInfo(args) {
+  const id = args.salesChannelId ?? args.connectionId;
+  if (!id) {
+    return {
+      content: [{ type: "text", text: "Error: salesChannelId is required" }],
+      isError: true
+    };
+  }
+  if (!args.salesChannelId && args.connectionId) {
+    console.warn(
+      "get-store-info: `connectionId` is deprecated \u2014 use `salesChannelId` instead"
+    );
+  }
   try {
-    const resolved = await resolveStoreInfo(args.connectionId, getCandidateApiUrls());
+    const resolved = await resolveStoreInfo(id, getCandidateApiUrls());
     return {
       content: [
         {
@@ -3664,7 +4678,8 @@ async function handleGetStoreInfo(args) {
               storeName: resolved.info.storeName,
               currency: resolved.info.currency,
               language: resolved.info.language,
-              connectionId: args.connectionId,
+              salesChannelId: id,
+              connectionId: id,
               apiBaseUrl: resolved.apiBaseUrl
             },
             null,
@@ -3749,9 +4764,11 @@ async function resolveStoreCapabilities(connectionId, candidateUrls) {
 
 // src/tools/get-store-capabilities.ts
 var GET_STORE_CAPABILITIES_NAME = "get-store-capabilities";
-var GET_STORE_CAPABILITIES_DESCRIPTION = "Get live store capabilities and configured features for a vibe-coded connection. Returns what payment providers, OAuth, shipping, discounts, and other features are set up. Use this to discover what your store supports and what pages/components to build.";
+var GET_STORE_CAPABILITIES_DESCRIPTION = "Get live store capabilities and configured features for a sales channel. Returns what payment providers, OAuth, shipping, discounts, and other features are set up. Use this to discover what your store supports and what pages/components to build.";
 var GET_STORE_CAPABILITIES_SCHEMA = {
-  connectionId: import_zod5.z.string().describe("Vibe-coded connection ID (starts with vc_)")
+  salesChannelId: import_zod5.z.string().optional().describe("Sales channel ID (starts with vc_)"),
+  /** @deprecated alias of salesChannelId */
+  connectionId: import_zod5.z.string().optional().describe("Deprecated alias of salesChannelId \u2014 kept for backwards compat")
 };
 function formatCapabilities(caps) {
   const lines = [];
@@ -3864,15 +4881,27 @@ function formatCapabilities(caps) {
   }
   if (suggestions.length === 0) {
     suggestions.push(
-      "Start by building the required features. Use get-required-features with this connectionId for the checklist."
+      "Start by building the required features. Use get-required-features with this salesChannelId for the checklist."
     );
   }
   suggestions.forEach((s) => lines.push(`- ${s}`));
   return lines.join("\n");
 }
 async function handleGetStoreCapabilities(args) {
+  const id = args.salesChannelId ?? args.connectionId;
+  if (!id) {
+    return {
+      content: [{ type: "text", text: "Error: salesChannelId is required" }],
+      isError: true
+    };
+  }
+  if (!args.salesChannelId && args.connectionId) {
+    console.warn(
+      "get-store-capabilities: `connectionId` is deprecated \u2014 use `salesChannelId` instead"
+    );
+  }
   try {
-    const resolved = await resolveStoreCapabilities(args.connectionId, getCandidateApiUrls());
+    const resolved = await resolveStoreCapabilities(id, getCandidateApiUrls());
     return {
       content: [{ type: "text", text: formatCapabilities(resolved.capabilities) }]
     };
@@ -3977,7 +5006,7 @@ var RULES = {
   tokens: {
     title: "Auth tokens & BFF pattern",
     body: `- NEVER store customer auth tokens in \`localStorage\` directly from client code. Use a Backend-For-Frontend proxy: the server receives the token, sets an HttpOnly cookie, and the client reads session state from an endpoint like \`/api/auth/me\`.
-- NEVER put the admin API key (\`brainerce_*\`) in client code. It is a server-only secret. Client code uses \`connectionId\` or storefront endpoints.
+- NEVER put the admin API key (\`brainerce_*\`) in client code. It is a server-only secret. Client code uses \`salesChannelId\` (or the deprecated \`connectionId\` alias) or storefront endpoints.
 - OAuth callbacks arrive with the token in URL params. Extract it SERVER-side and exchange it for a session cookie before redirecting to the app. Do not let the token land in browser history.
 - On logout, clear the BFF session server-side. A client-only logout that forgets to tell the server leaves an active session on the server until it expires.`
   },
@@ -4045,21 +5074,21 @@ var FLOWS = {
 1. **Collect address + email.** Build a form that captures customer email, billing address, shipping address (with \`line1\`, \`line2\`, \`city\`, \`region\`, \`postalCode\`, \`country\`). \`email\` is REQUIRED on \`SetShippingAddressDto\`.
 2. **Submit the address to get shipping rates.**
    \`\`\`ts
-   const { shippingRates } = await client.setShippingAddress(checkoutId, {
+   const { checkout, rates } = await client.setShippingAddress(checkoutId, {
      email,
      firstName,
      lastName,
      line1, line2, city, region, postalCode, country,
    });
    \`\`\`
-   The response includes the available shipping rates for that address + the store's zones.
+   \`rates\` = available shipping rates for that address + the store's zones. \`checkout\` = updated checkout object.
 3. **Let the customer pick a rate**, then persist the selection:
    \`\`\`ts
-   await client.setShippingMethod(checkoutId, rateId);
+   await client.selectShippingMethod(checkoutId, rateId);
    \`\`\`
-4. **Fetch payment providers for this checkout:**
+4. **Fetch payment providers:**
    \`\`\`ts
-   const providers = await client.getPaymentProviders(checkoutId);
+   const providers = await client.getPaymentProviders();
    \`\`\`
    The response tells you which providers are configured (Stripe, Grow, PayPal, Sandbox) and how to render each. Each provider has a \`renderType\` telling you whether to show a Stripe Elements form, a redirect button, a PayPal button, or a sandbox "complete test order" button.
 5. **Confirm payment using the provider's recommended flow.** For Stripe: Stripe Elements \u2192 \`stripe.confirmCardPayment\` using the clientSecret returned by the SDK. For sandbox payments: call \`completeGuestCheckout(checkoutId)\` directly. For PayPal/Grow: follow the redirect and handle the return on your confirmation page.
@@ -4075,28 +5104,28 @@ Never bypass these steps. Never call \`submitGuestOrder\` / \`createOrder\` \u20
   "auth-register": {
     title: "Registration",
     body: `1. **Collect** email, password, first name, last name. Enforce strong passwords client-side: 8+ chars, upper, lower, number, special.
-2. **Call register:**
+2. **Call registerCustomer:**
    \`\`\`ts
-   const result = await client.register({ email, password, firstName, lastName });
+   const result = await client.registerCustomer({ email, password, firstName, lastName });
    \`\`\`
 3. **Branch on \`result.requiresVerification\`:**
-   - If \`true\`: route the user to your verify-email UI. Do NOT treat them as logged in yet.
-   - If \`false\`: the user is logged in. Store the token via your BFF session and route to the account area.
+   - If \`true\`: store the token temporarily (e.g. sessionStorage), route the user to your verify-email UI. Do NOT treat them as logged in yet.
+   - If \`false\`: call \`client.setCustomerToken(result.token)\` and route to the account area.
 4. **On the verify-email step:** collect a 6-digit code and call \`client.verifyEmail(code)\`. Offer a "resend code" button wired to \`client.resendVerificationEmail()\`.
-5. **After verifyEmail resolves:** the user is now logged in. Persist the session via your BFF and route to the account area.
+5. **After verifyEmail resolves:** call \`client.setCustomerToken(result.token)\` \u2014 the user is now logged in \u2014 then route to the account area.
 
 Build the verify-email step EVEN IF the store currently has verification disabled. It auto-hides; store owners enable it later.`
   },
   "auth-login": {
     title: "Login",
     body: `1. **Collect** email + password.
-2. **Call login:**
+2. **Call loginCustomer:**
    \`\`\`ts
-   const result = await client.login({ email, password });
+   const result = await client.loginCustomer(email, password);
    \`\`\`
 3. **Branch on \`result.requiresVerification\`:**
    - If \`true\`: route to verify-email. The user must complete verification before accessing account features.
-   - If \`false\`: persist the session via your BFF and route to the previous page (or account area).
+   - If \`false\`: call \`client.setCustomerToken(result.token)\` and route to the previous page (or account area).
 4. **Offer OAuth buttons** from \`client.getAvailableOAuthProviders()\`. Render a placeholder region even when no providers are returned \u2014 the region auto-hides today and shows buttons the moment a provider is enabled in the dashboard.
 5. **On error**, render the specific message (invalid credentials, rate limited, account disabled) \u2014 never swallow.`
   },
@@ -4121,15 +5150,24 @@ Build both steps EVEN IF the store has no email provider configured today \u2014
   },
   oauth: {
     title: "OAuth sign-in",
-    body: `1. **Render available providers:**
+    body: `1. **Get available provider names:**
    \`\`\`ts
-   const providers = await client.getAvailableOAuthProviders();
+   const { providers } = await client.getAvailableOAuthProviders();
+   // providers = ['GOOGLE', 'FACEBOOK', 'GITHUB'] (strings, not objects with authorizationUrl)
    \`\`\`
-   Each provider has \`{ provider: 'GOOGLE' | 'FACEBOOK' | 'GITHUB', authorizationUrl }\`.
-2. **Build a button for each** that redirects the browser to \`authorizationUrl\`. Do NOT open a popup; the full-page redirect is required.
-3. **On the provider's side** the user authenticates, and the provider redirects back to your OAuth callback URL with \`token\` + \`oauth_success\` (or \`oauth_error\`) query params.
-4. **The callback handler MUST run server-side (BFF).** Extract the token from the query params, exchange it for a session cookie via your BFF, then redirect the browser to the account area. Never let the token land in browser history as a query param or localStorage.
-5. **On \`oauth_error\`:** redirect to login with an error message.
+2. **For each provider, fetch the authorization URL:**
+   \`\`\`ts
+   const { authorizationUrl } = await client.getOAuthAuthorizeUrl(provider, {
+     redirectUrl: \`\${window.location.origin}/auth/callback\`,
+   });
+   window.location.href = authorizationUrl; // full-page redirect, NOT a popup
+   \`\`\`
+3. **On the callback page** the URL contains \`token\` + \`oauth_success\` (or \`oauth_error\`) query params. Extract and apply the token:
+   \`\`\`ts
+   const token = new URLSearchParams(location.search).get('token');
+   if (token) client.setCustomerToken(token); // then redirect to account
+   \`\`\`
+4. **On \`oauth_error\`:** redirect to login with an error message.
 
 Build the OAuth button region AND the callback handler even when no providers are configured. They auto-hide.`
   },
@@ -4151,7 +5189,7 @@ Build the OAuth button region AND the callback handler even when no providers ar
 
 - **Cart ID persistence:** the SDK stores the cart ID across reloads. You do not need to write cart-to-localStorage code yourself.
 - **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.
+- **Writes:** use \`client.addToCart\`, \`client.updateCartItem\`, \`client.removeCartItem\`, \`client.applyCoupon\`, \`client.removeCoupon\`. After each mutation the SDK returns the updated cart. On the **checkout page** use \`client.applyCheckoutCoupon(checkoutId, code)\` / \`client.removeCheckoutCoupon(checkoutId)\` \u2014 these update checkout totals atomically. Never use \`applyCoupon\` after a checkout session exists.
 - **Totals:** call \`getCartTotals(cart)\` \u2014 do NOT read \`cart.total\`. The helper understands taxes, shipping, and discounts.
 - **\`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.`
@@ -4270,18 +5308,20 @@ ${flow.body}`
 // src/tools/get-required-features.ts
 var import_zod9 = require("zod");
 var GET_REQUIRED_FEATURES_NAME = "get-required-features";
-var GET_REQUIRED_FEATURES_DESCRIPTION = "Get the functional coverage checklist for a Brainerce store. Returns user-capability-level features (what users must be able to do) rather than pages or file paths. Every feature marked mandatory must exist in the finished build, even when the underlying capability is currently disabled \u2014 those features auto-hide and store owners enable them later. Pass a connectionId to tune the checklist to the live store; without it, returns the generic complete-store checklist.";
+var GET_REQUIRED_FEATURES_DESCRIPTION = "Get the functional coverage checklist for a Brainerce store. Returns user-capability-level features (what users must be able to do) rather than pages or file paths. Every feature marked mandatory must exist in the finished build, even when the underlying capability is currently disabled \u2014 those features auto-hide and store owners enable them later. Pass a salesChannelId to tune the checklist to the live store; without it, returns the generic complete-store checklist.";
 var GET_REQUIRED_FEATURES_SCHEMA = {
-  connectionId: import_zod9.z.string().optional().describe(
-    "Vibe-coded connection ID (starts with vc_). Optional \u2014 without it, returns the generic checklist."
-  )
+  salesChannelId: import_zod9.z.string().optional().describe(
+    "Sales channel ID (starts with vc_). Optional \u2014 without it, returns the generic checklist."
+  ),
+  /** @deprecated alias of salesChannelId */
+  connectionId: import_zod9.z.string().optional().describe("Deprecated alias of salesChannelId \u2014 kept for backwards compat")
 };
 var FEATURES = [
   {
     id: "browse-products",
     title: "Browse, filter, and search products",
-    description: "Users can list products with pagination, apply category / price / attribute filters, sort by name / price / newest, and run a search with autocomplete. Must handle empty states and loading states.",
-    sdk: "client.getProducts({ page, limit, filters, sort }), client.searchProducts(query)",
+    description: "Users can list products with pagination, apply category / price / attribute / custom-field filters, sort by name / price / newest, and run a search with autocomplete. Custom-field filters surface metafield definitions whose filterable=true (SELECT, MULTI_SELECT, BOOLEAN). Must handle empty states and loading states.",
+    sdk: "client.getProducts({ page, limit, filters, sort, metafields }), client.getPublicMetafieldDefinitions(), client.getSearchSuggestions(query)",
     mandatory: "mandatory"
   },
   {
@@ -4311,7 +5351,7 @@ var FEATURES = [
     id: "cart-coupons",
     title: "Apply and remove coupon codes",
     description: "Users can enter a coupon code, see it applied to the cart, see the discount amount, and remove it. Build the UI even if no coupons are configured today \u2014 it auto-hides.",
-    sdk: "client.applyCoupon(code), client.removeCoupon()",
+    sdk: "client.applyCoupon(cartId, code), client.removeCoupon(cartId) \u2014 on cart page. client.applyCheckoutCoupon(checkoutId, code), client.removeCheckoutCoupon(checkoutId) \u2014 on checkout page (use when checkoutId exists)",
     mandatory: "mandatory",
     capabilityFlag: "hasCoupons",
     whenDisabledNote: "Store has no coupons configured today. Build the UI anyway \u2014 it auto-hides until the store owner creates a coupon."
@@ -4328,7 +5368,7 @@ var FEATURES = [
     id: "checkout",
     title: "Complete a full checkout end-to-end",
     description: "Users can enter their address, pick a shipping rate, pick a payment provider, pay, and land on a confirmation page showing the real order. Displays checkout.lineItems (not cart.items) on the summary.",
-    sdk: "client.setShippingAddress, client.setShippingMethod, client.getPaymentProviders, provider-specific confirm, client.handlePaymentSuccess, client.waitForOrder",
+    sdk: "client.setShippingAddress (returns { checkout, rates }), client.selectShippingMethod, client.getPaymentProviders(), provider-specific confirm, client.handlePaymentSuccess, client.waitForOrder",
     flowRef: "checkout",
     mandatory: "mandatory"
   },
@@ -4344,7 +5384,7 @@ var FEATURES = [
     id: "register",
     title: "Register a new account with email verification",
     description: 'Users can create an account (email, password, first + last name). Handles the requiresVerification branch by routing to an email-verification step. Verification step collects a 6-digit code and has a "resend code" action.',
-    sdk: "client.register({email, password, firstName, lastName}), client.verifyEmail(code), client.resendVerificationEmail()",
+    sdk: "client.registerCustomer({email, password, firstName, lastName}), client.verifyEmail(code), client.resendVerificationEmail()",
     flowRef: "auth-register",
     mandatory: "mandatory",
     capabilityFlag: "oauth",
@@ -4354,7 +5394,7 @@ var FEATURES = [
     id: "login",
     title: "Log in with email / password and handle verification branch",
     description: "Users can log in. The login form handles the requiresVerification branch by routing to the verify-email step. Specific errors render (bad credentials, rate limited, disabled account).",
-    sdk: "client.login({email, password})",
+    sdk: "client.loginCustomer(email, password)",
     flowRef: "auth-login",
     mandatory: "mandatory"
   },
@@ -4387,14 +5427,14 @@ var FEATURES = [
     id: "header",
     title: "Global header with cart count and search",
     description: "A header visible across the experience with the store logo, navigation, a cart icon with live item count, a search input with autocomplete (debounced ~300ms, 2-char minimum), and a login / account action. Below the header, discount banners render when active.",
-    sdk: "client.getCart() for the count, client.searchProducts(query) for autocomplete",
+    sdk: "client.getCart() for the count, client.getSearchSuggestions(query) for autocomplete",
     mandatory: "mandatory"
   },
   {
     id: "discount-banners",
     title: "Show active discount banners and badges",
     description: "Active discount rules render as banners (below the header) and as badges on product cards / detail pages. Build the UI even if the store has no active discounts today \u2014 it auto-hides.",
-    sdk: "client.getDiscountBanners(), getProductDiscountBadge(product)",
+    sdk: "client.getDiscountBanners(), client.getProductDiscountBadge(productId)",
     mandatory: "mandatory",
     capabilityFlag: "hasDiscountRules",
     whenDisabledNote: "Store has no discount rules active. Build the banner and badge components anyway \u2014 they auto-hide."
@@ -4496,10 +5536,16 @@ function renderCapabilitiesSummary(caps) {
   return lines.join("\n");
 }
 async function handleGetRequiredFeatures(args) {
+  const id = args.salesChannelId ?? args.connectionId;
+  if (!args.salesChannelId && args.connectionId) {
+    console.warn(
+      "get-required-features: `connectionId` is deprecated \u2014 use `salesChannelId` instead"
+    );
+  }
   let caps = null;
-  if (args.connectionId) {
+  if (id) {
     try {
-      const resolved = await resolveStoreCapabilities(args.connectionId, getCandidateApiUrls());
+      const resolved = await resolveStoreCapabilities(id, getCandidateApiUrls());
       caps = resolved.capabilities;
     } catch {
       caps = null;
@@ -4511,11 +5557,11 @@ async function handleGetRequiredFeatures(args) {
   );
   if (caps) {
     sections.push(renderCapabilitiesSummary(caps));
-  } else if (args.connectionId) {
+  } else if (id) {
     sections.push(
       `## Live store capabilities
 
-Could not fetch live capabilities for \`${args.connectionId}\`. Proceeding with the generic checklist. Call \`get-store-capabilities\` separately if you want a targeted checklist.`
+Could not fetch live capabilities for \`${id}\`. Proceeding with the generic checklist. Call \`get-store-capabilities\` separately if you want a targeted checklist.`
     );
   }
   sections.push("## Features");