@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,71 @@
+# Pricing Plans — seeding
+
+Seed by **running `seed-pricing-plans.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 Pricing Plans app if needed, and creates everything
+in the right order.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/pricing-plans/seed/seed-pricing-plans.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3 plans** — a tier ladder
+the grid can render (e.g. free / monthly / yearly), each with 3–4 perks; together they
+exercise every price shape the UI handles. Plans have no seedable images (the owner adds one
+per plan in the dashboard).
+
+```json
+{
+  "plans": [
+    { "name": "Community", "type": "free",
+      "description": "Get a taste — member perks, zero commitment.",
+      "perks": ["Member-only newsletter", "Community events access"] },
+    { "name": "Studio Membership", "price": "29.00",
+      "type": "recurring", "billingCycle": { "period": "MONTH", "count": 1 },
+      "description": "The full experience, month to month.",
+      "perks": ["Unlimited group classes", "10% off workshops", "Priority booking"] },
+    { "name": "Annual Pass", "price": "290.00",
+      "type": "recurring", "billingCycle": { "period": "YEAR", "count": 1 },
+      "description": "Two months free, billed yearly.",
+      "perks": ["Everything in Studio Membership", "2 guest passes", "Annual member gift"] }
+  ]
+}
+```
+
+- `type` — `"recurring"` (default; `billingCycle` defaults to `{ "period": "MONTH", "count": 1 }`),
+  `"one-time"` (bills once, then ends; `billingCycle: null` makes it never expire), or
+  `"free"` (amount forced to `"0"` + a per-member-lifetime purchase limit).
+- `price` — a decimal string (`"29.00"`; a number is stringified). Currency is site-derived —
+  never sent.
+- `perks` — display-only bullets on the plan card; they grant nothing by themselves.
+- `termsAndConditions` (plain text), `visibility` (`"PUBLIC"`), `buyable` (`true`) — optional
+  overrides. A `buyable: false` plan renders without a subscribe CTA (merchant-assigned).
+
+## Covering bookings services (only when bookings is also seeded)
+
+A plan can COVER bookings services — members then book them with the membership. The link
+goes through the Benefit Programs API, not the plan object, keyed by the **bookings seed's
+service ids** — so seed bookings FIRST, then pass the ids:
+
+```json
+{ "name": "Studio Membership", "price": "29.00",
+  "perks": ["Unlimited group classes"],
+  "coveredServiceIds": ["<bookings service id>", "…"] }
+```
+
+Unlimited coverage is the default; a limited pack (e.g. 8 sessions) instead uses
+`"bookingsCoverage": { "serviceIds": [...], "creditAmount": 8 }`. A plans-only run just
+omits both — coverage is skipped automatically.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Escape hatch — individual functions
+`setupPricingPlans` composes exported steps — `installPricingPlansApp`, `createPlans`,
+`attachBookingsCoverage` (and its `getProgramDefinition`, `createPoolDefinition`,
+`createBenefitItems` sub-steps), 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 recipe is `wix-headless/references/inline-recipes/setup-pricing-plans.md`.

package/skills/wix-headless-fast/references/pricing-plans/seed/seed-pricing-plans.mjs

@@ -0,0 +1,279 @@
+// Pricing Plans 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/pricing-plans/seed/seed-pricing-plans.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Pricing Plans app if needed,
+// creates the plans (Plans V3 — one create call per plan; there is no bulk-create), and —
+// only when a plan carries bookings service ids — wires the plan to COVER those services
+// through the Benefit Programs API. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "plans": [{ "name", "description"?, "price"? (decimal string; a number is stringified),
+//                 "type"?: "recurring"|"one-time"|"free",
+//                 "billingCycle"?: { "period": "DAY"|"WEEK"|"MONTH"|"YEAR", "count" } | null,
+//                 "perks"?: ["..."], "termsAndConditions"?, "visibility"?, "buyable"?,
+//                 "coveredServiceIds"?: ["<bookings service id>"],
+//                 "bookingsCoverage"?: { "serviceIds"?, "creditAmount"? } }] }
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →
+// read the live API reference; authoritative source recipe:
+// wix-headless/references/inline-recipes/setup-pricing-plans.md.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+
+const API = "https://www.wixapis.com";
+const PRICING_PLANS_APP_ID = "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3";
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97"; // coverage providerAppId — NOT the Plans id
+const PP_NAMESPACE = "@wix/pricing-plans"; // literal, with the @ and the slash, in every coverage call
+
+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));
+
+// billingTerms selects the plan type (recurring | one-time | free). recurring: billingCycle
+// {period,count} (default MONTH/1) + ON_PURCHASE + UNTIL_CANCELLED. one-time: endType
+// CYCLES_COMPLETED + billingCycleCount 1 (bill once, then ends); an unlimited one-time
+// instead sets billingCycle:null + UNTIL_CANCELLED. free: MUST be the no-cycle unlimited
+// shape — a $0 variant with a billingCycle is rejected ("Free pricing variant cannot be
+// recurring").
+function buildBillingTerms(plan) {
+  const type = plan.type || "recurring";
+  if (type === "free") {
+    return { billingCycle: null, startType: "ON_PURCHASE", endType: "UNTIL_CANCELLED" };
+  }
+  if (type === "one-time") {
+    if (plan.billingCycle === null) {
+      return { billingCycle: null, startType: "ON_PURCHASE", endType: "UNTIL_CANCELLED" };
+    }
+    const cycle = plan.billingCycle || { period: "MONTH", count: 1 };
+    return {
+      billingCycle: cycle,
+      startType: "ON_PURCHASE",
+      endType: "CYCLES_COMPLETED",
+      cyclesCompletedDetails: { billingCycleCount: 1 },
+    };
+  }
+  // recurring
+  const cycle = plan.billingCycle || { period: "MONTH", count: 1 };
+  return { billingCycle: cycle, startType: "ON_PURCHASE", endType: "UNTIL_CANCELLED" };
+}
+
+// One pricingVariant with one pricingStrategy (schema allows ≤20 but is "currently limited
+// to 1"). Amounts are decimal STRINGS ("20.00"); the variant id is a REQUIRED
+// client-supplied GUID — omitting it returns 400.
+function buildPricingVariant(plan) {
+  const free = (plan.type || "recurring") === "free";
+  const amount = free ? "0" : String(plan.price);
+  return {
+    id: randomUUID(),
+    name: plan.variantName || "Standard",
+    billingTerms: buildBillingTerms(plan),
+    pricingStrategies: [{ flatRate: { amount } }],
+  };
+}
+
+// plain plan -> Plans V3 create body. status:"ACTIVE" is REQUIRED (omitting → 400
+// "status value is required"); currency is NOT sent (read-only, site-derived); perks are
+// display-only bullets, each with a REQUIRED client-supplied GUID.
+function buildPlan(plan) {
+  const free = (plan.type || "recurring") === "free";
+  return {
+    name: plan.name,
+    description: plan.description,
+    status: "ACTIVE",
+    visibility: plan.visibility || "PUBLIC",
+    buyable: plan.buyable ?? true,
+    buyerCanCancel: plan.buyerCanCancel ?? true,
+    ...(plan.termsAndConditions ? { termsAndConditions: plan.termsAndConditions } : {}),
+    pricingVariants: [buildPricingVariant(plan)],
+    perks: (plan.perks ?? []).map((p) => ({
+      id: randomUUID(),
+      description: typeof p === "string" ? p : p.description,
+    })),
+    // free: cap lifetime reuse. Array + maxCount per the SDK schema (PurchaseLimit[]); the
+    // recipe's older `{ type, count }` object form predates it.
+    ...(free ? { purchaseLimits: [{ type: "PER_MEMBER_LIFETIME", maxCount: 1 }] } : {}),
+  };
+}
+
+// ---- operations ----------------------------------------------------------------------------------
+
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installPricingPlansApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: PRICING_PLANS_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// Create the plan(s) — Plans V3 has NO bulk-create: one POST per plan. Keep plan.id: the
+// frontend orders by it AND it is the coverage externalId.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan.md
+export async function createPlans(ctx, plans) {
+  const out = [];
+  for (const plan of plans) {
+    const r = await req(ctx, "/pricing-plans/v3/plans", { body: { plan: buildPlan(plan) } });
+    out.push({
+      id: r.plan?.id,
+      slug: r.plan?.slug,
+      name: plan.name,
+      coveredServiceIds: plan.coveredServiceIds,
+    });
+  }
+  return out;
+}
+
+// ---- bookings coverage via Benefit Programs (SKIP when no bookings in the run) -------------------
+// Strictly ordered: plan.id -> programDefinition.id -> itemSetId -> items. Do NOT parallelize.
+
+// 2a: READ the auto-created program definition (the Plans app creates it; you never create
+// it). Provisioning is ~immediate but async — retry ONCE after a short backoff, don't loop.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/program-definitions/introduction.md
+export async function getProgramDefinition(ctx, planId) {
+  const path = `/benefit-programs/v1/program-definitions/by-namespace-and-external-id?externalId=${planId}&namespace=${encodeURIComponent(PP_NAMESPACE)}`;
+  try {
+    const r = await req(ctx, path, { method: "GET" });
+    if (r.programDefinition?.id) return r.programDefinition.id;
+  } catch {
+    /* fall through to the single insurance retry */
+  }
+  await sleep(1000);
+  const r = await req(ctx, path, { method: "GET" });
+  return r.programDefinition?.id;
+}
+
+// 2b: create ONE pool definition with EXACTLY ONE benefit naming Bookings as the provider.
+// price "0" = unlimited (default; no creditConfiguration). Limited pack: pass creditAmount →
+// price "1" + details.creditConfiguration (a SIBLING of benefits[], NOT inside a benefit —
+// nesting it 400s with "Price should be 0 when credit pool is not set up").
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/create-pool-definition.md
+export async function createPoolDefinition(ctx, programDefinitionId, { creditAmount } = {}) {
+  const limited = creditAmount != null;
+  const details = {
+    ...(limited ? { creditConfiguration: { amount: String(creditAmount) } } : {}),
+    benefits: [
+      {
+        benefitKey: randomUUID(),
+        displayName: "Bookings sessions",
+        providerAppId: BOOKINGS_APP_ID,
+        price: limited ? "1" : "0",
+      },
+    ],
+  };
+  const r = await req(ctx, "/benefit-programs/v1/pool-definitions", {
+    body: {
+      poolDefinition: {
+        namespace: PP_NAMESPACE,
+        displayName: "Bookings benefit",
+        programDefinitionIds: [programDefinitionId],
+        details,
+      },
+      cascade: "IMMEDIATELY",
+    },
+  });
+  // itemSetId lives at poolDefinition.details.benefits[i].itemSetId — one benefit here, so [0].
+  return r.poolDefinition?.details?.benefits?.[0]?.itemSetId;
+}
+
+// 2c: bulk-create the benefit items — ONE item per covered service (externalId = bookings
+// service id). Up to 100 per call; category is an empty string; namespace/providerAppId
+// repeat 2b's values.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/items/bulk-create-items.md
+export async function createBenefitItems(ctx, itemSetId, serviceIds) {
+  return req(ctx, "/benefit-programs/v1/bulk/items/create", {
+    body: {
+      items: serviceIds.map((externalId) => ({
+        namespace: PP_NAMESPACE,
+        category: "",
+        providerAppId: BOOKINGS_APP_ID,
+        itemSetId,
+        externalId,
+      })),
+      returnEntity: true,
+    },
+  });
+}
+
+/**
+ * Wire a plan to COVER bookings services (per plan). Runs 2a → 2b → 2c in order.
+ * serviceIds come from the BOOKINGS seed — seed bookings first.
+ */
+export async function attachBookingsCoverage(ctx, planId, serviceIds, { creditAmount } = {}) {
+  const programDefinitionId = await getProgramDefinition(ctx, planId);
+  if (!programDefinitionId) throw new Error(`No program definition for plan ${planId} — is the Pricing Plans app installed?`);
+  const itemSetId = await createPoolDefinition(ctx, programDefinitionId, { creditAmount });
+  await createBenefitItems(ctx, itemSetId, serviceIds);
+  return { itemSetId, serviceIds };
+}
+
+/**
+ * ONE-CALL seed: install → create plans (ids kept in memory) → per covering plan, wire
+ * bookings coverage (2a → 2b → 2c, strictly ordered). The default path.
+ */
+export async function setupPricingPlans(ctx, { plans = [] } = {}) {
+  await installPricingPlansApp(ctx);
+  const created = await createPlans(ctx, plans);
+  const coverageAttached = [];
+  for (let i = 0; i < created.length; i++) {
+    const cov = plans[i].bookingsCoverage || {};
+    const serviceIds = cov.serviceIds || created[i].coveredServiceIds;
+    if (!serviceIds?.length) continue; // plans-only plan — coverage skipped
+    const r = await attachBookingsCoverage(ctx, created[i].id, serviceIds, { creditAmount: cov.creditAmount });
+    coverageAttached.push({ planId: created[i].id, ...r });
+  }
+  return {
+    plans: created,
+    coverageAttached,
+    benefitsCreated: coverageAttached.reduce((n, c) => n + c.serviceIds.length, 0),
+  };
+}
+
+// ---- 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-pricing-plans.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupPricingPlans(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/restaurants/INSTRUCTIONS.md

@@ -0,0 +1,165 @@
+# Restaurants — playbook
+
+The restaurant machinery ships as files — the assembled menu tree (menus → sections → items
+with variants, modifiers, labels), the dish-ordering cart on the eCom current cart with the
+exact restaurant `catalogReference`, the hosted checkout, and the table-reservation
+hold → reserve flow, typed end-to-end. **The presentation is yours**: you design and
+implement the dish card, the menu surface, the order-cart chrome, and the reservations
+surface on the shipped hooks/DTOs, plus the home page and the brand. You never write
+ordering or reservation logic; you never skip designing.
+
+## The file map (deployed into `src/`)
+
+**Don't read the shipped files** — this table and the contracts below are everything you
+need. Open a shipped file's source only on a real fallback (runtime error / uncovered field),
+or to read a reference component's pattern.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
+| `wix/restaurants/types.ts` | the DTOs (`MenuData`, `MenuSection`, `MenuItem`, `OrderCart`, `ReservationSlot`, …) — contracts below |
+| `wix/restaurants/menu.ts` | `fetchMenus` — the whole display-ordered menu tree, one call |
+| `wix/restaurants/ordering.ts` · `order-store.ts` | dish add-to-cart (Orders-app catalogReference) + eCom Cart V2 + shared cart state (module store — spans Astro islands) |
+| `wix/restaurants/reservations.ts` | locations, AVAILABLE slots, `holdReservation`, `completeReservation` — the exact hold→reserve sequence lives here |
+| `hooks/restaurants/useMenus.ts` | menu browsing + menu switching — contract below |
+| `hooks/restaurants/useOrderCart.ts` | order-cart state + actions — contract below |
+| `hooks/restaurants/useReservation.ts` | the whole reservation state machine — contract below |
+| `components/restaurants/MenuView.tsx` (+ `MenuItemCard`) · `OrderCartButton.tsx` · `OrderCartDrawer.tsx` · `ReservationView.tsx` | **REFERENCE implementations** — correct, plain; build your own instead of shipping them |
+| `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | site chrome — **yours to brand** (keep the `seo-tags` slot, global.css import, and one OrderCartButton + one OrderCartDrawer, both `client:only`). If another vertical is also deployed, its layout won — merge the Menu/Reservations links + cart mounts there |
+| `pages/menu.astro` | SSR menu — **keep the frontmatter**, swap the island import to YOUR component |
+| `pages/reservations.astro` | reservations — the island stays `client:only="react"` (availability is timezone-specific); swap the import to YOUR component |
+
+## What you build — the design job
+
+1. **The dish card + menu surface** — your card (photo treatment, price/variants, labels,
+   sold-out state, add-to-order) and your menu layout (menu tabs when >1, section navigation,
+   section rhythm), with skeletons while loading and an honest empty state — on `useMenus` +
+   `useOrderCart`.
+2. **The order-cart chrome** — your header order button (live count) and your cart panel
+   (lines, quantity stepper, remove, subtotal, checkout CTA) — on `useOrderCart`, which owns
+   ALL cart logic; you own how it looks.
+3. **The reservations surface** — party/date/time query, slot pills, the 10-minute-hold
+   details form (first name + phone required), and the confirmed vs pending-approval states —
+   on `useReservation`.
+4. **The home page** — hero, a featured-dishes strip (fetch `fetchMenus()` in frontmatter →
+   your cards; `item.featured` marks highlights), hours/location story, reserve CTA.
+
+Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
+Style everything with Tailwind utilities on the tokens.
+
+### The contracts your components consume
+
+```ts
+// MenuData → sections → items, all display-ordered:
+// MenuItem = { id, name, description, price /* display string; null when variant-priced */,
+//   marketPrice /* true → "Market price", not orderable */,
+//   variants: [{ variantId, name, price }], imageUrl, labels: [{ id, name, iconUrl }],
+//   modifierGroups: [{ id, name, required, minSelections, maxSelections,
+//                      modifiers: [{ id, name, preSelected, additionalCharge, inStock }] }],
+//   inStock, featured }
+// ⚠ MENU prices carry NO currency symbol unless the platform formatted them — render as
+//   given; if plain decimals, prefix the brand's currency yourself. Order-cart prices ARE
+//   formatted. Modifier groups are DISPLAY-ONLY (selections aren't sent on the cart line).
+
+// useMenus({ initialMenus? }) →
+// { menus: MenuData[]|null /* null = loading → skeletons */,
+//   activeMenuId, setActiveMenuId(id), activeMenu: MenuData|null, error }
+
+// useOrderCart() →
+// { cart: { lines, itemCount, subtotal, currency }|null,
+//   ordering: boolean|null,                 // false → show "ordering unavailable"; null = resolving
+//   busy, error, open,
+//   addToOrder(itemId, { menuId, sectionId }, qty?),  // ids from the render context — see hard rules
+//   updateQuantity(lineItemId, qty), removeLine(lineItemId),
+//   checkout(),                             // browser redirects to the Wix-hosted checkout
+//   openCart(), closeCart(), refresh() }
+// OrderLine = { lineItemId, itemName, quantity, unitPrice, linePrice, imageUrl,
+//               descriptionLines, status /* not "IN_STOCK" → can't check out */ }
+
+// useReservation() →
+// { locations: [{ id, partySizeMin, partySizeMax, approvalMode, onlineReservationsEnabled }]|null,
+//   location, setLocationId(id),            // picker only when locations.length > 1
+//   date, setDate("YYYY-MM-DD"), time, setTime("HH:mm"), partySize, setPartySize(n),
+//   slots: ReservationSlot[]|null, findSlots(),   // AVAILABLE only; null until findSlots ran
+//   held, holdSlot(slot),                    // 10-minute hold → render the details form
+//   reservee, setReserveeField(field, value), // firstName + phone (E.164) required
+//   canConfirm, confirm(),                    // gate the CTA on canConfirm
+//   confirmed: { reservationId, status: "RESERVED"|"REQUESTED" }|null,
+//   reset(), loading, error }
+```
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the
+   winning layout instead if another vertical is also deployed).
+2. Write your components under `src/components/restaurants/` (new names — don't overwrite the
+   references), swap the island imports in `pages/menu.astro` and `pages/reservations.astro`.
+   Menu island: `client:load` with the SSR props; reservations island and the cart chrome:
+   `client:only="react"`. **Author your surfaces in as few messages as possible** — batch
+   multiple Writes per message.
+3. Write `pages/index.astro` (home) — it exists from the scaffold; Read it before overwriting.
+
+### Wiring — React SPA (Vite etc.)
+
+Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
+plugins — deploy added the dep). Routes: `/menu` → your menu surface (`useMenus()` fetches
+client-side when no `initialMenus`); `/reservations` → your reservation surface. Mount your
+order button in the header and your drawer once.
+
+## Hard rules
+
+- **Ordering logic only through the shipped exports** — `useOrderCart`/`addToOrder` own the
+  restaurant `catalogReference` (the Orders app id + `operationId`/`menuId`/`sectionId` — all
+  three, no `variantId`), the line-refusal checks, and the checkout redirect. Never re-derive
+  any of it, never hand-build a checkout URL.
+- **Thread `menuId` + `sectionId` from the render context** — each dish is rendered inside a
+  known section of a known menu (the `fetchMenus` tree); pass those ids to `addToOrder`.
+  Never look them up again.
+- **Modifier groups are display-only** — show them on the dish (diners read them; staff sees
+  choices at the counter), but don't invent a way to send selections: that cart-line shape
+  isn't documented. Send quantity only, as shipped.
+- **Reservations only through `useReservation`** — AVAILABLE-only slots, the hold's
+  `revision`, the firstName+phone requirement, and the RESERVED/REQUESTED split all live in
+  the data layer. Gate the CTA on `canConfirm`, surface `error` (holds expire in 10 minutes —
+  the hook already restarts the flow).
+- **The confirmed state must reflect REAL success**: render it only from `confirmed`, and
+  render `REQUESTED` as "pending the restaurant's approval", never as confirmed. A visitor
+  returning from the hosted checkout is NOT an order-success signal.
+- **Honest unavailability**: `ordering === false` → an "ordering unavailable" state on the
+  add button; `onlineReservationsEnabled === false` → a "call us to book" notice (the toggle
+  is premium-gated). Never mock menus, dishes, prices, slots, or availability.
+- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard link (`https://manage.wix.com/dashboard/<siteId>`) plus:
+`…/wix-restaurants-menus-new` (edit the menu), `…/wix-restaurants-orders-new/settings`
+(fulfillment: pickup/delivery hours, fees), `…/wix-table-reservations/table-reservations`
+(tables, availability). Real paid orders need a premium plan + a connected payment method,
+and the online-reservations toggle itself is premium — mention both.
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-restaurants.mjs` from the project
+root. Seed a menu that exercises the UI (a few sections, an image per dish) and turn on the
+ordering + reservations add-ons when the restaurant takes orders/bookings.
+
+## Verify (before declaring done)
+
+- [ ] `/menu` renders the live menu SSR (view-source shows dish names) through YOUR
+      components, sections in seeded order; an empty backend shows your honest empty state.
+- [ ] Add to order works (drawer opens, count badge is live); quantity ± / remove work; the
+      order survives a reload (same visitor token); checkout redirects to the Wix-hosted
+      checkout — or, with no ordering operation, your "ordering unavailable" state shows.
+- [ ] `/reservations`: only AVAILABLE times offered; hold → details form → confirm produces
+      your RESERVED or REQUESTED state; a non-premium site shows your honest
+      "reservations aren't open yet" notice instead of a broken form.
+- [ ] Dish card / menu / cart chrome / reservations / home are YOUR designs on the tokens;
+      data-layer/hook files unedited.
+- [ ] Dashboard links handed to the owner, with the premium notes.

package/skills/wix-headless-fast/references/restaurants/app/components/restaurants/MenuView.tsx

@@ -0,0 +1,142 @@
+// REFERENCE menu surface: menu tabs (when >1), section nav, and the dish card, on the
+// @theme tokens. Correct and complete; per the skill's model you design and build your own
+// on useMenus + useOrderCart. Note the load-bearing wiring: each card threads its menuId +
+// sectionId from the render context into addToOrder — never re-derive them.
+import { useState } from "react";
+import { useMenus } from "../../hooks/restaurants/useMenus";
+import { useOrderCart } from "../../hooks/restaurants/useOrderCart";
+import type { MenuData, MenuItem } from "../../wix/restaurants/types";
+
+export interface MenuItemCardProps {
+  item: MenuItem;
+  menuId: string;
+  sectionId: string;
+}
+
+export function MenuItemCard({ item, menuId, sectionId }: MenuItemCardProps) {
+  const { addToOrder, ordering, busy } = useOrderCart();
+  const [error, setError] = useState<string | null>(null);
+  const canAdd = ordering === true && item.inStock && !item.marketPrice && !busy;
+
+  return (
+    <div className="flex gap-4 rounded-lg border border-border p-4">
+      {item.imageUrl && (
+        <img
+          src={item.imageUrl}
+          alt={item.name}
+          loading="lazy"
+          className="h-24 w-24 flex-shrink-0 rounded-md bg-secondary object-cover"
+        />
+      )}
+      <div className="min-w-0 flex-1">
+        <div className="flex items-baseline justify-between gap-3">
+          <p className="text-sm font-semibold">{item.name}</p>
+          <p className="whitespace-nowrap text-sm text-foreground">
+            {item.marketPrice ? "Market price" : (item.price ?? "")}
+          </p>
+        </div>
+        {item.labels.length > 0 && (
+          <p className="mt-0.5 text-xs text-muted-foreground">{item.labels.map((l) => l.name).join(" · ")}</p>
+        )}
+        {item.description && (
+          <p className="mt-1 text-xs leading-relaxed text-muted-foreground">{item.description}</p>
+        )}
+        {item.variants.length > 0 && (
+          <p className="mt-1 text-xs text-muted-foreground">
+            {item.variants.map((v) => `${v.name} ${v.price}`).join(" · ")}
+          </p>
+        )}
+        {item.modifierGroups.length > 0 && (
+          <p className="mt-1 text-xs text-muted-foreground">
+            {/* Modifier groups are DISPLAY-ONLY — selections aren't sent on the cart line. */}
+            Options: {item.modifierGroups.map((g) => g.name).join(", ")}
+          </p>
+        )}
+        <div className="mt-2 flex items-center gap-3">
+          {ordering !== null && !item.marketPrice && (
+            <button
+              type="button"
+              disabled={!canAdd}
+              onClick={() =>
+                addToOrder(item.id, { menuId, sectionId }).catch((e: unknown) =>
+                  setError(e instanceof Error ? e.message : String(e)),
+                )
+              }
+              className="rounded-full bg-primary px-4 py-1.5 text-xs font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-40"
+            >
+              {!item.inStock ? "Sold out" : ordering === false ? "Ordering unavailable" : "Add to order"}
+            </button>
+          )}
+          {error && <p className="text-xs text-red-600">{error}</p>}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export interface MenuViewProps {
+  initialMenus?: MenuData[];
+  emptyMessage?: string;
+}
+
+const tab = (active: boolean) =>
+  `rounded-full border px-4 py-1.5 text-sm font-medium transition-colors ${
+    active
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function MenuView({
+  initialMenus,
+  emptyMessage = "The menu is being written — check back soon.",
+}: MenuViewProps) {
+  const { menus, activeMenuId, setActiveMenuId, activeMenu, error } = useMenus({ initialMenus });
+
+  if (menus === null) {
+    return (
+      <div aria-busy="true">
+        {Array.from({ length: 4 }, (_, i) => (
+          <div key={i} className="mb-4 h-24 animate-pulse rounded-lg bg-secondary" />
+        ))}
+      </div>
+    );
+  }
+  if (menus.length === 0) {
+    return <p className="py-16 text-center text-muted-foreground">{error ?? emptyMessage}</p>;
+  }
+
+  return (
+    <div>
+      {menus.length > 1 && (
+        <div className="mb-8 flex flex-wrap gap-2" role="group" aria-label="Menus">
+          {menus.map((m) => (
+            <button key={m.id} type="button" className={tab(m.id === activeMenuId)} onClick={() => setActiveMenuId(m.id)}>
+              {m.name}
+            </button>
+          ))}
+        </div>
+      )}
+      {activeMenu && activeMenu.sections.length > 1 && (
+        <nav className="mb-8 flex flex-wrap gap-x-5 gap-y-1 text-sm" aria-label="Sections">
+          {activeMenu.sections.map((s) => (
+            <a key={s.id} href={`#section-${s.id}`} className="text-muted-foreground no-underline transition-colors hover:text-foreground">
+              {s.name}
+            </a>
+          ))}
+        </nav>
+      )}
+      {error && <p className="mb-4 text-sm text-red-600">{error}</p>}
+      {activeMenu?.sections.map((section) => (
+        <section key={section.id} id={`section-${section.id}`} className="mb-12">
+          <h2 className="text-lg font-semibold tracking-tight">{section.name}</h2>
+          {section.description && <p className="mt-1 text-sm text-muted-foreground">{section.description}</p>}
+          <div className="mt-4 grid grid-cols-1 gap-4 md:grid-cols-2">
+            {section.items.map((item) => (
+              <MenuItemCard key={item.id} item={item} menuId={activeMenu.id} sectionId={section.id} />
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}