@brainerce/mcp-server 3.11.0 → 3.12.0

package/dist/bin/http.js

@@ -163,7 +163,26 @@ import {
   getDescriptionContent, isHtmlDescription,
   getProductMetafieldValue, getProductCustomizationFields,
 } from 'brainerce';
-\`\`\``;
+\`\`\`
+
+### Available features \u2014 request each topic for full docs
+
+| Topic | What it covers |
+|-------|----------------|
+| \`products\` | Catalog listing, search, PDP, variants, swatches, stock, attributes |
+| \`cart\` | Guest + logged-in cart, add/remove/update, reservations |
+| \`checkout\` | Guest + customer checkout, shipping, address |
+| \`payment\` | Payment providers, intents, status polling, confirmation |
+| \`auth\` | Customer sign-up, login, OAuth, email verification |
+| \`discounts\` | Coupons, banners, nudges |
+| \`recommendations\` | Cross-sell / upsell grids |
+| \`reviews\` | Product reviews & ratings |
+| \`inventory\` | Stock badges, reservation countdown |
+| \`inquiries\` | Contact / custom forms |
+| \`i18n\` | Multi-language, RTL |
+| \`admin\` | Server-to-server admin API (products, orders, customers) |
+| \`storefront-bot\` | **AI chat widget** \u2014 add Brainerce's AI shopping assistant to any page with one script tag or \`BrainerceBot.mount()\`. Answers product questions, shows recommendation cards, handles cart adds, opens escalation form. |
+| \`content\` | Blog, articles, static pages |`;
 }
 function getCheckoutFlowSection(_currency) {
   return `## \u26A0\uFE0F CHECKOUT FLOW (CRITICAL \u2014 READ CAREFULLY!)
@@ -1885,8 +1904,8 @@ function getTaxDisplaySection(_currency) {
 | Product Page | \u274C No | "Price excludes tax" (optional note) |
 | Cart Page | \u26A0\uFE0F "Calculated at checkout" | No address yet |
 | Checkout (before address) | \u26A0\uFE0F "Enter address to calculate" | Waiting for location |
-| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` |
-| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` |
+| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` (0 in VAT mode \u2192 \`checkout.taxBreakdown.totalTax\`) |
+| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` (0 in VAT mode \u2192 \`order.taxBreakdown.totalTax\`) |
 
 ### Cart Page \u2014 Partial Display
 
@@ -1938,7 +1957,13 @@ const totals = getCartTotals(cart);
     <div className="flex justify-between text-green-600"><span>Discount</span><span>-{formatPrice(order.discountAmount, { currency: order.currency })}</span></div>
   )}
   <div className="flex justify-between"><span>Shipping</span><span>{formatPrice(order.shippingAmount, { currency: order.currency })}</span></div>
-  <div className="flex justify-between"><span>Tax</span><span>{formatPrice(order.taxAmount, { currency: order.currency })}</span></div>
+  {/* Inclusive (VAT) stores keep taxAmount="0" \u2014 the real VAT is on taxBreakdown.totalTax. */}
+  {(() => {
+    const tax = parseFloat(order.taxAmount || '0') || order.taxBreakdown?.totalTax || 0;
+    if (tax <= 0) return null;
+    const incl = order.taxBreakdown?.pricesIncludeTax;
+    return <div className="flex justify-between"><span>{incl ? 'Tax (incl.)' : 'Tax'}</span><span>{formatPrice(tax, { currency: order.currency })}</span></div>;
+  })()}
   <div className="flex justify-between font-bold text-lg border-t pt-2"><span>Total Paid</span><span>{formatPrice(order.totalAmount, { currency: order.currency })}</span></div>
 </div>
 \`\`\``;
@@ -2067,7 +2092,7 @@ A useful order card includes ALL of the following when the data is present. Each
 | **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
 | **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
 | Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
-| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. |
+| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. In VAT-inclusive mode \`taxAmount\` is 0 \u2014 read \`order.taxBreakdown.totalTax\` and label "Tax (incl.)". |
 
 #### Rendering \`order.items[i].customizations\` by type
 
@@ -2512,8 +2537,9 @@ await admin.createTaxRate({ name: 'VAT (Food)', rate: 0, country: 'GB', taxClass
 await admin.mergeTaxClasses(food.id, standardClassId);
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreTaxClasses()\` lists
-the store's classes (storefront-safe fields only) for a transparency badge.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreTaxClasses()\`
+lists the store's classes (storefront-safe fields only) for a transparency badge.
 
 For a buyer-facing tax preview on PDP / PLP / cart, \`estimateTax({ country,
 subtotal })\` returns the tax portion at the Standard rate for the buyer's
@@ -2535,8 +2561,10 @@ A region binds countries \u2192 currency + tax-display mode + enabled payment
 providers. Manage them via the SDK (scopes \`regions:read\` / \`regions:write\`).
 \`detectRegion\` is a pure client-side helper to map a buyer's country to a
 region; pass the resolved \`regionId\` to \`createCheckout\` to associate the
-checkout with a region (recorded for reporting + provider scoping; currency
-follows the cart until FX price conversion lands).
+checkout with a region (recorded for reporting + provider scoping). FX-at-checkout:
+presentment-enabled regions (Stripe today) charge in the region currency and the
+checkout response carries a \`presentment\` overlay with the charged amounts;
+otherwise the checkout is charged in the store base currency.
 
 \`\`\`typescript
 const eu = await admin.createRegion({
@@ -2549,9 +2577,12 @@ const { data: regions } = await admin.getRegions();
 const region = admin.detectRegion('DE', regions); // \u2192 eu, else default, else null
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreRegions()\` lists
-active regions, \`getStoreRegion(id)\` returns one region + its payment providers.
-Pair with \`detectRegion\` to pick the buyer's region for currency display.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreRegions()\`
+lists active regions, \`getStoreRegion(id)\` returns one region + its payment
+providers. \`getAutoRegion(country)\` and \`estimateTax({ country, subtotal })\` work
+in both modes too. Pair with \`detectRegion\` to pick the buyer's region for
+currency display.
 
 \`\`\`typescript
 const store = new BrainerceClient({ storeId: 'store_123' });
@@ -3175,6 +3206,38 @@ Rules:
   count updates when the bot adds items.
 `;
 }
+function getStorefrontAnalyticsSection(connectionId) {
+  return `## Storefront Traffic Analytics (visits, countries, sources)
+
+Brainerce can track cookieless storefront traffic \u2014 how many people visit the
+store, from which countries, and from which traffic sources \u2014 and surface it in
+the merchant dashboard alongside sales (so the merchant gets a REAL conversion
+rate: visits \u2192 orders).
+
+Add ONE line to the storefront's root layout (\`<head>\` or end of \`<body>\`):
+
+\`\`\`html
+<script defer src="https://api.brainerce.com/t.js" data-channel="${connectionId}"></script>
+\`\`\`
+
+That's it \u2014 the pixel auto-sends a pageview beacon on load and on SPA route
+changes. Stores scaffolded with \`create-brainerce-store\` already include it.
+
+Privacy: the pixel is cookieless and stores NO personal data \u2014 no cookie, no
+cross-site/cross-day tracking, and the visitor IP is resolved to a country
+server-side then discarded. No cookie-consent banner is required for it under
+GDPR/ePrivacy.
+
+CSP: if the storefront sets a Content-Security-Policy, allow the script + beacon:
+- \`script-src\` \u2026 \`https://api.brainerce.com\`
+- \`connect-src\` \u2026 \`https://api.brainerce.com\`
+
+The merchant can toggle tracking per sales channel in the dashboard. The data
+shows up under Dashboard \u2192 Analytics (visits over time, by country, by source,
+by device) and can also be asked of the AI assistant ("how many visits did I get
+this month and from where?").
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3231,6 +3294,9 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getBlogSection();
     case "storefront-bot":
       return getStorefrontBotSection(cid);
+    case "analytics":
+    case "traffic-analytics":
+      return getStorefrontAnalyticsSection(cid);
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3299,6 +3365,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getStorefrontAnalyticsSection(cid),
+        "",
+        "---",
+        "",
         getProductCustomizationFieldsSection(),
         "",
         "---",
@@ -3368,6 +3438,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inquiries",
     "content",
     "storefront-bot",
+    "analytics",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: import_zod.z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -3405,7 +3476,7 @@ interface Product {
   priceMin?: string | null;  // Lowest variant price (VARIABLE products) \u2014 same as basePrice for VARIABLE, kept for back-compat and JSON-LD range display.
   priceMax?: string | null;  // Highest variant price (VARIABLE products). Use with priceMin for "\u20AA49 \u2013 \u20AA199" range.
   priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
-  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive, display-only. The buyer is still charged in store currency at checkout; payment provider handles customer-side FX.
+  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive. For presentment-enabled regions (Stripe) the displayPrice uses the same buffered rate the checkout charges (browsed == checkout); for display-only regions it is mid-market and the buyer is charged in store currency at checkout (payment provider handles customer-side FX).
   displayPrice?: string;        // basePrice \xD7 daily FX rate, in displayCurrency.
   displaySalePrice?: string;    // salePrice \xD7 rate (if salePrice present).
   displayPriceMin?: string;     // priceMin \xD7 rate (VARIABLE products).
@@ -3659,7 +3730,7 @@ interface Checkout {
   status: CheckoutStatus;
   email?: string | null;
   customerId?: string | null;
-  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping (currency follows the cart until FX lands)
+  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping. FX-at-checkout: presentment-enabled regions (Stripe) charge in the region currency \u2014 see the presentment field below; else charged in store base currency
   shippingAddress?: CheckoutAddress | null;
   billingAddress?: CheckoutAddress | null;
   shippingRateId?: string | null;
@@ -3679,6 +3750,18 @@ interface Checkout {
   itemCount: number;
   availableShippingRates?: ShippingRate[];
   reservation?: ReservationInfo;
+  // FX-at-checkout: present ONLY when the region charges in its own currency (presentment-enabled \u2014 Stripe today). The amounts the buyer is actually CHARGED, in presentment.currency; presentment.total equals the payment intent amount. Render these (not total/currency above) when present. Absent = charged in store base currency. The fields above stay the base reference.
+  presentment?: {
+    currency: string;        // ISO-4217 charged currency, e.g. "EUR"
+    subtotal: string;
+    discountAmount: string;
+    shippingAmount: string;
+    taxAmount: string;
+    surchargeAmount: string;
+    total: string;           // equals the charged amount, to the cent
+    fxChargingRate: string;  // base\u2192presentment rate (buffer included)
+    fxBufferPercent: string | null;
+  };
   createdAt: string;
   updatedAt: string;
 }
@@ -3770,6 +3853,8 @@ interface Order {
   totalAmount: string;   // ALWAYS use this, not .total
   total?: string;        // optional alias
   currency?: string;
+  taxAmount?: string | null;       // 0 in inclusive (VAT) mode \u2014 read taxBreakdown.totalTax
+  taxBreakdown?: TaxBreakdown | null;  // carries the included VAT when prices include tax
   customer?: OrderCustomer | null;
   items: OrderItem[];
   itemCount?: number;
@@ -4054,10 +4139,22 @@ interface CartAppliedDiscount {
 }
 
 // Recommendation types
+interface RecommendationVariant {
+  id: string; name?: string; price?: string; salePrice?: string;
+  attributes?: Record<string, string>; image?: ProductImage | string; inventory?: InventoryInfo;
+}
 interface ProductRecommendation {
-  id: string; name: string; slug: string; basePrice: string; salePrice?: string;
+  id: string; name: string; slug: string;
+  // For a VARIABLE target, basePrice is the pinned variant's price (when
+  // targetVariantId is set) or the "from {min variant}" range \u2014 never 0.
+  basePrice: string; salePrice?: string;
   images: ProductImage[]; type: 'SIMPLE' | 'VARIABLE'; inventory?: InventoryInfo;
   relationType: string;
+  // Variant context (VARIABLE targets):
+  targetVariantId?: string | null;        // merchant-pinned variant, or null
+  requiresVariantSelection?: boolean;      // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];      // present when requiresVariantSelection
 }
 interface ProductRecommendationsResponse {
   crossSells: ProductRecommendation[];
@@ -4091,6 +4188,12 @@ interface CartBundleOfferOfferedProduct {
   salePrice: string | null;
   images: Array<{ url: string }>;
   type: string;
+  // Variant context (VARIABLE offered products):
+  variantId?: string | null;               // merchant-pinned variant for this slot
+  requiresVariantSelection?: boolean;       // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];       // present when requiresVariantSelection
+  // originalPrice = pinned/cheapest variant price for VARIABLE (not a 0 parent base).
   originalPrice: string;
   discountedPrice: string;
 }
@@ -4574,10 +4677,12 @@ interface UpdateRegionDto extends Partial<CreateRegionDto> { isActive?: boolean
 // client.detectRegion(country, regions): Region | null  \u2014 pure, no network.
 //   \u2192 region whose countries includes the code, else the default region, else null.
 // Pass the resolved regionId to createCheckout to associate the checkout with a
-// region (recorded for reporting + provider scoping; currency follows the cart
-// until FX price conversion lands).
+// region (recorded for reporting + provider scoping). FX-at-checkout:
+// presentment-enabled regions (Stripe) charge in the region currency and the
+// response carries a presentment overlay; else charged in store base currency.
 //
-// Storefront (public, no apiKey \u2014 storeId mode):
+// Storefront (public, no apiKey \u2014 storeId mode OR vibe-coded mode, salesChannelId 'vc_*';
+// the vc routes are gated on products:read, which every connection already has):
 interface PublicRegion {
   id: string; name: string; slug: string; currency: string;
   countries: string[]; taxInclusive: boolean; isDefault: boolean;
@@ -4629,7 +4734,8 @@ interface AssignTaxClassDto { productIds?: string[]; variantIds?: string[]; cate
 //                deleteTaxClass(id), setDefaultTaxClass(id), assignTaxClass(id, dto),
 //                mergeTaxClasses(id, targetId)
 //
-// SDK methods (storefront, public \u2014 storeId mode, no apiKey):
+// SDK methods (storefront, public \u2014 storeId mode OR vibe-coded mode 'vc_*', no apiKey;
+// the vc routes are gated on products:read, which every connection already has):
 //   getStoreRegions(), getStoreRegion(id), getAutoRegion(country)
 //   getStoreTaxClasses(), estimateTax({ country?, subtotal })
 //

package/dist/bin/stdio.js

@@ -160,7 +160,26 @@ import {
   getDescriptionContent, isHtmlDescription,
   getProductMetafieldValue, getProductCustomizationFields,
 } from 'brainerce';
-\`\`\``;
+\`\`\`
+
+### Available features \u2014 request each topic for full docs
+
+| Topic | What it covers |
+|-------|----------------|
+| \`products\` | Catalog listing, search, PDP, variants, swatches, stock, attributes |
+| \`cart\` | Guest + logged-in cart, add/remove/update, reservations |
+| \`checkout\` | Guest + customer checkout, shipping, address |
+| \`payment\` | Payment providers, intents, status polling, confirmation |
+| \`auth\` | Customer sign-up, login, OAuth, email verification |
+| \`discounts\` | Coupons, banners, nudges |
+| \`recommendations\` | Cross-sell / upsell grids |
+| \`reviews\` | Product reviews & ratings |
+| \`inventory\` | Stock badges, reservation countdown |
+| \`inquiries\` | Contact / custom forms |
+| \`i18n\` | Multi-language, RTL |
+| \`admin\` | Server-to-server admin API (products, orders, customers) |
+| \`storefront-bot\` | **AI chat widget** \u2014 add Brainerce's AI shopping assistant to any page with one script tag or \`BrainerceBot.mount()\`. Answers product questions, shows recommendation cards, handles cart adds, opens escalation form. |
+| \`content\` | Blog, articles, static pages |`;
 }
 function getCheckoutFlowSection(_currency) {
   return `## \u26A0\uFE0F CHECKOUT FLOW (CRITICAL \u2014 READ CAREFULLY!)
@@ -1882,8 +1901,8 @@ function getTaxDisplaySection(_currency) {
 | Product Page | \u274C No | "Price excludes tax" (optional note) |
 | Cart Page | \u26A0\uFE0F "Calculated at checkout" | No address yet |
 | Checkout (before address) | \u26A0\uFE0F "Enter address to calculate" | Waiting for location |
-| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` |
-| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` |
+| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` (0 in VAT mode \u2192 \`checkout.taxBreakdown.totalTax\`) |
+| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` (0 in VAT mode \u2192 \`order.taxBreakdown.totalTax\`) |
 
 ### Cart Page \u2014 Partial Display
 
@@ -1935,7 +1954,13 @@ const totals = getCartTotals(cart);
     <div className="flex justify-between text-green-600"><span>Discount</span><span>-{formatPrice(order.discountAmount, { currency: order.currency })}</span></div>
   )}
   <div className="flex justify-between"><span>Shipping</span><span>{formatPrice(order.shippingAmount, { currency: order.currency })}</span></div>
-  <div className="flex justify-between"><span>Tax</span><span>{formatPrice(order.taxAmount, { currency: order.currency })}</span></div>
+  {/* Inclusive (VAT) stores keep taxAmount="0" \u2014 the real VAT is on taxBreakdown.totalTax. */}
+  {(() => {
+    const tax = parseFloat(order.taxAmount || '0') || order.taxBreakdown?.totalTax || 0;
+    if (tax <= 0) return null;
+    const incl = order.taxBreakdown?.pricesIncludeTax;
+    return <div className="flex justify-between"><span>{incl ? 'Tax (incl.)' : 'Tax'}</span><span>{formatPrice(tax, { currency: order.currency })}</span></div>;
+  })()}
   <div className="flex justify-between font-bold text-lg border-t pt-2"><span>Total Paid</span><span>{formatPrice(order.totalAmount, { currency: order.currency })}</span></div>
 </div>
 \`\`\``;
@@ -2064,7 +2089,7 @@ A useful order card includes ALL of the following when the data is present. Each
 | **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
 | **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
 | Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
-| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. |
+| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. In VAT-inclusive mode \`taxAmount\` is 0 \u2014 read \`order.taxBreakdown.totalTax\` and label "Tax (incl.)". |
 
 #### Rendering \`order.items[i].customizations\` by type
 
@@ -2509,8 +2534,9 @@ await admin.createTaxRate({ name: 'VAT (Food)', rate: 0, country: 'GB', taxClass
 await admin.mergeTaxClasses(food.id, standardClassId);
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreTaxClasses()\` lists
-the store's classes (storefront-safe fields only) for a transparency badge.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreTaxClasses()\`
+lists the store's classes (storefront-safe fields only) for a transparency badge.
 
 For a buyer-facing tax preview on PDP / PLP / cart, \`estimateTax({ country,
 subtotal })\` returns the tax portion at the Standard rate for the buyer's
@@ -2532,8 +2558,10 @@ A region binds countries \u2192 currency + tax-display mode + enabled payment
 providers. Manage them via the SDK (scopes \`regions:read\` / \`regions:write\`).
 \`detectRegion\` is a pure client-side helper to map a buyer's country to a
 region; pass the resolved \`regionId\` to \`createCheckout\` to associate the
-checkout with a region (recorded for reporting + provider scoping; currency
-follows the cart until FX price conversion lands).
+checkout with a region (recorded for reporting + provider scoping). FX-at-checkout:
+presentment-enabled regions (Stripe today) charge in the region currency and the
+checkout response carries a \`presentment\` overlay with the charged amounts;
+otherwise the checkout is charged in the store base currency.
 
 \`\`\`typescript
 const eu = await admin.createRegion({
@@ -2546,9 +2574,12 @@ const { data: regions } = await admin.getRegions();
 const region = admin.detectRegion('DE', regions); // \u2192 eu, else default, else null
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreRegions()\` lists
-active regions, \`getStoreRegion(id)\` returns one region + its payment providers.
-Pair with \`detectRegion\` to pick the buyer's region for currency display.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreRegions()\`
+lists active regions, \`getStoreRegion(id)\` returns one region + its payment
+providers. \`getAutoRegion(country)\` and \`estimateTax({ country, subtotal })\` work
+in both modes too. Pair with \`detectRegion\` to pick the buyer's region for
+currency display.
 
 \`\`\`typescript
 const store = new BrainerceClient({ storeId: 'store_123' });
@@ -3172,6 +3203,38 @@ Rules:
   count updates when the bot adds items.
 `;
 }
+function getStorefrontAnalyticsSection(connectionId) {
+  return `## Storefront Traffic Analytics (visits, countries, sources)
+
+Brainerce can track cookieless storefront traffic \u2014 how many people visit the
+store, from which countries, and from which traffic sources \u2014 and surface it in
+the merchant dashboard alongside sales (so the merchant gets a REAL conversion
+rate: visits \u2192 orders).
+
+Add ONE line to the storefront's root layout (\`<head>\` or end of \`<body>\`):
+
+\`\`\`html
+<script defer src="https://api.brainerce.com/t.js" data-channel="${connectionId}"></script>
+\`\`\`
+
+That's it \u2014 the pixel auto-sends a pageview beacon on load and on SPA route
+changes. Stores scaffolded with \`create-brainerce-store\` already include it.
+
+Privacy: the pixel is cookieless and stores NO personal data \u2014 no cookie, no
+cross-site/cross-day tracking, and the visitor IP is resolved to a country
+server-side then discarded. No cookie-consent banner is required for it under
+GDPR/ePrivacy.
+
+CSP: if the storefront sets a Content-Security-Policy, allow the script + beacon:
+- \`script-src\` \u2026 \`https://api.brainerce.com\`
+- \`connect-src\` \u2026 \`https://api.brainerce.com\`
+
+The merchant can toggle tracking per sales channel in the dashboard. The data
+shows up under Dashboard \u2192 Analytics (visits over time, by country, by source,
+by device) and can also be asked of the AI assistant ("how many visits did I get
+this month and from where?").
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3228,6 +3291,9 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getBlogSection();
     case "storefront-bot":
       return getStorefrontBotSection(cid);
+    case "analytics":
+    case "traffic-analytics":
+      return getStorefrontAnalyticsSection(cid);
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3296,6 +3362,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getStorefrontAnalyticsSection(cid),
+        "",
+        "---",
+        "",
         getProductCustomizationFieldsSection(),
         "",
         "---",
@@ -3365,6 +3435,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inquiries",
     "content",
     "storefront-bot",
+    "analytics",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: import_zod.z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -3402,7 +3473,7 @@ interface Product {
   priceMin?: string | null;  // Lowest variant price (VARIABLE products) \u2014 same as basePrice for VARIABLE, kept for back-compat and JSON-LD range display.
   priceMax?: string | null;  // Highest variant price (VARIABLE products). Use with priceMin for "\u20AA49 \u2013 \u20AA199" range.
   priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
-  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive, display-only. The buyer is still charged in store currency at checkout; payment provider handles customer-side FX.
+  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive. For presentment-enabled regions (Stripe) the displayPrice uses the same buffered rate the checkout charges (browsed == checkout); for display-only regions it is mid-market and the buyer is charged in store currency at checkout (payment provider handles customer-side FX).
   displayPrice?: string;        // basePrice \xD7 daily FX rate, in displayCurrency.
   displaySalePrice?: string;    // salePrice \xD7 rate (if salePrice present).
   displayPriceMin?: string;     // priceMin \xD7 rate (VARIABLE products).
@@ -3656,7 +3727,7 @@ interface Checkout {
   status: CheckoutStatus;
   email?: string | null;
   customerId?: string | null;
-  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping (currency follows the cart until FX lands)
+  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping. FX-at-checkout: presentment-enabled regions (Stripe) charge in the region currency \u2014 see the presentment field below; else charged in store base currency
   shippingAddress?: CheckoutAddress | null;
   billingAddress?: CheckoutAddress | null;
   shippingRateId?: string | null;
@@ -3676,6 +3747,18 @@ interface Checkout {
   itemCount: number;
   availableShippingRates?: ShippingRate[];
   reservation?: ReservationInfo;
+  // FX-at-checkout: present ONLY when the region charges in its own currency (presentment-enabled \u2014 Stripe today). The amounts the buyer is actually CHARGED, in presentment.currency; presentment.total equals the payment intent amount. Render these (not total/currency above) when present. Absent = charged in store base currency. The fields above stay the base reference.
+  presentment?: {
+    currency: string;        // ISO-4217 charged currency, e.g. "EUR"
+    subtotal: string;
+    discountAmount: string;
+    shippingAmount: string;
+    taxAmount: string;
+    surchargeAmount: string;
+    total: string;           // equals the charged amount, to the cent
+    fxChargingRate: string;  // base\u2192presentment rate (buffer included)
+    fxBufferPercent: string | null;
+  };
   createdAt: string;
   updatedAt: string;
 }
@@ -3767,6 +3850,8 @@ interface Order {
   totalAmount: string;   // ALWAYS use this, not .total
   total?: string;        // optional alias
   currency?: string;
+  taxAmount?: string | null;       // 0 in inclusive (VAT) mode \u2014 read taxBreakdown.totalTax
+  taxBreakdown?: TaxBreakdown | null;  // carries the included VAT when prices include tax
   customer?: OrderCustomer | null;
   items: OrderItem[];
   itemCount?: number;
@@ -4051,10 +4136,22 @@ interface CartAppliedDiscount {
 }
 
 // Recommendation types
+interface RecommendationVariant {
+  id: string; name?: string; price?: string; salePrice?: string;
+  attributes?: Record<string, string>; image?: ProductImage | string; inventory?: InventoryInfo;
+}
 interface ProductRecommendation {
-  id: string; name: string; slug: string; basePrice: string; salePrice?: string;
+  id: string; name: string; slug: string;
+  // For a VARIABLE target, basePrice is the pinned variant's price (when
+  // targetVariantId is set) or the "from {min variant}" range \u2014 never 0.
+  basePrice: string; salePrice?: string;
   images: ProductImage[]; type: 'SIMPLE' | 'VARIABLE'; inventory?: InventoryInfo;
   relationType: string;
+  // Variant context (VARIABLE targets):
+  targetVariantId?: string | null;        // merchant-pinned variant, or null
+  requiresVariantSelection?: boolean;      // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];      // present when requiresVariantSelection
 }
 interface ProductRecommendationsResponse {
   crossSells: ProductRecommendation[];
@@ -4088,6 +4185,12 @@ interface CartBundleOfferOfferedProduct {
   salePrice: string | null;
   images: Array<{ url: string }>;
   type: string;
+  // Variant context (VARIABLE offered products):
+  variantId?: string | null;               // merchant-pinned variant for this slot
+  requiresVariantSelection?: boolean;       // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];       // present when requiresVariantSelection
+  // originalPrice = pinned/cheapest variant price for VARIABLE (not a 0 parent base).
   originalPrice: string;
   discountedPrice: string;
 }
@@ -4571,10 +4674,12 @@ interface UpdateRegionDto extends Partial<CreateRegionDto> { isActive?: boolean
 // client.detectRegion(country, regions): Region | null  \u2014 pure, no network.
 //   \u2192 region whose countries includes the code, else the default region, else null.
 // Pass the resolved regionId to createCheckout to associate the checkout with a
-// region (recorded for reporting + provider scoping; currency follows the cart
-// until FX price conversion lands).
+// region (recorded for reporting + provider scoping). FX-at-checkout:
+// presentment-enabled regions (Stripe) charge in the region currency and the
+// response carries a presentment overlay; else charged in store base currency.
 //
-// Storefront (public, no apiKey \u2014 storeId mode):
+// Storefront (public, no apiKey \u2014 storeId mode OR vibe-coded mode, salesChannelId 'vc_*';
+// the vc routes are gated on products:read, which every connection already has):
 interface PublicRegion {
   id: string; name: string; slug: string; currency: string;
   countries: string[]; taxInclusive: boolean; isDefault: boolean;
@@ -4626,7 +4731,8 @@ interface AssignTaxClassDto { productIds?: string[]; variantIds?: string[]; cate
 //                deleteTaxClass(id), setDefaultTaxClass(id), assignTaxClass(id, dto),
 //                mergeTaxClasses(id, targetId)
 //
-// SDK methods (storefront, public \u2014 storeId mode, no apiKey):
+// SDK methods (storefront, public \u2014 storeId mode OR vibe-coded mode 'vc_*', no apiKey;
+// the vc routes are gated on products:read, which every connection already has):
 //   getStoreRegions(), getStoreRegion(id), getAutoRegion(country)
 //   getStoreTaxClasses(), estimateTax({ country?, subtotal })
 //

package/dist/index.js

@@ -186,7 +186,26 @@ import {
   getDescriptionContent, isHtmlDescription,
   getProductMetafieldValue, getProductCustomizationFields,
 } from 'brainerce';
-\`\`\``;
+\`\`\`
+
+### Available features \u2014 request each topic for full docs
+
+| Topic | What it covers |
+|-------|----------------|
+| \`products\` | Catalog listing, search, PDP, variants, swatches, stock, attributes |
+| \`cart\` | Guest + logged-in cart, add/remove/update, reservations |
+| \`checkout\` | Guest + customer checkout, shipping, address |
+| \`payment\` | Payment providers, intents, status polling, confirmation |
+| \`auth\` | Customer sign-up, login, OAuth, email verification |
+| \`discounts\` | Coupons, banners, nudges |
+| \`recommendations\` | Cross-sell / upsell grids |
+| \`reviews\` | Product reviews & ratings |
+| \`inventory\` | Stock badges, reservation countdown |
+| \`inquiries\` | Contact / custom forms |
+| \`i18n\` | Multi-language, RTL |
+| \`admin\` | Server-to-server admin API (products, orders, customers) |
+| \`storefront-bot\` | **AI chat widget** \u2014 add Brainerce's AI shopping assistant to any page with one script tag or \`BrainerceBot.mount()\`. Answers product questions, shows recommendation cards, handles cart adds, opens escalation form. |
+| \`content\` | Blog, articles, static pages |`;
 }
 function getCheckoutFlowSection(_currency) {
   return `## \u26A0\uFE0F CHECKOUT FLOW (CRITICAL \u2014 READ CAREFULLY!)
@@ -1908,8 +1927,8 @@ function getTaxDisplaySection(_currency) {
 | Product Page | \u274C No | "Price excludes tax" (optional note) |
 | Cart Page | \u26A0\uFE0F "Calculated at checkout" | No address yet |
 | Checkout (before address) | \u26A0\uFE0F "Enter address to calculate" | Waiting for location |
-| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` |
-| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` |
+| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` (0 in VAT mode \u2192 \`checkout.taxBreakdown.totalTax\`) |
+| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` (0 in VAT mode \u2192 \`order.taxBreakdown.totalTax\`) |
 
 ### Cart Page \u2014 Partial Display
 
@@ -1961,7 +1980,13 @@ const totals = getCartTotals(cart);
     <div className="flex justify-between text-green-600"><span>Discount</span><span>-{formatPrice(order.discountAmount, { currency: order.currency })}</span></div>
   )}
   <div className="flex justify-between"><span>Shipping</span><span>{formatPrice(order.shippingAmount, { currency: order.currency })}</span></div>
-  <div className="flex justify-between"><span>Tax</span><span>{formatPrice(order.taxAmount, { currency: order.currency })}</span></div>
+  {/* Inclusive (VAT) stores keep taxAmount="0" \u2014 the real VAT is on taxBreakdown.totalTax. */}
+  {(() => {
+    const tax = parseFloat(order.taxAmount || '0') || order.taxBreakdown?.totalTax || 0;
+    if (tax <= 0) return null;
+    const incl = order.taxBreakdown?.pricesIncludeTax;
+    return <div className="flex justify-between"><span>{incl ? 'Tax (incl.)' : 'Tax'}</span><span>{formatPrice(tax, { currency: order.currency })}</span></div>;
+  })()}
   <div className="flex justify-between font-bold text-lg border-t pt-2"><span>Total Paid</span><span>{formatPrice(order.totalAmount, { currency: order.currency })}</span></div>
 </div>
 \`\`\``;
@@ -2090,7 +2115,7 @@ A useful order card includes ALL of the following when the data is present. Each
 | **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
 | **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
 | Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
-| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. |
+| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. In VAT-inclusive mode \`taxAmount\` is 0 \u2014 read \`order.taxBreakdown.totalTax\` and label "Tax (incl.)". |
 
 #### Rendering \`order.items[i].customizations\` by type
 
@@ -2535,8 +2560,9 @@ await admin.createTaxRate({ name: 'VAT (Food)', rate: 0, country: 'GB', taxClass
 await admin.mergeTaxClasses(food.id, standardClassId);
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreTaxClasses()\` lists
-the store's classes (storefront-safe fields only) for a transparency badge.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreTaxClasses()\`
+lists the store's classes (storefront-safe fields only) for a transparency badge.
 
 For a buyer-facing tax preview on PDP / PLP / cart, \`estimateTax({ country,
 subtotal })\` returns the tax portion at the Standard rate for the buyer's
@@ -2558,8 +2584,10 @@ A region binds countries \u2192 currency + tax-display mode + enabled payment
 providers. Manage them via the SDK (scopes \`regions:read\` / \`regions:write\`).
 \`detectRegion\` is a pure client-side helper to map a buyer's country to a
 region; pass the resolved \`regionId\` to \`createCheckout\` to associate the
-checkout with a region (recorded for reporting + provider scoping; currency
-follows the cart until FX price conversion lands).
+checkout with a region (recorded for reporting + provider scoping). FX-at-checkout:
+presentment-enabled regions (Stripe today) charge in the region currency and the
+checkout response carries a \`presentment\` overlay with the charged amounts;
+otherwise the checkout is charged in the store base currency.
 
 \`\`\`typescript
 const eu = await admin.createRegion({
@@ -2572,9 +2600,12 @@ const { data: regions } = await admin.getRegions();
 const region = admin.detectRegion('DE', regions); // \u2192 eu, else default, else null
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreRegions()\` lists
-active regions, \`getStoreRegion(id)\` returns one region + its payment providers.
-Pair with \`detectRegion\` to pick the buyer's region for currency display.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreRegions()\`
+lists active regions, \`getStoreRegion(id)\` returns one region + its payment
+providers. \`getAutoRegion(country)\` and \`estimateTax({ country, subtotal })\` work
+in both modes too. Pair with \`detectRegion\` to pick the buyer's region for
+currency display.
 
 \`\`\`typescript
 const store = new BrainerceClient({ storeId: 'store_123' });
@@ -3198,6 +3229,38 @@ Rules:
   count updates when the bot adds items.
 `;
 }
+function getStorefrontAnalyticsSection(connectionId) {
+  return `## Storefront Traffic Analytics (visits, countries, sources)
+
+Brainerce can track cookieless storefront traffic \u2014 how many people visit the
+store, from which countries, and from which traffic sources \u2014 and surface it in
+the merchant dashboard alongside sales (so the merchant gets a REAL conversion
+rate: visits \u2192 orders).
+
+Add ONE line to the storefront's root layout (\`<head>\` or end of \`<body>\`):
+
+\`\`\`html
+<script defer src="https://api.brainerce.com/t.js" data-channel="${connectionId}"></script>
+\`\`\`
+
+That's it \u2014 the pixel auto-sends a pageview beacon on load and on SPA route
+changes. Stores scaffolded with \`create-brainerce-store\` already include it.
+
+Privacy: the pixel is cookieless and stores NO personal data \u2014 no cookie, no
+cross-site/cross-day tracking, and the visitor IP is resolved to a country
+server-side then discarded. No cookie-consent banner is required for it under
+GDPR/ePrivacy.
+
+CSP: if the storefront sets a Content-Security-Policy, allow the script + beacon:
+- \`script-src\` \u2026 \`https://api.brainerce.com\`
+- \`connect-src\` \u2026 \`https://api.brainerce.com\`
+
+The merchant can toggle tracking per sales channel in the dashboard. The data
+shows up under Dashboard \u2192 Analytics (visits over time, by country, by source,
+by device) and can also be asked of the AI assistant ("how many visits did I get
+this month and from where?").
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3254,6 +3317,9 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getBlogSection();
     case "storefront-bot":
       return getStorefrontBotSection(cid);
+    case "analytics":
+    case "traffic-analytics":
+      return getStorefrontAnalyticsSection(cid);
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3322,6 +3388,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getStorefrontAnalyticsSection(cid),
+        "",
+        "---",
+        "",
         getProductCustomizationFieldsSection(),
         "",
         "---",
@@ -3391,6 +3461,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inquiries",
     "content",
     "storefront-bot",
+    "analytics",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: import_zod.z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -3428,7 +3499,7 @@ interface Product {
   priceMin?: string | null;  // Lowest variant price (VARIABLE products) \u2014 same as basePrice for VARIABLE, kept for back-compat and JSON-LD range display.
   priceMax?: string | null;  // Highest variant price (VARIABLE products). Use with priceMin for "\u20AA49 \u2013 \u20AA199" range.
   priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
-  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive, display-only. The buyer is still charged in store currency at checkout; payment provider handles customer-side FX.
+  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive. For presentment-enabled regions (Stripe) the displayPrice uses the same buffered rate the checkout charges (browsed == checkout); for display-only regions it is mid-market and the buyer is charged in store currency at checkout (payment provider handles customer-side FX).
   displayPrice?: string;        // basePrice \xD7 daily FX rate, in displayCurrency.
   displaySalePrice?: string;    // salePrice \xD7 rate (if salePrice present).
   displayPriceMin?: string;     // priceMin \xD7 rate (VARIABLE products).
@@ -3682,7 +3753,7 @@ interface Checkout {
   status: CheckoutStatus;
   email?: string | null;
   customerId?: string | null;
-  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping (currency follows the cart until FX lands)
+  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping. FX-at-checkout: presentment-enabled regions (Stripe) charge in the region currency \u2014 see the presentment field below; else charged in store base currency
   shippingAddress?: CheckoutAddress | null;
   billingAddress?: CheckoutAddress | null;
   shippingRateId?: string | null;
@@ -3702,6 +3773,18 @@ interface Checkout {
   itemCount: number;
   availableShippingRates?: ShippingRate[];
   reservation?: ReservationInfo;
+  // FX-at-checkout: present ONLY when the region charges in its own currency (presentment-enabled \u2014 Stripe today). The amounts the buyer is actually CHARGED, in presentment.currency; presentment.total equals the payment intent amount. Render these (not total/currency above) when present. Absent = charged in store base currency. The fields above stay the base reference.
+  presentment?: {
+    currency: string;        // ISO-4217 charged currency, e.g. "EUR"
+    subtotal: string;
+    discountAmount: string;
+    shippingAmount: string;
+    taxAmount: string;
+    surchargeAmount: string;
+    total: string;           // equals the charged amount, to the cent
+    fxChargingRate: string;  // base\u2192presentment rate (buffer included)
+    fxBufferPercent: string | null;
+  };
   createdAt: string;
   updatedAt: string;
 }
@@ -3793,6 +3876,8 @@ interface Order {
   totalAmount: string;   // ALWAYS use this, not .total
   total?: string;        // optional alias
   currency?: string;
+  taxAmount?: string | null;       // 0 in inclusive (VAT) mode \u2014 read taxBreakdown.totalTax
+  taxBreakdown?: TaxBreakdown | null;  // carries the included VAT when prices include tax
   customer?: OrderCustomer | null;
   items: OrderItem[];
   itemCount?: number;
@@ -4077,10 +4162,22 @@ interface CartAppliedDiscount {
 }
 
 // Recommendation types
+interface RecommendationVariant {
+  id: string; name?: string; price?: string; salePrice?: string;
+  attributes?: Record<string, string>; image?: ProductImage | string; inventory?: InventoryInfo;
+}
 interface ProductRecommendation {
-  id: string; name: string; slug: string; basePrice: string; salePrice?: string;
+  id: string; name: string; slug: string;
+  // For a VARIABLE target, basePrice is the pinned variant's price (when
+  // targetVariantId is set) or the "from {min variant}" range \u2014 never 0.
+  basePrice: string; salePrice?: string;
   images: ProductImage[]; type: 'SIMPLE' | 'VARIABLE'; inventory?: InventoryInfo;
   relationType: string;
+  // Variant context (VARIABLE targets):
+  targetVariantId?: string | null;        // merchant-pinned variant, or null
+  requiresVariantSelection?: boolean;      // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];      // present when requiresVariantSelection
 }
 interface ProductRecommendationsResponse {
   crossSells: ProductRecommendation[];
@@ -4114,6 +4211,12 @@ interface CartBundleOfferOfferedProduct {
   salePrice: string | null;
   images: Array<{ url: string }>;
   type: string;
+  // Variant context (VARIABLE offered products):
+  variantId?: string | null;               // merchant-pinned variant for this slot
+  requiresVariantSelection?: boolean;       // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];       // present when requiresVariantSelection
+  // originalPrice = pinned/cheapest variant price for VARIABLE (not a 0 parent base).
   originalPrice: string;
   discountedPrice: string;
 }
@@ -4597,10 +4700,12 @@ interface UpdateRegionDto extends Partial<CreateRegionDto> { isActive?: boolean
 // client.detectRegion(country, regions): Region | null  \u2014 pure, no network.
 //   \u2192 region whose countries includes the code, else the default region, else null.
 // Pass the resolved regionId to createCheckout to associate the checkout with a
-// region (recorded for reporting + provider scoping; currency follows the cart
-// until FX price conversion lands).
+// region (recorded for reporting + provider scoping). FX-at-checkout:
+// presentment-enabled regions (Stripe) charge in the region currency and the
+// response carries a presentment overlay; else charged in store base currency.
 //
-// Storefront (public, no apiKey \u2014 storeId mode):
+// Storefront (public, no apiKey \u2014 storeId mode OR vibe-coded mode, salesChannelId 'vc_*';
+// the vc routes are gated on products:read, which every connection already has):
 interface PublicRegion {
   id: string; name: string; slug: string; currency: string;
   countries: string[]; taxInclusive: boolean; isDefault: boolean;
@@ -4652,7 +4757,8 @@ interface AssignTaxClassDto { productIds?: string[]; variantIds?: string[]; cate
 //                deleteTaxClass(id), setDefaultTaxClass(id), assignTaxClass(id, dto),
 //                mergeTaxClasses(id, targetId)
 //
-// SDK methods (storefront, public \u2014 storeId mode, no apiKey):
+// SDK methods (storefront, public \u2014 storeId mode OR vibe-coded mode 'vc_*', no apiKey;
+// the vc routes are gated on products:read, which every connection already has):
 //   getStoreRegions(), getStoreRegion(id), getAutoRegion(country)
 //   getStoreTaxClasses(), estimateTax({ country?, subtotal })
 //

package/dist/index.mjs

@@ -154,7 +154,26 @@ import {
   getDescriptionContent, isHtmlDescription,
   getProductMetafieldValue, getProductCustomizationFields,
 } from 'brainerce';
-\`\`\``;
+\`\`\`
+
+### Available features \u2014 request each topic for full docs
+
+| Topic | What it covers |
+|-------|----------------|
+| \`products\` | Catalog listing, search, PDP, variants, swatches, stock, attributes |
+| \`cart\` | Guest + logged-in cart, add/remove/update, reservations |
+| \`checkout\` | Guest + customer checkout, shipping, address |
+| \`payment\` | Payment providers, intents, status polling, confirmation |
+| \`auth\` | Customer sign-up, login, OAuth, email verification |
+| \`discounts\` | Coupons, banners, nudges |
+| \`recommendations\` | Cross-sell / upsell grids |
+| \`reviews\` | Product reviews & ratings |
+| \`inventory\` | Stock badges, reservation countdown |
+| \`inquiries\` | Contact / custom forms |
+| \`i18n\` | Multi-language, RTL |
+| \`admin\` | Server-to-server admin API (products, orders, customers) |
+| \`storefront-bot\` | **AI chat widget** \u2014 add Brainerce's AI shopping assistant to any page with one script tag or \`BrainerceBot.mount()\`. Answers product questions, shows recommendation cards, handles cart adds, opens escalation form. |
+| \`content\` | Blog, articles, static pages |`;
 }
 function getCheckoutFlowSection(_currency) {
   return `## \u26A0\uFE0F CHECKOUT FLOW (CRITICAL \u2014 READ CAREFULLY!)
@@ -1876,8 +1895,8 @@ function getTaxDisplaySection(_currency) {
 | Product Page | \u274C No | "Price excludes tax" (optional note) |
 | Cart Page | \u26A0\uFE0F "Calculated at checkout" | No address yet |
 | Checkout (before address) | \u26A0\uFE0F "Enter address to calculate" | Waiting for location |
-| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` |
-| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` |
+| Checkout (after address) | \u2705 **REQUIRED** | \`checkout.taxAmount\` (0 in VAT mode \u2192 \`checkout.taxBreakdown.totalTax\`) |
+| Order Confirmation | \u2705 **REQUIRED** | \`order.taxAmount\` (0 in VAT mode \u2192 \`order.taxBreakdown.totalTax\`) |
 
 ### Cart Page \u2014 Partial Display
 
@@ -1929,7 +1948,13 @@ const totals = getCartTotals(cart);
     <div className="flex justify-between text-green-600"><span>Discount</span><span>-{formatPrice(order.discountAmount, { currency: order.currency })}</span></div>
   )}
   <div className="flex justify-between"><span>Shipping</span><span>{formatPrice(order.shippingAmount, { currency: order.currency })}</span></div>
-  <div className="flex justify-between"><span>Tax</span><span>{formatPrice(order.taxAmount, { currency: order.currency })}</span></div>
+  {/* Inclusive (VAT) stores keep taxAmount="0" \u2014 the real VAT is on taxBreakdown.totalTax. */}
+  {(() => {
+    const tax = parseFloat(order.taxAmount || '0') || order.taxBreakdown?.totalTax || 0;
+    if (tax <= 0) return null;
+    const incl = order.taxBreakdown?.pricesIncludeTax;
+    return <div className="flex justify-between"><span>{incl ? 'Tax (incl.)' : 'Tax'}</span><span>{formatPrice(tax, { currency: order.currency })}</span></div>;
+  })()}
   <div className="flex justify-between font-bold text-lg border-t pt-2"><span>Total Paid</span><span>{formatPrice(order.totalAmount, { currency: order.currency })}</span></div>
 </div>
 \`\`\``;
@@ -2058,7 +2083,7 @@ A useful order card includes ALL of the following when the data is present. Each
 | **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
 | **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
 | Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
-| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. |
+| Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. In VAT-inclusive mode \`taxAmount\` is 0 \u2014 read \`order.taxBreakdown.totalTax\` and label "Tax (incl.)". |
 
 #### Rendering \`order.items[i].customizations\` by type
 
@@ -2503,8 +2528,9 @@ await admin.createTaxRate({ name: 'VAT (Food)', rate: 0, country: 'GB', taxClass
 await admin.mergeTaxClasses(food.id, standardClassId);
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreTaxClasses()\` lists
-the store's classes (storefront-safe fields only) for a transparency badge.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreTaxClasses()\`
+lists the store's classes (storefront-safe fields only) for a transparency badge.
 
 For a buyer-facing tax preview on PDP / PLP / cart, \`estimateTax({ country,
 subtotal })\` returns the tax portion at the Standard rate for the buyer's
@@ -2526,8 +2552,10 @@ A region binds countries \u2192 currency + tax-display mode + enabled payment
 providers. Manage them via the SDK (scopes \`regions:read\` / \`regions:write\`).
 \`detectRegion\` is a pure client-side helper to map a buyer's country to a
 region; pass the resolved \`regionId\` to \`createCheckout\` to associate the
-checkout with a region (recorded for reporting + provider scoping; currency
-follows the cart until FX price conversion lands).
+checkout with a region (recorded for reporting + provider scoping). FX-at-checkout:
+presentment-enabled regions (Stripe today) charge in the region currency and the
+checkout response carries a \`presentment\` overlay with the charged amounts;
+otherwise the checkout is charged in the store base currency.
 
 \`\`\`typescript
 const eu = await admin.createRegion({
@@ -2540,9 +2568,12 @@ const { data: regions } = await admin.getRegions();
 const region = admin.detectRegion('DE', regions); // \u2192 eu, else default, else null
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreRegions()\` lists
-active regions, \`getStoreRegion(id)\` returns one region + its payment providers.
-Pair with \`detectRegion\` to pick the buyer's region for currency display.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreRegions()\`
+lists active regions, \`getStoreRegion(id)\` returns one region + its payment
+providers. \`getAutoRegion(country)\` and \`estimateTax({ country, subtotal })\` work
+in both modes too. Pair with \`detectRegion\` to pick the buyer's region for
+currency display.
 
 \`\`\`typescript
 const store = new BrainerceClient({ storeId: 'store_123' });
@@ -3166,6 +3197,38 @@ Rules:
   count updates when the bot adds items.
 `;
 }
+function getStorefrontAnalyticsSection(connectionId) {
+  return `## Storefront Traffic Analytics (visits, countries, sources)
+
+Brainerce can track cookieless storefront traffic \u2014 how many people visit the
+store, from which countries, and from which traffic sources \u2014 and surface it in
+the merchant dashboard alongside sales (so the merchant gets a REAL conversion
+rate: visits \u2192 orders).
+
+Add ONE line to the storefront's root layout (\`<head>\` or end of \`<body>\`):
+
+\`\`\`html
+<script defer src="https://api.brainerce.com/t.js" data-channel="${connectionId}"></script>
+\`\`\`
+
+That's it \u2014 the pixel auto-sends a pageview beacon on load and on SPA route
+changes. Stores scaffolded with \`create-brainerce-store\` already include it.
+
+Privacy: the pixel is cookieless and stores NO personal data \u2014 no cookie, no
+cross-site/cross-day tracking, and the visitor IP is resolved to a country
+server-side then discarded. No cookie-consent banner is required for it under
+GDPR/ePrivacy.
+
+CSP: if the storefront sets a Content-Security-Policy, allow the script + beacon:
+- \`script-src\` \u2026 \`https://api.brainerce.com\`
+- \`connect-src\` \u2026 \`https://api.brainerce.com\`
+
+The merchant can toggle tracking per sales channel in the dashboard. The data
+shows up under Dashboard \u2192 Analytics (visits over time, by country, by source,
+by device) and can also be asked of the AI assistant ("how many visits did I get
+this month and from where?").
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3222,6 +3285,9 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getBlogSection();
     case "storefront-bot":
       return getStorefrontBotSection(cid);
+    case "analytics":
+    case "traffic-analytics":
+      return getStorefrontAnalyticsSection(cid);
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3290,6 +3356,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getStorefrontAnalyticsSection(cid),
+        "",
+        "---",
+        "",
         getProductCustomizationFieldsSection(),
         "",
         "---",
@@ -3359,6 +3429,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inquiries",
     "content",
     "storefront-bot",
+    "analytics",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -3396,7 +3467,7 @@ interface Product {
   priceMin?: string | null;  // Lowest variant price (VARIABLE products) \u2014 same as basePrice for VARIABLE, kept for back-compat and JSON-LD range display.
   priceMax?: string | null;  // Highest variant price (VARIABLE products). Use with priceMin for "\u20AA49 \u2013 \u20AA199" range.
   priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
-  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive, display-only. The buyer is still charged in store currency at checkout; payment provider handles customer-side FX.
+  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive. For presentment-enabled regions (Stripe) the displayPrice uses the same buffered rate the checkout charges (browsed == checkout); for display-only regions it is mid-market and the buyer is charged in store currency at checkout (payment provider handles customer-side FX).
   displayPrice?: string;        // basePrice \xD7 daily FX rate, in displayCurrency.
   displaySalePrice?: string;    // salePrice \xD7 rate (if salePrice present).
   displayPriceMin?: string;     // priceMin \xD7 rate (VARIABLE products).
@@ -3650,7 +3721,7 @@ interface Checkout {
   status: CheckoutStatus;
   email?: string | null;
   customerId?: string | null;
-  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping (currency follows the cart until FX lands)
+  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping. FX-at-checkout: presentment-enabled regions (Stripe) charge in the region currency \u2014 see the presentment field below; else charged in store base currency
   shippingAddress?: CheckoutAddress | null;
   billingAddress?: CheckoutAddress | null;
   shippingRateId?: string | null;
@@ -3670,6 +3741,18 @@ interface Checkout {
   itemCount: number;
   availableShippingRates?: ShippingRate[];
   reservation?: ReservationInfo;
+  // FX-at-checkout: present ONLY when the region charges in its own currency (presentment-enabled \u2014 Stripe today). The amounts the buyer is actually CHARGED, in presentment.currency; presentment.total equals the payment intent amount. Render these (not total/currency above) when present. Absent = charged in store base currency. The fields above stay the base reference.
+  presentment?: {
+    currency: string;        // ISO-4217 charged currency, e.g. "EUR"
+    subtotal: string;
+    discountAmount: string;
+    shippingAmount: string;
+    taxAmount: string;
+    surchargeAmount: string;
+    total: string;           // equals the charged amount, to the cent
+    fxChargingRate: string;  // base\u2192presentment rate (buffer included)
+    fxBufferPercent: string | null;
+  };
   createdAt: string;
   updatedAt: string;
 }
@@ -3761,6 +3844,8 @@ interface Order {
   totalAmount: string;   // ALWAYS use this, not .total
   total?: string;        // optional alias
   currency?: string;
+  taxAmount?: string | null;       // 0 in inclusive (VAT) mode \u2014 read taxBreakdown.totalTax
+  taxBreakdown?: TaxBreakdown | null;  // carries the included VAT when prices include tax
   customer?: OrderCustomer | null;
   items: OrderItem[];
   itemCount?: number;
@@ -4045,10 +4130,22 @@ interface CartAppliedDiscount {
 }
 
 // Recommendation types
+interface RecommendationVariant {
+  id: string; name?: string; price?: string; salePrice?: string;
+  attributes?: Record<string, string>; image?: ProductImage | string; inventory?: InventoryInfo;
+}
 interface ProductRecommendation {
-  id: string; name: string; slug: string; basePrice: string; salePrice?: string;
+  id: string; name: string; slug: string;
+  // For a VARIABLE target, basePrice is the pinned variant's price (when
+  // targetVariantId is set) or the "from {min variant}" range \u2014 never 0.
+  basePrice: string; salePrice?: string;
   images: ProductImage[]; type: 'SIMPLE' | 'VARIABLE'; inventory?: InventoryInfo;
   relationType: string;
+  // Variant context (VARIABLE targets):
+  targetVariantId?: string | null;        // merchant-pinned variant, or null
+  requiresVariantSelection?: boolean;      // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];      // present when requiresVariantSelection
 }
 interface ProductRecommendationsResponse {
   crossSells: ProductRecommendation[];
@@ -4082,6 +4179,12 @@ interface CartBundleOfferOfferedProduct {
   salePrice: string | null;
   images: Array<{ url: string }>;
   type: string;
+  // Variant context (VARIABLE offered products):
+  variantId?: string | null;               // merchant-pinned variant for this slot
+  requiresVariantSelection?: boolean;       // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];       // present when requiresVariantSelection
+  // originalPrice = pinned/cheapest variant price for VARIABLE (not a 0 parent base).
   originalPrice: string;
   discountedPrice: string;
 }
@@ -4565,10 +4668,12 @@ interface UpdateRegionDto extends Partial<CreateRegionDto> { isActive?: boolean
 // client.detectRegion(country, regions): Region | null  \u2014 pure, no network.
 //   \u2192 region whose countries includes the code, else the default region, else null.
 // Pass the resolved regionId to createCheckout to associate the checkout with a
-// region (recorded for reporting + provider scoping; currency follows the cart
-// until FX price conversion lands).
+// region (recorded for reporting + provider scoping). FX-at-checkout:
+// presentment-enabled regions (Stripe) charge in the region currency and the
+// response carries a presentment overlay; else charged in store base currency.
 //
-// Storefront (public, no apiKey \u2014 storeId mode):
+// Storefront (public, no apiKey \u2014 storeId mode OR vibe-coded mode, salesChannelId 'vc_*';
+// the vc routes are gated on products:read, which every connection already has):
 interface PublicRegion {
   id: string; name: string; slug: string; currency: string;
   countries: string[]; taxInclusive: boolean; isDefault: boolean;
@@ -4620,7 +4725,8 @@ interface AssignTaxClassDto { productIds?: string[]; variantIds?: string[]; cate
 //                deleteTaxClass(id), setDefaultTaxClass(id), assignTaxClass(id, dto),
 //                mergeTaxClasses(id, targetId)
 //
-// SDK methods (storefront, public \u2014 storeId mode, no apiKey):
+// SDK methods (storefront, public \u2014 storeId mode OR vibe-coded mode 'vc_*', no apiKey;
+// the vc routes are gated on products:read, which every connection already has):
 //   getStoreRegions(), getStoreRegion(id), getAutoRegion(country)
 //   getStoreTaxClasses(), estimateTax({ country?, subtotal })
 //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Framework-agnostic domain knowledge API for Brainerce. Provides SDK docs, types, business flows, critical rules, and store capabilities to AI tools like Lovable, Cursor, Bolt, v0, and Claude Code. Does NOT provide framework-specific boilerplate — clients build in whatever framework fits.",
   "bin": {
     "brainerce-mcp": "dist/bin/stdio.js"