@wix/agent-skills 1.27.0 → 1.29.0

package/skills/wix-headless-templates/donations/app/wix/donations/donate.ts

@@ -1,29 +1,19 @@
-// The donation flow over the SDK: a visitor's choice → an eCom checkout with one donation line →
-// the Wix-hosted checkout URL; and the thank-you page's order read. Payment, donor details and
-// receipts are Wix's hosted checkout and the eCom order — nothing here creates an order or builds
-// a URL by hand. Bodies and result readers live in ./donations-core (shared with the REST twin);
-// this file is the transport only. Copy as-is.
-//
-// Two routes to a checkout id, both kept:
-//   createDonationCheckout        — Create Checkout with the line (a donation never merges into a
-//                                   storefront visitor's current cart). The default.
-//   createDonationCheckoutViaCart — the Wix widget's own sequence: Create Cart → Create Checkout
-//                                   from the cart, channelType OTHER_PLATFORM. The fallback when
-//                                   the direct route is refused; also reachable by name.
-// Whether the Donations catalog plugin prices a line created directly is not yet verified live,
-// hence the automatic fallback.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/create-checkout.md
+// The donation flow over the SDK: a visitor's choice → an eCom cart with one donation line → the
+// Wix-hosted checkout URL; and the thank-you page's order read. In Cart V2 there is no separate
+// checkout entity: the cart IS the checkout, so its id is the id the redirect session takes.
+// Payment, donor details and receipts are Wix's hosted checkout and the eCom order — nothing here
+// creates an order or builds a URL by hand. Bodies and result readers live in ./donations-core
+// (shared with the REST twin); this file is the transport only. Copy as-is.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
-import { cart as cartModule, checkout as checkoutModule, orders as ordersModule } from "@wix/ecom";
+import { cartV2 as cartV2Module, orders as ordersModule } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";
 import {
   cartBody,
-  checkoutBody,
+  cartIdOf,
   checkoutError,
-  checkoutIdOf,
-  rawId,
   redirectBody,
   redirectUrl,
   toReceipt,
@@ -34,8 +24,7 @@ import type { DonationInput, DonationReceipt } from "./types";
 
 export type { DonatePaths };
 
-const checkoutApi = wixModule(checkoutModule);
-const cartApi = wixModule(cartModule);
+const cartV2Api = wixModule(cartV2Module);
 const ordersApi = wixModule(ordersModule);
 const redirects = wixModule(redirectsModule);
 
@@ -46,37 +35,21 @@ export interface DonateOptions {
   paths?: DonatePaths;
 }
 
-/** Create Checkout with the donation line → checkout id. */
-export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
-  const checkout: Raw = await checkoutApi.createCheckout(checkoutBody(campaignId, input) as any);
-  return checkoutIdOf(checkout);
-}
-
-/** The Wix widget's route: Create Cart (the note as buyerNote) → Create Checkout from the cart → checkout id. */
-export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
-  const cart: Raw = await cartApi.createCart(cartBody(campaignId, input) as any);
-  const res: Raw = await cartApi.createCheckout(rawId(cart), { channelType: "OTHER_PLATFORM" });
-  return checkoutIdOf(res);
-}
-
 /**
  * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
- * Direct Create Checkout first, the cart route when that is refused, then one redirect session
- * whose thank-you callback lands on `/donate/thank-you?orderId=`.
+ * One Create Cart (the cart is the checkout) → one redirect session whose thank-you callback lands
+ * on `/donate/thank-you?orderId=`.
  */
 export async function donationCheckoutUrl(campaignId: string, input: DonationInput, { origin, paths }: DonateOptions = {}): Promise<string> {
   const site = origin ?? (typeof window !== "undefined" ? window.location.origin : "");
-  let checkoutId: string;
+  let cartId: string;
   try {
-    checkoutId = await createDonationCheckout(campaignId, input);
-  } catch (direct) {
-    try {
-      checkoutId = await createDonationCheckoutViaCart(campaignId, input);
-    } catch {
-      throw checkoutError(direct);
-    }
+    const cart: Raw = await cartV2Api.createCart(cartBody(campaignId, input) as any);
+    cartId = cartIdOf(cart);
+  } catch (e) {
+    throw checkoutError(e);
   }
-  const session: Raw = await redirects.createRedirectSession(redirectBody(checkoutId, campaignId, site, paths) as any);
+  const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
   return redirectUrl(session);
 }
 

package/skills/wix-headless-templates/donations/app/wix/donations/donations-core.ts

@@ -1,7 +1,7 @@
 // Donation rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./campaigns.ts
 // + ./donate.ts (the SDK, managed Astro and React) and the REST twins in templates/donations/rest/
 // (fetch, a static site or a port to another language). Every rule about amounts, fees, frequency,
-// goal math, validation, the checkout line and the redirect body lives HERE, once. A raw campaign
+// goal math, validation, the cart line and the redirect body lives HERE, once. A raw campaign
 // may come from the SDK (`_id`, coverImage as a `wix:image://` string) or from REST (`id`,
 // coverImage as { id, url }); the mappers accept both. Has its own formatMoney so it stands alone
 // when stripped. Imports are type-only so a strip to JS emits no imports.
@@ -351,10 +351,10 @@ export function toInput(options: DonationOptions, sel: DonationSelection): Donat
   return { amount, frequency: sel.frequency, coverFee: options.askCoverFee && sel.coverFee, note: sel.note.trim() };
 }
 
-// ---- checkout -------------------------------------------------------------------------------------
+// ---- cart -----------------------------------------------------------------------------------------
 
 /**
- * The one line item a donation checkout carries. `amount` is a NUMBER and `frequency` the enum
+ * The one catalog item a donation cart carries. `amount` is a NUMBER and `frequency` the enum
  * string; `donorCoveringFees` is sent only when the donor opted in (the Donations catalog plugin
  * prices the line from these options — never a customLineItem, never a computed price).
  */
@@ -370,27 +370,26 @@ export function donationLineItem(campaignId: string, input: DonationInput): Raw
   };
 }
 
-/** Create Checkout body: the donation line, channelType WEB, the note as the checkout's buyerNote. */
-export function checkoutBody(campaignId: string, input: DonationInput): Raw {
-  return {
-    lineItems: [donationLineItem(campaignId, input)],
-    channelType: "WEB",
-    ...(input.note ? { checkoutInfo: { buyerNote: input.note } } : {}),
-  };
-}
-
-/** Create Cart body — the Wix widget's own route (fallback): the note as the cart's buyerNote. */
+/**
+ * Create Cart body (Cart V2): the single donation catalog item, the WEB channel on the cart's
+ * `source`, the donor note as the cart's `note`. In V2 the created cart IS the checkout — its id is
+ * the id the redirect session takes; there is no separate Create Checkout step.
+ */
 export function cartBody(campaignId: string, input: DonationInput): Raw {
   return {
-    lineItems: [donationLineItem(campaignId, input)],
-    ...(input.note ? { cartInfo: { buyerNote: input.note } } : {}),
+    cart: { source: { channelType: "WEB" }, ...(input.note ? { note: input.note } : {}) },
+    catalogItems: [donationLineItem(campaignId, input)],
   };
 }
 
-/** The checkout id out of either transport's response for either route. */
-export function checkoutIdOf(res: Raw | null | undefined): string {
-  const id = res?._id ?? res?.id ?? res?.checkoutId ?? res?.checkout?.id ?? res?.checkout?._id ?? "";
-  if (!id) throw new Error("Checkout couldn't start: no checkout id returned.");
+/**
+ * The cart id out of the Create Cart response — the id a V2 donation hands the redirect session
+ * (the cart is the checkout). The SDK returns a Cart directly (`_id`); REST wraps it as
+ * `{ cart: { id } }`.
+ */
+export function cartIdOf(res: Raw | null | undefined): string {
+  const id = res?._id ?? res?.id ?? res?.cart?._id ?? res?.cart?.id ?? "";
+  if (!id) throw new Error("Checkout couldn't start: no cart id returned.");
   return String(id);
 }
 

package/skills/wix-headless-templates/donations/project/src/wix/donations/donate.ts

@@ -1,29 +1,19 @@
-// The donation flow over the SDK: a visitor's choice → an eCom checkout with one donation line →
-// the Wix-hosted checkout URL; and the thank-you page's order read. Payment, donor details and
-// receipts are Wix's hosted checkout and the eCom order — nothing here creates an order or builds
-// a URL by hand. Bodies and result readers live in ./donations-core (shared with the REST twin);
-// this file is the transport only. Copy as-is.
-//
-// Two routes to a checkout id, both kept:
-//   createDonationCheckout        — Create Checkout with the line (a donation never merges into a
-//                                   storefront visitor's current cart). The default.
-//   createDonationCheckoutViaCart — the Wix widget's own sequence: Create Cart → Create Checkout
-//                                   from the cart, channelType OTHER_PLATFORM. The fallback when
-//                                   the direct route is refused; also reachable by name.
-// Whether the Donations catalog plugin prices a line created directly is not yet verified live,
-// hence the automatic fallback.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/create-checkout.md
+// The donation flow over the SDK: a visitor's choice → an eCom cart with one donation line → the
+// Wix-hosted checkout URL; and the thank-you page's order read. In Cart V2 there is no separate
+// checkout entity: the cart IS the checkout, so its id is the id the redirect session takes.
+// Payment, donor details and receipts are Wix's hosted checkout and the eCom order — nothing here
+// creates an order or builds a URL by hand. Bodies and result readers live in ./donations-core
+// (shared with the REST twin); this file is the transport only. Copy as-is.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
-import { cart as cartModule, checkout as checkoutModule, orders as ordersModule } from "@wix/ecom";
+import { cartV2 as cartV2Module, orders as ordersModule } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";
 import {
   cartBody,
-  checkoutBody,
+  cartIdOf,
   checkoutError,
-  checkoutIdOf,
-  rawId,
   redirectBody,
   redirectUrl,
   toReceipt,
@@ -34,8 +24,7 @@ import type { DonationInput, DonationReceipt } from "./types";
 
 export type { DonatePaths };
 
-const checkoutApi = wixModule(checkoutModule);
-const cartApi = wixModule(cartModule);
+const cartV2Api = wixModule(cartV2Module);
 const ordersApi = wixModule(ordersModule);
 const redirects = wixModule(redirectsModule);
 
@@ -46,37 +35,21 @@ export interface DonateOptions {
   paths?: DonatePaths;
 }
 
-/** Create Checkout with the donation line → checkout id. */
-export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
-  const checkout: Raw = await checkoutApi.createCheckout(checkoutBody(campaignId, input) as any);
-  return checkoutIdOf(checkout);
-}
-
-/** The Wix widget's route: Create Cart (the note as buyerNote) → Create Checkout from the cart → checkout id. */
-export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
-  const cart: Raw = await cartApi.createCart(cartBody(campaignId, input) as any);
-  const res: Raw = await cartApi.createCheckout(rawId(cart), { channelType: "OTHER_PLATFORM" });
-  return checkoutIdOf(res);
-}
-
 /**
  * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
- * Direct Create Checkout first, the cart route when that is refused, then one redirect session
- * whose thank-you callback lands on `/donate/thank-you?orderId=`.
+ * One Create Cart (the cart is the checkout) → one redirect session whose thank-you callback lands
+ * on `/donate/thank-you?orderId=`.
  */
 export async function donationCheckoutUrl(campaignId: string, input: DonationInput, { origin, paths }: DonateOptions = {}): Promise<string> {
   const site = origin ?? (typeof window !== "undefined" ? window.location.origin : "");
-  let checkoutId: string;
+  let cartId: string;
   try {
-    checkoutId = await createDonationCheckout(campaignId, input);
-  } catch (direct) {
-    try {
-      checkoutId = await createDonationCheckoutViaCart(campaignId, input);
-    } catch {
-      throw checkoutError(direct);
-    }
+    const cart: Raw = await cartV2Api.createCart(cartBody(campaignId, input) as any);
+    cartId = cartIdOf(cart);
+  } catch (e) {
+    throw checkoutError(e);
   }
-  const session: Raw = await redirects.createRedirectSession(redirectBody(checkoutId, campaignId, site, paths) as any);
+  const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
   return redirectUrl(session);
 }
 

package/skills/wix-headless-templates/donations/project/src/wix/donations/donations-core.ts

@@ -1,7 +1,7 @@
 // Donation rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./campaigns.ts
 // + ./donate.ts (the SDK, managed Astro and React) and the REST twins in templates/donations/rest/
 // (fetch, a static site or a port to another language). Every rule about amounts, fees, frequency,
-// goal math, validation, the checkout line and the redirect body lives HERE, once. A raw campaign
+// goal math, validation, the cart line and the redirect body lives HERE, once. A raw campaign
 // may come from the SDK (`_id`, coverImage as a `wix:image://` string) or from REST (`id`,
 // coverImage as { id, url }); the mappers accept both. Has its own formatMoney so it stands alone
 // when stripped. Imports are type-only so a strip to JS emits no imports.
@@ -351,10 +351,10 @@ export function toInput(options: DonationOptions, sel: DonationSelection): Donat
   return { amount, frequency: sel.frequency, coverFee: options.askCoverFee && sel.coverFee, note: sel.note.trim() };
 }
 
-// ---- checkout -------------------------------------------------------------------------------------
+// ---- cart -----------------------------------------------------------------------------------------
 
 /**
- * The one line item a donation checkout carries. `amount` is a NUMBER and `frequency` the enum
+ * The one catalog item a donation cart carries. `amount` is a NUMBER and `frequency` the enum
  * string; `donorCoveringFees` is sent only when the donor opted in (the Donations catalog plugin
  * prices the line from these options — never a customLineItem, never a computed price).
  */
@@ -370,27 +370,26 @@ export function donationLineItem(campaignId: string, input: DonationInput): Raw
   };
 }
 
-/** Create Checkout body: the donation line, channelType WEB, the note as the checkout's buyerNote. */
-export function checkoutBody(campaignId: string, input: DonationInput): Raw {
-  return {
-    lineItems: [donationLineItem(campaignId, input)],
-    channelType: "WEB",
-    ...(input.note ? { checkoutInfo: { buyerNote: input.note } } : {}),
-  };
-}
-
-/** Create Cart body — the Wix widget's own route (fallback): the note as the cart's buyerNote. */
+/**
+ * Create Cart body (Cart V2): the single donation catalog item, the WEB channel on the cart's
+ * `source`, the donor note as the cart's `note`. In V2 the created cart IS the checkout — its id is
+ * the id the redirect session takes; there is no separate Create Checkout step.
+ */
 export function cartBody(campaignId: string, input: DonationInput): Raw {
   return {
-    lineItems: [donationLineItem(campaignId, input)],
-    ...(input.note ? { cartInfo: { buyerNote: input.note } } : {}),
+    cart: { source: { channelType: "WEB" }, ...(input.note ? { note: input.note } : {}) },
+    catalogItems: [donationLineItem(campaignId, input)],
   };
 }
 
-/** The checkout id out of either transport's response for either route. */
-export function checkoutIdOf(res: Raw | null | undefined): string {
-  const id = res?._id ?? res?.id ?? res?.checkoutId ?? res?.checkout?.id ?? res?.checkout?._id ?? "";
-  if (!id) throw new Error("Checkout couldn't start: no checkout id returned.");
+/**
+ * The cart id out of the Create Cart response — the id a V2 donation hands the redirect session
+ * (the cart is the checkout). The SDK returns a Cart directly (`_id`); REST wraps it as
+ * `{ cart: { id } }`.
+ */
+export function cartIdOf(res: Raw | null | undefined): string {
+  const id = res?._id ?? res?.id ?? res?.cart?._id ?? res?.cart?.id ?? "";
+  if (!id) throw new Error("Checkout couldn't start: no cart id returned.");
   return String(id);
 }
 

package/skills/wix-headless-templates/donations/rest/donate.ts

@@ -1,19 +1,17 @@
 // The donation flow over REST — the twin of app/wix/donations/donate.ts. Same exports, same
 // signatures; the bodies and result readers come from donations-core (the SAME file the SDK
-// transport uses). A donation is an eCom checkout with one catalog line; the hosted checkout takes
-// payment and donor details. Never create the order yourself, never hand-build a checkout URL.
-// Two routes to a checkout id, both kept: Create Checkout directly (default), and the Wix widget's
-// Create Cart → Create Checkout from the cart (the fallback when the direct route is refused).
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/create-checkout.md
+// transport uses). A donation is an eCom cart with one catalog line; the hosted checkout takes
+// payment and donor details. In Cart V2 the cart IS the checkout — its id is the id the redirect
+// session takes, so there is one route and no separate Create Checkout call. Never create the
+// order yourself, never hand-build a checkout URL.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
 import { wixRequest } from "./client.js";
 import {
   cartBody,
-  checkoutBody,
+  cartIdOf,
   checkoutError,
-  checkoutIdOf,
-  rawId,
   redirectBody,
   redirectUrl,
   toReceipt,
@@ -31,46 +29,22 @@ export interface DonateOptions {
   paths?: DonatePaths;
 }
 
-/**
- * Create Checkout with the donation line → checkout id.
- * POST /ecom/v1/checkouts  { lineItems: [{ quantity: 1, catalogReference: { appId, catalogItemId, options: { amount, frequency, donorCoveringFees? } } }], channelType: "WEB", checkoutInfo?: { buyerNote } }  → { checkout: { id } }
- */
-export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
-  const res = await wixRequest<Raw>("/ecom/v1/checkouts", { body: checkoutBody(campaignId, input) });
-  return checkoutIdOf(res);
-}
-
-/**
- * The Wix widget's route → checkout id.
- * POST /ecom/v1/carts  { lineItems, cartInfo?: { buyerNote } }  → { cart: { id } }
- * POST /ecom/v1/carts/{id}/create-checkout  { channelType: "OTHER_PLATFORM" }  → { checkoutId }
- */
-export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
-  const created = await wixRequest<Raw>("/ecom/v1/carts", { body: cartBody(campaignId, input) });
-  const cartId = rawId(created?.cart);
-  if (!cartId) throw new Error("Checkout couldn't start: no cart id returned.");
-  const res = await wixRequest<Raw>(`/ecom/v1/carts/${cartId}/create-checkout`, { body: { channelType: "OTHER_PLATFORM" } });
-  return checkoutIdOf(res);
-}
-
 /**
  * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
  * `origin` must be the site's real https origin as registered on the OAuth app's allowed domains.
+ * POST /ecom/v2/carts  { cart: { source: { channelType: "WEB" }, note? }, catalogItems: [{ quantity: 1, catalogReference: { appId, catalogItemId, options: { amount, frequency, donorCoveringFees? } } }] }  → { cart: { id } } (the cart is the checkout)
  * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }  → { redirectSession: { fullUrl } }
  */
 export async function donationCheckoutUrl(campaignId: string, input: DonationInput, { origin, paths }: DonateOptions = {}): Promise<string> {
   const site = origin ?? (typeof window !== "undefined" ? window.location.origin : "");
-  let checkoutId: string;
+  let cartId: string;
   try {
-    checkoutId = await createDonationCheckout(campaignId, input);
-  } catch (direct) {
-    try {
-      checkoutId = await createDonationCheckoutViaCart(campaignId, input);
-    } catch {
-      throw checkoutError(direct);
-    }
+    const res = await wixRequest<Raw>("/ecom/v2/carts", { body: cartBody(campaignId, input) });
+    cartId = cartIdOf(res);
+  } catch (e) {
+    throw checkoutError(e);
   }
-  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectBody(checkoutId, campaignId, site, paths) });
+  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectBody(cartId, campaignId, site, paths) });
   return redirectUrl(session);
 }
 

package/skills/wix-headless-templates/pricing-plans/INSTRUCTIONS.md

@@ -336,8 +336,10 @@ other road — an eCom checkout with one PLAN line item (`catalogItemId: plan.id
 must share one checkout with products (a cart holding a membership and a T-shirt). Both end on a
 Wix-hosted checkout with coupons, notes, and login handled there. The DTO carries
 `pricingVariantId` so the eCom path is reachable without touching the DTO if a brief needs it;
-building it means `@wix/ecom` `checkout.createCheckout` plus a redirect session with
-`ecomCheckout: { checkoutId }` — a new function beside `purchase.ts`, not a change to it.
+building it means adding the plan line (and any product lines) to the current cart with `@wix/ecom`
+`currentCartV2` — in Cart V2 the cart IS the checkout, so the cart's id is the id passed to a
+redirect session with `ecomCheckout: { checkoutId }` — a new function beside `purchase.ts`, not a
+change to it.
 
 ## Gated content — requires the `members` vertical
 

package/skills/wix-headless-templates/restaurants/app/wix/restaurants/types.ts

@@ -21,7 +21,7 @@ export interface MenuItemLabel {
   iconUrl: string;
 }
 
-/** One price variant of an item ("Glass" / "Bottle"). An item has price OR variants. */
+/** One price variant of an item ("Small" / "Large"). An item has price OR variants. */
 export interface MenuItemVariant {
   variantId: string;
   name: string;

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/types.ts

@@ -21,7 +21,7 @@ export interface MenuItemLabel {
   iconUrl: string;
 }
 
-/** One price variant of an item ("Glass" / "Bottle"). An item has price OR variants. */
+/** One price variant of an item ("Small" / "Large"). An item has price OR variants. */
 export interface MenuItemVariant {
   variantId: string;
   name: string;

package/skills/wix-headless-templates/restaurants/seed/SEED.md

@@ -45,9 +45,9 @@ size, or a `modifierGroups` entry) when the restaurant takes orders, so the dish
         { "name": "Branzino", "description": "Whole roasted sea bass, lemon, herbs.",
           "price": 28, "imageUrl": "https://…" }
       ] },
-      { "name": "Vino", "items": [
-        { "name": "Chianti Classico", "description": "Sangiovese, Tuscany.",
-          "variants": [{ "name": "Glass", "price": 11 }, { "name": "Bottle", "price": 44 }], "imageUrl": "https://…" }
+      { "name": "Pizze", "items": [
+        { "name": "Margherita", "description": "San Marzano tomato, fior di latte, basil.",
+          "variants": [{ "name": "Small", "price": 14 }, { "name": "Large", "price": 22 }], "imageUrl": "https://…" }
       ] },
       { "name": "Dolci", "items": [
         { "name": "Tiramisù", "description": "Espresso-soaked ladyfingers, mascarpone.",
@@ -65,7 +65,7 @@ size, or a `modifierGroups` entry) when the restaurant takes orders, so the dish
 ```
 
 - `price` — a number; stored as a decimal string in the **site currency** (never send one per item).
-  An item has `price` OR `variants` (each `{ name, price }` — "Glass" / "Bottle"), never both; an
+  An item has `price` OR `variants` (each `{ name, price }` — "Small" / "Large"), never both; an
   item with neither renders as "Market price" and can't be ordered online.
 - `modifierGroups` — per item: `{ name, required?, min?, max?, modifiers: [{ name, price?, preSelected?, inStock? }] }`.
   `required: true, min: 1, max: 1` is a single choice (radios); `max` alone is "choose up to";

package/skills/wix-headless-templates/restaurants/seed/seed-restaurants.mjs

@@ -166,7 +166,7 @@ export async function createModifierGroups(ctx, groups) {
 }
 
 /**
- * Bulk-create price variants (the reusable "Glass" / "Bottle" names; the price per item lives on
+ * Bulk-create price variants (the reusable "Small" / "Large" names; the price per item lives on
  * the item's priceVariants reference). Returns ids in input order.
  * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-variants/bulk-create-variants.md
  */

package/skills/wix-headless-templates/shared/capabilities/site-search/seed/install.mjs

@@ -29,9 +29,9 @@ if (!siteId) {
   console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
   process.exit(1);
 }
-const token = execFileSync("npx", ["-y", "@wix/cli@latest", "token", "--site", siteId], { encoding: "utf8" }).trim();
+const token = execFileSync("npx", ["-y", "@wix/cli@1.1.258", "token", "--site", siteId], { encoding: "utf8" }).trim();
 if (!token) {
-  console.log(JSON.stringify({ error: "the Wix CLI returned no token — run `npx @wix/cli@latest login` first" }));
+  console.log(JSON.stringify({ error: "the Wix CLI returned no token — run `npx @wix/cli@1.1.258 login` first" }));
   process.exit(1);
 }
 try {

package/skills/wix-headless-templates/shared/seed/wix-cli.mjs

@@ -1,12 +1,15 @@
 // The Wix CLI the seeds call for a site token and for `wix env pull`.
 //
 // Order: the project's own copy (node_modules/.bin/wix, installed with the template's lock), then
-// a `wix` on PATH, then `npx -y @wix/cli@latest` — which installs the CLI before running it, 20 to
+// a `wix` on PATH, then `npx -y @wix/cli@<pinned>` — which installs the CLI before running it, 20 to
 // 60 s and a wall of npm output on a fresh machine. The first two take under two seconds.
 import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
 
+// The CLI version the fallback installs; equal to `@wix/cli` in wix-headless-kit/install/pins.json.
+const WIX_CLI_VERSION = "1.1.258";
+
 export function resolveWixCli(cwd = process.cwd()) {
   const bin = process.platform === "win32" ? "wix.cmd" : "wix";
   const local = join(cwd, "node_modules", ".bin", bin);
@@ -19,7 +22,7 @@ export function resolveWixCli(cwd = process.cwd()) {
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
     if (dir && existsSync(join(dir, bin))) return { file: join(dir, bin), prefix: [] };
   }
-  return { file: "npx", prefix: ["-y", "@wix/cli@latest"] };
+  return { file: "npx", prefix: ["-y", `@wix/cli@${WIX_CLI_VERSION}`] };
 }
 
 /**
@@ -33,7 +36,7 @@ export function wixToken(siteId, cwd = process.cwd()) {
   // An older CLI starts its "update available" box on the token's own line, so a line split is
   // not enough: the token is the first long run of token characters.
   const token = out.match(/[A-Za-z0-9._-]{40,}/)?.[0];
-  if (!token) throw new Error("The Wix CLI returned no token — run `wix login` (or `npx @wix/cli@latest login`) first.");
+  if (!token) throw new Error(`The Wix CLI returned no token — run \`wix login\` (or \`npx @wix/cli@${WIX_CLI_VERSION} login\`) first.`);
   return token;
 }
 

package/skills/wix-headless-templates/storefront/app/wix/storefront/cart.ts

@@ -167,8 +167,7 @@ export async function setNote(note: string): Promise<Cart> {
 /**
  * Start the Wix-hosted checkout for the current cart and return the URL to navigate to.
  * The cart's id IS the checkout id — no separate checkout-creation call (Wix's own storefront
- * does the same; `createCheckoutFromCurrentCart` is the alternative when a checkout must exist
- * before redirecting).
+ * does the same).
  * Call from the browser: the return origin must be the site's real https origin
  * (window.location.origin), never a server-derived request origin.
  */

package/skills/wix-headless-templates/storefront/project/src/wix/storefront/cart.ts

@@ -167,8 +167,7 @@ export async function setNote(note: string): Promise<Cart> {
 /**
  * Start the Wix-hosted checkout for the current cart and return the URL to navigate to.
  * The cart's id IS the checkout id — no separate checkout-creation call (Wix's own storefront
- * does the same; `createCheckoutFromCurrentCart` is the alternative when a checkout must exist
- * before redirecting).
+ * does the same).
  * Call from the browser: the return origin must be the site's real https origin
  * (window.location.origin), never a server-derived request origin.
  */

package/skills/wix-manage/references/bookings/diagnose-availability-issues.md

@@ -64,7 +64,7 @@ Interpret the result:
 
 > **The hidden-service trap.** A service that's **hidden** from the site, or has **online booking turned off**, can still list slots here — so bookable slots do **not** prove customers can book it. When the complaint is "customers can't book / can't find this service" (as opposed to "the calendar is empty"), **run [Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking) before trusting the slot count** — it's the single most common cause and neither `ListAvailabilityTimeSlots` nor `DiagnoseAvailability` detects it.
 
-If **no slots come back at all**, also sanity-check the inputs before concluding "no availability": the queried window isn't entirely in the past, and any `locations` filter is actually offered by the service.
+If **no slots come back at all**, also double-check the inputs before concluding "no availability": the queried window isn't entirely in the past, and any `locations` filter is actually offered by the service.
 
 ---
 

package/skills/wix-manage/references/ecommerce/ecom-shipping.md

@@ -39,7 +39,7 @@ Set up and tune how a store ships — what rates to charge, which regions are co
 
 ### Troubleshoot
 
-> - [Shipping rate incorrect (customer charged wrong shipping)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — tags: `[intent:rate-incorrect]` · priority 0 · *audit rates via the Rate Pricing Sanity guardrail, then correct the rate structure*
+> - [Shipping rate incorrect (customer charged wrong shipping)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — tags: `[intent:rate-incorrect]` · priority 0 · *audit rates via the Rate Pricing Plausibility guardrail, then correct the rate structure*
 
 ## Tag matching
 
@@ -53,7 +53,7 @@ The agent matches the merchant's natural-language query to an `intent:*` tag (cu
 | "How much should I charge for shipping?" | any | `ecom-shipping-setup-rates` via `[intent:setup-rates]` |
 | "I want customers to pick up from my shop" | any | `ecom-shipping-setup-pickup` via `[intent:setup-pickup]` |
 | "Some regions have no shipping option" | any | `ecom-shipping-fix-coverage` via `[intent:fix-coverage]` |
-| "A customer was charged the wrong shipping" | any | `ecom-shipping-optimize-rates` via `[intent:rate-incorrect]` (runs rate-sanity guardrail first) |
+| "A customer was charged the wrong shipping" | any | `ecom-shipping-optimize-rates` via `[intent:rate-incorrect]` (runs rate-plausibility guardrail first) |
 
 ## Base recipe (fallback)
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md

@@ -68,7 +68,7 @@ Check for: duplicate codes, overlapping scopes with active coupons, and cross-me
 
 - **Duplicate / conflicting code** — reject a code already in use.
 - **Cross-mechanism stacking** — coupons stack with automatic discount rules at checkout. Query active discount rules on overlapping scope; if found, warn with the combined effective discount ("a 20% coupon during a 20% automatic sale = ~36% off"). Only one coupon applies per checkout, but automatic rules are unlimited.
-- **% sanity** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed; > 100% always block.
+- **% plausibility** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed; > 100% always block.
 - **Margin** — if cost data is available, ensure the discount doesn't push price below cost; otherwise warn for > 40%.
 - **User override** — explicit merchant values override these caps; document the override in your reasoning.
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-discount-rule.md

@@ -129,10 +129,10 @@ These checks guard every discount creation (rule **or** coupon). Run them before
 - **Time overlap** — overlapping `activeTimeInfo` on the same scope (`existingStart < newEnd AND existingEnd > newStart`) → warn about the overlap window.
 - **Cross-mechanism (automatic + coupon)** — automatic discounts and coupons both apply at checkout. If creating a rule, query active coupons on overlapping scope (and vice-versa); warn with the combined effective discount. (Only one coupon per checkout, but automatic rules are unlimited.)
 
-**Margin / sanity:**
+**Margin / plausibility:**
 - **Global cap** — default max discount **25%**; flag anything higher (proceed only on explicit request).
 - **Minimum margin** — default floor **15%**; if cost data is available, `effective_margin = (price − cost − discount_amount) / price × 100` must stay ≥ 15% (block + explain otherwise).
-- **% sanity** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed ("makes the product free"); > 100% always block.
+- **% plausibility** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed ("makes the product free"); > 100% always block.
 - **Stacking margin** — when a new discount overlaps existing active ones, evaluate the *combined* discount against the cap and margin floor, not just the new one in isolation.
 
 | Scenario | Action |

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md

@@ -4,7 +4,7 @@ description: "BUNDLE_AND_SAVE sub-flow — load [Goal: Drive Cross-Sells] FIRST
 ---
 # Flow: Bundle & Save Campaign
 
-> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity).
+> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-plausibility).
 
 Creates a discount that rewards customers for purchasing multiple items, encouraging product discovery and cross-selling. The discount activates when the cart contains a minimum number of items, and targets categories or products where bundling makes strategic sense.