@wix/agent-skills 1.15.0 → 1.15.1

package/skills/wix-app/references/stores/GET_PRODUCT.md

@@ -0,0 +1,99 @@
+# Stores — Get Product
+
+## Get a single product
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);  // returns Product directly
+  return product;
+}
+const { product } = await products.getProduct(id);  // V1 wraps in { product }
+return product;
+```
+
+---
+
+## Read product options and choices (V1 vs V3)
+
+V1 and V3 differ in **both where choices live and what the choice fields are named**. Getting this wrong causes `TS2339` at validate time.
+
+| | V1 | V3 |
+|---|---|---|
+| Options array on product | `product.productOptions` | `product.options` |
+| Option name | `option.name` | `option.name` |
+| Option type | `option.optionType` (`"color"` / `"drop_down"`) | `option.optionRenderType` (`"SWATCH_CHOICES"` / `"TEXT_CHOICES"`) |
+| **Choices array** | `option.choices` ← **directly on the option** | `option.choicesSettings?.choices` ← **nested** |
+| Choice display value | `choice.value` | `choice.name` |
+| Choice color | `choice.value` (hex string) | `choice.colorCode` |
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  for (const option of product.options ?? []) {
+    const choices = option.choicesSettings?.choices ?? [];  // ✅ nested — NOT option.choices / option.optionValues (TS2339)
+    for (const choice of choices) {
+      render(option.name, choice.name, choice.colorCode);   // name = label; colorCode = hex for SWATCH_CHOICES
+    }
+  }
+} else {
+  const res = await products.getProduct(id);
+  const product = res.product!;  // product is optional in the raw type; ! matches SDK's strict-mode guarantee
+  for (const option of product.productOptions ?? []) {
+    for (const choice of option.choices ?? []) {           // ✅ direct in V1
+      render(option.name, choice.value);                   // value = label or hex string
+    }
+  }
+}
+```
+
+**In a site plugin on a product page**: get `productId` from `widget.getProp('product-id')`, then call the appropriate version's `getProduct` — same pattern as above.
+
+---
+
+## Modifiers (V1 `manageVariants=false` options)
+
+In V3, options that **don't** create variants (V1 `manageVariants=false`) live on `product.modifiers`, not `product.options`. They use the identical `choicesSettings.choices` pattern. Reading only `product.options` silently misses these.
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  // variant-creating options
+  for (const option of product.options ?? []) {
+    for (const choice of option.choicesSettings?.choices ?? []) {
+      render(option.name, choice.name, choice.colorCode);
+    }
+  }
+  // display-only / free-text customizations (formerly manageVariants=false)
+  for (const modifier of product.modifiers ?? []) {
+    for (const choice of modifier.choicesSettings?.choices ?? []) {
+      render(modifier.name, choice.name, choice.colorCode);
+    }
+  }
+}
+```
+
+---
+
+## Variant choices (V1 object map → V3 array)
+
+V1 `variant.choices` was a plain object map `{ "Size": "Small" }`. V3 restructures it as an array — accessing it with a key returns `undefined` silently.
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  // variants are NOT returned by queryProducts — use getProduct or Read-Only Variants API
+  for (const variant of product.variantsInfo?.variants ?? []) {
+    for (const c of variant.choices ?? []) {
+      render(c.optionChoiceNames?.optionName, c.optionChoiceNames?.choiceName);
+    }
+    // ❌ variant.choices['Size'] — always undefined in V3 (object map is gone)
+  }
+} else {
+  const res = await products.getProduct(id);
+  const product = res.product!;  // product is optional in the raw type; ! matches SDK's strict-mode guarantee
+  for (const variant of product.variants ?? []) {
+    // V1: choices is { [optionName]: value }
+    render(Object.entries(variant.choices ?? {}).map(([k, v]) => `${k}:${v}`).join(', '));
+  }
+}
+```

package/skills/wix-app/references/stores/INVENTORY.md

@@ -0,0 +1,37 @@
+# Stores — Inventory
+
+## Increment stock
+
+```typescript
+import { inventory, inventoryItemsV3 } from '@wix/stores';
+
+if (v === 'V3_CATALOG') {
+  // Per-variant; flat shape.
+  await inventoryItemsV3.bulkIncrementInventoryItems([
+    { inventoryItemId, incrementBy: 5 },
+  ]);
+} else {
+  // Per-product (variant optional).
+  await inventory.incrementInventory([
+    { productId, variantId, incrementBy: 5 },
+  ]);
+}
+```
+
+To find a V3 inventory item ID, use `inventoryItemsV3.searchInventoryItems` filtered by `productId` / `variantId`.
+
+---
+
+## Query inventory
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const res = await inventoryItemsV3.queryInventoryItems().eq('productId', productId).find();
+  return res.items;
+}
+// V1: filter is a JSON-stringified expression.
+const res = await inventory.queryInventory({
+  query: { filter: JSON.stringify({ productId }) },
+});
+return res.inventoryItems;
+```

package/skills/wix-app/references/stores/QUERY.md

@@ -0,0 +1,87 @@
+# Stores — Query / List Products
+
+## List products with pagination
+
+Both versions expose a fluent query builder, but the paging method differs:
+
+| Aspect | V1 (`products.queryProducts()`) | V3 (`productsV3.queryProducts()`) |
+|--------|--------------------------------|----------------------------------|
+| API style | Fluent builder: `.skip().limit().find()` | Fluent builder: `.skipTo(cursor).limit().find()` |
+| Pagination | Offset (`.skip(n)`) | Cursor (`.skipTo(cursor)`) |
+| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `Product[]`) |
+| Total count | `res.totalCount` | **None** — V3 only has `cursors.next` + `hasNext()` |
+| `hasNext` | `res.hasNext()` (method) | `res.hasNext()` (method) |
+| Next cursor | n/a | `res.cursors.next` (string) |
+
+```typescript
+import { catalogVersioning, products, productsV3 } from '@wix/stores';
+
+export interface ProductsPage {
+  products: unknown[];        // narrow at call site
+  nextCursor: string | null;  // V3 only
+  hasNext: boolean;
+  totalCount: number | null;  // V1 only
+}
+
+export async function listProductsPage(
+  limit: number,
+  cursorOrSkip: string | number | undefined,
+): Promise<ProductsPage> {
+  const v = await getVersion();
+  if (v === 'STORES_NOT_INSTALLED') {
+    return { products: [], nextCursor: null, hasNext: false, totalCount: 0 };
+  }
+
+  if (v === 'V3_CATALOG') {
+    let builder = productsV3.queryProducts().limit(limit);
+    if (typeof cursorOrSkip === 'string') builder = builder.skipTo(cursorOrSkip);
+    // Do NOT chain a sort — see OVERVIEW.md gotcha #10.
+    const res = await builder.find();
+    return {
+      products: res.items,
+      nextCursor: res.cursors.next ?? null,
+      hasNext: res.hasNext(),
+      totalCount: null,
+    };
+  }
+
+  const skip = typeof cursorOrSkip === 'number' ? cursorOrSkip : 0;
+  const res = await products.queryProducts().skip(skip).limit(limit).find();
+  return {
+    products: res.items,
+    nextCursor: null,
+    hasNext: res.hasNext(),
+    totalCount: res.totalCount ?? null,
+  };
+}
+```
+
+> **Two ways to call V3 `queryProducts`:** the canonical builder shown above, and a direct-call form `productsV3.queryProducts({ cursorPaging: { limit, cursor } })` returning a `Promise<{ products, pagingMetadata }>`. Both compile and run, but the builder is more idiomatic and matches V1's shape.
+
+---
+
+## Display price/stock without fetching variants
+
+V3 `queryProducts` does not return variants. Read product-level rollup fields instead:
+
+```typescript
+function displayPrice(p: { actualPriceRange?: { minValue?: { amount?: string }; maxValue?: { amount?: string } } }): string {
+  const min = p.actualPriceRange?.minValue?.amount;
+  const max = p.actualPriceRange?.maxValue?.amount;
+  if (!min) return '—';
+  return max && max !== min ? `${min} – ${max}` : min;
+}
+
+function stockLabel(status: string | undefined): string {
+  switch (status) {
+    case 'IN_STOCK': return 'In Stock';
+    case 'OUT_OF_STOCK': return 'Out of Stock';
+    case 'PARTIALLY_OUT_OF_STOCK': return 'Limited';
+    case 'PREORDER': return 'Pre-order';
+    default: return '—';
+  }
+}
+// V1 path: product.stock.inventoryStatus  (same UPPER_SNAKE_CASE values)
+// V3 path: product.inventory.availabilityStatus (adds PREORDER)
+// SKU lives on the variant — show "—" in lists, or use Read-Only Variants API.
+```

package/skills/wix-app/references/stores/WRITE.md

@@ -0,0 +1,55 @@
+# Stores — Write Operations (Create / Update / Delete)
+
+## Create a product (single-variant, with price)
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.createProduct({
+    name: 'My Product',
+    productType: 'PHYSICAL',                            // UPPER_CASE
+    variantsInfo: {
+      variants: [{
+        price: { actualPrice: { amount: '19.99' } },    // string, on the variant
+        sku: 'SKU-001',
+      }],
+    },
+  });
+  return product;
+}
+
+const { product } = await products.createProduct({
+  name: 'My Product',
+  productType: 'physical',                              // lower-case
+  priceData: { price: 19.99 },                          // number, on the product
+  sku: 'SKU-001',
+});
+return product;
+```
+
+---
+
+## Update a product (V3 needs `revision`)
+
+```typescript
+if (v === 'V3_CATALOG') {
+  // Signature: updateProduct(_id, productFields). Returns Product directly.
+  const current = await productsV3.getProduct(id);
+  if (current.revision == null) throw new Error(`Product ${id} has no revision`);
+  return await productsV3.updateProduct(id, {
+    revision: current.revision,  // narrowed — required under exactOptionalPropertyTypes
+    name: 'New name',
+  });
+}
+// V1: updateProduct(id, productFields). Returns { product }.
+const { product } = await products.updateProduct(id, { name: 'New name' });
+return product;
+```
+
+---
+
+## Delete a product
+
+```typescript
+if (v === 'V3_CATALOG') await productsV3.deleteProduct(id);
+else await products.deleteProduct(id);
+```

package/skills/wix-headless/SKILL.md

@@ -91,7 +91,12 @@ If the credentials are absent, the Wix backend isn't reachable — **stop with a
 4. **Handoff** (`references/SDK_HANDOFF.md`) — after Setup and Seed, **emit** the integration guide: SDK bootstrap, per-capability call shapes, the **seeded IDs**, and the `@wix/*` package list.
 5. **Finalize deployment** (`<TYPE_DIR>/DEPLOYMENT.md`) — run the project-type's finalize steps.
 
-**Throughout any run** — if the user asks to send feedback to Wix, complains/gets frustrated, or the run hits substantial friction (repeated API/doc/tooling failures), you may **offer** to relay it to Wix per `references/FEEDBACK.md`. Send only after an explicit yes — never automatically.
+**Throughout any run** — if the user asks to send feedback to Wix, complains/gets frustrated, or the
+run hits any real friction (a confusing error, a doc gap, a tooling dead end, a workaround you had to
+invent — it doesn't need to repeat), **offer** to relay it to Wix per `references/FEEDBACK.md`. Default
+to offering rather than waiting to be asked. Every flow's finalize step (`<TYPE_DIR>/DEPLOYMENT.md` /
+`managed/CREATE.md` / `managed/CONNECT.md`) ends with the same checkpoint — treat it as a required
+self-check, not optional. Send only after an explicit yes — never automatically.
 
 **Managed create / connect / iterate** — after Discovery, hand the whole run to the managed flow:
 - **create** → **`references/managed/CREATE.md`** (scaffold → Setup → Seed → build the frontend → release).

package/skills/wix-headless/entry/bootstrap.mjs

@@ -26,7 +26,7 @@ const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headl
 
 // run a command, capture stdout+stderr (combined), return {status, out}
 function capture(cmd, args, opts = {}) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: false, env: AGENT_ENV, ...opts });
+  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
   return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
 }
 
@@ -43,7 +43,7 @@ function checkCli() {
 // ── 2. Login (human-in-the-loop device code; forward the CLI's own events) ───
 function login() {
   return new Promise((resolve) => {
-    const child = spawn(WIX[0], [...WIX.slice(1), 'login'], { shell: false, env: AGENT_ENV });
+    const child = spawn(WIX[0], [...WIX.slice(1), 'login'], { shell: isWin, env: AGENT_ENV });
     const rl = readline.createInterface({ input: child.stdout });
     let loggedIn = false;
     // Buffer the CLI's own diagnostics (stderr + any non-event stdout chatter) so a

package/skills/wix-headless/entry/skill.md

@@ -65,8 +65,6 @@ The script emits one JSON object per line:
 Install the Wix Headless skills (`CI=1` forces plain non-interactive CLI output — keep it on every Wix CLI command):
 
 ```bash
-CI=1 wix skills add
-# Fallback if 'wix skills' isn't registered for this project type:
 CI=1 npx skills@latest add wix/skills --yes
 ```
 

package/skills/wix-headless/references/CAPABILITIES.md

@@ -48,7 +48,8 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 - **Implementation checklist:** show the event's title, date and time, and location; show the description; show ticket types where they exist (ticketed events); a register/RSVP action; collect additional-guest names where extra guests are allowed; a confirmation after registering.
 
 ### bookings — appointments and classes
-- **Intent:** book / appointment / schedule / class / session / reserve a slot / reserve a table.
+- **Intent:** book / appointment / schedule / class / session / reserve a slot — a **service or appointment with a provider** (a stylist, trainer, tutor, clinic, studio).
+- **Not bookings — route to `restaurants` instead:** a **table at a restaurant** is a Table Reservations concern, not a bookable service; and a **special dining occasion guests reserve** — a wine tasting, cheese pairing, chef's table, or tasting-menu evening at a restaurant — is a **restaurants → Table Reservations *experience*** (see the restaurants entry), **not** a bookings service. Reach for `bookings` only when what's booked is a standalone service/class with a provider, never a seat at a restaurant.
 - **Required site features:** a list of services; a page per service; a way to pick a time and book it.
 - **Implementation checklist:** show each service's name, duration, and price; show the staff or provider; show the available time slots; a book action; a confirmation after booking.
 
@@ -58,9 +59,10 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 - **Implementation checklist:** show each plan's name, price, and billing cycle; list what each plan includes (the perks); a clear "choose plan" action; highlight a recommended tier where it makes sense.
 
 ### restaurants — menus and food
-- **Intent:** menu / restaurant / cafe / food / dish list / order food / dine-in.
-- **Required site features:** a menu organized into sections; each item with a name, description, and price. (Online ordering and table reservations are optional add-ons — separate apps; see `SETUP.md`.)
-- **Implementation checklist:** show the menu grouped into sections in order; each item's name, description, price, and labels (vegan, spicy…) and modifiers / variants where they exist; an order action if online ordering is wired; a reserve-a-table action if reservations are wired.
+- **Intent:** menu / restaurant / cafe / food / dish list / order food / dine-in / **reserve a table** / a **special dining occasion guests reserve** (wine tasting, cheese pairing, chef's table, tasting-menu evening).
+- **Required site features:** a menu organized into sections; each item with a name, description, and price. **Add-ons, each on demand (separate apps/features; see `SETUP.md`):** online ordering, table reservations, and — **when the brief names special dining occasions** — **experiences** (a reservation that *is* a curated occasion at the restaurant, e.g. a wine-and-cheese pairing), which ride on the Table Reservations app.
+- **Experiences vs bookings — decide here:** an **experience** is a **reservation that is itself a special dining occasion at the restaurant** — it books seats at the restaurant's own location and carries its own name, per-guest price, schedule, and booking form. Use it for pairing sessions, tastings, and chef's tables. Use the separate **`bookings`** vertical only for a **service/appointment/class with a provider** that isn't a seat at the restaurant. For anything a restaurant hosts and seats, prefer an experience.
+- **Implementation checklist:** show the menu grouped into sections in order; each item's name, description, price, and labels (vegan, spicy…) and modifiers / variants where they exist; an order action if online ordering is wired; a reserve-a-table action if reservations are wired; **if experiences are wired, list each experience with its name, description, per-guest price, and schedule, and a reserve-seats action.**
 
 ### portfolio — showcase projects
 - **Intent:** portfolio / showcase / gallery of projects / creative work / case studies.

package/skills/wix-headless/references/DISCOVERY.md

@@ -27,7 +27,7 @@ For each capability, build its `intent.<cap>` block — the inputs the seed step
 | events | `{ eventCount, titles: [] }` | `eventCount: 2`, titles brand-derived, future dates |
 | bookings | `{ serviceCount, servicesNamed: [] }` | `serviceCount: 2`, brand-derived service names |
 | pricing-plans | `{ planCount, tiersNamed: [] }` | `planCount: 2` (e.g. Basic / Pro), monthly billing |
-| restaurants | `{ menuName, sections: [{ name, itemCount }] }` | one menu, 2 sections, `itemCount: 3` each |
+| restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (wine/cheese pairing, chef's table) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
 | portfolio | `{ collections: [{ name }], projectCount }` | one brand-derived collection, `projectCount: 3` |
 
 Counts are deliberately small (the seed shows the shape, not a full catalog).

package/skills/wix-headless/references/FEEDBACK.md

@@ -10,16 +10,27 @@ This is **not** support, and not for the user's own site content. It is meta-fee
 
 ## When to offer it (user-approved only — never auto-send)
 
-Sending is always the user's call. Offer once, in plain prose, in any of these situations; send only
-after an explicit yes:
+Sending is always the user's call, but **offering is not** — default to offering, don't wait to be
+asked or for the user to complain first. Offer once, in plain prose, in any of these situations; send
+only after an explicit yes:
 
 - The user **explicitly asks** to send feedback / report something to Wix ("tell Wix that…", "report
   this", "send feedback"). Then just confirm the wording and send.
 - The user **complains, is frustrated, or reports a Wix bug** in the course of the work ("this API is
   broken", "the docs are wrong", "why is this so hard"). Acknowledge, then offer to pass it on.
-- **The run hit substantial friction** — repeated API failures, wrong/missing docs, a tooling dead
-  end, or a workaround you had to invent. When you notice the pattern, offer: *"This tripped us up a
-  few times — want me to send it to Wix as feedback?"*
+- **The run hit any real friction** — not just repeated failures. A single confusing error, a doc
+  that was wrong/stale/missing, an extra round trip you had to make, a workaround you had to invent,
+  or anything that cost more turns than it should have all qualify — it doesn't need to have happened
+  more than once. When you notice it, offer in the moment: *"That [error/doc gap] tripped us up —
+  want me to send it to Wix as feedback?"*
+- **At the natural end of every run** (deployment/handoff, or wherever the skill's flow closes out),
+  do a deliberate self-check over the whole session even if nothing felt dramatic at the time — friction
+  you shrugged off or silently retried past is still signal. If the self-check turns up anything,
+  offer before you sign off rather than letting the run end without asking.
+
+Bias toward offering over staying quiet: a redundant offer costs the user one "no thanks"; a friction
+point that goes unreported is a signal Wix never gets. Only skip the offer when the run was genuinely
+clean end to end.
 
 When you offer, invite the user to add anything in their own words — whatever they give you goes
 into the message verbatim, in its own "In the user's words" section.

package/skills/wix-headless/references/SDK_HANDOFF.md

@@ -45,6 +45,7 @@ For each loaded capability, give the host the **package(s)** from the map below
 | restaurants — online ordering (add-on; only when the Orders app is in the run) | add `@wix/ecom` + `@wix/redirects` to the row above | `how-to-code-restaurant-orders.md` — ordering cart/checkout on top of the menu display. |
 | portfolio | `@wix/portfolio` (+ `media` from `@wix/sdk` to resolve image strings; **no** `@wix/ecom`/`@wix/redirects` — display-only) | `how-to-code-portfolio.md` — Portfolio v1 display-only read. |
 | restaurants — table reservations (add-on; only when the Table Reservations app is in the run) | `@wix/table-reservations` (a **distinct** package from `@wix/restaurants`; **no ecom/redirects** — a reservation is a hold, not a purchase) | `how-to-code-restaurant-reservations.md` — book-a-table hold→reserve. |
+| restaurants — experiences (add-on; special dining occasions guests reserve — wine/cheese pairing, chef's table) | `@wix/table-reservations` (same package; the **`experiences`** namespace + `timeSlots`/`reservations`) | `how-to-code-restaurant-reservations.md` — "Booking an experience" (query experiences → scheduled slots → reserve with `experienceId`). |
 
 > **Cross-cutting packages** (`CAPABILITIES.md` § "Cross-cutting capabilities"): these aren't per-vertical rows but get added to the package list when the run used them. If **coupons** were seeded, add `@wix/marketing`. The eCommerce checkout packages (`@wix/ecom`, `@wix/redirects`) are already folded into the stores row above — include them once when any purchase-flow vertical is present.
 
@@ -62,6 +63,7 @@ Carry only the **structural** carve-outs the coding step genuinely reads — the
 Everything else the host resolves live from the queries in §3. (Static platform constants — Stores/Bookings app IDs, the Blog appDefId — and the public `clientId` are needed too, but they're identical for every site, not seed output; they're in §2/§3.)
 
 ### 5 · Integration notes (headless-auth specifics the per-module docs won't frame)
+- **Restaurants online ordering has real-world go-live preconditions the code can't satisfy — surface them to the owner.** For a working ordering flow the site needs: **(1) a business location with a real address** (the skill sets this in `setup-restaurant-orders.md` STEP 0 — but if the brief gave no address, a placeholder was used and the owner MUST replace it, or checkout stays "testing only"); **(2) a premium plan**; **(3) a configured payment method**. State these plainly in the guide/summary — the site is not "done" for real orders until the owner completes them. (The same premium+payment note applies to any eCommerce checkout, e.g. stores.)
 - The visitor token has **no per-user identity** → seeded **CMS collections are public/shared** across all visitors (not per-user, not cross-device). Per-user storage needs member auth.
 - Frontend CMS access is **read**; visitor writes go through **Forms** submissions.
 - **Blog comments are member-gated — read public, write authenticated.** Querying/rendering comments is public, so list them server-side in SSR. **Submitting** needs a logged-in member, so don't gate the form behind an upfront login check (that branch is what burns deliberation): render the form always and resolve identity at submit — POST to a backend endpoint (`src/pages/api/*.ts`) that calls `createComment` with the request session; if the caller isn't a member, redirect to the built-in `/api/auth/login?returnUrl=…`. **Do not build the comment form as a client island** — the API-endpoint + session path is the documented shape and avoids the browser-auth detour. The comment API keys (post `referenceId`, Blog appDefId, author lookup via `post.memberId`) are in `how-to-code-a-blog.md`.

package/skills/wix-headless/references/SEED.md

@@ -4,6 +4,8 @@ For each resolved capability, create the backend content its *what* names. This
 
 Use `$TOKEN` / `$SITE_ID` from the provided authentication mechanism (see `<TYPE_DIR>/AUTHENTICATION.md`). The capabilities are **independent** — no cross-capability ordering or shared data (**two exceptions:** (a) **pricing-plans depends on bookings' service IDs**, so seed bookings before pricing-plans; (b) **restaurants online ordering depends on the restaurants menu** — the ordering add-on binds each menu to an operation, so the menu must be seeded before ordering — both in §2). For each one: read its inline recipe (§1; §2 maps each capability to its `setup-*.md`), build the body from `intent.<cap>` + `brand`, execute against `wixapis.com` with the universal call shape (Bearer `$TOKEN` + `wix-site-id` — see `SETUP.md` §1), and collect the created IDs into a `seeded` map keyed by capability.
 
+> **Cleaning up install sample data is fine on a fresh install — but never delete real content without approval.** Some recipes start by removing the app install's **default sample/mock data** (e.g. a demo "Dinner Menu", a "My Portfolio" collection, sample products). That is safe **when you just installed the app and what's present is obviously the install's own sample/demo content**. But the site may already hold **real content** (an iterate/connect re-run, or a site the owner has populated) — if what's there isn't obviously install sample data, or you're unsure, **do not delete it: ask the user for approval first.** Seeding is otherwise **additive** — create the requested content alongside what's there; deleting or overwriting existing products / collections / menus / forms / projects / media is destructive and needs the user's explicit ask or approval.
+
 > **Concurrency is an optional optimization, never a requirement.** Seeding the capabilities **one after another always works** — that is the safe default, and an agent doing everything itself simply seeds each in turn. Because the capabilities are independent (above), **if** your runtime can run work concurrently you **may** seed several at the same time to save wall-clock. Treat this strictly as "you may," never "you must": a correct seed must never *depend* on parallelism.
 >
 > **These constraints hold whether you seed serially or concurrently:**
@@ -36,7 +38,7 @@ Each entry states only the entities, where their count/content comes from, the p
 - **events** — *A ticketed or RSVP occasion, or upcoming events.* Recipe: **`setup-events.md`**. Each event is **either `TICKETING`** (paid — it has ticket tiers) **or `RSVP`** (free — the registration form is built-in, so don't seed form fields) per intent. For an **RSVP occasion** (a wedding, party, gathering): one RSVP event with the occasion's real details (title, a **future** date/time, location). For a **ticketed** event: the event plus its ticket tiers (default a single `"General Admission"` tier if none named). For a **listing** site: `intent.events.eventCount` events with brand-appropriate titles and **future** start dates (a default location/timezone is fine). Text-only. **Keep:** nothing for the handoff — events and tiers are discovered **live** (`queryEvents`, `getEventBySlug`, `queryAvailableTickets`); track `eventIds`/`ticketDefinitionIds` only transiently.
 - **bookings** — *Bookable services.* Recipe: **`setup-bookings.md`**. `intent.bookings.serviceCount` services (name + short description fitting `brand`, a simple duration and price); keep the schedule minimal. **Keep:** `serviceIds[]` as **seed-time state** (pricing-plans' coverage step keys on them, below); nothing for the handoff — services are discovered **live** (`queryServices`).
 - **pricing-plans** — *Membership tiers.* Recipe: **`setup-pricing-plans.md`**. `intent.pricing-plans.planCount` recurring plans (name, price, a monthly billing cycle) fitting `brand`. **When bookings is also in this run and the intent is a membership that covers services** (a studio/gym/class pass), also **attach the covered bookings services to the plan** — seed the bookings services first, since coverage keys on their service ids (see the recipe). **Keep:** the bookings coverage only transiently, to wire it during seeding; nothing for the handoff — plans are discovered **live** (`queryPlans`) and plan→service coverage is read **live** at checkout, never from a frozen map (see `how-to-code-pricing-plans.md`).
-- **restaurants** — *A menu.* Recipe: **`setup-restaurants.md`** (add-ons have their own recipes, below). Create the `itemCount` items per section first (name, description, price fitting `brand`), then the `intent.restaurants.sections` referencing those item ids, then the menu referencing the section ids — **items → sections → menu** (build bottom-up: a section is created with its `itemIds`, a menu with its `sectionIds`, so each child must exist before its parent — see `setup-restaurants.md` STEP 1–3). Text-only. **Keep (seed-time only):** `menuId`, `sectionIds[]`, `itemIds[]` to build the tree; nothing goes to the handoff — the frontend reads menus **live** (`listMenus`/`listSections`/`listItems`). **Online ordering (add-on, on demand)** — only when the request calls for ordering (not just a displayed menu): install the Orders app (per `SETUP.md` §2) and follow **`setup-restaurant-orders.md`**; **seed the menu FIRST, then ordering, in the same unit** (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). **Keep:** nothing for the handoff — read **live** (`listOperations`/`listFulfillmentMethods`); track `operationId`/`fulfillmentMethodIds[]` transiently. **Table reservations (add-on, on demand, INDEPENDENT of ordering/menu)** — only when the request calls for reservations: install the Table Reservations app (per `SETUP.md` §2) and follow **`setup-restaurant-reservations.md`**; **no menu dependency** (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and **nothing to bulk-seed** (visitors create reservations at runtime); enabling online reservations is **premium-gated** (record the precondition, don't fail). **Keep:** nothing for the handoff — read **live** (`listReservationLocations`); track `reservationLocationId` transiently.
+- **restaurants** — *A menu.* Recipe: **`setup-restaurants.md`** (add-ons have their own recipes, below). Create the `itemCount` items per section first (name, description, price fitting `brand`), then the `intent.restaurants.sections` referencing those item ids, then the menu referencing the section ids — **items → sections → menu** (build bottom-up: a section is created with its `itemIds`, a menu with its `sectionIds`, so each child must exist before its parent — see `setup-restaurants.md` STEP 1–3). Text-only. **Keep (seed-time only):** `menuId`, `sectionIds[]`, `itemIds[]` to build the tree; nothing goes to the handoff — the frontend reads menus **live** (`listMenus`/`listSections`/`listItems`). **Online ordering (add-on, on demand)** — only when the request calls for ordering (not just a displayed menu): install the Orders app (per `SETUP.md` §2) and follow **`setup-restaurant-orders.md`**; **seed the menu FIRST, then ordering, in the same unit** (ordering auto-provisions per menu either way — see the concurrency note above — but keeping them one unit gives the ordering verify a menu to confirm against). **Configure the business-location address (`setup-restaurant-orders.md` STEP 0) — required for ordering to work end-to-end; without it Wix limits ordering to "testing only" and checkout breaks.** If the brief gives no address, set a placeholder and flag the owner in the handoff. Completing a *paid* order additionally needs premium + a payment method (dashboard/premium — surface, don't fail). **Keep:** nothing for the handoff — read **live** (`listOperations`/`listFulfillmentMethods`); track `operationId`/`fulfillmentMethodIds[]` transiently. **Table reservations (add-on, on demand, INDEPENDENT of ordering/menu)** — only when the request calls for reservations: install the Table Reservations app (per `SETUP.md` §2) and follow **`setup-restaurant-reservations.md`**; **no menu dependency** (reservations bind to a location, not a menu — do NOT apply the menu-first rule) and **nothing to bulk-seed** (visitors create reservations at runtime); **configure the business-location address (`setup-restaurant-reservations.md` STEP 0)** — the reservation location is the site's business location, so set a real address (placeholder + owner flag if the brief names none; shared with ordering if both are present); enabling online reservations is **premium-gated** (record the precondition, don't fail). **Keep:** nothing for the handoff — read **live** (`listReservationLocations`); track `reservationLocationId` transiently. **Experiences (add-on within Table Reservations, on demand)** — only when the request names **special dining occasions guests reserve** (wine/cheese pairing, chef's table, tasting-menu evening — an *experience*, not a `bookings` service; see `CAPABILITIES.md`): they need the **Table Reservations app** (no extra install) and a configured **business-location address** (`setup-restaurant-reservations.md` STEP 0, same as reservations) and, unlike plain reservations, they **are** seeded — create one Experience per named occasion on the default reservation location, following **`setup-restaurant-experiences.md`**. Booking an experience is **premium-gated** like online reservations (record the precondition, don't fail). **Keep:** nothing for the handoff — experiences are read **live** (`queryExperiences`); track `experienceId`(s) transiently.
 - **portfolio** — *A project showcase.* Recipe: **`setup-portfolio.md`**. Create the `intent.portfolio.collections` (title + short description fitting `brand`), then `intent.portfolio.projectCount` projects assigned to them — **collections before projects** (a project's `collectionIds` must hold real collection ids; see the recipe). Text-only by default (omit `coverImage`; images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `collectionIds{<name>}` to assign projects into their collections; nothing goes to the handoff — the frontend lists collections and projects **live** (`collections.queryCollections` / `projects.queryProjects`), so owner-added content appears with no code change.
 
 > **Cross-cutting (on demand).** `coupons` is not a standalone capability (`CAPABILITIES.md` § "Cross-cutting capabilities") — there's no app to install and it's not in `verticals[]`. If intent calls for discounts **and** a parent vertical (stores / bookings / events / pricing-plans) is in this run, create coupons scoped to that parent and add the coupon to the `seeded` map (`seeded.coupons = { couponIds[] }`). **Coupons has no inline recipe** — read the create shape from the docs (`DOC_DISCOVERY.md` is the fallback): every coupon needs a scope with a namespace and its parent vertical's app installed (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/about-wix-coupons.md>), and the create-coupon spec needs name/code/start + a scope namespace + exactly one coupon-type field (<https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/create-a-coupon.md>). eCommerce needs no seeding — it's the runtime checkout layer that rides along.

package/skills/wix-headless/references/SETUP.md

@@ -24,7 +24,7 @@ For each capability in `verticals[]`, install its app by `appDefId` (these are t
 - **events** → `140603ad-af8d-84a5-2c80-a0f60cb47351`
 - **bookings** → `13d21c63-b5ec-5912-8397-c3a5ddb27a97`
 - **pricing-plans** → `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`
-- **restaurants** → `b278a256-2757-4f19-9313-c05c783bec92` (Wix Restaurants **Menus** — the seedable core). Online ordering and table reservations are **separate optional apps**, install only if intent calls for them: Orders (New) → `9a5d83fd-8570-482e-81ab-cfa88942ee60`, Table Reservations → `f9c07de2-5341-40c6-b096-8eb39de391fb`.
+- **restaurants** → `b278a256-2757-4f19-9313-c05c783bec92` (Wix Restaurants **Menus** — the seedable core). Online ordering and table reservations are **separate optional apps**, install only if intent calls for them: Orders (New) → `9a5d83fd-8570-482e-81ab-cfa88942ee60`, Table Reservations → `f9c07de2-5341-40c6-b096-8eb39de391fb`. **Experiences** (special dining occasions guests reserve — wine tastings, chef's tables; see `CAPABILITIES.md`) are a **feature of the Table Reservations app, not a separate install** — installing Table Reservations is all that's needed to create and book them (`setup-restaurant-experiences.md`).
 - **portfolio** → `d90652a2-f5a1-4c7c-84c4-d4cdcc41f130` (Wix Portfolio; the install ships a default sample collection + projects — `setup-portfolio.md` STEP 0 cleans them)
 - **cms** → **no install** (Wix Data is core) — skip
 

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