@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-headless/references/inline-recipes/setup-restaurant-orders.md

@@ -0,0 +1,197 @@
+---
+name: "Setup Restaurant Orders"
+description: Configures Wix Restaurants **Online Ordering** on top of an already-seeded Menus backend. Installing the Orders app AUTO-PROVISIONS a working ordering setup (an ENABLED operation with Pickup + Delivery attached, and every menu ordering-enabled), so this recipe VERIFIES that baseline and CUSTOMIZES the fulfillment methods to the request — it does NOT build ordering from scratch. Specifies the *how* (calls + format); which methods/fees/hours and which menus come from the request.
+---
+**RECIPE**: Business Recipe – Online-Ordering Setup for Wix Restaurants (Orders app)
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` **and** `wix-site-id: <SITE_ID>`. Body-bearing requests also need `Content-Type: application/json`.
+
+A checklist for online ordering on a Wix site that already has a **Restaurants Menus** backend.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial ordering setup.
+
+> **⚠️ THE ORDERS-APP INSTALL DOES ALMOST EVERYTHING — this recipe VERIFIES and CUSTOMIZES, it does NOT create ordering from scratch.** Installing the Orders app auto-provisions a **fully working** ordering setup with **zero** extra calls:
+> - one **operation** (`onlineOrderingStatus: "ENABLED"`, `default: true`, `defaultFulfillmentType: "PICKUP"`, a full `orderScheduling`);
+> - **three fulfillment methods already attached** to it — a `"Pickup"` (enabled), a `"Delivery Area #1"` (DELIVERY, RADIUS, enabled, `fee "0"`), and a `"DoorDash Drive"` (DELIVERY, provider-based, **disabled**);
+> - a **menu-ordering-settings** object per menu, each already `onlineOrderingEnabled: true` and bound to the operation.
+>
+> So a site with a seeded menu is **already orderable (pickup + delivery) the moment the Orders app is installed.** The steps below **verify** that baseline and **reshape it to the request** (rename/re-fee/re-hour the auto methods, disable unwanted ones, add extra ones). If the request asks for nothing beyond "let people order," all steps are just confirmations — keep the auto-provisioned defaults and do only the verification (STEP 2 reshapes methods **only** when the request names specifics).
+
+> **⚠️ DEPENDS ON MENUS — the menu must exist.** A customer orders **menu items**, and each menu is bound to the ordering operation through a **menu-ordering-settings** object. This recipe assumes the **Menus** backend is already seeded (`setup-restaurants.md` — menu → sections → items, all `visible: true`) and its `menuId`(s) are in hand. Installing the **Orders** app **auto-installs the Menus app** and **auto-creates one menu-ordering-settings object per menu** — for menus that already exist *and* for menus created *after* install — each already `onlineOrderingEnabled: true` and bound to the operation. So whichever order you install Orders vs. seed menus, every menu ends up orderable automatically; STEP 3 only verifies it.
+
+> **This recipe is the *how*, not the *what*.** Which fulfillment methods to offer (pickup, delivery, or both), their fees / minimum-order amounts / hours / delivery area, and which menus are orderable come from the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide those quantities. Per the "simple seeds" default, **if the request names no ordering specifics, keep the auto-provisioned defaults** and do only the verification steps.
+
+> **⚠️ API surfaces — this vertical spans SEVERAL micro-services, each on its OWN host prefix** (unlike Menus, which is all under `restaurants/menus/v1`). Do not "normalize" them to a single prefix:
+> - **Operations** — `https://www.wixapis.com/restaurants-operations/v1/operations`
+> - **Fulfillment methods** — `https://www.wixapis.com/fulfillment-methods/v1/fulfillment-methods`
+> - **Menu ordering settings** — `https://www.wixapis.com/menu-ordering-settings/v1/menu-ordering-settings`
+>
+> These are the **new** Wix Restaurants Orders APIs. A superseded cURL sample in the docs still shows the old `restaurants/v1/fulfillment-methods` host **and** a snake_case `fulfillment_method` wrapper — ignore both. Use the `fulfillment-methods/v1/...` host and the **camelCase `fulfillmentMethod`** wrapper (for both create and update).
+
+> **⚠️ Operations & operation groups are AUTO-provisioned — never create them.** There is **no create-operation / create-operation-group** call in this flow. On install Wix creates one operation group and, for a headless site with **no business location configured**, a single operation with `businessLocationId: "none"`. You **discover** that operation (STEP 1) and, only if customizing, **PATCH** it; you never POST one.
+
+---
+
+## Article: Steps for Setting Up Wix Restaurants Online Ordering
+**YOU MUST** complete all the following steps **in the given order** (0-3) without skipping any and **without requiring additional user input**. Every step is idempotent — it verifies the auto-provisioned state and only writes when the request calls for a change or the state is wrong.
+
+### STEP 0: Configure the business location address (required for ordering to actually work)
+
+**⚠️ Online ordering needs a business location with a REAL address — without it, ordering is "testing only" and checkout breaks at runtime.** This is the #1 silent gap for ordering sites: the Wix docs are explicit — *"If locations aren't configured on a site, online ordering functionality is limited to testing only, and in some cases may not work as expected"* (<https://dev.wix.com/docs/api-reference/business-solutions/restaurants/about-business-locations.md>). A site provisions with a **default location that has no street address** (only an auto-defaulted country/city), which counts as *not configured*. Fix it here, before verifying the operation.
+
+The **default** business location is the one online ordering reads; its address also **propagates to Site Properties** (the site's business address that the Business Manager shows). Docs: Locations API <https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md> · Update Location <https://dev.wix.com/docs/api-reference/business-management/locations/update-location.md>.
+
+1. **List locations** and take the default (`GET https://www.wixapis.com/locations/v1/locations` → the entry with `default: true`). Keep its **`id`** and **`revision`**. (There is normally exactly one, auto-provisioned.)
+2. **Overwrite it with a real address** via **Update Location** — `PUT https://www.wixapis.com/locations/v1/locations/<id>`. Use the address from the request; the timezone should match it.
+
+```bash
+curl -sS <AUTH> -X PUT "https://www.wixapis.com/locations/v1/locations/<id>" \
+  -d '{
+    "location": {
+      "id": "<id>", "revision": "<revision>", "default": true,
+      "name": "<Business name>", "timeZone": "Europe/Paris",
+      "email": "<email>", "phone": "<phone>",
+      "address": {
+        "country": "FR", "subdivision": "FR-75", "city": "Paris", "postalCode": "75001",
+        "streetAddress": { "number": "18", "name": "Rue des Lumières" },
+        "formattedAddress": "18 Rue des Lumières, 75001 Paris, France"
+      }
+    }
+  }'
+```
+
+**⚠️ CRITICAL — earned gotchas (verified against the live API):**
+- **Update Location is a FULL OVERRIDE, not a partial update** (the docs say so explicitly). Send the **whole** `location` object, not just the address — omitted fields are wiped. A partial "just the address" body is the classic *"it reported success but nothing changed / it's not in the Business Manager"* failure.
+- **Echo `"default": true`.** The default flag isn't in the documented request params, but omitting it on a full override reads as flipping it off and **400s** with `CHANGE_DEFAULT_FORBIDDEN`. (Good news: this API fails **loudly** — prefer it over a field-mask-less Site-Properties `PATCH`, which silently no-ops.)
+- **`revision` is mandatory** (from STEP 0.1) and increments each update; a stale one 400s.
+- **`address.country` is a 2-letter ISO-3166 code** (`"FR"`, `"US"`), not a full name.
+- **No default location at all?** (a bare Orders-only site can have none — operations then carry `businessLocationId: "none"`.) **Create** one instead: `POST https://www.wixapis.com/locations/v1/locations` with the same `location` body (no `id`/`revision`), then it becomes the site's location and operations auto-bind on first-location-add (see about-business-locations). Docs: <https://dev.wix.com/docs/api-reference/business-management/locations/create-location.md>.
+- **The operation's `businessLocationDetails` is a denormalized snapshot with eventual-consistency lag** — after the update it may briefly still show the old placeholder address (e.g. a "San Francisco" default). That's cosmetic and self-heals; checkout reads the configured location/site address, which is correct immediately. Don't loop trying to "force" the snapshot.
+
+**Where the address comes from:** the request. If the brief names the restaurant's address, use it. **If it doesn't, a real address is genuine owner info the skill can't invent** — set a clearly-marked placeholder and **flag prominently in the handoff/summary that the owner must set their real business address before ordering works** (this is exactly the "make it work end-to-end" gap). Pair this with the premium/payment precondition below.
+
+### STEP 1: Verify (and if needed enable) the operation
+
+List operations and take the one Wix created on install. Keep its **`id`** and **`revision`**.
+
+```bash
+curl -sS <AUTH> -X GET "https://www.wixapis.com/restaurants-operations/v1/operations"
+```
+
+Response (`operations[]`, sorted by created date ascending):
+
+```json
+{ "operations": [
+  { "id": "<operationId>", "revision": "2", "name": "Ordering page 1", "default": true,
+    "onlineOrderingStatus": "ENABLED", "defaultFulfillmentType": "PICKUP",
+    "fulfillmentIds": ["<deliveryId>", "<pickupId>", "<doordashId>"],
+    "orderScheduling": { "type": "ASAP", "asapOptions": { "preparationTime": { "type": "MAX_TIME", "maxTimeOptions": { "timeUnit": "MINUTES", "duration": 30 } }, "asapFutureHandlingType": "BUSINESS_DAYS_AHEAD_HANDLING", "businessDaysAheadHandlingOptions": { "daysCount": 0 } } },
+    "operationGroupId": "<groupId>", "businessLocationId": "none" }
+] }
+```
+
+**⚠️ CRITICAL:**
+- **Do not POST to create an operation** — there is none to create; use the one that already exists. If `operations[]` comes back **empty**, the Orders-app install hasn't finished provisioning — **wait briefly and retry the GET once**; do not create anything. Still empty after one retry → **fail loud** (install didn't complete).
+- **`onlineOrderingStatus` is normally already `"ENABLED"`** on the auto-created operation — nothing to do. Only if you see `"DISABLED"` (or you paused it), PATCH it on:
+  ```bash
+  curl -sS <AUTH> -X PATCH "https://www.wixapis.com/restaurants-operations/v1/operations/<operationId>" \
+    -d '{ "operation": { "revision": "<operationRevision>", "onlineOrderingStatus": "ENABLED" } }'
+  ```
+  Enum values: `ENABLED` / `DISABLED` / `PAUSED_UNTIL`. **`revision` is mandatory and must be current** (it increments by 1 each PATCH; a stale revision 400s). **If you PATCH `orderScheduling`, send the whole object** — it's overwritten wholesale, not merged.
+- For a locationless headless site `businessLocationId` is **`"none"`** — expected; it matches the menu's `"none"` so ordering binds. Don't set a location.
+- Read `fulfillmentIds` here — it lists the methods currently attached to the operation (STEP 2 needs it).
+
+### STEP 2: Reconcile the fulfillment methods to the request
+
+List the fulfillment methods the install created, then shape them to the request. **Which methods/fees/hours/areas the site should offer come from the request — this step only gives the calls.**
+
+```bash
+curl -sS <AUTH> -X GET "https://www.wixapis.com/fulfillment-methods/v1/fulfillment-methods"
+```
+
+The install ships three (all with an `America/..`-defaulted **San Francisco placeholder** address and time zone from the site's region): a `PICKUP` `"Pickup"` (enabled), a `DELIVERY` `"Delivery Area #1"` (RADIUS, enabled, `fee "0"`), and a `DELIVERY` `"DoorDash Drive"` (provider-based, **disabled**). Keep each `fulfillmentMethod.id` and `revision`.
+
+Do only what the request calls for:
+
+**(a) Customize an auto-created method** (rename, set fee/minimum/hours/area) — PATCH it, partial body is fine:
+
+```bash
+curl -sS <AUTH> -X PATCH "https://www.wixapis.com/fulfillment-methods/v1/fulfillment-methods/<methodId>" \
+  -d '{ "fulfillmentMethod": { "revision": "<methodRevision>", "name": "Delivery", "fee": "5", "minOrderPrice": "20" } }'
+```
+
+**(b) Disable a method the request doesn't want** — PATCH `enabled: false` (leave `"DoorDash Drive"` disabled unless the request wants a 3rd-party courier):
+
+```bash
+curl -sS <AUTH> -X PATCH "https://www.wixapis.com/fulfillment-methods/v1/fulfillment-methods/<methodId>" \
+  -d '{ "fulfillmentMethod": { "revision": "<methodRevision>", "enabled": false } }'
+```
+
+**(c) Add a method beyond the defaults** (e.g. a "Curbside" pickup) — create it, THEN attach it to the operation:
+
+```bash
+# create — camelCase `fulfillmentMethod` wrapper
+curl -sS <AUTH> -X POST "https://www.wixapis.com/fulfillment-methods/v1/fulfillment-methods" \
+  -d '{ "fulfillmentMethod": {
+        "type": "PICKUP", "name": "Curbside", "enabled": true, "fee": "0", "minOrderPrice": "0",
+        "availability": { "availableTimes": [ { "dayOfWeek": "MON", "timeRanges": [ { "startTime": { "hours": 9, "minutes": 0 }, "endTime": { "hours": 22, "minutes": 0 } } ] } ], "timeZone": "America/New_York" },
+        "pickupOptions": { "instructions": "Wait in your car." } } }'
+# → { "fulfillmentMethod": { "id": "<newId>", "revision": "1", ... } }   (address auto-defaults if omitted)
+```
+Then PATCH the operation to add `<newId>` to `fulfillmentIds` (the create does **not** attach it — see the callout):
+
+```bash
+curl -sS <AUTH> -X PATCH "https://www.wixapis.com/restaurants-operations/v1/operations/<operationId>" \
+  -d '{ "operation": { "revision": "<currentOperationRevision>", "fulfillmentIds": [ "<existingId1>", "<existingId2>", "<newId>" ] } }'
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **A newly created fulfillment method is NOT auto-attached to the operation** (after a create, `operation.fulfillmentIds` is unchanged). Only the *install's* three are attached automatically. So whenever you **create** a method, you must **PATCH the operation's `fulfillmentIds`** to include it (pass the full array — existing ids **plus** the new one), or it won't be offered at checkout. Customizing/disabling an *existing* attached method needs no re-attach.
+- **Attach each fulfillment method to exactly one operation** — Wix warns that sharing a method across operations breaks ordering.
+- **Wrap create/update bodies in `fulfillmentMethod`** (camelCase). **`fee` and `minOrderPrice` are decimal STRINGS** (`"0"`, `"5"`, `"20"`), never numbers. Currency is site-derived — send none.
+- **`enabled: true`** to offer a method. **`availability.availableTimes[]`** is one entry per open weekday, each `timeRanges: [{startTime,endTime}]` (`hours` 0-23, `minutes` 0-59); `availability.timeZone` is required but Wix overrides it with the site's language-and-region zone, so any valid IANA zone is accepted.
+- **`pickupOptions`** for `PICKUP`, **`deliveryOptions`** (with a `deliveryArea`) for `DELIVERY` — send the one matching `type`. Omitting the pickup `address` is fine; it defaults from the operation.
+- **`revision` is mandatory on every PATCH** and increments by 1 each update; a stale one 400s.
+- Retry a failed create/update **once** with the same format; do not loop.
+
+> **The San Francisco / `fee "0"` defaults are placeholders.** They're harmless for a locationless demo site (a visitor can still build a cart). Only override the delivery `deliveryArea` / pickup `address` when the request gives a real location; otherwise leave them.
+
+### STEP 3: Verify each menu is orderable
+
+Menu-ordering-settings are auto-created **and auto-enabled** per menu (both pre- and post-install menus), so this is normally a confirmation. List them and check each menu the request marks orderable.
+
+```bash
+curl -sS <AUTH> -X POST "https://www.wixapis.com/menu-ordering-settings/v1/menu-ordering-settings/query" -d '{ "query": {} }'
+```
+
+Response — one object per menu; match by **`menuId`**:
+
+```json
+{ "menuOrderingSettings": [
+  { "id": "<settingsId>", "revision": "1", "operationId": "<operationId>", "menuId": "<menuId>",
+    "onlineOrderingEnabled": true, "availability": { "type": "ALWAYS_AVAILABLE", "timeZone": "America/New_York" } }
+] }
+```
+
+**⚠️ CRITICAL:**
+- **Normally every entry is already `onlineOrderingEnabled: true` with `operationId` set** — nothing to do; just confirm it. Only if an entry shows `onlineOrderingEnabled: false` or `operationId: "none"` (or the request wants a menu *not* orderable), PATCH it:
+  ```bash
+  curl -sS <AUTH> -X PATCH "https://www.wixapis.com/menu-ordering-settings/v1/menu-ordering-settings/<settingsId>" \
+    -d '{ "menuOrderingSettings": { "revision": "<settingsRevision>", "operationId": "<operationId>", "onlineOrderingEnabled": true, "availability": { "type": "ALWAYS_AVAILABLE", "timeZone": "America/New_York" } } }'
+  ```
+- **`availability.type: "ALWAYS_AVAILABLE"`** makes the menu orderable during the operation's hours; a `timeZone` is required. **`revision` is mandatory** and increments per update.
+- The settings object's `businessLocationId` (inherited from its menu, `"none"` for a locationless site) must match the operation's `businessLocationId` for ordering to bind — both are `"none"` here, so they match. Don't override it.
+- To make a menu **display-only** (not orderable), PATCH that one to `onlineOrderingEnabled: false`; leave the rest enabled.
+
+> **⚠️ LIVE CHECKOUT PRECONDITIONS (note, don't fail).** A visitor can browse the orderable menu and build a cart with just this setup, but **completing an order** end-to-end needs three things beyond the seed: **(1) a configured business location with a real address** (STEP 0 — without it ordering is "testing only"); **(2) a premium plan**; and **(3) a configured payment method** (checkout rides on Wix eCommerce). STEP 0 handles (1) via API; (2) and (3) are **dashboard/premium provisioning** the skill can't do headlessly. Surface all three in the handoff; do **not** fail the seed over them.
+
+---
+
+## Conclusion
+Following these steps confirms/completes online ordering for a site whose **Menus** backend is already seeded:
+- A **business location with a real address is configured first** (STEP 0, Update Location full-override) — without it ordering is "testing only"; the address propagates to Site Properties. If the brief gives no address, a placeholder is set and the owner is flagged to fix it.
+- The **Orders-app install already produced a working setup** — an `ENABLED` operation with Pickup + Delivery attached and every menu ordering-enabled; this recipe **verifies** that and **reshapes it to the request**, it does not build it from nothing.
+- The **operation** is discovered, never created (operations/groups are auto-provisioned); it stays `onlineOrderingStatus: "ENABLED"`.
+- **Fulfillment methods** are reconciled to the request — auto-created ones customized (decimal-string `fee`/`minOrderPrice`, weekly `availability`), unwanted ones disabled, extra ones created **and attached** to the operation via `fulfillmentIds` (a create does not auto-attach).
+- Every orderable **menu** is confirmed `onlineOrderingEnabled: true` and bound to the operation through menu-ordering-settings.
+- Each Orders micro-service is called on its **own host prefix** (`restaurants-operations` / `fulfillment-methods` / `menu-ordering-settings`) with the camelCase `fulfillmentMethod` wrapper; `revision` is passed on every PATCH. Real paid checkout additionally needs a premium plan + payment method (handoff note).
+</content>

package/skills/wix-headless/references/inline-recipes/setup-restaurant-reservations.md

@@ -0,0 +1,136 @@
+---
+name: "Setup Restaurant Reservations"
+description: Configures Wix **Table Reservations**. Installing the app AUTO-provisions a default reservation location with a full config (approval AUTOMATIC, party size, weekly schedule, tables) — but with online reservations turned OFF. This recipe VERIFIES that location, CUSTOMIZES its config to the request, and TURNS ON online reservations (premium-gated). There is nothing to bulk-seed and no menu dependency. Specifies the *how* (calls + format); party sizes / hours come from the request.
+---
+**RECIPE**: Business Recipe – Table-Reservations Setup for Wix Restaurants (Table Reservations app)
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` **and** `wix-site-id: <SITE_ID>`. Body-bearing requests also need `Content-Type: application/json`.
+
+A checklist for turning on **table reservations** for a Wix site.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial reservations setup.
+
+> **⚠️ Reservations is CONFIGURATION, not creation — there is NOTHING to bulk-seed.** Reservations themselves are created by **visitors at runtime** (the frontend flow), not at setup. And a **reservation location CANNOT be created via this API** — the docs are explicit: locations are "created and archived only through the Dashboard, or the Locations API." The Reservation Locations API only **queries / lists / updates**. So "setup" here means: verify the location the install already made, configure it, and switch online reservations on.
+
+> **⚠️ THE INSTALL AUTO-provisions a default reservation location — this recipe VERIFIES and CONFIGURES it.** Installing the Table Reservations app auto-creates **one reservation location** (`default: true`) with its own `location` object and a **complete default configuration** — `approval.mode: "AUTOMATIC"` (manual approval already OFF), `partySize {min:1, max:6}`, `minimumReservationNotice 30 MINUTES`, `defaultTurnoverTime 90`, a 7-day `businessSchedule` (08:00–22:00), `timeSlotInterval 15`, and table management ON with default tables. **The one thing OFF is `onlineReservationsEnabled: false`** — flipping it on is STEP 3.
+
+> **⚠️ NO menu dependency.** Reservations bind to a **location**, not a menu (unlike online ordering, which is menu-first). Do **not** copy the orders "seed the menu first" constraint — reservations can be set up with no menu at all.
+
+> **This recipe is the *how*, not the *what*.** Party-size limits, business hours, turnover time, and reservation-notice come from the request you're fulfilling. This recipe only specifies the calls and the request format. Per the "simple seeds" default, if the request names no reservation specifics, keep the auto-provisioned config and just do STEP 1 + STEP 3.
+
+> **API surface:** the **Reservation Locations** API on `https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations` (list `GET`, query `POST …/query`, get `GET …/{id}`, update `PATCH …/{id}`). The frontend visitor flow (time slots, held/reserve) is a separate concern — see `how-to-code-restaurant-reservations.md`.
+
+> **⚠️ Field names — post-Jan-2026 migration.** Use the **new** field names: **`partySize`** (not `partiesSize`), **`approval`** (not `manualApproval`), **`tables.ids`** (not `tableIds`), **`ignoreConflicts`** (not the three old flags). The old names were removed after 2026-02-28; the install response still echoes some deprecated twins (e.g. `partiesSize` alongside `partySize`) — write the new ones.
+
+---
+
+## Article: Steps for Setting Up Wix Table Reservations
+**YOU MUST** complete the steps in order (0-3) without requiring additional user input. Every step is idempotent — it verifies the auto-provisioned state and only writes when the request calls for a change.
+
+### STEP 0: Configure the business location address
+
+**Set a real street address on the site's default business location.** The reservation location **is** the site's business location (same entity — the reservation location's `location` object is the business `Location`), and a fresh site provisions it with an **empty street address**. A complete restaurant site needs a real address: it's where guests come, it's what the reservation/experience surface and the Business Manager show, and it's the **same** location online ordering requires (so a site with both ordering and reservations does this once). Set it via the **Locations API** — `PUT https://www.wixapis.com/locations/v1/locations/<id>` (Update Location). Docs: <https://dev.wix.com/docs/api-reference/business-management/locations/introduction.md>.
+
+```bash
+# 1) find the default location + its revision
+curl -sS <AUTH> -X GET "https://www.wixapis.com/locations/v1/locations"   # take the entry with "default": true
+# 2) overwrite it with a real address (FULL override — send the whole object)
+curl -sS <AUTH> -X PUT "https://www.wixapis.com/locations/v1/locations/<id>" \
+  -d '{ "location": {
+    "id": "<id>", "revision": "<revision>", "default": true,
+    "name": "<Business name>", "timeZone": "Europe/Paris",
+    "address": { "country": "FR", "subdivision": "FR-75", "city": "Paris", "postalCode": "75001",
+      "streetAddress": { "number": "18", "name": "Rue des Lumières" },
+      "formattedAddress": "18 Rue des Lumières, 75001 Paris, France" } } }'
+```
+
+**⚠️ Earned gotchas (identical to `setup-restaurant-orders.md` STEP 0 — the same call):** Update Location is a **full override**, not a partial update (a "just the address" body is the classic *"reported success, nothing changed"* failure); **echo `"default": true`** or it 400s `CHANGE_DEFAULT_FORBIDDEN`; **`revision` is mandatory**; **`country` is a 2-letter ISO code**. The address also propagates to Site Properties. **Where the address comes from:** the request; if the brief names none, set a clearly-marked placeholder and **flag in the handoff that the owner must set their real address**.
+
+### STEP 1: Discover the auto-provisioned default reservation location
+
+List reservation locations and take the default one. Keep its **`id`** and **`revision`** (the PATCH in STEP 2/3 needs both).
+
+```bash
+curl -sS <AUTH> -X GET "https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations"
+```
+
+Response (`reservationLocations[]`):
+
+```json
+{ "reservationLocations": [
+  { "id": "<reservationLocationId>", "revision": "1", "default": true, "archived": false,
+    "location": { "id": "<locationId>", "name": "Location 1", "timeZone": "America/New_York" },
+    "configuration": { "onlineReservations": {
+      "approval": { "mode": "AUTOMATIC" },
+      "partySize": { "min": 1, "max": 6 },
+      "minimumReservationNotice": { "number": 30, "unit": "MINUTES" },
+      "defaultTurnoverTime": 90,
+      "businessSchedule": { "periods": [ { "openDay": "MONDAY", "openTime": "08:00", "closeDay": "MONDAY", "closeTime": "22:00" } ] },
+      "onlineReservationsEnabled": false,
+      "timeSlotInterval": 15
+    } } }
+] }
+```
+
+**⚠️ CRITICAL:**
+- **Do not POST to create a location** — there is no create method in this API; use the one the install made. If `reservationLocations[]` is **empty**, the install hasn't finished provisioning — **wait briefly and retry the GET once**; do not try to create one. Still empty after one retry → **fail loud** (either the install didn't complete, or the site genuinely has no location; a location can only be added via the Dashboard / Locations API, which is out of scope here).
+- Take the entry with **`default: true`** (there's normally exactly one). Keep `reservationLocation.id` and the **current** `revision`.
+- **Verify `configuration.onlineReservations.approval.mode` is `"AUTOMATIC"`** — that means manual approval is OFF, which is required for a headless site to auto-confirm reservations (there's no dashboard operator to approve). It's the default; only PATCH it (STEP 2 shape) if you find it set to a manual mode.
+
+### STEP 2: Customize the configuration (only what the request names)
+
+PATCH the location to set party-size limits, hours, turnover, or notice per the request. Partial updates are supported; **`revision` is mandatory**. **Config PATCH works on a non-premium site** (unlike the enable toggle in STEP 3).
+
+```bash
+curl -sS <AUTH> -X PATCH \
+  "https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations/<reservationLocationId>" \
+  -d '{
+    "reservationLocation": {
+      "id": "<reservationLocationId>",
+      "revision": "<revision>",
+      "configuration": { "onlineReservations": {
+        "partySize": { "min": 2, "max": 10 },
+        "minimumReservationNotice": { "number": 60, "unit": "MINUTES" },
+        "defaultTurnoverTime": 90
+      } }
+    }
+  }'
+```
+
+**⚠️ CRITICAL:**
+- **`revision` must be the current one** (from STEP 1, or the previous PATCH's response); it increments by 1 each update — a stale revision 400s. Keep the new revision for STEP 3.
+- **You cannot change the `location` object** via this method (address/name live on the business Location) — attempting to returns an application error. Only touch `configuration`.
+- Use the **new** field names (`partySize`, `approval`) — see the migration callout above.
+- Skip this step entirely if the request names no reservation specifics (keep the auto-provisioned config).
+
+### STEP 3: Turn on online reservations (premium-gated)
+
+Flip `onlineReservationsEnabled` on so visitors can book. Send the current `revision`.
+
+```bash
+curl -sS <AUTH> -X PATCH \
+  "https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations/<reservationLocationId>" \
+  -d '{
+    "reservationLocation": {
+      "id": "<reservationLocationId>",
+      "revision": "<revision>",
+      "configuration": { "onlineReservations": { "onlineReservationsEnabled": true } }
+    }
+  }'
+```
+
+**⚠️ CRITICAL — this toggle is PREMIUM-ONLY; on a non-premium site it returns `428 PREMIUM_ONLY`, NOT success.** On a free/headless site this PATCH fails with:
+```json
+{ "message": "Can't turn on online reservation for a non-premium website", "details": { "applicationError": { "code": "PREMIUM_ONLY" } } }
+```
+This is a **site-provisioning precondition, not a recipe bug** — treat `428 PREMIUM_ONLY` as an **expected, non-fatal** outcome: record that the site must be upgraded to premium before online reservations can be turned on (the owner then enables it, in the Dashboard or via this same call on the premium site), and **continue**. Do **not** retry-spiral it and do **not** fail the whole seed over it. (This is stricter than online ordering, where only *paid checkout* needs premium — here the *enable toggle itself* is gated.) On a premium site the same call returns the updated location with `onlineReservationsEnabled: true`.
+
+---
+
+## Conclusion
+Following these steps configures Table Reservations for a site:
+- Uses the **auto-provisioned default reservation location** (discovered, never created — locations come only from the Dashboard / Locations API), with its `id` + `revision` kept.
+- Verifies **manual approval is off** (`approval.mode: "AUTOMATIC"`) so a headless site auto-confirms.
+- **Customizes** party size / hours / turnover / notice per the request via `PATCH` (works on non-premium; `revision` mandatory; `location` object immutable here; new field names).
+- **Attempts to enable online reservations** (`onlineReservationsEnabled: true`) — succeeds on premium, returns a non-fatal **`428 PREMIUM_ONLY`** on a non-premium site (recorded as a premium precondition, not a failure).
+- **Nothing is bulk-seeded** and there is **no menu dependency** — reservations are created by visitors at runtime (`how-to-code-restaurant-reservations.md`).
+</content>

package/skills/wix-headless/references/inline-recipes/setup-restaurants.md

@@ -0,0 +1,152 @@
+---
+name: "Setup Restaurants"
+description: Initializes a Wix Restaurants Menus backend — cleans the install's default sample menu, then bulk-creates items, bulk-creates sections (referencing item ids), and creates the menu (referencing section ids), all visible. Specifies the *how* (calls + format); the menu/section/item counts and names come from the request.
+---
+**RECIPE**: Business Recipe – Initial Setup for Wix Restaurants (Menus API)
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` **and** `wix-site-id: <SITE_ID>`. Body-bearing requests also need `Content-Type: application/json`.
+
+A concise checklist for preparing any new Wix site that uses the Wix Restaurants **Menus** app.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial menu setup.
+
+> **This recipe is the *how*, not the *what*.** What to seed — how many menus, which sections, how many items per section and their names/descriptions/prices — is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide quantities or which entities to create.
+
+> **API surfaces:** everything is the Restaurants **Menus V1** API on `https://www.wixapis.com/restaurants/menus/v1/...` (menus, sections, items — all under this one service). This is the **new** Wix Restaurants Menus API; do not mix in any older `restaurants/v1beta` or ordering/reservations endpoints. Online ordering and table reservations are **separate apps** and out of scope for menu seeding.
+
+> **REST flattens the protobuf wrappers.** The raw method schemas show fields like `visible`, `id`, `description` as wrapper objects (`{"value": …}`). In the actual REST JSON they are **plain values** — send `"visible": true`, `"description": "text"`, and read back `"id": "<guid>"`. Never send `{"value": …}`.
+
+---
+
+## Article: Steps for Setting Up Wix Restaurants Menus
+**YOU MUST** complete all the following steps **in the given order** (0-3) without skipping any and **without requiring additional user input**. The **Attach images** step runs last, only when `imagery` is on.
+
+**⚠️ CRITICAL ORDER REQUIREMENT: build the hierarchy BOTTOM-UP — items (STEP 1) → sections (STEP 2) → menu (STEP 3).** A section is created with the **`itemIds`** of the items it contains, and a menu is created with the **`sectionIds`** of the sections it contains. So the child ids must exist before you create the parent. Do the cleanup (STEP 0) first of all, so the ids you delete are provably the install's samples.
+
+### STEP 0: Clean the install — remove the default sample menu
+
+**A freshly installed Wix Restaurants Menus app ships a fully populated default "Dinner Menu"** (roughly one menu, ~4 sections, ~21 items). **Only remove the menu when it's obviously the install's own default "Dinner Menu" on a fresh install.** Do **not** assume an existing menu is a sample: the site may already hold the owner's **real menu** (a connect/iterate run, or an owner-populated site). If what's there isn't obviously install sample data, or you're unsure, **do not delete it — ask the user first** (`SEED.md`: seeding is additive; deleting real content needs the owner's approval). When it clearly is the install's sample, remove it **before** creating yours so the storefront shows only the intended menu (children before parents: items → sections → menus):
+
+1. **Bulk-delete items** — `GET https://www.wixapis.com/restaurants/menus/v1/items` (collect every `items[].id`), then `DELETE https://www.wixapis.com/restaurants/menus/v1/bulk/items/delete` with body `{"ids": ["<id>", …]}`.
+2. **Bulk-delete sections** — `GET https://www.wixapis.com/restaurants/menus/v1/sections` (collect every `sections[].id`), then `DELETE https://www.wixapis.com/restaurants/menus/v1/bulk/sections/delete` with body `{"ids": ["<id>", …]}`.
+3. **Delete menus** — `GET https://www.wixapis.com/restaurants/menus/v1/menus` (collect every `menus[].id`), then delete each one with `DELETE https://www.wixapis.com/restaurants/menus/v1/menus/{menuId}` (**no bulk-delete endpoint for menus** — one DELETE per menu; there is normally just the single default menu). Single delete takes only the path id — **no `revision` needed**.
+
+The bulk-delete responses carry per-id `results[].itemMetadata.success`; a menu delete returns `200 {}`. If the lists come back empty, this is a safe no-op — continue.
+
+### STEP 1: Bulk-create the items
+
+Create all items in a **single bulk request** to `POST https://www.wixapis.com/restaurants/menus/v1/bulk/items/create`. **How many items, and their names/descriptions/prices, come from the request you're fulfilling — this step only gives the call and the required format.**
+
+**Request body shape** (one representative item shown — repeat item objects inside the `items` array):
+
+```json
+{
+  "items": [
+    {
+      "name": "Bruschetta al Pomodoro",
+      "description": "Grilled sourdough, San Marzano tomatoes, basil.",
+      "priceInfo": { "price": "9.50" },
+      "visible": true
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **Price goes in `priceInfo.price` as a decimal STRING** (`"9.50"`, not the number `9.50`). The currency is **derived from the site** — do **not** send a currency; the response echoes a `priceInfo.formattedPrice` (e.g. `"$9.50"`) in the site's currency.
+- **Do NOT use the top-level `price` field** — it is deprecated (superseded by `priceInfo`). Use `priceInfo.price`.
+- **`description` is a plain string** (not rich-text nodes). Omit it for a name-only item.
+- **Set `"visible": true` explicitly** on every item (see the visibility callout below).
+- **Imagery is opt-in** (`SEED.md` § "Entity images"). Seed **text-only by default** — omit `image`. When `imagery` is on, the **Attach images** step below writes an `image` onto each item in a second pass.
+- If part of the bulk request fails, retry the failed items **once** with the exact same format; do not loop.
+
+**⚠️ Reading the response — created items are under `results[].item`, and `results[].itemMetadata.success` is the per-item flag.** A successful bulk create returns `200`:
+
+```json
+{ "results": [
+  { "itemMetadata": { "id": "<itemId>", "originalIndex": 0, "success": true },
+    "item": { "id": "<itemId>", "name": "Bruschetta al Pomodoro", "priceInfo": { "price": "9.50", "formattedPrice": "$9.50" }, "visible": true } }
+], "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0 } }
+```
+
+Keep each item's **`id`** (from `results[].item.id`), grouped by the section it belongs to — STEP 2 wires items into sections via these ids.
+
+### STEP 2: Bulk-create the sections (referencing their item ids)
+
+Create all sections in a **single bulk request** to `POST https://www.wixapis.com/restaurants/menus/v1/bulk/sections/create`. Each section carries the **`itemIds`** array of the items (from STEP 1) that belong to it. **Which sections, and which items go in each, come from the request you're fulfilling.**
+
+**Request body shape** (repeat section objects inside the `sections` array):
+
+```json
+{
+  "sections": [
+    {
+      "name": "Antipasti",
+      "description": "To start",
+      "visible": true,
+      "itemIds": ["<itemId1>", "<itemId2>"]
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+**⚠️ CRITICAL:**
+- **`itemIds` must be real item ids from STEP 1**, in the display order you want. An item can appear in more than one section, but normally each item belongs to exactly one.
+- **Set `"visible": true` explicitly.**
+- Read created sections from **`results[].item`** (the bulk envelope reuses the generic `item` key even for sections). Keep each section's **`id`** — STEP 3 wires sections into the menu via these ids.
+- Retry failed sections **once**; do not loop.
+
+### STEP 3: Create the menu (referencing its section ids)
+
+Create the menu with `POST https://www.wixapis.com/restaurants/menus/v1/menus`. The menu carries the **`sectionIds`** array of the sections (from STEP 2) it contains. There is normally **one** menu; if the request calls for several, use the bulk endpoint `POST https://www.wixapis.com/restaurants/menus/v1/bulk/menus/create` with a `{"menus": [ … ], "returnEntity": true}` body (same envelope as items/sections).
+
+**Request body shape** — the single-create wraps the menu in a **`menu`** object:
+
+```json
+{
+  "menu": {
+    "name": "Dinner",
+    "description": "Evening menu",
+    "visible": true,
+    "sectionIds": ["<sectionId1>", "<sectionId2>"]
+  }
+}
+```
+
+**⚠️ CRITICAL:**
+- **`sectionIds` must be real section ids from STEP 2**, in display order.
+- **Set `"visible": true` explicitly.**
+- The single-create response is `{"menu": { "id": "<menuId>", "sectionIds": [ … ], "visible": true, "urlQueryParam": "dinner" }}` — read the **`menu.id`** (bulk create returns `results[].item` like the others). Keep the `menuId`.
+- **`businessLocationId` is optional** — omit it and the menu/section bind to the site's default (main) business location. Only set it for a multi-location restaurant when the request names locations.
+
+**⚠️ VISIBILITY — set `"visible": true` explicitly at every level (item, section, menu).** Storefront menu queries return only visible entities to visitors. Always include `visible: true` on every item, every section, and the menu, rather than relying on a default — an entity created without it may exist but not render on the live site.
+
+### Attach images (imagery ON only — skip otherwise)
+
+**Only when `imagery` is on** (`SEED.md` § "Entity images"). Items were created text-only in STEP 1; this pass-2 step writes a generated dish image onto each. The **item** is the image-bearing entity (sections and the menu render from their items) — attach per item. Generate + import per `references/IMAGE_GENERATION.md` → keep `file.url` and its `file.id`, then PATCH the item.
+
+**⚠️ On write, `image` is an OBJECT `{ id, url, height, width }`** (per the Create/Update Item docs) — even though the storefront SDK surfaces `item.image` as a bare *string* on **read** (`how-to-code-restaurants.md` § "Rendering images"; at the REST layer the read is an object too). Do **not** write a plain string. The binding field is the image **`id`** (the Wix Media file id); `url` + dimensions are descriptive.
+
+**⚠️ CRITICAL: Update Item is a FULL-ENTITY REPLACE with NO field mask — you MUST echo the item's existing `priceInfo` (and `priceVariants`, if the item is variant-priced) in the PATCH body, alongside `image`.** A body of just `{ id, revision, image }` drops the price and fails **`428 MISSING_ITEM_PRICING`** (`"Item must have either price or price variants"`) — the write does **not** apply. So first **`GET https://www.wixapis.com/restaurants/menus/v1/items/{itemId}`** for the item's current **`revision` + `priceInfo`** (or reuse the `item.revision` + `item.priceInfo` from STEP 1's `returnEntity` response), and echo both back:
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/restaurants/menus/v1/items/<itemId>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "item": { "id": "<itemId>", "revision": "<current revision>", "priceInfo": { "price": "<current price>" }, "image": { "id": "<file.id>", "url": "<file.url>", "height": 1024, "width": 1024 } } }'
+```
+
+- **Bulk variant** — to image many items at once, `POST https://www.wixapis.com/restaurants/menus/v1/bulk/items/update` with `{"items": [ { "item": { "id", "revision", "priceInfo", "image": {…} } }, … ]}` (each item still needs its own `revision` **and** its `priceInfo` — the full-replace rule applies per item).
+- A **stale or omitted `revision`** fails the update — fetch/echo the current one.
+- **Never block on image failure** (`SEED.md` § "Entity images" / IMAGE_GENERATION "Credits, cost & the not-generating fallback") — on failure, skip and leave the item text-only.
+
+---
+
+## Conclusion
+Following these steps **in order** sets up a new Wix Restaurants Menus site:
+- Starts from a **clean menu** — the install's default sample "Dinner Menu", its sections, and its items are all removed first.
+- Contains the menu, sections, and items called for by the request, built **bottom-up** (items → sections → menu) so every parent references real child ids.
+- Every item, section, and menu is created **`visible: true`** so it appears on the live site.
+- Prices are decimal strings under `priceInfo.price`; currency is the site's own. All calls use the Restaurants **Menus V1** API.
+- Items are seeded **text-only**; when `imagery` is on, the **Attach images** step writes an `image` **object** (`{ id, url, height, width }`) onto each — never a bare string. Update Item is a full replace with no field mask, so the PATCH echoes the item's existing `revision` **and** `priceInfo` alongside `image` (a body missing `priceInfo` fails `428 MISSING_ITEM_PRICING`).

package/skills/wix-headless/references/managed/AUTHENTICATION.md

@@ -0,0 +1,57 @@
+# Authentication — managed (Wix CLI)
+
+For a **managed** project (hosted on Wix infrastructure), every Wix call uses a token minted by the **Wix CLI** — `@wix/cli` + `curl`, no MCP, no SDK. This file is the authority for how `managed` obtains `$TOKEN`, `$SITE_ID`, and the public `clientId`; the flow files (`SETUP.md`, `SEED.md`, `SDK_HANDOFF.md`) defer here.
+
+## 1 · Ensure an authenticated CLI session
+
+```bash
+npx @wix/cli@latest whoami   # exits 0 when logged in; non-zero when logged out
+```
+
+If it's non-zero, **log in yourself** — don't punt to the user and stop:
+
+1. Run `npx @wix/cli@latest login` with **`run_in_background: true`** (no shell `&`, no redirect of your own — the harness captures stdout to its task-output file and returns the path).
+2. Poll that file for the first JSON event: `{"event":"awaiting_user","userCode":"…","verificationUri":"…"}`.
+3. Surface it to the user in plain prose: *"Open `<verificationUri>` and enter the code `<userCode>` — I'll continue once you've logged in."* **Send the message; do not re-invoke login.**
+4. Wait for the harness `task-notification` with `<status>completed</status>` (not a sleep loop). On exit 0, run `whoami` once to confirm, then proceed.
+
+## 2 · Mint the token
+
+```bash
+SITE_ID="<siteId>"   # from wix.config.json
+TOKEN=$(npx @wix/cli@latest token --site "$SITE_ID")
+```
+
+- Mints a **site-scoped REST token**. **Mint once per run and never re-mint** — the CLI returns a **byte-identical** token on every call within a run (it caches internally), so re-minting only costs ~1.25 s of startup. Cache `$TOKEN` and `$SITE_ID` in scratch.
+- Use `npx @wix/cli@latest token …` (not bare `wix token`) so `npx` resolves the project-local CLI.
+- The first `--site "$SITE_ID"` call is the source of truth for `SITE_ID`; bind it in scratch, don't re-derive mid-run.
+
+## 3 · `clientId` for the frontend
+
+The frontend's public `clientId` **is the `appId` field in `wix.config.json`** — for a managed headless project the OAuth **app id and the client id are the same value** (app-id === client-id). It's the same file you already read for `siteId` (§2), so **read `appId` straight from there** — do **not** query the OAuth-apps API, search the docs, or mint anything to obtain it. (It's the public OAuth id, not a secret.)
+
+## REST call shape
+
+```bash
+curl -sS -w "\nHTTP_STATUS:%{http_code}" \
+  -X POST "https://www.wixapis.com/<endpoint>" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "wix-site-id: $SITE_ID" \
+  -H "Content-Type: application/json" \
+  -d '<body>'
+```
+
+- **`Authorization: Bearer $TOKEN`** — the `Bearer` prefix is required.
+- **`wix-site-id: $SITE_ID`** — required by every site-scoped family; include it always.
+- **`Content-Type: application/json`** — on every POST/PATCH body.
+- **Parsing the response:** `-w` appends a `HTTP_STATUS:<code>` line *after* the JSON body. `grep` that line for the status, but parse the **body separately** — piping the combined output to a JSON parser (`python3 -m json.tool`, `json.load`, `jq`) chokes on the trailing status line (`Extra data: line 2 …`). Capture the body to a file with `-o body.json` (status still comes from `-w`), or drop the last line, before parsing.
+
+## Recovery ladder
+
+Re-mint is **not** a recovery step (the token is byte-identical) — retry the *same* call with the cached token.
+
+| Symptom | First response | If it still fails |
+|---|---|---|
+| `401 Unauthorized` | Retry once with the cached token. | CLI session expired — run `npx @wix/cli@latest login` (a new session), then re-mint. |
+| `403 Forbidden` | Retry once with the cached token. | App not installed yet (re-check the apps-installer returned 200), or the caller lacks permission — surface the response; don't loop. |
+| `404` on a documented URL | Re-read the recipe — a path typo. | Recipe bug; surface and stop. |