@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -0,0 +1,119 @@
+# 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.
+
+---
+
+## Search products by name
+
+V3 `queryProducts` filters only on `_id`, `slug`, `options.id` and `handle` — `name` is a
+compile error. Use `productsV3.searchProducts()`, a direct call rather than a builder. V1 has
+no search method; its builder accepts `name` via `startsWith` (prefix match only, no `fuzzy`).
+
+Imports come from the first example in this file.
+
+```typescript
+// `v` comes from getVersion() — see STORES_VERSIONING.md.
+export async function searchByName(
+  term: string,
+  limit: number,
+  v: 'V1_CATALOG' | 'V3_CATALOG' | 'STORES_NOT_INSTALLED',
+) {
+  if (v === 'V3_CATALOG') {
+    const res = await productsV3.searchProducts({
+      cursorPaging: { limit },
+      // `fields` is required for free-text search. Searchable: 'name', 'description',
+      // 'variantsInfo.variants.sku', 'minVariantPriceInfo.sku'.
+      search: { expression: term, fields: ['name'], fuzzy: true },
+    });
+    // Note `products` (not `items`) and `pagingMetadata.hasNext` (a property, not a method).
+    return res.products ?? [];
+  }
+  const res = await products.queryProducts().startsWith('name', term).limit(limit).find();
+  return res.items;
+}
+```
+
+---
+
+## 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-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-docs
-description: "Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain `curl` (zero dependencies) — find a page by **semantic search** (`POST /mcp-docs-search/v1/docs/search`, natural-language `{ search_term, document_type }`) **or by browsing** the docs tree as a menu from the `llms.txt` root (append `.md` to any docs path), then read the page by appending `.md` to its URL; and (2) the Wix MCP doc tools when your agent has them. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema."
+description: "Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain `curl` (zero dependencies) — find a page by **semantic search** (`POST /mcp-docs-search/v1/docs/search`, natural-language `{ search_term, document_type }`) **or by browsing** the docs tree as a menu — a structured, typed, counted browse of the REST API reference (`POST /mcp-docs-search/v1/docs/menu/browse`), or the `.md` menu tree from the `llms.txt` root for any portal — then read the page by appending `.md` to its URL; and (2) the Wix MCP doc tools when your agent has them. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema."
 ---
 
 # Wix Docs — look up the Wix API/SDK documentation
@@ -54,8 +54,40 @@ curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search' \
 # no jq? → python3 -c 'import sys,json;[print(r["title"],r["url"]) for r in json.load(sys.stdin)["results"] if r.get("url")]'
 ```
 
-**B. Browse the tree from the root, like a menu.** Every docs path has a `.md` twin, so you can
-navigate the docs as a menu tree — no search needed. `curl https://dev.wix.com/docs/llms.txt` is the
+**B. Browse the docs tree as a menu.** Two ways: the **structured browse endpoint** for the REST
+API reference (preferred there — typed, counted, filterable), and the **`.md` menu tree** for every
+portal and for reading pages.
+
+**B1. Structured browse — REST API reference (`api-reference`).** `POST
+/mcp-docs-search/v1/docs/menu/browse` walks the tree and returns each child with its **kind**, its
+**HTTP verb** (for methods), and **subtree counts** ("Catalog V3 — 121 methods, 32 articles"), so
+you pick the right area by shape — in ~2 KB, not a ~40 KB menu page you have to `grep`. `include`,
+`name_filter`, and `depth` jump straight to what you want. Body: `menu_url?` (absolute docs URL;
+omit for the portal root — the top-level verticals), `document_type?` (`REST`, default), `depth?`
+(1, max 6), `include?` (`CATEGORY`·`RESOURCE`·`METHOD`·`ARTICLE`·`WEBHOOK`·`OBJECT`·`SKILL`),
+`deprecated?` (`HIDE` default·`SHOW`·`ONLY`), `name_filter?`, `format?` (`MARKDOWN` default →
+`content` string; `STRUCTURED` → JSON tree with `url`/`http_method`/`resource_id`/`child_counts`).
+
+```bash
+# a vertical's structure, with per-child subtree counts
+curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/stores"}' \
+  | jq -r '.content'
+
+# jump straight to a method by name — no multi-level grep
+curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/bookings","include":["METHOD"],"name_filter":"cancel","depth":4}' \
+  | jq -r '.content'
+```
+
+REST (`api-reference`) only, and browse-only: it hands you the page **URL** — read it by appending
+`.md` (§2), and get the exact schema from §C.
+
+**B2. `.md` menu tree — every portal, and how you read pages.** Every docs path has a `.md` twin, so
+you can navigate any portal with zero dependencies; use it for the **non-REST portals** (SDK, Velo,
+Headless, CLI) and to read leaves. `curl https://dev.wix.com/docs/llms.txt` is the
 top-level map; the portals under it:
 
 | Portal | Start here for |

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).
@@ -112,11 +117,13 @@ Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL
 | What | Path |
 |---|---|
 | Vertical index (intent matching + per-vertical site spec) | `<SKILL_ROOT>/references/CAPABILITIES.md` |
-| Discovery (infer capabilities + brand + intent) | `<SKILL_ROOT>/references/DISCOVERY.md` |
+| Discovery (infer capabilities + brand + intent; existing site → the Dynamic Context call in §1) | `<SKILL_ROOT>/references/DISCOVERY.md` |
 | Setup (install apps) | `<SKILL_ROOT>/references/SETUP.md` |
 | Seed (create backend content) | `<SKILL_ROOT>/references/SEED.md` |
 | SDK-integration handoff (emitted, or applied by create/connect) | `<SKILL_ROOT>/references/SDK_HANDOFF.md` |
 | Image generation (opt-in; agnostic) | `<SKILL_ROOT>/references/IMAGE_GENERATION.md` |
+| Design — fallback visual quality bar for the built frontend, when the user gave no design direction of their own (managed **create** only) | `<SKILL_ROOT>/references/DESIGN.md` |
+| Content — fallback copy quality bar for the built frontend, when the user gave no copy/voice direction of their own (managed **create** only) | `<SKILL_ROOT>/references/CONTENT.md` |
 | AI features — text/chat + embeddings (opt-in; agnostic) | `<SKILL_ROOT>/references/AI_FEATURES.md` |
 | Feedback — relay the user's headless-experience feedback to Wix (opt-in; user-approved) | `<SKILL_ROOT>/references/FEEDBACK.md` |
 | **Authentication** — obtain `$TOKEN`/`$SITE_ID`/`clientId` (project-type-specific) | `<TYPE_DIR>/AUTHENTICATION.md` |

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/CONTENT.md

@@ -0,0 +1,36 @@
+# Content — default copy quality bar for the built frontend (managed create)
+
+**Applies when this skill writes frontend page copy from scratch** (managed `create`, `CREATE.md` §4) — hero/section headlines, subtitles, kickers, CTA labels, and any image captions the pages include. Same scope as `DESIGN.md`: not `connect`/`iterate` (the copy already exists there).
+
+**Same precedence rule as `DESIGN.md`: fallback, not override.** If the user supplied their own copy, brand voice, or tone direction, use theirs — don't overwrite it to match the conventions below. The one exception is **§1** — a comprehension floor, not a style preference: whatever the voice, a first-time visitor must still be able to tell what the business *is* from the hero.
+
+## 1 · Say what the business is — explicitly, above the fold
+
+- A first-time visitor must know what the site *is* and what they can *do*, straight from the hero — never left to infer from mood or voice alone.
+- The **business category** (e.g. "yoga studio", "restaurant", "construction services") must appear **literally** in at least one of: the H1, a kicker above the H1, or the **first clause of the subtitle**. A witty H1 alone is not enough.
+- The **subtitle leads with the offer**, in plain language, before any flavor — put the verb the visitor actually cares about early ("Book…", "Order…", "Learn…", "Hire…").
+- Voice-driven, evocative H1s are welcome — but only when the category sits explicitly right beside them (kicker or subtitle). When in doubt, name the category in the kicker.
+
+## 2 · Kickers (micro-copy above titles)
+
+- **Cut a kicker that only restates the title** (e.g. "The Courses" above a Courses heading) — it adds nothing.
+- **Keep a kicker that carries real information**: category + location ("Yoga Studio · Downtown"), a feature's proper name, event details, dates, price framing.
+- A kicker is the right place to satisfy §1 when the H1 itself is voice-led rather than literal.
+
+## 3 · Titles, subtitles, paragraphs, CTAs
+
+- **Titles and subtitles end without a period.** Paragraphs (full running sentences) keep theirs.
+- No fluff — every line should move the visitor's understanding forward, the H1 and subtitle most of all.
+- **CTA labels are short and avoid all-caps** unless a specific reason demands it (readability). Word them to the actual action (ties to `DESIGN.md` §2's "one primary CTA, worded to the action" rule) — not generic verbs.
+
+## 4 · Images — the real subject comes first
+
+- **At least one image on the page must show the real story of the business** — the actual thing, not just abstract graphics, dashboards, or decorative art. A climbing outfitter shows mountains and climbers; a clinic shows the room; a workshop shows the tools and hands at work.
+- **Decorative/supporting visuals (illustrations, icons, patterns, textures) layer in *addition to* the real subject, never *instead of* it.** They earn their place by reinforcing the story and mood once the business is genuinely shown — not by standing in for it.
+- Imagery (real or decorative) matches the tone, voice, and era of the business.
+- When the user must supply their own real photos (the business has a specific, particular space/product/person that generated imagery can't stand in for), use a **fillable image slot with a descriptive placeholder** naming exactly what belongs there — not a generic stock image presented as final.
+
+## 5 · Image captions
+
+- A caption describes what is **actually seen** in its image. Tone can vary (serious, playful, informative) but must stay aligned with the image's real content.
+- **No meaningless captions, and no caption that ignores the image.** A slogan or pull-quote overlaid on a photo is not a caption — if a true caption is wanted, write one that describes the scene once the real image is in place.

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

@@ -0,0 +1,54 @@
+# Design — default visual quality bar for the built frontend (managed create)
+
+**Applies when this skill builds the frontend from scratch** (managed `create`, `CREATE.md` §4). It does **not** apply to `connect`/`iterate` — there the design already exists (brought in by the user), and the job is wiring, not designing (`CONNECT.md` §4).
+
+**This is a fallback, not an override.** It fills the gap **only when the user gave no design direction of their own** — no palette, no "make it dark/minimal/playful," no reference site or screenshot, no brand guidelines. The moment the user specifies *any* of that, their explicit intent wins outright — don't apply a rule below just because it's here if it contradicts what they asked for. Two exceptions that hold regardless of what's requested: **§3 (accessibility)** is a hard floor — if a user-requested palette fails contrast, fix the specific pair to comply, don't ship a violation — and the **anti-genericism intent** of §1 (derive tokens from *this* brand, don't reuse the last project's look) still applies even when the user supplied their own palette/theme, since it's about not being lazy with *their* inputs, not about overriding them.
+
+This is the **agent's own design-tokens contract** — it's the thing `IMAGE_GENERATION.md` and `DISCOVERY.md` §4 already assume exists when they say a themed-block fallback "follows the site's own design tokens (palette, radius, spacing)". Decide the tokens below *before* writing the first component; every page and fallback then draws from that one decision instead of improvising per-component.
+
+## 1 · Decide the design tokens once, before any component
+
+A short, explicit decision — a few lines, not a document — derived from `brand.description`/`brand.vibe` (`DISCOVERY.md` §2):
+
+- **Theme polarity** — light, dark, or vivid/tinted. Argue it from the business, never default to dark for "premium" (a light, high-key theme can be just as strong — e.g. healthcare/wellness usually reads better light).
+- **Palette** — 2–4 hex colors, one dominant + accents drawn from **analogous hues** (adjacent on the color wheel, ~30° arc) — not complementary jumps. Functional colors (error/success/warning) sit outside this count.
+- **Type scale** — one heading scale + one body size. Body text floor: **16px, 1.5 line-height** (§3 is non-negotiable, this is where you set it).
+- **Radius + spacing** — pick once (e.g. "12px radius, 24px section padding") and reuse everywhere; don't let each component invent its own.
+
+Hold these as the run's design tokens. Reuse them literally in the themed-block fallback (`IMAGE_GENERATION.md`) and every page — don't re-derive per page.
+
+**Vary this across projects.** Don't reach for the same palette/theme/layout on every build — derive it from *this* brand's vibe each time. Repeating the same look across unrelated projects is a failure mode, not a shortcut.
+
+## 2 · Layout (hard rules)
+
+- **Full-bleed, not boxed.** Don't wrap the page in a narrow centered container (no `max-w-4xl mx-auto` outer shell). Design for the full viewport; use the peripheral space intentionally.
+- **One primary CTA per page**, worded to the page's actual action — `Book a Table`, `Add to Cart`, `Reserve Your Spot`, not generic verbs ("Submit", "Click here", "Go").
+- **Icons never sit on a filled/tinted background shell** — no circle/square/pill behind a nav or card icon. The glyph renders directly on the surface.
+- **Identify the site's 3–4 core pages/sections from its resolved vertical** (`verticals[]`, `DISCOVERY.md` §1) before laying out anything, and design each to its own intent:
+
+  | Vertical | Core pages/sections to get right |
+  |---|---|
+  | stores | Home hero, product grid, product detail, cart |
+  | blog | Post list, post detail |
+  | cms | Collection list, item detail |
+  | forms | The form itself — clear single-column, one obvious submit |
+  | events | Event list, event detail + RSVP |
+  | bookings | Service list, booking widget/flow |
+  | pricing-plans | Plan comparison, checkout/signup |
+  | restaurants | Menu, reservation/ordering flow |
+  | portfolio | Project grid, case-study/project detail |
+
+## 3 · Accessibility (hard rules, no exceptions)
+
+- **WCAG 2.2 AA contrast** — every chosen background/foreground pair must hit **4.5:1** for body text, **3:1** for large text (≥24px or ≥19px bold). Check the actual hex pair against the ratio — don't assume a palette is accessible because it "looks fine."
+- **16px minimum body font**, **1.5 minimum line-height** for body copy.
+
+## 4 · Content & imagery hygiene
+
+- **No emojis** in UI copy, headings, or empty states.
+- **No stock-photo clichés** — generic handshake/lightbulb/laptop-on-desk imagery reads as filler, not a real page.
+- Generated imagery already carries its own purity rule (no text/logos/watermarks/UI-mockups — `IMAGE_GENERATION.md` § Prompts, "no text, no watermarks"); nothing additional to do here beyond following that section as written.
+
+## What this doesn't cover
+
+This is a floor, not a template library — it constrains the *how* (contrast, layout shape, token discipline), not the *what* (that's `verticals[]` + `brand` from Discovery, and the user's intent). Two builds with the same vertical and different brand vibes should still look nothing alike.

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

@@ -6,6 +6,30 @@ Discovery is pure inference — it needs **no authentication** and is **agnostic
 
 ## 1 · Resolve the capability set
 
+> **Targeting an existing site with an ambiguous brief? Read the site — don't guess.** When the
+> run points at a site that already exists (connect/iterate, a funnel-created site) and an
+> elevated credential is already available, one documented call returns the site's context —
+> installed apps by name (including the Stores catalog version), status, URL,
+> locale/currency/timezone, and CMS collections — as an agent-ready markdown report:
+>
+> ```bash
+> curl -sS -X POST 'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+>   -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+>   -d "{\"siteId\": \"$SITE_ID\"}"
+> ```
+>
+> Docs: <https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context-markdown.md>
+> (a JSON variant lives at the same path without `/markdown`). With an API key, send it raw as
+> the `Authorization` header value, no `Bearer` prefix.
+>
+> The installed business apps map to the vertical set and seed `verticals[]` directly (CMS
+> collections present → cms); inference below then only fills what the site can't answer
+> (brand, per-capability intent). Several verticals installed → prioritize by the user's words
+> and by which holds real (non-sample) content. Nothing relevant installed → **ask the user one
+> short question** ("what do you offer — products, appointments, posts, events?") rather than
+> defaulting to a store. This is the one case where Discovery may use the authentication
+> mechanism early; with no credential at hand yet, skip it and infer from the words as below.
+
 Read the **user intent** (+ optional project signals: `package.json` name, README, visible copy) against the vertical index in `references/CAPABILITIES.md` — each entry there carries the intent signals that point to it. Pick every vertical that genuinely fits → `verticals[]`. Multiple signals → multiple capabilities. On ambiguity, prefer the more specific vertical; if nothing dynamic is named, fall to the **forms** floor (a contact form). **Never return an empty set.**
 
 Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · pricing-plans · restaurants · portfolio** (`CAPABILITIES.md` § "Built verticals"). If intent points squarely at a vertical outside that set, note it plainly as not-yet-wired (per the index) and resolve the rest; don't force an unrelated capability in its place.
@@ -27,7 +51,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/IMAGE_GENERATION.md

@@ -36,6 +36,14 @@ body: { "url": "<imageURL from generate>", "mimeType": "image/png", "displayName
 
 Keep two values from the `file` object: **`file.url`** (the full permanent `wixstatic.com` URL) and **`file.id`** (the WixMedia file id, e.g. `<hash>~mv2.jpg`). Some entities bind by url, others by id — **which one a given entity uses is the recipe's concern** (§3), not this common section's. (The import response has **no `fileUrl` field** — the id is `file.id`.)
 
+**Importing several images? Use one bulk call, not N singles** — `POST https://www.wixapis.com/site-media/v1/bulk/files/import-v2` (≤100 per call):
+
+```
+body: { "importFileRequests": [ { "url": "<imageURL>", "mimeType": "image/png", "displayName": "<name>.png" }, … ] }
+```
+
+Response is `{ "results": [ { "itemMetadata": { "originalIndex", "success" }, "item": { "url", "id", … } } ] }` — read each hit's **`item.url`** / **`item.id`** (same values as the single import's `file.url` / `file.id`) and its `itemMetadata.success`.
+
 ## 3 · Attach (by entity type)
 
 The pass-2 **write shape is per-entity earned knowledge and lives in each capability's seed recipe** — right next to the create shape the seeder already reads (`inline-recipes/setup-<capability>.md`). **That recipe is authoritative** — read the exact shape there (field paths, any required companion fields, silent-drop warnings, confirm-by-requery), not here. This section is navigation only and carries no shapes:
@@ -57,6 +65,8 @@ The pass-2 **write shape is per-entity earned knowledge and lives in each capabi
 
 Brand-contextual, never generic. Include: subject; the brand aesthetic/mood; the palette (real tones, e.g. "warm cream and forest green"); style/lighting; and always **"no text, no watermarks"** (AI-rendered text is garbled). Pull context from the brand + the entity (product name/description, post topic, page purpose).
 
+**At least one image per page must show the real subject of the business** — the actual service/product/space, not just abstract or decorative art; decorative visuals layer in *addition* to that, never *instead of* it (`CONTENT.md` § Images has the full rule + the fillable-slot fallback for when only the user's own real photos will do).
+
 ## Credits, cost & the not-generating fallback
 
 Each generated image costs **1 Wix AI credit**, billed at the account level regardless of project type (the account behind the metasite must have credits). Volume is bounded in `DISCOVERY.md` §4 — carry those two values through:

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-a-store.md

@@ -52,7 +52,8 @@ A concise contract for writing the **frontend code** of a storefront against a C
 The exact field paths the storefront reads, and the **plausible-wrong sibling** each is mistaken for — the sections below reference these instead of re-describing them. All `amount`s are **strings**. These are **read** shapes; the cart-add body (under *Adding to cart*) is a separate **write** shape, and the `_id` rule applies to read **entities**, not to method-return wrappers (note `checkoutId`).
 
 ```jsonc
-// productsV3.queryProducts() / .searchProducts()  →  result.items[]
+// productsV3.queryProducts().…find()  →  result.items[]
+// productsV3.searchProducts({...})    →  result.products[]
 product = {
   _id,                                            // links · cart catalogItemId · variant filter   (NOT .id → empty → HTTP 500)
   slug, name, visible,                            // only visible:true is returned to a visitor token
@@ -119,7 +120,7 @@ const res = await categories.queryCategories({
 **⚠️ CRITICAL: category filtering MUST use `searchProducts`, NOT `queryProducts`.** `directCategoriesInfo.categories` is **not declared as filterable in `queryProducts`** — passing it there returns HTTP `400 "... is not declared as filterable"`, which the SDK **swallows silently**, leaving an empty category page that looks like "no products". This is the #1 way this breaks. Use Search Products:
 
 ```js
-const { items } = await productsV3.searchProducts({
+const { products } = await productsV3.searchProducts({
   filter: { 'directCategoriesInfo.categories': { $matchItems: [{ id: categoryId }] } },
 });
 ```