@wix/agent-skills 1.19.2 → 1.20.1

package/skills/wix-headless-fast/references/restaurants/app/wix/restaurants/reservations.ts

@@ -1,8 +1,8 @@
-// Table reservations (@wix/table-reservations) — the only file that touches raw reservation
-// entities. Copy as-is; extend by calling these exports, never by editing them.
+// Table reservations (@wix/table-reservations) over the SDK — the only file that touches raw
+// reservation entities on this transport. Rules and mappers live in ./reservations-core (shared
+// with the REST twin in references/restaurants/rest/); this file is the transport only. Copy
+// as-is; extend by calling these exports, never by editing them.
 //
-// The flow is location → AVAILABLE slots → hold (10-minute temporary reservation) → reserve
-// with the visitor's details. A reservation is a hold, not a purchase — no cart, no checkout.
 // getTimeSlots takes POSITIONAL args and a Date (not an ISO string); reserveReservation takes
 // THREE positional args (id, reservee, revision) and the only exit from HELD is reserve.
 // Failures are loud — surface the message, don't swallow it.
@@ -12,20 +12,14 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/reserve-reservation.md
 import { reservationLocations, timeSlots, reservations as reservationsModule } from "@wix/table-reservations";
 import { wixModule } from "../sdk";
-import type {
-  ReservationConfirmation,
-  ReservationHold,
-  ReservationLocationInfo,
-  ReservationReservee,
-  ReservationSlot,
-} from "./types";
+import { availableSlots, reserveeBody, toConfirmation, toHold, toLocations } from "./reservations-core";
+import type { Raw } from "./menu-core";
+import type { ReservationConfirmation, ReservationHold, ReservationLocationInfo, ReservationReservee, ReservationSlot } from "./types";
 
 const locationsApi = wixModule(reservationLocations);
 const timeSlotsApi = wixModule(timeSlots);
 const reservationsApi = wixModule(reservationsModule);
 
-type Raw = Record<string, any>;
-
 /**
  * Active (non-archived) reservation locations, default first. [] when Table Reservations
  * isn't set up. `onlineReservationsEnabled: false` means the premium-gated toggle is off —
@@ -33,41 +27,7 @@ type Raw = Record<string, any>;
  */
 export async function fetchReservationLocations(): Promise<ReservationLocationInfo[]> {
   const res: Raw = await locationsApi.listReservationLocations();
-  return (res.reservationLocations ?? [])
-    .filter((l: Raw) => l.archived !== true)
-    .map((l: Raw): ReservationLocationInfo => {
-      const online = l.configuration?.onlineReservations ?? {};
-      return {
-        id: l._id ?? "",
-        default: l.default === true,
-        partySizeMin: online.partySize?.min ?? 1,
-        partySizeMax: online.partySize?.max ?? 20,
-        approvalMode: online.approval?.mode ?? "AUTOMATIC",
-        onlineReservationsEnabled: online.onlineReservationsEnabled === true,
-      };
-    })
-    .filter((l: ReservationLocationInfo) => l.id)
-    .sort((a: ReservationLocationInfo, b: ReservationLocationInfo) => Number(b.default) - Number(a.default));
-}
-
-function toSlot(raw: Raw): ReservationSlot {
-  const start: Date = raw.startDate instanceof Date ? raw.startDate : new Date(raw.startDate);
-  let label = "";
-  let dayKey = "";
-  try {
-    label = start.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
-    const pad = (n: number) => String(n).padStart(2, "0");
-    dayKey = `${start.getFullYear()}-${pad(start.getMonth() + 1)}-${pad(start.getDate())}`;
-  } catch {
-    /* label/dayKey stay "" — startIso still books */
-  }
-  return {
-    startIso: start.toISOString(),
-    label,
-    dayKey,
-    durationMinutes: raw.duration ?? 0,
-    manualApproval: raw.manualApproval === true,
-  };
+  return toLocations(res.reservationLocations ?? []);
 }
 
 /**
@@ -82,35 +42,21 @@ export async function fetchReservationSlots(
   { slotsBefore = 6, slotsAfter = 6 }: { slotsBefore?: number; slotsAfter?: number } = {},
 ): Promise<ReservationSlot[]> {
   // The date param is a Date — the SDK types it as Date, not the ISO string the docs show.
-  const res: Raw = await timeSlotsApi.getTimeSlots(locationId, new Date(aroundIso), partySize, {
-    slotsBefore,
-    slotsAfter,
-  });
-  return (res.timeSlots ?? [])
-    .filter((s: Raw) => s.status === "AVAILABLE")
-    .map((s: Raw) => toSlot(s));
+  const res: Raw = await timeSlotsApi.getTimeSlots(locationId, new Date(aroundIso), partySize, { slotsBefore, slotsAfter });
+  return availableSlots(res.timeSlots ?? []);
 }
 
 /**
  * Hold a slot for 10 minutes while the visitor enters their details. The returned hold
  * carries the { reservationId, revision } that completeReservation NEEDS — keep both.
  */
-export async function holdReservation(
-  locationId: string,
-  startIso: string,
-  partySize: number,
-): Promise<ReservationHold> {
+export async function holdReservation(locationId: string, startIso: string, partySize: number): Promise<ReservationHold> {
   const res: Raw = await reservationsApi.createHeldReservation({
     reservationLocationId: locationId,
     startDate: new Date(startIso),
     partySize,
   });
-  const reservationId = res.reservation?._id;
-  const revision = res.reservation?.revision;
-  if (!reservationId || !revision) {
-    throw new Error("That time couldn't be held — it may have just been taken. Pick another slot.");
-  }
-  return { reservationId, revision, startIso, partySize };
+  return toHold(res, startIso, partySize);
 }
 
 /**
@@ -122,25 +68,7 @@ export async function completeReservation(
   hold: Pick<ReservationHold, "reservationId" | "revision">,
   reservee: ReservationReservee,
 ): Promise<ReservationConfirmation> {
-  if (!reservee.firstName?.trim() || !reservee.phone?.trim()) {
-    throw new Error("First name and phone number are required.");
-  }
-  const res: Raw = await reservationsApi.reserveReservation(
-    hold.reservationId,
-    {
-      firstName: reservee.firstName.trim(),
-      phone: reservee.phone.trim(),
-      ...(reservee.lastName?.trim() ? { lastName: reservee.lastName.trim() } : {}),
-      ...(reservee.email?.trim() ? { email: reservee.email.trim() } : {}),
-    },
-    hold.revision,
-  );
-  const reservation = res.reservation;
-  if (!reservation?._id) {
-    throw new Error("The reservation couldn't be completed — the hold may have expired. Start over.");
-  }
-  return {
-    reservationId: reservation._id,
-    status: reservation.status === "REQUESTED" ? "REQUESTED" : "RESERVED",
-  };
+  const body = reserveeBody(reservee);
+  const res: Raw = await reservationsApi.reserveReservation(hold.reservationId, body, hold.revision);
+  return toConfirmation(res);
 }

package/skills/wix-headless-fast/references/restaurants/rest/menu.ts

@@ -0,0 +1,60 @@
+// Menu reads over REST (Wix Restaurants Menus V1) — the twin of app/wix/restaurants/menu.ts. Same
+// export, same MenuData tree; the rules and the id-array stitching come from menu-core (the SAME
+// file the SDK transport uses, deployed flat next to this one by deploy.mjs --stack static), so
+// this file is only the transport: one GET per list, literal paths and query params. Every call
+// here is safe from a browser with a visitor token. Porting: keep the paths, keep the params, port
+// the core once. Entities carry `id` here (the SDK spells it `_id`); the core accepts both.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/list-menus.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/list-items.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { anyLabels, assembleMenus, collectGroupIds, collectModifierIds, collectVariantIds, type Raw } from "./menu-core.js";
+import type { MenuData } from "./types.js";
+
+const VISIBLE = { onlyVisible: "true" };
+const get = (path: string, query?: Record<string, string | readonly string[]>) => wixRequest<Raw>(path, { method: "GET", query });
+
+/**
+ * The site's full menu tree, assembled and display-ordered — the one entry point for every menu
+ * surface; [] when no menus exist. Three list reads, then the referenced variants, modifier groups,
+ * and labels, then the groups' modifiers (an array query param repeats the key: ?variantIds=a&variantIds=b).
+ * GET /restaurants/menus-menu/v1/menus?onlyVisible=true
+ * GET /restaurants/menus-section/v1/sections?onlyVisible=true
+ * GET /restaurants/menus-item/v1/items?onlyVisible=true
+ * GET /restaurants/item-variants/v1/variants?variantIds=…
+ * GET /restaurants/item-modifier-group/v1/modifier-groups?modifierGroupIds=…
+ * GET /restaurants/item-modifiers/v1/modifiers?modifierIds=…
+ * GET /restaurants/item-labels/v1/labels
+ */
+export async function fetchMenus(): Promise<MenuData[]> {
+  const [menusRes, sectionsRes, itemsRes] = await Promise.all([
+    get("/restaurants/menus-menu/v1/menus", VISIBLE),
+    get("/restaurants/menus-section/v1/sections", VISIBLE),
+    get("/restaurants/menus-item/v1/items", VISIBLE),
+  ]);
+  const menus: Raw[] = menusRes?.menus ?? [];
+  if (!menus.length) return [];
+  const items: Raw[] = itemsRes?.items ?? [];
+  const variantIds = collectVariantIds(items);
+  const groupIds = collectGroupIds(items);
+  const [variantsRes, groupsRes, labelsRes] = await Promise.all([
+    variantIds.length ? get("/restaurants/item-variants/v1/variants", { variantIds }) : Promise.resolve({ variants: [] } as Raw),
+    groupIds.length ? get("/restaurants/item-modifier-group/v1/modifier-groups", { modifierGroupIds: groupIds }) : Promise.resolve({ modifierGroups: [] } as Raw),
+    anyLabels(items) ? get("/restaurants/item-labels/v1/labels") : Promise.resolve({ labels: [] } as Raw),
+  ]);
+  const groups: Raw[] = groupsRes?.modifierGroups ?? [];
+  const modifierIds = collectModifierIds(groups);
+  const modifiersRes: Raw = modifierIds.length ? await get("/restaurants/item-modifiers/v1/modifiers", { modifierIds }) : { modifiers: [] };
+  return assembleMenus(
+    {
+      menus,
+      sections: sectionsRes?.sections ?? [],
+      items,
+      variants: variantsRes?.variants ?? [],
+      groups,
+      modifiers: modifiersRes?.modifiers ?? [],
+      labels: labelsRes?.labels ?? [],
+    },
+    imgSrc,
+  );
+}

package/skills/wix-headless-fast/references/restaurants/rest/ordering.ts

@@ -0,0 +1,169 @@
+// Online ordering over REST (Restaurants Orders + Wix eCom Cart V2) — the twin of
+// app/wix/restaurants/ordering.ts. Same exports, same OrderCart/OrderLine DTOs; rules and mappers
+// from ordering-core (the SAME file the SDK transport uses, deployed flat next to this one). The
+// request shapes are exact and rewriting them is how carts break: the Orders app id, and options
+// { operationId, menuId, sectionId } — all three, no variantId. Failures are loud: a missing
+// operation, an unavailable line, an empty order at checkout all throw — surface the message.
+// All calls run with the visitor token: the cart is the token's (see ./client).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/list-operations.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/fulfillment-methods/list-fulfillment-methods.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  RESTAURANTS_ORDERS_APP_ID,
+  assertOrderAdded,
+  assertOrderCheckoutable,
+  assertOrderContext,
+  estimateSubtotal,
+  orderCatalogItem,
+  pickOperationId,
+  rawId,
+  toFulfillmentMethods,
+  toOrderCart,
+} from "./ordering-core.js";
+import type { Raw } from "./menu-core.js";
+import type { FulfillmentMethodInfo, OrderCart } from "./types.js";
+
+export { RESTAURANTS_ORDERS_APP_ID };
+
+const CART = "/ecom/v2/carts/current";
+
+// The ordering operation is site config — resolve once, reuse for every add.
+// GET /restaurants-operations/v1/operations
+let operationIdPromise: Promise<string | null> | null = null;
+
+/** The operation to order through (ENABLED, else default, else first) — null when the site has no online ordering. */
+export function resolveOperationId(): Promise<string | null> {
+  operationIdPromise ??= wixRequest<Raw>("/restaurants-operations/v1/operations", { method: "GET" })
+    .then((res) => pickOperationId(res?.operations ?? []))
+    .catch(() => {
+      operationIdPromise = null; // transient failure — allow a retry on the next call
+      return null;
+    });
+  return operationIdPromise;
+}
+
+/** Enabled pickup/delivery methods, for display.  GET /fulfillment-methods/v1/fulfillment-methods */
+export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]> {
+  try {
+    const res = await wixRequest<Raw>("/fulfillment-methods/v1/fulfillment-methods", { method: "GET" });
+    return toFulfillmentMethods(res?.fulfillmentMethods ?? []);
+  } catch {
+    return []; // display nicety — ordering still works without the list
+  }
+}
+
+// A line's attributes.image may come back absent — join the menu items' images by the line's
+// catalogItemId, once per item, cached for the session.  GET /restaurants/menus-item/v1/items?itemIds=…
+const lineImageCache = new Map<string, string>();
+async function fillLineImages(cart: OrderCart, raws: Raw[]): Promise<void> {
+  const wanted = new Map<string, number[]>();
+  raws.forEach((raw, i) => {
+    if (cart.lines[i].imageUrl) return;
+    const itemId = raw.source?.catalogReference?.catalogItemId;
+    if (!itemId) return;
+    const cached = lineImageCache.get(itemId);
+    if (cached !== undefined) { cart.lines[i].imageUrl = cached; return; }
+    wanted.set(itemId, [...(wanted.get(itemId) ?? []), i]);
+  });
+  if (!wanted.size) return;
+  try {
+    const res = await wixRequest<Raw>("/restaurants/menus-item/v1/items", { method: "GET", query: { itemIds: [...wanted.keys()] } });
+    for (const item of (res?.items ?? []) as Raw[]) {
+      const url = imgSrc(item.image, 300, 300);
+      lineImageCache.set(rawId(item), url);
+      for (const i of wanted.get(rawId(item)) ?? []) cart.lines[i].imageUrl = url;
+    }
+  } catch {
+    /* images are a nicety — the cart stays correct without them */
+  }
+}
+
+async function readCartWithSubtotal(raw: Raw | null): Promise<OrderCart> {
+  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
+  if (!raw?.lineItems?.length) return toOrderCart(raw, "", imgSrc);
+  // The after-discount subtotal comes from the estimate, never from hand-summing lines; fees, tax,
+  // and delivery resolve at checkout.   POST /ecom/v2/carts/current/estimate  {}
+  let subtotal = "";
+  try {
+    subtotal = estimateSubtotal(await wixRequest<Raw>(`${CART}/estimate`, { body: {} }), raw);
+  } catch {
+    /* the estimate is a display nicety — the cart itself is still valid */
+  }
+  const cart = toOrderCart(raw, subtotal, imgSrc);
+  await fillLineImages(cart, raw.lineItems as Raw[]);
+  return cart;
+}
+
+// GET /ecom/v2/carts/current — a 404 means no cart yet.
+async function getCurrentCartRaw(): Promise<Raw | null> {
+  try {
+    return (await wixRequest<Raw>(CART, { method: "GET" }))?.cart ?? null;
+  } catch (e) {
+    if (e instanceof WixApiError && e.status === 404) return null;
+    throw e;
+  }
+}
+
+/** The visitor's current order cart. An empty cart (not an error) when none exists yet. */
+export async function fetchOrderCart(): Promise<OrderCart> {
+  return readCartWithSubtotal(await getCurrentCartRaw());
+}
+
+/**
+ * Add a menu item to the current order. `menuId` and `sectionId` are the ids of the menu and
+ * section the item is RENDERED UNDER — thread them from the render context (the fetchMenus tree).
+ * Throws when ordering isn't configured or the line is refused (a refused add still returns 200).
+ * POST /ecom/v2/carts/current/add-line-items
+ *   { catalogItems: [{ quantity, catalogReference: { catalogItemId, appId: <Orders app>, options: { operationId, menuId, sectionId } } }] }
+ */
+export async function addToOrder(
+  itemId: string,
+  { menuId, sectionId }: { menuId: string; sectionId: string },
+  quantity = 1,
+): Promise<OrderCart> {
+  const operationId = await resolveOperationId();
+  if (!operationId) throw new Error("Online ordering isn't available right now.");
+  assertOrderContext(itemId, menuId, sectionId);
+  const res = await wixRequest<Raw>(`${CART}/add-line-items`, {
+    body: { catalogItems: [orderCatalogItem(itemId, { operationId, menuId, sectionId }, quantity)] },
+  });
+  assertOrderAdded(res?.cart, itemId);
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Change a line's quantity. `lineItemId` is OrderLine.lineItemId, never the menu item id.
+ * POST /ecom/v2/carts/current/update-line-items  { lineItems: [{ lineItemId, quantity: { newQuantity } }] }
+ */
+export async function updateOrderQuantity(lineItemId: string, quantity: number): Promise<OrderCart> {
+  const res = await wixRequest<Raw>(`${CART}/update-line-items`, { body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/** Remove a line by OrderLine.lineItemId.  POST /ecom/v2/carts/current/remove-line-items  { lineItemIds } */
+export async function removeOrderLine(lineItemId: string): Promise<OrderCart> {
+  const res = await wixRequest<Raw>(`${CART}/remove-line-items`, { body: { lineItemIds: [lineItemId] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Start the Wix-hosted checkout for the current order and return the URL to navigate the FULL
+ * document to. The cart's id IS the checkout id; fulfillment (pickup/delivery + time) and payment
+ * are collected on the hosted page. `origin` must be the site's real https origin as registered on
+ * the OAuth app's allowed domains (browser: window.location.origin) — an unlisted or http origin
+ * 403s on return.
+ * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }
+ */
+export async function orderCheckoutUrl(origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
+  const raw = await getCurrentCartRaw();
+  assertOrderCheckoutable(raw);
+  const res = await wixRequest<Raw>("/headless/v1/redirect-session", {
+    body: { ecomCheckout: { checkoutId: rawId(raw) }, callbacks: origin ? { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` } : {} },
+  });
+  const url = res?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");
+  return url;
+}

package/skills/wix-headless-fast/references/restaurants/rest/reservations.ts

@@ -0,0 +1,68 @@
+// Table reservations over REST — the twin of app/wix/restaurants/reservations.ts. Same exports,
+// same DTOs; rules and mappers from reservations-core (the SAME file the SDK transport uses,
+// deployed flat next to this one). The flow is location → AVAILABLE slots → hold → reserve; a
+// reservation is a hold, not a purchase — no cart, no checkout. Every call here is a visitor's own
+// action with the visitor token. The hold and reserve calls are premium-gated on the site: a
+// non-premium site answers 428 "site must be premium" — surface it, don't retry.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/time-slots/get-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-held-reservation.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/reserve-reservation.md
+import { wixRequest } from "./client.js";
+import { availableSlots, reserveeBody, toConfirmation, toHold, toLocations } from "./reservations-core.js";
+import type { Raw } from "./menu-core.js";
+import type { ReservationConfirmation, ReservationHold, ReservationLocationInfo, ReservationReservee, ReservationSlot } from "./types.js";
+
+const RESERVATIONS = "/table-reservations/reservations/v1";
+
+/**
+ * Active (non-archived) locations, default first; [] when Table Reservations isn't set up.
+ * `onlineReservationsEnabled: false` → the premium-gated toggle is off; render an honest notice.
+ * GET /table-reservations/reservation-locations/v1/reservation-locations
+ */
+export async function fetchReservationLocations(): Promise<ReservationLocationInfo[]> {
+  const res = await wixRequest<Raw>("/table-reservations/reservation-locations/v1/reservation-locations", { method: "GET" });
+  return toLocations(res?.reservationLocations ?? []);
+}
+
+/**
+ * AVAILABLE slots around a moment for a party size (UNAVAILABLE / NON_WORKING_HOURS dropped).
+ * POST /table-reservations/reservations/v1/time-slots  { reservationLocationId, date, partySize, slotsBefore, slotsAfter }
+ */
+export async function fetchReservationSlots(
+  locationId: string,
+  aroundIso: string,
+  partySize: number,
+  { slotsBefore = 6, slotsAfter = 6 }: { slotsBefore?: number; slotsAfter?: number } = {},
+): Promise<ReservationSlot[]> {
+  const res = await wixRequest<Raw>(`${RESERVATIONS}/time-slots`, {
+    body: { reservationLocationId: locationId, date: new Date(aroundIso).toISOString(), partySize, slotsBefore, slotsAfter },
+  });
+  return availableSlots(res?.timeSlots ?? []);
+}
+
+/**
+ * Hold a slot for 10 minutes while the visitor enters their details; the hold's { reservationId, revision } feed completeReservation.
+ * POST /table-reservations/reservations/v1/reservations/hold  { reservationDetails: { reservationLocationId, startDate, partySize } }
+ */
+export async function holdReservation(locationId: string, startIso: string, partySize: number): Promise<ReservationHold> {
+  const res = await wixRequest<Raw>(`${RESERVATIONS}/reservations/hold`, {
+    body: { reservationDetails: { reservationLocationId: locationId, startDate: new Date(startIso).toISOString(), partySize } },
+  });
+  return toHold(res, startIso, partySize);
+}
+
+/**
+ * Complete a held reservation. firstName and phone (E.164) are REQUIRED; an expired hold can't be
+ * reserved — start a fresh hold.
+ * POST /table-reservations/reservations/v1/reservations/{reservationId}/reserve  { revision, reservee: { firstName, phone, lastName?, email? } }
+ */
+export async function completeReservation(
+  hold: Pick<ReservationHold, "reservationId" | "revision">,
+  reservee: ReservationReservee,
+): Promise<ReservationConfirmation> {
+  const body = reserveeBody(reservee);
+  const res = await wixRequest<Raw>(`${RESERVATIONS}/reservations/${encodeURIComponent(hold.reservationId)}/reserve`, {
+    body: { revision: hold.revision, reservee: body },
+  });
+  return toConfirmation(res);
+}

package/skills/wix-headless-fast/references/restaurants/seed/SEED.md

@@ -67,6 +67,14 @@ restaurant that takes orders and reservations:
   **seeding is strictly additive — never delete or overwrite existing content**; ask first
   if a cleanup seems needed.
 
+## Supplied content
+
+The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For a restaurant the user hands
+over the menu, often as a PDF or a photo. Each menu becomes an entry in `menus`, each heading a
+`section`, each dish an `item` with `name`, `description`, `price` and, when they supplied one, its
+photo as `imageUrl`. The restaurant's address, hours and party sizes go into `ordering` and
+`reservations` only when the user stated them; otherwise leave those out and say so.
+
 ## Escape hatch — individual functions
 `setupRestaurants` composes exported steps — `installMenusApp`, `installOrdersApp`,
 `installTableReservationsApp`, `removeSampleMenu`, `createMenu`, `importImage`,

package/skills/wix-headless-fast/references/shared/SUPPLIED-CONTENT.md

@@ -0,0 +1,23 @@
+# Supplied content — when the user brings their own
+
+When the brief supplies the content in any form — a CSV, JSON or spreadsheet, a list typed in the
+prompt, a PDF or an image of a price list or a menu, a folder of photos with a text file beside
+it, a link to a page that lists it — that source is the seed plan. The vertical's default count
+("start with 3", "a few posts") applies only to catalogs you draft yourself.
+
+Read it however it needs to be read: parse the file (a quoted comma inside a description is
+common), open the PDF, fetch the page, look at the images. Then map, don't author:
+
+- Every entry in the source becomes an entry in the plan. Names, titles, descriptions, prices,
+  dates verbatim; never rename, reprice, reword, reorder or add.
+- Column and field names vary; map by meaning to the fields the vertical's `SEED.md` plan
+  shape defines. Anything the plan has no field for is dropped — say which columns you dropped.
+- Their images only: an image URL column → the plan's image URL field, verified with `curl -sI`
+  → 200; a local file → the plan's image path field. An entry with no image is seeded without one
+  and listed in your summary. **Never an `imagePrompt` beside supplied content** — these are their
+  things, not a mood board.
+- Currency, time zone, address: only when the source or the brief states them.
+- Show the user the count you read next to the count you seeded, and the mapping you applied.
+
+The vertical's `SEED.md` says what an entry is for that vertical and which of its plan fields the
+usual columns land in.

package/skills/wix-headless-fast/references/shared/app/wix/media.ts

@@ -23,5 +23,59 @@ export function imgSrc(value: MediaLike, width = 600, height = 600): string {
   if (typeof v === "string" && v.startsWith("wix:image://")) {
     return media.getScaledToFillImageUrl(v, width, height, {});
   }
-  return typeof v === "string" ? v : "";
+  if (typeof v !== "string") return "";
+  // An absolute Wix media URL (bare, or already carrying a /v1/fill/ segment at some other size):
+  // re-issue it through the scaler at the requested size, so every image path lands on one shape.
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  if (m) return `https://static.wixstatic.com/media/${m[1]}/v1/fill/w_${width},h_${height},al_c,q_90/${m[1]}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = typeof value === "object" && value !== null ? (value.image ?? value.url ?? "") : (value ?? "");
+  if (typeof raw !== "string" || !raw) return "";
+  if (raw.startsWith("wix:image://")) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcSet: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * The identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): string {
+  const v = typeof value === "object" && value !== null ? (value.image ?? value.url ?? "") : (value ?? "");
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
 }

package/skills/wix-headless-fast/references/shared/app/wix/sdk.ts

@@ -15,6 +15,7 @@
 // docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
 // docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
 import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
 import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
 import { WIX_CLIENT_ID } from "./config";
 
@@ -66,6 +67,18 @@ export function wixModule<T>(module: T): T {
     : module;
 }
 
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
 /**
  * The shared data client's manual-mode auth strategy, or null under ambient auth. The
  * Members vertical deliberately owns a separate explicit client for its custom in-app login;