@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-reservations.md

@@ -16,13 +16,16 @@ A contract for the **frontend code** that lets a visitor **book a table**: readi
 
 ## The modules and the client (read this first)
 
-**One package: `@wix/table-reservations`** — a **distinct** package from `@wix/restaurants` (menus) and from the Orders app. It exposes three namespaces you use:
+**One package: `@wix/table-reservations`** — a **distinct** package from `@wix/restaurants` (menus) and from the Orders app. It exposes the namespaces you use:
 
 | Need | Package | Module (namespace) |
 |---|---|---|
 | The reservation location (id, party-size bounds) | `@wix/table-reservations` | `reservationLocations` |
 | Available time slots for a date + party size | `@wix/table-reservations` | `timeSlots` |
 | Create / hold / reserve a reservation | `@wix/table-reservations` | `reservations` |
+| **Experiences** — special dining occasions guests reserve (only when experiences are in the run) | `@wix/table-reservations` | `experiences` |
+
+> **Experiences** ride on this same package and booking mechanism — see the **Booking an experience** feature below. Skip that section entirely if the run has no experiences.
 
 **No cart, no `@wix/ecom`, no `@wix/redirects`.** A basic table reservation is a **hold**, not a purchase — there's no checkout in this flow. (Deposit/prepayment reservations exist — status `PAYMENT_INFORMATION_PENDING` — but they're out of scope for the standard book-a-table flow.)
 
@@ -161,6 +164,42 @@ Docs: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/res
 **Single-shot alternative:** if you collect all details up front (no "hold while they type" step), call `reservations.createReservation({ details: { reservationLocationId, startDate, partySize }, reservee })` instead — same `firstName`/`phone` requirement; it returns `RESERVED`/`REQUESTED` directly, skipping the `HELD` phase. **⚠️ The location/time/party go under a nested `details` object (NOT top-level), and this method returns the `Reservation` DIRECTLY — not wrapped in `{ reservation }`** (unlike `createHeldReservation`/`reserveReservation`). Top-level fields or reading `.reservation` off the result fails to type-check.
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-reservation.md?apiView=SDK>
 
+### Booking an experience (only when experiences are in the run)
+
+An **experience** is a reservation that *is* a curated dining occasion (wine/cheese pairing, chef's table). It uses the **same** booking mechanism as a table, with two differences: you **list experiences** to show and choose from, and you offer bookable times **projected from the experience's own schedule** (there is *no* experience-scoped slot API — see Gotcha C) rather than from `getScheduledTimeSlots`, then stamp the chosen `experienceId` onto the reservation. Read the shapes from the docs (`.md?apiView=SDK`); the earned drift gotchas below are what the docs won't tell you.
+
+Flow (mirrors the docs' sample flow — <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/sample-flows.md>):
+
+```js
+import { experiences, reservations } from '@wix/table-reservations';
+
+// 1 · list experiences to display (name, price, schedule) — see gotcha A
+const { items: exps = [] } = await experiences.queryExperiences().find();
+const exp = exps.find((e) => e._id === chosenId);
+
+// 2 · offer bookable times from the EXPERIENCE'S OWN schedule — do NOT call
+//     getScheduledTimeSlots for an experience (it can't scope to one — Gotcha C).
+//     queryExperiences() already returned the schedule; project the next occurrences yourself.
+const sched = exp.configuration?.onlineReservations?.businessSchedule; // { durationInMinutes, entries[] }
+// entries[].weeklyOptions.startDaysAndTimes[{ day, time }]  →  next N dates matching each weekday+time
+// (ONE_TIME entries carry oneTimeOptions.{startDate,startTime}). Build the option list from these.
+
+// 3 · book it — experienceId rides in details (see gotcha B); firstName + phone required
+const done = await reservations.createReservation({
+  details: { reservationLocationId, experienceId, startDate: chosenOccurrence, partySize },
+  reservee: { firstName, lastName, email, phone },
+});
+```
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/query-experiences.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-reservation.md?apiView=SDK>
+
+**⚠️ Gotcha A — `queryExperiences()` is a QUERY BUILDER, not an object-arg method.** Call `experiences.queryExperiences().find()` (chain `.eq()`/`.limit()` etc. before `.find()` if needed) and read the array from the **result's `.items`**. Passing a query object — `queryExperiences({})` — does not type-check and returns no data; `await`-ing the un-`.find()`ed builder gives you the builder, not the results.
+
+**⚠️ Gotcha B — `details.experienceId` is a valid REST field but the SDK `Details` type may OMIT it (version drift).** The REST API accepts `experienceId` inside `details` (the Experiences intro and the reservation's own `meta` confirm `details.experienceId`), but an installed `@wix/table-reservations` older than the Experiences feature ships a `Details` type without it — so TypeScript rejects the property. Build the reservation object and **pass it through an `any` cast** (or `// @ts-expect-error`) so `experienceId` reaches the request body; it works at runtime. Don't drop the field to satisfy the compiler — a reservation without it books a plain table, not the experience.
+
+**⚠️ Gotcha C — there is NO experience-scoped slot fetch; project times from the experience's own `businessSchedule` instead.** The upstream `get-scheduled-time-slots` doc prose says "pass the GUID of that experience to this method," but **no such parameter exists at any layer**: the SDK (`@wix/auto_sdk_table-reservations_time-slots` ≤ 1.0.47, pulled by `@wix/table-reservations`) field-picks only `{ reservationLocationId, partySize, timeRange }`, and the REST body is those same three fields — so an `experienceId` option is **silently dropped** (an `as any` cast is a **no-op** here, unlike Gotcha B). Calling `getScheduledTimeSlots` for an experience returns the **location's default slots** (wrong day/time/duration), presented to guests as the experience's — and it **fails silently**: a populated-but-wrong list looks healthy, and the premium gate (below) stops live verification before you'd notice. Instead, **derive upcoming occurrences from the experience's own `configuration.onlineReservations.businessSchedule`** — `entries[].weeklyOptions.startDaysAndTimes[{ day, time }]` (or `oneTimeOptions`) + `durationInMinutes`, already returned by `queryExperiences()`. Treat that as a **display projection**; real capacity/conflict enforcement happens server-side when `createReservation` runs.
+
+**⚠️ Same premium precondition** as online reservations: **creating** experiences is free, but **booking** one needs a premium site with online reservations enabled (`428 PREMIUM_ONLY` otherwise — `setup-restaurant-experiences.md`). Build the flow; treat a booking failure on a non-premium site as a provisioning precondition, not a code bug.
+
 ---
 
 ## Conclusion
@@ -169,5 +208,6 @@ A correct Table-Reservations frontend:
 - uses **`_id`** (never `id`) for the location and reservation, and **defaults the `list*` array** (`= []`) so strict/`astro check` passes;
 - calls **`getTimeSlots(locationId, new Date(date), partySize, options?)`** with **positional** args — the `date` param is a **`Date`** (not the ISO string the doc shows) — and books only **`status === 'AVAILABLE'`** slots (passing the slot's `Date` `startDate` onward);
 - books via **`createHeldReservation({...})` → `reserveReservation(id, reservee, revision)`** (three positional args; `firstName` + `phone` required; 10-minute hold; `reserveReservation` is the only exit from `HELD`);
-- treats **`onlineReservationsEnabled` (premium)** as a precondition — the read/book flow only works once it's on.
+- treats **`onlineReservationsEnabled` (premium)** as a precondition — the read/book flow only works once it's on;
+- **for experiences** (when in the run): lists via **`queryExperiences().find()`** (builder → `.items`); offers times **projected from the experience's own `businessSchedule`** — there is **no** experience-scoped `getScheduledTimeSlots` (Gotcha C: the `experienceId` option is silently dropped, so that call returns the location's slots); and books via `createReservation` with **`details.experienceId`** (an `any` cast past the SDK `Details` type — Gotcha B) — same premium precondition.
 </content>

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

@@ -20,7 +20,11 @@ A concise checklist for turning a freshly provisioned Wix site with the **Wix Bo
 
 **⚠️ CRITICAL ORDER REQUIREMENT: resolve a staff resource (STEP 1) and a category (STEP 2) BEFORE creating services (STEP 3).** An APPOINTMENT service is rejected (`MISSING_APPOINTMENT_RESOURCES`) unless `staffMemberIds` is non-empty, and **any service without a `category.id` is invisible on the live site** (see STEP 3). For CLASS services, sessions are created **after** the service (STEP 4) because they need the service's returned `schedule.id`.
 
-There is **no clean-up step** — a fresh Wix Bookings install ships no sample *services* (only a default "Business Owner" staff resource, which you reuse in STEP 1), so there is nothing to delete first.
+**Check for pre-existing services first.** A freshly provisioned Wix Bookings app may ship demo/sample services (e.g. "Sample service" rows) that would otherwise appear in the live storefront alongside yours — so before STEP 1, check and clean up only if needed:
+1. **List** — `POST https://www.wixapis.com/bookings/v2/services/query` `<AUTH>` with body `{"query": {"paging": {"limit": 100}}}`; collect every `service.id`.
+2. **If any come back, delete them** — `DELETE https://www.wixapis.com/bookings/v2/services/<serviceId>` `<AUTH>` for each. If the list is empty, there's nothing to clean — move on.
+
+Clean the install's **own demo services** yourself via the API — that's part of this setup, so don't leave obvious sample services in place or push that work onto the user. But do **not** assume every existing service is a sample: the site may already hold the owner's **real services** (a connect/iterate run, or an owner-populated site). If what's there isn't obviously the install's demo 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 they clearly are install samples, delete them before creating yours. (The default **"Business Owner" staff resource** is a resource, **not** a service — leave it; you reuse it in STEP 1.)
 
 ### STEP 1: Resolve a staff resource (REQUIRED for APPOINTMENT)
 

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

@@ -18,7 +18,7 @@ A concise checklist for preparing any new Wix site that uses the **Wix Forms** a
 ## Article: Steps for Setting Up Wix Forms
 **YOU MUST** complete the steps in order, without requiring additional user input: clean the default form (STEP 1) **before** creating yours (STEP 2), then verify (STEP 3).
 
-**⚠️ CRITICAL ORDER REQUIREMENT: clean any pre-existing forms FIRST (STEP 1), before creating any form.** Listing-then-deleting before you create guarantees every id you delete is a pre-existing form, never one you just created — and it prevents a name collision (see STEP 1).
+**⚠️ CRITICAL ORDER REQUIREMENT: clean the install's default sample form FIRST (STEP 1), before creating any form.** Listing-then-deleting before you create guarantees every id you delete is a pre-existing form, never one you just created — and it prevents a name collision (see STEP 1). **But only delete forms that are obviously the install's own default sample form:** the site may already hold the owner's **real forms** (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).
 
 ### STEP 1: Clean — remove any pre-existing (install-default) forms
 

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

@@ -22,10 +22,10 @@ A concise checklist for preparing any new Wix site that uses the Online Stores a
 
 ### STEP 1: Clean the store — remove the default sample products
 
-A freshly provisioned Wix Stores app comes pre-seeded with demo/sample products. Remove them **before** creating yours, so the storefront shows only your catalog. Do this **first** — cleaning before you create guarantees the ids you delete are the install's samples, never your own products.
+A freshly provisioned Wix Stores app comes pre-seeded with demo/sample products. **Only remove products that are obviously the install's own demo/sample data on a fresh install.** Do **not** assume the existing products are samples: the site may already hold the owner's **real catalog** (a connect/iterate run, or an owner-populated store). If what's there isn't obviously install demo 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 they clearly are the install's samples, remove them **before** creating yours so the storefront shows only the intended catalog.
 
 1. **List the existing products** — `POST https://www.wixapis.com/stores/v3/products/query` with body `{"query": {"paging": {"limit": 50}}}`. Collect every `product.id` from the response.
-2. **Bulk-delete them in one call** — `POST https://www.wixapis.com/stores/v3/bulk/products/delete` with body `{"productIds": ["<id1>", "<id2>", …]}` (the ids from step 1; up to 100 per call). The query on a fresh install returns the sample products; delete exactly those ids.
+2. **Bulk-delete them in one call** — `POST https://www.wixapis.com/stores/v3/bulk/products/delete` with body `{"productIds": ["<id1>", "<id2>", …]}` (the ids from step 1; up to 100 per call). On a fresh install the query returns only the install's sample products — delete those. **If it returns anything that could be the owner's real catalog, stop and ask first** (above).
 
 ### STEP 2: Bulk-create the products (with options)
 
@@ -158,13 +158,38 @@ The request body is `items` (each with the product's `catalogItemId` and the Sto
 
 ### Attach images (imagery ON only — skip otherwise)
 
-**Only when `imagery` is on** (`SEED.md` § "Entity images"). Products were created text-only above; this pass-2 step writes a generated brand image onto each. Generate + import per `references/IMAGE_GENERATION.md`, keep `file.url`, then PATCH the product.
+**Only when `imagery` is on** (`SEED.md` § "Entity images"). Products were created text-only above; this pass-2 step writes a generated brand image onto each. Generate + import per `references/IMAGE_GENERATION.md`, keep each image's `url`.
 
-- The field that persists is **`media.itemsInfo.items`**, NOT `media.main`. `PATCH /stores/v3/products/{id}` setting `"media": { "itemsInfo": { "items": [ { "url": "<static.wixstatic.com/…>", "altText": "…" } ] } }`; the image may be referenced by a `static.wixstatic.com` **`url`** or by its Wix Media **`id`** (`<hash>~mv2.png`), either works.
-- **⚠️ `media.main` set ALONE silently no-ops** — a `200` comes back but re-query shows no image; that is the trap. The server promotes the first `itemsInfo.items` entry to `media.main` for you, so **verify success by reading `media.main`** (`media.main.image.url` resolves to a `static.wixstatic.com` URL). Conversely `media.itemsInfo` is **write-only** — it comes back `null` on read, so never assert on it.
-- **428 prevention:** first `GET /stores/v3/products/{id}` for its **`revision` + `options` + `variantsInfo`** and echo all three back in the PATCH body — do **not** send a field mask (the validator runs before masking).
-- Send **one image per product** (primary); a larger gallery is out of scope for the seed.
-- **Never block on image failure** — skip and leave the product text-only.
+**Attach every product in ONE call** — `POST https://www.wixapis.com/stores/v3/bulk/products/update` (up to 100 products). You already hold each product's `id` **and `revision`** from STEP 2's bulk-create response (`productResults.results[].item`), so **no per-product `GET` is needed**. Each entry nests under a `product` wrapper carrying just `id`, `revision`, and `media` — options, variants, and every other field are left untouched (it's a partial update):
+
+```json
+{
+  "products": [
+    { "product": {
+        "id": "<product id>",
+        "revision": "<from the create response>",
+        "media": { "itemsInfo": { "items": [ { "url": "<static.wixstatic.com/… or Wix Media id>", "altText": "…" } ] } }
+    } }
+  ]
+}
+```
+
+- **`revision` is required on every entry** — omitting it fails `400 "revision must not be empty"`. Use the revision from the create response (or a fresh query); a stale one fails the optimistic-concurrency check.
+- **Everything nests under `product`** — `id` / `revision` / `media` at the entry root fails validation. **Send no field mask** (the validator runs before masking → `428`).
+- **Write the image via `media.itemsInfo.items`**; the server derives `media.main` from it. One primary image per product (a larger gallery is out of scope for the seed). The image may be referenced by a `static.wixstatic.com` **`url`** or by its Wix Media **`id`** (`<hash>~mv2.png`) — either works.
+- **Success shape** — `bulkActionMetadata` totals the run, and each result carries an `itemMetadata`:
+
+  ```jsonc
+  {
+    "results": [ { "itemMetadata": { "id": "<product id>", "originalIndex": 0, "success": true } } ],
+    "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0, "undetailedFailures": 0 }
+  }
+  ```
+  Read `itemMetadata.success` per product (the result carries no product body). **Retry only the failed ids once**, then move on.
+- **Confirm by requery** — `POST …/stores/v3/products/query` with `"fields": ["MEDIA_ITEMS_INFO"]`; the attached image is at `media.main.image.url`. Wix **re-hosts** the image on attach, so that URL is a **new** `wixstatic.com` id — verify it's *a* wixstatic URL, never string-equality against the one you sent. The read-back can lag a beat; one empty read right after success isn't a failure.
+- **Never block on image failure** — a product that won't attach stays text-only.
+
+**One-off fix (single product).** To (re)attach a single image later, `PATCH https://www.wixapis.com/stores/v3/products/{id}` with the same `{ "product": { "id", "revision", "media": {…} } }` body — same rules apply (revision required, no field mask, media-only is a partial update that leaves options/variants intact). Read the current `revision` from `GET …/products/{id}` → `response.product.revision` (the GET is not flat); the `200` response carries the image at `media.main.url`.
 
 ---
 

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

@@ -13,6 +13,8 @@ A concise checklist for preparing any new Wix site that uses the Wix Portfolio a
 
 > **API surfaces:** everything is the Portfolio **v1** API on `https://www.wixapis.com/portfolio/v1/...` — `/collections` and `/projects`. Use the **public `/portfolio/v1/...`** form; the method pages' schema headers show an internal `/portfolio/collections/api/v1/...` / `/portfolio/projects/projects/api/v1/...` URL — **do not** call those.
 
+> **This recipe seeds content and assumes the Portfolio app is already installed.** Installing apps is a separate, earlier step in the run (the **Setup** step — `SETUP.md` — runs before any seeding); this recipe only *creates content* on an already-installed app. So if a call returns **`428` / `APP_NOT_INSTALLED`**, it means the Setup step was skipped for Portfolio — **fail loudly with the response verbatim** and let Setup handle the install. Do **not** fabricate a limitation ("I can't install apps / do it in your Wix dashboard") — installing is not this recipe's job, but it *is* something the skill does, in Setup.
+
 > **Visibility is `hidden`, not `visible` — and it defaults to visible.** Portfolio's polarity is the **inverse** of Stores/Restaurants: entities carry a `hidden` boolean that **defaults to `false` (shown)**. So a collection/project created with no `hidden` field **appears on the live site** — you do **not** need to set anything to make it visible. Only set `"hidden": true` to hide one. (Send a plain boolean — `"hidden": false` — never a `{"value": …}` wrapper.) **Note:** when you omit `hidden` (or send `false`), the field is **absent** from the create/list response — proto3 drops false defaults — so *absent* reads as *false* reads as *shown*; `hidden` appears in the response only when you explicitly sent `true`. Don't treat a missing `hidden` as an error.
 
 ---
@@ -24,7 +26,7 @@ A concise checklist for preparing any new Wix site that uses the Wix Portfolio a
 
 ### STEP 0: Clean the portfolio — remove the default sample data
 
-A freshly installed Wix Portfolio app comes pre-seeded with **one sample collection ("My Portfolio") and several sample projects** ("Editorial Portraits", "Seasonal Lookbook", …), all assigned to that collection. Remove them **before** creating yours, so the site shows only your content. Do this **first** — cleaning before you create guarantees the ids you delete are the install's samples, never your own.
+A freshly installed Wix Portfolio app comes pre-seeded with **one sample collection ("My Portfolio") and several sample projects** ("Editorial Portraits", "Seasonal Lookbook", …), all assigned to that collection. **Only remove data that is obviously the install's own sample content on a fresh install** (that "My Portfolio" collection and its sample projects). Do **not** assume existing collections/projects are samples: the site may already hold the owner's **real content** (a connect/iterate run, or an owner-populated portfolio). 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 samples, remove it **before** creating yours so the site shows only the intended content.
 
 **Delete children before the parent — projects first, then collections.** (Deleting a collection does not clean up the projects that reference it.)
 

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

@@ -0,0 +1,73 @@
+---
+name: "Setup Restaurant Experiences"
+description: Seeds Wix Table Reservations **Experiences** — a reservation that IS a special dining occasion at the restaurant (wine tasting, cheese pairing, chef's table, tasting-menu evening), as opposed to a plain table booking or a Bookings service. Points to the live docs for the full create payload and carries only the earned gotchas the docs don't state (field-shape drift, payment policy, premium gating, when-to-use). The occasions/prices/schedule come from the request.
+---
+**RECIPE**: Business Recipe – Experiences Setup for Wix Table Reservations (Experiences API)
+
+> **Standard call shape (every curl below).** `<AUTH>` = `Authorization: Bearer <TOKEN>` **and** `wix-site-id: <SITE_ID>`. Body-bearing requests also need `Content-Type: application/json`.
+
+## When to use experiences (and when NOT to)
+
+An **experience** is a **reservation that is itself a curated dining occasion at the restaurant** — it books seats at the restaurant's own reservation location but overrides the location's defaults with its own name, description, per-guest payment policy, party-size, schedule, and booking form. Reach for it when the brief names a **wine tasting, cheese/wine pairing, chef's table, or tasting-menu evening**.
+
+- **Experience vs plain reservation:** a plain reservation just books a table; an experience books a *named, scheduled, often paid occasion*. Same booking mechanism, different intent.
+- **Experience vs `bookings`:** the separate `bookings` vertical is for a **service/appointment/class with a provider** (spa, tutor, studio). If a restaurant *hosts and seats* the occasion, it's an experience — not a booking. (See `CAPABILITIES.md` — "Experiences vs bookings".)
+
+## Prerequisites
+
+- The **Table Reservations app** is installed (`SETUP.md` §2). **Experiences are a feature of that app — there is no separate app to install.**
+- A **reservation location exists** — the install auto-provisions the default one (`setup-restaurant-reservations.md` STEP 1). Discover it and take its **`id`**; every experience is created against that `reservationLocationId`. No menu dependency.
+
+## The docs are the source of truth for the payload — read them, don't guess
+
+Read these `.md` twins directly (first priority; append `.md` to the article URL). This recipe deliberately does **not** re-inline the full schema — it changes, and the docs carry the complete, current field tree:
+
+- **About Experiences** (what they are, how they bind to reservations/locations/time-slots): <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/introduction.md>
+- **Create Experience** (the full create payload + example): <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/create-experience.md>
+- **Query / Get Experience**: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/query-experiences.md> · <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/get-experience.md>
+- **Sample flow** (showcase + book an experience end-to-end): <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/sample-flows.md>
+
+Endpoint: `POST https://www.wixapis.com/table-reservations/experiences/v1/experiences`.
+
+## The flow
+
+1. **Discover the reservation location** (`setup-restaurant-reservations.md` STEP 1) → keep `reservationLocationId`.
+2. **Create one experience per named occasion.** Build the body from the request (occasion name, per-guest price, party size, days/times, duration) per the **Create Experience** doc. Keep each returned `experience.id`. Set `configuration.visible: true` so it shows on the live site.
+3. Per the "simple seeds" default, create only the occasions the brief names (typically 1–3); don't invent a full calendar.
+
+Minimal shape (the doc has the complete tree — this is only the skeleton to orient against):
+
+```jsonc
+{ "experience": {
+  "reservationLocationId": "<reservationLocationId>",
+  "configuration": {
+    "displayInfo": { "name": "…", "shortDescription": "…" },
+    "paymentPolicy": { "paymentPolicyType": "PER_GUEST", "perGuestOptions": { "price": "55.00" } },
+    "onlineReservations": {
+      "partySize": { "min": 2, "max": 8 },
+      "minimumReservationNotice": { "number": 24, "unit": "HOURS" },
+      "maximumReservationNotice": { "number": 60, "unit": "DAYS" },
+      "approval": { "mode": "AUTOMATIC" },
+      "maxGuests": { "number": 16 },
+      "businessSchedule": { "durationInMinutes": 90, "entries": [
+        { "recurrence": "WEEKLY", "weeklyOptions": { "startDaysAndTimes": [ { "day": "FRIDAY", "time": "18:30" } ] } }
+      ] }
+    },
+    "visible": true
+  }
+} }
+```
+
+## Earned gotchas (what the docs won't tell you — verified against the live API)
+
+- **⚠️ Notice fields are FLAT under `onlineReservations`, not wrapped.** Send `onlineReservations.minimumReservationNotice` and `.maximumReservationNotice` **directly**. The Create-Experience doc *example* nests them inside a `noticePeriod` object — that wrapper is stale; the required-parameters list (same page) shows them flat, and the flat form is what the API accepts. Follow the parameter tree, not the example blob.
+- **Required at create** (creation 400s without them): `reservationLocationId`; `configuration.displayInfo.name`; `configuration.paymentPolicy.paymentPolicyType`; `configuration.onlineReservations.partySize.min/max`, `.approval.mode`, `.minimumReservationNotice.{number,unit}`, `.maximumReservationNotice.{number,unit}`, `.maxGuests.number`. (Confirm against the doc — the list evolves.)
+- **`paymentPolicyType`: `PER_GUEST` or `FREE`.** `PER_GUEST` needs `perGuestOptions.price` (decimal **string**, e.g. `"55.00"`; currency is the site's). `FREE` needs no price. Creating a `PER_GUEST` experience succeeds on a free site, but a guest **completing** a paid experience booking needs the same premium + payment provider that any paid reservation does (below).
+- **`businessSchedule.entries[]`** carries the recurrence: `WEEKLY` with `weeklyOptions.startDaysAndTimes[{ day, time }]` (`day` is `MONDAY`…`SUNDAY`, `time` is `"HH:mm"`), or `ONE_TIME` with `oneTimeOptions`. `durationInMinutes` sits on `businessSchedule`, not per entry.
+- **⚠️ Booking an experience is PREMIUM-GATED**, exactly like turning on online reservations (`setup-restaurant-reservations.md` STEP 3 → `428 PREMIUM_ONLY` on a free site). **Creating** the experience works on a free site; **booking** it at runtime needs the site to be premium with online reservations enabled. Record the precondition in the handoff; **don't fail the seed** over it.
+- **Cover image (opt-in):** `configuration.displayInfo.coverImage` takes a Wix Media image (`{ id, url, … }`) — attach it in the imagery pass (`IMAGE_GENERATION.md`) only when `imagery` is on; otherwise omit and the frontend renders a themed block.
+- **⚠️ Heads-up for the booking UI (not a seed step):** the experiences **sample-flow doc** (linked above) tells the frontend to call `getScheduledTimeSlots` with the experience GUID — **that parameter doesn't exist** (neither the SDK nor REST scopes slots to an experience), so it silently returns the *location's* slots. The frontend must instead project bookable times from the experience's own `businessSchedule`. Full detail: `how-to-code-restaurant-reservations.md` (Gotcha C).
+
+## Keep
+
+Nothing crosses into the handoff — experiences are read **live** on the frontend (`queryExperiences`). Track the created `experienceId`(s) only transiently (to confirm success / attach cover images). Frontend booking contract: `how-to-code-restaurant-reservations.md` (Experiences section).

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

@@ -32,7 +32,42 @@ A checklist for online ordering on a Wix site that already has a **Restaurants M
 ---
 
 ## Article: Steps for Setting Up Wix Restaurants Online Ordering
-**YOU MUST** complete all the following steps **in the given order** (1-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.
+**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
 
@@ -147,12 +182,13 @@ Response — one object per menu; match by **`menuId`**:
 - 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 PRECONDITION (note, don't fail).** A visitor can browse the orderable menu and build a cart with just this setup, but **completing a paid order** at runtime needs the site to have a **premium plan and a configured payment method** (checkout rides on Wix eCommerce). That's a site-provisioning concern, not a seed step — surface it in the handoff; do **not** fail the seed over it.
+> **⚠️ 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).

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

@@ -24,7 +24,26 @@ A checklist for turning on **table reservations** for a Wix site.
 ---
 
 ## Article: Steps for Setting Up Wix Table Reservations
-**YOU MUST** complete the steps in order (1-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.
+**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
 

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

@@ -24,7 +24,7 @@ A concise checklist for preparing any new Wix site that uses the Wix Restaurants
 
 ### 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). Remove it **before** creating yours, so the storefront shows only your menu. Do this **first** — cleaning before you create guarantees the ids you delete are the install's samples, never your own entities. Delete children before parents (items → sections → menus):
+**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>", …]}`.

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

@@ -14,7 +14,7 @@ Run these in order:
 
 **If a `wix.config.json` (or `.wix/`) is already present, the project is already connected to Wix — this is the *iterate* case.** Do **not** run `init` again (it's for attaching a *new* Wix project). Read `./wix.config.json` → hold `SITE_ID` in scratch, and skip to §2.
 
-> **Iterate is incremental.** An already-connected project may already be set up and/or seeded from a prior run. In §3–§4, **check current state before acting** — query installed apps before installing, check for already-seeded content before seeding (re-seeding duplicates it), and inspect existing wiring before adding. Do only the delta the new intent requires; leave the rest untouched.
+> **Iterate is incremental.** An already-connected project may already be set up and/or seeded from a prior run. In §3–§4, **check current state before acting** — query installed apps before installing (the Dynamic Context call in `DISCOVERY.md` §1 reports them in one call), check for already-seeded content before seeding (re-seeding duplicates it), and inspect existing wiring before adding. Do only the delta the new intent requires; leave the rest untouched.
 
 Otherwise, attach Wix in place:
 
@@ -71,4 +71,4 @@ static-hosting fixes in **`references/managed/DEPLOYMENT.md`** — the entry fil
 `index.html`, and `outputDirectory` must point at the directory holding it (init's `./dist` default is
 wrong for static). Then finalize per **`references/managed/DEPLOYMENT.md`** (`npx @wix/cli@latest release` — Wix
 publishes + registers the origin OOTB). Close with a short summary (apps installed, content seeded, what
-was wired, live URL).
+was wired) and **both links — the live site URL and the site dashboard `https://manage.wix.com/dashboard/<SITE_ID>`** (see `managed/DEPLOYMENT.md` § "Give the user both links"; `<SITE_ID>` is the `siteId` in scratch), then run the feedback checkpoint (`managed/DEPLOYMENT.md` § "Before you sign off").

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

@@ -93,6 +93,20 @@ Run the agnostic flow against the scaffolded site:
   (`createClient({ modules, auth: OAuthStrategy({ clientId }) })`), where `clientId` is the public
   `appId` from the `wix.config.json` written by `init` (§1).
 
+**If the user didn't specify their own design direction** (no palette, no theme/style words, no
+reference site, no brand guidelines), **decide the run's design tokens per `references/DESIGN.md`**
+before writing any component — theme polarity, a 2–4 color palette, type scale, radius/spacing — and
+hold them for reuse across every page and the themed-block fallback (`IMAGE_GENERATION.md`). If the
+user *did* specify a direction, use theirs instead — `DESIGN.md` is a fallback, not a checklist to
+enforce over an explicit ask. Either way, `DESIGN.md` §3's accessibility floor (WCAG 2.2 AA contrast,
+16px/1.5 body type) always applies — a page that fails it isn't done yet, regardless of whose palette
+it's using.
+
+**For page copy:** if the user didn't supply their own copy or voice direction, write hero/section
+headlines, kickers, subtitles, and CTA labels per **`references/CONTENT.md`** — otherwise use theirs.
+Either way, `CONTENT.md` §1 (the business's category must read literally above the fold) always holds —
+a page a first-time visitor can't identify isn't done yet, regardless of voice.
+
 Then build the pages the user's intent calls for, **wired to the live backend**, using
 **`references/SDK_HANDOFF.md`** for the per-capability packages, the SDK docs, and the seeded schema to
 bind (collection/form names + field keys; all other content is queried live). Install the SDK packages the loaded verticals need, author the pages/components directly in the
@@ -127,4 +141,4 @@ depends on `frontendFramework` (§0):
 - **Non-Astro** → the framework's own build (e.g. `npm run build`); a static (no-build) site skips this.
   `release` publishes whatever `site.outputDirectory` points at (default `./dist`).
 
-Close with a short summary (apps installed, content seeded, pages built, live URL).
+Close with a short summary (apps installed, content seeded, pages built) and **both links — the live site URL and the site dashboard `https://manage.wix.com/dashboard/<SITE_ID>`** (see `managed/DEPLOYMENT.md` § "Give the user both links"; `<SITE_ID>` is the `siteId` in scratch), then run the feedback checkpoint (`managed/DEPLOYMENT.md` § "Before you sign off").

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

@@ -14,6 +14,53 @@ CI=1 npx @wix/cli@latest release
 - The deployed origin is registered on the OAuth app automatically — the frontend's visitor SDK calls are accepted from the live URL with no extra step.
 - The published URL is printed on stdout (`Site published on <url>`).
 
+## Give the user both links — the live site **and** the dashboard
+
+When you close the run, surface **two** links, not one:
+
+1. **The live site URL** — the `Site published on <url>` value from release above.
+2. **The site dashboard (Business Manager)** — `https://manage.wix.com/dashboard/<SITE_ID>`, where `<SITE_ID>` is the `siteId` held in scratch (read from `wix.config.json`). This is where the owner manages the site behind the headless frontend — view store orders, edit content, manage members, etc. **Always include it**: a headless site has no editor button, so without this link the owner has no obvious way back into their own backend, and the seeded content/apps look unreachable.
+
+Present them plainly, e.g.:
+
+```
+Live site:  <published-url>
+Dashboard:  https://manage.wix.com/dashboard/<SITE_ID>
+```
+
+## Suggest a custom domain (proactive, after release)
+
+After delivering the links above, **proactively offer a custom domain** — don't wait for the user to ask. The published URL is a generic Wix subdomain; a custom domain is the obvious next step, and the CLI handles the whole flow.
+
+1. **Suggest options.** Build a search query from what you know about the site — its business name, topic, or purpose from this run (not a generic placeholder):
+
+   ```bash
+   npx @wix/cli@latest account domain suggest "<business name or site topic>" --limit 5 --json
+   ```
+
+   All returned suggestions are already available for purchase. Show the user a few of the best fits, and mention they can explore more options — re-run `suggest` with different keywords, a higher `--limit`, or `--tld com net ...` to filter extensions.
+
+2. **Offer to buy, with a direct purchase link.** For the domain(s) the user likes, generate a site-scoped deep link so the purchase is tied to this site and can be connected after payment:
+
+   ```bash
+   npx @wix/cli@latest account --site-id <SITE_ID> domain buy <domain> --json
+   ```
+
+   Use the `siteId` from `wix.config.json`. `buy` does **not** charge anything — it returns a checkout URL (`https://manage.wix.com/get-domain?...`); the user completes payment in the browser.
+
+   > Your site is live at <published-url>, and you can manage it from your [dashboard](https://manage.wix.com/dashboard/<SITE_ID>).
+   > To build a professional online presence, [connect a custom domain](<checkout-url>) — **mybusiness.com** is available.
+
+If the user isn't interested, drop it — one offer, no upselling.
+
+## Before you sign off — feedback checkpoint
+
+This is the last step of the run — the natural point to check `../FEEDBACK.md`. Don't wait for the
+user to complain: run a quick self-check over the whole session (not just this final step) — a
+confusing API response, a doc that was wrong/missing, an extra retry, a workaround you had to invent,
+anything that cost more turns than it should have. If anything qualifies, **offer** to relay it to Wix
+as you deliver the links above; send only after an explicit yes.
+
 ## Member login on a **non-Astro** frontend — register the callback URI (post-release)
 
 **Only when the run has member login on a non-Astro SPA/static frontend using the Wix login page** (`inline-recipes/how-to-code-members-non-astro.md` — the `getAuthUrl` → `/callback` handshake). Astro's built-in `/api/auth/*` callback shapes are auto-registered; a **non-Astro SPA's own callback path is not** — and **login stays dead (4xx on the login redirect) until you register it**. This is a genuine gap `wix release` does *not* close for you.

package/skills/wix-headless/references/self-managed/DEPLOYMENT.md

@@ -5,3 +5,11 @@ For a **self-managed** project, the deploy/finalize steps are **not yet decided
 Because hosting is the user's (not Wix's), this will likely mirror the self-hosted finalize pattern — **publish the metasite** and **register the deployed origin** on the OAuth app once the live URL is known (see `../stripe/DEPLOYMENT.md` for that shape) — but the exact mechanism, and how credentials/URL are supplied, are TBD.
 
 > **TBD.** Until this is defined, tell the user that `self-managed` deployment isn't wired yet, and that the frontend's visitor calls will be rejected until its origin is registered on the OAuth app.
+
+## Before you sign off — feedback checkpoint
+
+This is the last step of the run — the natural point to check `../FEEDBACK.md`. Don't wait for the
+user to complain: run a quick self-check over the whole session — a confusing API response, a doc
+that was wrong/missing, an extra retry, a workaround you had to invent, anything that cost more turns
+than it should have. If anything qualifies, **offer** to relay it to Wix before you close out; send
+only after an explicit yes.

package/skills/wix-headless/references/stripe/DEPLOYMENT.md

@@ -61,3 +61,11 @@ curl -sS -w "\nHTTP_STATUS:%{http_code}" -X PATCH \
 If the agent isn't the one deploying — the user will deploy the site themselves — the skill **cannot know the deployed URL**, so it cannot register the origin. (It can still publish the site — step 1 doesn't need the URL.) **Flag the origin step to the user clearly**, e.g.:
 
 > *"One required step remains before the frontend can talk to Wix: once your site is live, its URL must be registered on the Wix OAuth app (allowed domains). Give me the deployed URL — or re-run this skill with it — and I'll register it. Until then, Wix SDK calls from the live site will be rejected."*
+
+## Before you sign off — feedback checkpoint
+
+This is the last step of the run — the natural point to check `../FEEDBACK.md`. Don't wait for the
+user to complain: run a quick self-check over the whole session (not just this final step) — a
+confusing API response, a doc that was wrong/missing, an extra retry, a workaround you had to invent,
+anything that cost more turns than it should have. If anything qualifies, **offer** to relay it to Wix
+before you close out; send only after an explicit yes.