@wix/agent-skills 1.17.0 → 1.18.0

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

@@ -0,0 +1,81 @@
+# Restaurants — seeding
+
+Seed by **running `seed-restaurants.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Restaurants apps, builds each menu bottom-up (items → sections →
+menu, all visible), imports+attaches images, and configures ordering/reservations.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/restaurants/seed/seed-restaurants.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to one menu with ~3 sections
+of 2–3 items each** (the seed shows the shape; the owner adds the rest in the dashboard),
+every item with an image (a menu without photos looks broken) — the default is an
+`imagePrompt` (AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual —
+subject, aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually
+supplied use `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
+(their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never
+block the seed, a failed image leaves that item text-only — and both add-ons on for a
+restaurant that takes orders and reservations:
+
+```json
+{
+  "menus": [
+    { "name": "Dinner", "description": "Evening menu", "sections": [
+      { "name": "Antipasti", "description": "To start", "items": [
+        { "name": "Bruschetta al Pomodoro", "description": "Grilled sourdough, San Marzano tomatoes, basil.",
+          "price": 9.5, "imageUrl": "https://…" },
+        { "name": "Burrata", "description": "Creamy burrata, heirloom tomatoes, olive oil.",
+          "price": 14, "imageUrl": "https://…" }
+      ] },
+      { "name": "Mains", "items": [
+        { "name": "Tagliatelle al Ragù", "description": "Slow-braised beef ragù, parmigiano.",
+          "price": 22, "imageUrl": "https://…" },
+        { "name": "Branzino", "description": "Whole roasted sea bass, lemon, herbs.",
+          "price": 28, "imageUrl": "https://…" }
+      ] },
+      { "name": "Dolci", "items": [
+        { "name": "Tiramisù", "description": "Espresso-soaked ladyfingers, mascarpone.",
+          "price": 10, "imageUrl": "https://…" }
+      ] }
+    ] }
+  ],
+  "ordering": { "address": {
+    "name": "Trattoria Lumina", "timeZone": "America/New_York",
+    "address": { "country": "US", "subdivision": "US-NY", "city": "New York", "postalCode": "10012",
+      "streetAddress": { "number": "18", "name": "Prince Street" },
+      "formattedAddress": "18 Prince Street, New York, NY 10012" } } },
+  "reservations": { "partySize": { "min": 1, "max": 10 } }
+}
+```
+
+- `price` — a number; stored as a decimal string in the **site currency** (never send one).
+- `ordering` — installs the Orders app, which **auto-provisions** a working setup (ENABLED
+  operation, Pickup + Delivery methods, every menu orderable); the seed verifies it. The
+  `address` is **required for real ordering** — without one, ordering is "testing only" and
+  checkout breaks. If the brief names no address, pass `"ordering": true` and the result
+  carries a note to flag the owner. Completing a **paid** order additionally needs a premium
+  plan + a connected payment method (dashboard) — mention it, don't treat it as a failure.
+- `reservations` — installs Table Reservations, which auto-provisions a default reservation
+  location; `partySize` (or a full `configuration`) is a partial PATCH. The final
+  **enable-online-reservations toggle is premium-only**: on a free site the result carries
+  `reservations.premiumRequired: true` — expected, tell the owner, don't retry.
+- Fresh Menus installs ship a sample "Dinner Menu"; when THIS run installs the app the seed
+  removes that sample (`sampleMenuRemoved: true`). On a site that already had the app,
+  **seeding is strictly additive — never delete or overwrite existing content**; ask first
+  if a cleanup seems needed.
+
+## Escape hatch — individual functions
+`setupRestaurants` composes exported steps — `installMenusApp`, `installOrdersApp`,
+`installTableReservationsApp`, `removeSampleMenu`, `createMenu`, `importImage`,
+`attachItemImages`, `setBusinessLocation`, `listOperationsWithRetry`, `enableOperation`,
+`queryMenuOrderingSettings`, `updateMenuOrderingSettings`, `listReservationLocationsWithRetry`,
+`updateReservationLocation`, `enableOnlineReservations`, plus `makeCtx()` — import them only
+for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; the
+authoritative source recipes are `wix-headless/references/inline-recipes/setup-restaurants.md`,
+`setup-restaurant-orders.md`, and `setup-restaurant-reservations.md`.

package/skills/wix-headless-fast/references/restaurants/seed/seed-restaurants.mjs

@@ -0,0 +1,479 @@
+// Restaurants seed — a BUILD-TIME script, never shipped in the app. Run from the project
+// root (where wix.config.json lives) with a plan file:
+//
+//   node <SKILL_ROOT>/references/restaurants/seed/seed-restaurants.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Restaurants Menus app (plus
+// Orders / Table Reservations when the plan asks), builds each menu BOTTOM-UP (bulk items →
+// bulk sections → menu — every child exists before its parent, visible:true at every level),
+// imports+attaches item images, and configures the add-ons. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "menus": [{ "name", "description"?, "sections": [{ "name", "description"?,
+//                 "items": [{ "name", "description"?, "price", "imageUrl"? | "imagePrompt"? }] }] }],
+//     "ordering"?: true | { "address"? },        // menu-first add-on; address is STEP 0
+//     "reservations"?: true | { "partySize"? { "min","max" }, "address"? } }
+//
+// Seeding is ADDITIVE — with ONE recipe-sanctioned exception: when THIS run installs the
+// Menus app onto a site that didn't have it, the install's own sample "Dinner Menu" is
+// removed (it's provably not owner content). Nothing else is ever deleted. Unexpected
+// shapes → read the live API reference; authoritative source recipes:
+// wix-headless/references/inline-recipes/setup-restaurants.md, setup-restaurant-orders.md,
+// setup-restaurant-reservations.md.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+
+const API = "https://www.wixapis.com";
+const MENUS_APP_ID = "b278a256-2757-4f19-9313-c05c783bec92";
+const ORDERS_APP_ID = "9a5d83fd-8570-482e-81ab-cfa88942ee60";
+const TABLE_RESERVATIONS_APP_ID = "f9c07de2-5341-40c6-b096-8eb39de391fb";
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
+  const siteId = config.siteId ?? config.projectId;
+  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
+  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
+    encoding: "utf8",
+    cwd,
+  }).trim();
+  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
+  return { token, siteId };
+}
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---- app installs --------------------------------------------------------------------------------
+
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+async function installApp(ctx, appDefId) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+export async function installMenusApp(ctx) { return installApp(ctx, MENUS_APP_ID); }
+export async function installOrdersApp(ctx) { return installApp(ctx, ORDERS_APP_ID); }
+export async function installTableReservationsApp(ctx) { return installApp(ctx, TABLE_RESERVATIONS_APP_ID); }
+
+/** True when the Menus API answers — i.e. the app is already on the site. */
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/list-menus.md
+export async function menusAppPresent(ctx) {
+  try {
+    await req(ctx, "/restaurants/menus/v1/menus", { method: "GET" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---- menu (setup-restaurants.md) -----------------------------------------------------------------
+// Everything is Restaurants Menus V1 on /restaurants/menus/v1/... . REST flattens the
+// protobuf wrappers: plain values ("visible": true), never {"value": …}.
+
+/**
+ * Recipe STEP 0 — a FRESH Menus-app install ships a populated sample "Dinner Menu"
+ * (~4 sections, ~21 items) that would render next to the seeded menu. Call ONLY when this
+ * run installed the app onto a site that didn't have it (menusAppPresent was false) — then
+ * everything present is provably the install's own sample. Polls briefly (the sample
+ * provisions async), then deletes children before parents. No-op when nothing appears.
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/list-items.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/list-sections.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/bulk-delete-items.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/bulk-delete-sections.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/delete-menu.md
+ */
+export async function removeSampleMenu(ctx, { tries = 8, delayMs = 2000 } = {}) {
+  let menus = [];
+  for (let i = 0; i < tries; i++) {
+    const r = await req(ctx, "/restaurants/menus/v1/menus", { method: "GET" });
+    menus = r.menus ?? [];
+    if (menus.length) break;
+    if (i < tries - 1) await sleep(delayMs);
+  }
+  if (!menus.length) return { removed: false };
+
+  const itemsRes = await req(ctx, "/restaurants/menus/v1/items", { method: "GET" });
+  const sectionsRes = await req(ctx, "/restaurants/menus/v1/sections", { method: "GET" });
+  const itemIds = (itemsRes.items ?? []).map((it) => it.id).filter(Boolean);
+  const sectionIds = (sectionsRes.sections ?? []).map((s) => s.id).filter(Boolean);
+  if (itemIds.length) {
+    await req(ctx, "/restaurants/menus/v1/bulk/items/delete", { method: "DELETE", body: { ids: itemIds } });
+  }
+  if (sectionIds.length) {
+    await req(ctx, "/restaurants/menus/v1/bulk/sections/delete", { method: "DELETE", body: { ids: sectionIds } });
+  }
+  for (const m of menus) {
+    await req(ctx, `/restaurants/menus/v1/menus/${m.id}`, { method: "DELETE" }); // no bulk delete for menus
+  }
+  return { removed: true, menus: menus.map((m) => m.name) };
+}
+
+/**
+ * Build ONE menu BOTTOM-UP (items → sections → menu) in three bulk phases.
+ * price -> priceInfo.price as a decimal STRING; currency is the site's (send none).
+ * visible:true is baked in at every level — required to render on the live site.
+ * Returns { menuId, name, sectionIds, itemIds, items: [{ id, revision, price }] } — the
+ * per-item revision/price feed the image pass (Update Item is a full replace).
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/bulk-create-items.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/bulk-create-sections.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/create-menu.md
+ */
+export async function createMenu(ctx, menu) {
+  // STEP 1 — bulk-create every item across all sections in ONE request.
+  const flat = [];
+  menu.sections.forEach((sec, si) => (sec.items || []).forEach((it) => flat.push({ ...it, _section: si })));
+  const itemRes = await req(ctx, "/restaurants/menus/v1/bulk/items/create", {
+    body: {
+      items: flat.map((it) => ({
+        name: it.name,
+        ...(it.description ? { description: it.description } : {}),
+        priceInfo: { price: String(it.price) },
+        visible: true,
+      })),
+      returnEntity: true,
+    },
+  });
+  // created items are under results[].item (results[].itemMetadata.success is the per-item flag)
+  const createdItems = (itemRes.results ?? []).map((r) => r.item);
+  const itemIdsBySection = menu.sections.map(() => []);
+  flat.forEach((it, i) => {
+    const id = createdItems[i]?.id;
+    if (id) itemIdsBySection[it._section].push(id);
+  });
+
+  // STEP 2 — bulk-create sections, each carrying the itemIds of its items in display order.
+  const secRes = await req(ctx, "/restaurants/menus/v1/bulk/sections/create", {
+    body: {
+      sections: menu.sections.map((sec, si) => ({
+        name: sec.name,
+        ...(sec.description ? { description: sec.description } : {}),
+        visible: true,
+        itemIds: itemIdsBySection[si],
+      })),
+      returnEntity: true,
+    },
+  });
+  const sectionIds = (secRes.results ?? []).map((r) => r.item?.id);
+
+  // STEP 3 — create the menu (single create wraps in `menu`), carrying its sectionIds.
+  // businessLocationId omitted -> binds to the site's default (main) location.
+  const menuRes = await req(ctx, "/restaurants/menus/v1/menus", {
+    body: {
+      menu: {
+        name: menu.name,
+        ...(menu.description ? { description: menu.description } : {}),
+        visible: true,
+        sectionIds,
+      },
+    },
+  });
+  return {
+    menuId: menuRes.menu?.id,
+    name: menu.name,
+    sectionIds,
+    itemIds: createdItems.map((it) => it?.id),
+    items: createdItems.map((it, i) => ({ id: it?.id, revision: it?.revision, price: flat[i]?.price })),
+  };
+}
+
+// Restaurants binds an item image by Wix Media file ID — an external url must be imported
+// first; a plan `imagePrompt` is generated (Wix AI, 1 credit) then imported. Both live in the
+// shared util (parallel, resilient, never blocks the seed).
+export { importImage } from "../../shared/seed/images.mjs";
+
+// Image pass. Update Item is a FULL-ENTITY REPLACE with NO field mask — each entry MUST echo
+// the item's current `revision` AND `priceInfo`, or it fails 428 MISSING_ITEM_PRICING and the
+// image does NOT apply. `image` is an OBJECT { id, url, height, width } (never a bare string);
+// the binding field is the Wix Media file `id`.
+// items: [{ id, revision, price, image: { id, url, height, width } }]
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/bulk-update-item.md
+export async function attachItemImages(ctx, items) {
+  return req(ctx, "/restaurants/menus/v1/bulk/items/update", {
+    body: {
+      items: items.map((it) => ({
+        item: {
+          id: it.id,
+          revision: it.revision,
+          priceInfo: { price: String(it.price) },
+          image: it.image,
+        },
+      })),
+    },
+  });
+}
+
+// ---- business location (shared STEP 0 for ordering + reservations) ------------------------------
+// Update Location is a FULL OVERRIDE — send the WHOLE `location` object (omitted fields are
+// wiped), echo `default:true` (omitting it 400s CHANGE_DEFAULT_FORBIDDEN) and the current
+// `revision`. address.country is a 2-letter ISO code. Without a real address, ordering is
+// "testing only" and checkout breaks — a placeholder must be flagged to the owner.
+// location: { name, timeZone, email?, phone?, address: { country, subdivision, city,
+//             postalCode, streetAddress: { number, name }, formattedAddress } }
+// docs: https://dev.wix.com/docs/api-reference/business-management/locations/list-locations.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/locations/create-location.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/locations/update-location.md
+export async function setBusinessLocation(ctx, location) {
+  const list = await req(ctx, "/locations/v1/locations", { method: "GET" });
+  const def = (list.locations ?? []).find((l) => l.default);
+  if (!def) {
+    // No default location at all (a bare site can have none) -> CREATE one; operations
+    // auto-bind on first-location-add.
+    const r = await req(ctx, "/locations/v1/locations", { body: { location: { ...location, default: true } } });
+    return r.location;
+  }
+  const r = await req(ctx, `/locations/v1/locations/${def.id}`, {
+    method: "PUT",
+    body: { location: { ...location, id: def.id, revision: def.revision, default: true } },
+  });
+  return r.location;
+}
+
+// ---- online ordering (setup-restaurant-orders.md) ------------------------------------------------
+// The Orders-app install AUTO-provisions a working setup (an ENABLED operation with Pickup +
+// Delivery attached, every menu ordering-enabled) — these helpers VERIFY it; they never POST
+// an operation. Each micro-service is on its OWN host prefix — do not normalize.
+
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/list-operations.md
+export async function listOperations(ctx) {
+  const r = await req(ctx, "/restaurants-operations/v1/operations", { method: "GET" });
+  return r.operations ?? [];
+}
+
+// A fresh install provisions the operation ASYNC — poll until it lands.
+export async function listOperationsWithRetry(ctx, { tries = 15, delayMs = 2000 } = {}) {
+  for (let i = 0; i < tries; i++) {
+    const ops = await listOperations(ctx).catch(() => []);
+    if (ops.length) return ops;
+    if (i < tries - 1) await sleep(delayMs);
+  }
+  return [];
+}
+
+// Normally already ENABLED — only PATCH when DISABLED/PAUSED_UNTIL. revision mandatory + current.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/update-operation.md
+export async function enableOperation(ctx, operationId, revision) {
+  return req(ctx, `/restaurants-operations/v1/operations/${operationId}`, {
+    method: "PATCH",
+    body: { operation: { revision, onlineOrderingStatus: "ENABLED" } },
+  });
+}
+
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/menu-ordering-settings/query-menu-ordering-settings.md
+export async function queryMenuOrderingSettings(ctx) {
+  const r = await req(ctx, "/menu-ordering-settings/v1/menu-ordering-settings/query", { body: { query: {} } });
+  return r.menuOrderingSettings ?? [];
+}
+
+// Only when an entry shows onlineOrderingEnabled:false / operationId:"none".
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/menu-ordering-settings/update-menu-ordering-settings.md
+export async function updateMenuOrderingSettings(ctx, settingsId, patch) {
+  return req(ctx, `/menu-ordering-settings/v1/menu-ordering-settings/${settingsId}`, {
+    method: "PATCH",
+    body: { menuOrderingSettings: patch },
+  });
+}
+
+// ---- table reservations (setup-restaurant-reservations.md) ---------------------------------------
+// The install AUTO-provisions one default reservation location with a complete config; the
+// one thing OFF is onlineReservationsEnabled (premium-gated). A reservation location cannot
+// be created via this API — discover, configure, enable. Post-Jan-2026 field names:
+// partySize (not partiesSize), approval (not manualApproval).
+
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservation-locations/list-reservation-locations.md
+export async function listReservationLocations(ctx) {
+  const r = await req(ctx, "/table-reservations/reservation-locations/v1/reservation-locations", { method: "GET" });
+  return r.reservationLocations ?? [];
+}
+
+export async function listReservationLocationsWithRetry(ctx, { tries = 15, delayMs = 2000 } = {}) {
+  for (let i = 0; i < tries; i++) {
+    const locs = await listReservationLocations(ctx).catch(() => []);
+    if (locs.length) return locs;
+    if (i < tries - 1) await sleep(delayMs);
+  }
+  return [];
+}
+
+// Partial PATCH; revision mandatory; works on a non-premium site. The `location` object
+// (address/name) is IMMUTABLE here — only touch `configuration`.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservation-locations/update-reservation-location.md
+export async function updateReservationLocation(ctx, reservationLocationId, revision, configuration) {
+  return req(ctx, `/table-reservations/reservation-locations/v1/reservation-locations/${reservationLocationId}`, {
+    method: "PATCH",
+    body: { reservationLocation: { id: reservationLocationId, revision, configuration } },
+  });
+}
+
+// PREMIUM-ONLY: on a non-premium site this THROWS `428 PREMIUM_ONLY` — expected and
+// non-fatal; the caller records it and continues (never retry-spiral, never fail the seed).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservation-locations/update-reservation-location.md
+export async function enableOnlineReservations(ctx, reservationLocationId, revision) {
+  return req(ctx, `/table-reservations/reservation-locations/v1/reservation-locations/${reservationLocationId}`, {
+    method: "PATCH",
+    body: {
+      reservationLocation: {
+        id: reservationLocationId,
+        revision,
+        configuration: { onlineReservations: { onlineReservationsEnabled: true } },
+      },
+    },
+  });
+}
+
+/**
+ * ONE-CALL seed: Menus install (+ sample cleanup when fresh) → menus bottom-up → images →
+ * ordering add-on → reservations add-on, ids threaded in memory. The default path.
+ */
+export async function setupRestaurants(ctx, plan) {
+  const menusPlan = plan.menus ?? [];
+  const wasPresent = await menusAppPresent(ctx);
+  await installMenusApp(ctx);
+  let sampleMenuRemoved = false;
+  if (!wasPresent) {
+    const r = await removeSampleMenu(ctx).catch(() => ({ removed: false }));
+    sampleMenuRemoved = r.removed === true;
+  }
+
+  const createdMenus = [];
+  for (const m of menusPlan) createdMenus.push(await createMenu(ctx, m));
+
+  // image pass — resolve each item's image (import by url / generate by prompt) in ONE
+  // parallel wave (restaurants binds by file id), then bulk full-replace with revision +
+  // priceInfo echoed. Never block on image failure.
+  let imagesAttached = 0;
+  const imageItems = [];
+  menusPlan.forEach((m, mi) => {
+    const flat = m.sections.flatMap((s) => s.items || []);
+    flat.forEach((it, i) => {
+      const created = createdMenus[mi]?.items?.[i];
+      if ((it.imageUrl || it.imagePrompt) && created?.id) {
+        imageItems.push({ ...created, imageUrl: it.imageUrl, imagePrompt: it.imagePrompt, name: it.name });
+      }
+    });
+  });
+  const files = await resolveItemImages(ctx, imageItems.map((it) => ({
+    url: it.imageUrl,
+    path: it.imagePath,
+    prompt: it.imagePrompt,
+    displayName: `${it.name || "item"}.png`,
+  })));
+  const toAttach = imageItems
+    .map((it, i) => (files[i]
+      ? { id: it.id, revision: it.revision ?? "1", price: it.price,
+          image: { id: files[i].id, url: files[i].url, width: 1024, height: 1024 } }
+      : null))
+    .filter(Boolean);
+  if (toAttach.length) {
+    try {
+      await attachItemImages(ctx, toAttach);
+      imagesAttached = toAttach.length;
+    } catch {
+      /* the items stay text-only */
+    }
+  }
+
+  // shared STEP 0 address — set once across both add-ons.
+  let locationSet = false;
+  const ensureLocation = async (address) => {
+    if (address && !locationSet) {
+      await setBusinessLocation(ctx, address);
+      locationSet = true;
+    }
+  };
+
+  const ordering = { enabled: false, addressSet: false };
+  if (plan.ordering) {
+    const cfg = typeof plan.ordering === "object" ? plan.ordering : {};
+    await installOrdersApp(ctx); // auto-provisions operation + methods + per-menu settings
+    await ensureLocation(cfg.address);
+    ordering.addressSet = locationSet;
+    const ops = await listOperationsWithRetry(ctx);
+    const op = ops.find((o) => o.default) ?? ops[0];
+    if (!op) throw new Error("No ordering operation appeared — the Orders app install may not have completed; re-run the seed.");
+    if (op.onlineOrderingStatus !== "ENABLED") await enableOperation(ctx, op.id, op.revision);
+    // confirm each menu is orderable (auto-created + auto-enabled per menu; PATCH only when off)
+    const settings = await queryMenuOrderingSettings(ctx);
+    for (const s of settings) {
+      if (s.onlineOrderingEnabled === false || s.operationId === "none") {
+        await updateMenuOrderingSettings(ctx, s.id, {
+          revision: s.revision,
+          operationId: op.id,
+          onlineOrderingEnabled: true,
+          availability: { type: "ALWAYS_AVAILABLE", timeZone: cfg.address?.timeZone ?? "America/New_York" },
+        }).catch(() => {});
+      }
+    }
+    ordering.enabled = true;
+    ordering.operationId = op.id;
+    if (!ordering.addressSet) ordering.note = "No address in the plan — ordering is 'testing only' until the owner sets the real business address.";
+  }
+
+  const reservations = { enabled: false };
+  if (plan.reservations) {
+    const cfg = typeof plan.reservations === "object" ? plan.reservations : {};
+    await installTableReservationsApp(ctx); // auto-provisions the default reservation location
+    await ensureLocation(cfg.address);
+    let [loc] = await listReservationLocationsWithRetry(ctx);
+    if (!loc) throw new Error("No reservation location appeared — the Table Reservations install may not have completed; re-run the seed.");
+    const configuration = cfg.configuration ?? (cfg.partySize ? { onlineReservations: { partySize: cfg.partySize } } : null);
+    if (configuration) {
+      await updateReservationLocation(ctx, loc.id, loc.revision, configuration);
+      [loc] = await listReservationLocations(ctx); // re-read for the bumped revision
+    }
+    reservations.reservationLocationId = loc.id;
+    try {
+      await enableOnlineReservations(ctx, loc.id, loc.revision);
+      reservations.enabled = true;
+    } catch {
+      // 428 PREMIUM_ONLY on a free site — expected; record, don't fail.
+      reservations.premiumRequired = true;
+    }
+  }
+
+  return {
+    menus: createdMenus.map(({ items, ...m }) => m),
+    imagesAttached,
+    sampleMenuRemoved,
+    ordering,
+    reservations,
+  };
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  if (!planPath) {
+    console.error("usage: node seed-restaurants.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupRestaurants(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}

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

@@ -0,0 +1,22 @@
+# Content floor — the copy you write on every authored surface
+
+**A fallback, not an override.** If the user supplied copy, voice, or tone, use theirs. The
+one exception is the first rule — a comprehension floor, not a style preference.
+
+- **Say what the business is, literally, above the fold.** A first-time visitor must know
+  what the site *is* and can *do* from the hero alone. The business category ("ceramics
+  studio", "trattoria", "yoga studio") appears verbatim in the H1, the kicker above it, or
+  the first clause of the subtitle. A witty H1 is welcome — beside an explicit category,
+  never instead of one.
+- **The subtitle leads with the offer** — the verb the visitor cares about comes early
+  ("Book…", "Order…", "Browse…"), flavor after.
+- **Kickers carry information or don't exist.** "Handmade in Portland · Since 2019" earns its
+  place; "The Collection" above a Collection heading doesn't. A voice-led H1 pairs with an
+  informative kicker (that's where the category goes).
+- **Titles and subtitles end without a period.** Paragraphs keep theirs.
+- **CTA labels are short, concrete, and not all-caps** — the actual action, matching the one
+  primary CTA per page (`DESIGN.md`).
+- **No fluff.** Every line moves a visitor's understanding forward — the H1 and subtitle most
+  of all.
+- **A caption describes what its image actually shows.** A slogan overlaid on a photo is not
+  a caption; if none is warranted, write none.

package/skills/wix-headless-fast/references/shared/CUSTOM_OPERATIONS.md

@@ -0,0 +1,73 @@
+# Custom operations
+
+Shipped vertical code covers its advertised contract. A brief can also require an operation
+outside that contract: a member submission, a file derived in the browser, moderation, a
+custom business write, or a third-party service.
+
+## Decide the boundary first
+
+1. **Caller-permitted Wix operation** — add one function to the appropriate `src/wix/<vertical>/`
+   data layer. Use the documented SDK method; components call that function, never the SDK.
+2. **Privileged Wix operation** — on Wix-managed Astro, create a narrow `src/pages/api/` endpoint.
+   Authenticate/authorize the caller and validate the exact input before elevating the one SDK
+   call with `auth.elevate()`. On another stack, the equivalent belongs on a server using
+   server-only credentials. Never expose an elevated method or credential to the browser.
+3. **No documented Wix path** — simplify the feature to a supported design. Do not infer a
+   contract from generated types, SDK implementation files, or `node_modules`.
+
+## The research rule
+
+Read the relevant shipped playbook first. For a genuine gap, use `wix-docs` to read the
+official method or feature guide, then implement that contract. One documentation lookup and
+one type check are enough before coding. Investigate further only after a concrete error.
+
+## User-created public content
+
+Use the CMS vertical when a visitor or member submits content that the app must later list or
+show publicly. Seed the collection with the appropriate permission preset and never trust the
+browser to choose an owner, collection, or privileged action.
+
+For a small browser-created artifact, the official Wix-managed Astro pattern is a validated
+server endpoint that writes the contribution with elevation. For binary media, first confirm
+the Media Files API's authorization requirements: generating a media upload URL requires
+Manage Media Manager permission, so it is not a browser-side member call. Validate identity,
+MIME type, size, and destination before any elevated call. The authoritative references are:
+
+- `wix-docs`: **Upload Images to CMS** for the secure CMS contribution flow.
+- `wix-docs`: **Generate File Upload URL** and **Upload API** for Media Manager files.
+
+Keep the endpoint specific to the allowed contribution. An endpoint that accepts arbitrary
+SDK method names, collection ids, or upload destinations is a privilege-escalation bug.
+
+## Optional Media Upload capability
+
+Use this only when a site actually needs a normal file upload (not a small canvas artifact
+stored as a CMS data URL). Put the policy in the site plan; the Fast deployer ships the shared
+client helper and Astro endpoint once, plus a generated read-only policy module:
+
+```json
+{
+  "capabilities": {
+    "mediaUpload": {
+      "policies": [{
+        "id": "gallery-artwork",
+        "accept": ["image/png", "image/jpeg"],
+        "maxBytes": 5242880
+      }]
+    }
+  }
+}
+```
+
+The generated policy lives at `src/wix/media-upload/policies.generated.ts`; do not hand-edit
+it. The shared browser helper is `src/wix/media-upload/client.ts`:
+
+```ts
+const media = await uploadMedia("gallery-artwork", pngBlob, "my-drawing.png");
+// media.id and media.url are the Wix Media reference to store in the intended CMS image field.
+```
+
+The browser can select only the **named policy** and the bytes. The deployed API route fixes
+the destination and elevates only `files.generateFileUploadUrl`. A vertical uses the same
+capability by putting its own policy in its plan. Do not copy, fork, or widen the endpoint in
+vertical code.