@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -0,0 +1,155 @@
+---
+name: "Setup Portfolio"
+description: Initializes a Wix Portfolio backend — cleans the install's default sample collection + projects, then creates collections and creates projects assigned to them via collectionIds (collections before projects). Specifies the *how* (calls + format); the collection/project counts and names come from the request.
+---
+**RECIPE**: Business Recipe – Initial Setup for Wix Portfolio
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` **and** `wix-site-id: <SITE_ID>`. Body-bearing requests also need `Content-Type: application/json`.
+
+A concise checklist for preparing any new Wix site that uses the Wix Portfolio app.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial portfolio setup.
+
+> **This recipe is the *how*, not the *what*.** What to seed — how many collections, which ones, how many projects and their titles/descriptions — is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide quantities or which entities to create.
+
+> **API surfaces:** everything is the Portfolio **v1** API on `https://www.wixapis.com/portfolio/v1/...` — `/collections` and `/projects`. Use the **public `/portfolio/v1/...`** form; the method pages' schema headers show an internal `/portfolio/collections/api/v1/...` / `/portfolio/projects/projects/api/v1/...` URL — **do not** call those.
+
+> **This recipe seeds content and assumes the Portfolio app is already installed.** Installing apps is a separate, earlier step in the run (the **Setup** step — `SETUP.md` — runs before any seeding); this recipe only *creates content* on an already-installed app. So if a call returns **`428` / `APP_NOT_INSTALLED`**, it means the Setup step was skipped for Portfolio — **fail loudly with the response verbatim** and let Setup handle the install. Do **not** fabricate a limitation ("I can't install apps / do it in your Wix dashboard") — installing is not this recipe's job, but it *is* something the skill does, in Setup.
+
+> **Visibility is `hidden`, not `visible` — and it defaults to visible.** Portfolio's polarity is the **inverse** of Stores/Restaurants: entities carry a `hidden` boolean that **defaults to `false` (shown)**. So a collection/project created with no `hidden` field **appears on the live site** — you do **not** need to set anything to make it visible. Only set `"hidden": true` to hide one. (Send a plain boolean — `"hidden": false` — never a `{"value": …}` wrapper.) **Note:** when you omit `hidden` (or send `false`), the field is **absent** from the create/list response — proto3 drops false defaults — so *absent* reads as *false* reads as *shown*; `hidden` appears in the response only when you explicitly sent `true`. Don't treat a missing `hidden` as an error.
+
+---
+
+## Article: Steps for Setting Up Wix Portfolio
+**YOU MUST** complete all the following steps **in the given order** (0-2, plus 3 when imagery is on) without skipping any and **without requiring additional user input**.
+
+**⚠️ CRITICAL ORDER REQUIREMENT: create the COLLECTIONS first (STEP 1), then the PROJECTS (STEP 2).** A project is assigned to collections by a `collectionIds` array, and **that array is NOT validated on create** — a wrong or nonexistent collection id is **silently accepted**, producing an orphan project that appears under no collection. The only way to assign correctly is to create the collections first, read back their real ids, and thread those exact ids into each project. (There is **no** shared-revision `409` race — creating collections/projects concurrently is safe — but the id dependency still forces collections-before-projects.)
+
+### STEP 0: Clean the portfolio — remove the default sample data
+
+A freshly installed Wix Portfolio app comes pre-seeded with **one sample collection ("My Portfolio") and several sample projects** ("Editorial Portraits", "Seasonal Lookbook", …), all assigned to that collection. **Only remove data that is obviously the install's own sample content on a fresh install** (that "My Portfolio" collection and its sample projects). Do **not** assume existing collections/projects are samples: the site may already hold the owner's **real content** (a connect/iterate run, or an owner-populated portfolio). If what's there isn't obviously install sample data, or you're unsure, **do not delete it — ask the user first** (`SEED.md`: seeding is additive; deleting real content needs the owner's approval). When it clearly is the install's samples, remove it **before** creating yours so the site shows only the intended content.
+
+**Delete children before the parent — projects first, then collections.** (Deleting a collection does not clean up the projects that reference it.)
+
+1. **List the projects** — `GET https://www.wixapis.com/portfolio/v1/projects`. The projects are under `response.projects[]` (count at `response.metadata.count`). Collect every `project.id`.
+2. **Delete each project** — `DELETE https://www.wixapis.com/portfolio/v1/projects/{projectId}`, one call per id (there is **no** bulk-delete for projects). Each returns `200`.
+3. **List the collections** — `GET https://www.wixapis.com/portfolio/v1/collections` (`response.collections[]`); collect every `collection.id`.
+4. **Delete each collection** — `DELETE https://www.wixapis.com/portfolio/v1/collections/{collectionId}`, one call per id. Each returns `200`.
+5. **Verify** both lists now return `metadata.count: 0` before proceeding.
+
+### STEP 1: Create the collections
+
+Create the collections the request calls for — **which collections (and how many) come from the request**; this step only gives the call and format. Use **Create Collection**: `POST https://www.wixapis.com/portfolio/v1/collections`. There is **no bulk-create** — issue **one call per collection** (they may be fired concurrently — no `409` race — but sequential is just as correct and simplest).
+
+The body wraps the entity in a `collection` object:
+
+```json
+{
+  "collection": {
+    "title": "Brand Identity",
+    "description": "Logo systems and visual identities for growing companies.",
+    "hidden": false
+  }
+}
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **The display name is `title`, not `name`.** A `name` field is ignored.
+- **`slug` is optional — omit it and Wix auto-generates one from the title** (`"Brand Identity"` → `brand-identity`). Only send `slug` to force a specific one.
+- **`hidden` is optional and defaults to `false` (shown)** — omit it for a visible collection; send `"hidden": true` only to hide one.
+- **Text-only by default** — omit `coverImage` entirely (imagery is opt-in; see **Attach images**). `description` is a plain string.
+
+**Reading the response — the created collection is under `collection`, not a top-level field.** A `200` returns:
+
+```json
+{ "collection": { "id": "<collectionId>", "revision": "1", "title": "Brand Identity",
+  "slug": "brand-identity", "hidden": false, "sortOrder": 1783179721633, "url": { … } } }
+```
+
+Keep each **`collection.id`** (and `slug`) — the ids are the `collectionIds` you thread into projects in STEP 2. If a create fails, retry that collection **once** with the same body; do not loop.
+
+### STEP 2: Create the projects, assigned to their collections
+
+Create the projects the request calls for (counts/titles from the request). Use **Create Project**: `POST https://www.wixapis.com/portfolio/v1/projects` — **one call per project** (no bulk-create; concurrent is safe). Each project is assigned to one or more collections via **`collectionIds`**, populated with the **real ids from STEP 1**.
+
+The body wraps the entity in a `project` object:
+
+```json
+{
+  "project": {
+    "title": "Northwind Rebrand",
+    "description": "Full identity refresh for a logistics firm.",
+    "collectionIds": ["<collectionId from STEP 1>"],
+    "details": [
+      { "label": "Role", "text": "Brand & Art Direction" },
+      { "label": "Year", "text": "2025" }
+    ],
+    "hidden": false
+  }
+}
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **`collectionIds` must hold real ids captured from STEP 1.** They are **not validated** — a wrong/missing/guessed id is accepted silently and the project surfaces under no collection. Never invent a collection id; thread the STEP 1 response ids. A project with an **empty** `collectionIds: []` is created but belongs to no collection (only reachable from the all-projects list) — include at least one id unless the request truly wants an uncollected project.
+- **The display name is `title`, not `name`.** `slug` auto-generates from the title when omitted.
+- **`hidden` defaults to `false` (shown)** — same as collections; omit for visible.
+- **`details` is optional** — an array of `{ label, text }` pairs (Role, Year, Client, …) that renders as the project's metadata. Include a couple where the brief gives that info; omit for a bare project (`details` comes back `[]`).
+- **Text-only by default** — omit `coverImage` (see **Attach images**).
+
+**Reading the response** — the created project is under `project`:
+
+```json
+{ "project": { "id": "<projectId>", "revision": "1", "title": "Northwind Rebrand",
+  "slug": "northwind-rebrand", "hidden": false,
+  "collectionIds": ["<collectionId>"], "details": [ … ] } }
+```
+
+Keep each **`project.id`** and `slug`. If a create fails, retry that project **once** with the same body; do not loop.
+
+### Attach images (imagery opt-in — skip when imagery is off)
+
+**Only if `imagery` is on** (`SEED.md` § "Entity images"). Portfolio is a visual showcase, so the cover-image-bearing entities are **both projects and collections**. Generate + import each image per `references/IMAGE_GENERATION.md` (generate → import to Wix Media → keep the WixMedia image **id**), then **PATCH the entity's `coverImage`**.
+
+Attach to a project — `PATCH https://www.wixapis.com/portfolio/v1/projects/{projectId}` (collections are identical: `PATCH …/collections/{collectionId}` with a `collection` wrapper). Echo the entity's current **`revision`** (from the create response, or a fresh `GET`) — no field mask is needed:
+
+```json
+{
+  "project": {
+    "id": "<projectId>",
+    "revision": "<current revision>",
+    "coverImage": { "imageInfo": { "id": "<WixMedia image id>", "height": 2880, "width": 1920 } }
+  }
+}
+```
+
+- **`coverImage.imageInfo.id`** is the imported **WixMedia image id** (`file` id from the import step) — **and `height` + `width` are required** alongside it (`url` is read-only, returned populated). A missing revision or a stale one fails the PATCH.
+- Image failures never block the run — skip and leave the entity text-only.
+
+### Attach images — project gallery (imagery on only)
+
+**Only if `imagery` is on.** The cover (attached just above) is just the **listing-card thumbnail**. A project's **media gallery** — the ordered images on its detail page, which the frontend reads via the SDK `projectItems.listProjectItems(projectId)` (`how-to-code-portfolio.md`) — is a **separate `item` entity you must create**, one call per image. Without this step an imagery-on project has a cover but an empty gallery.
+
+```bash
+curl -X POST 'https://www.wixapis.com/portfolio/v1/items' \   # lowercase `items` — `/Items` (capital) 404s
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d '{ "item": {
+    "projectId": "<projectId from the create-projects step>",
+    "sortOrder": 1,
+    "title": "<image title>",
+    "image": { "imageInfo": { "id": "<WixMedia image id>", "height": 896, "width": 1200 } }
+  } }'
+```
+
+- **One call per image**; **`sortOrder`** (1, 2, 3…) sets the order the frontend renders. `image.imageInfo` is the same shape as `coverImage` (imported WixMedia id + height + width).
+- **Response nests the created item under `item`** (a top-level empty `projectId:""` echo is also returned — ignore it).
+- **⚠️ There is NO public list endpoint.** `GET /portfolio/v1/items?projectId=…`, `/projects/{id}/items`, `/items/project/{id}` **all 404** — do not hunt for one. To verify, `GET https://www.wixapis.com/portfolio/v1/items/{itemId}` one at a time; the frontend lists them via the SDK `projectItems.listProjectItems` (an internal URL the SDK resolves).
+- **Cover vs items:** cover = listing thumbnail (the cover PATCH above); items = ordered detail-page gallery (this call). An imagery-on portfolio typically wants **both** — if a project has only its cover image, reuse that WixMedia id as item #1 so the gallery isn't empty.
+- Item failures never block the run — skip and continue (a project with no items still renders from its cover).
+
+---
+
+## Conclusion
+Following these steps **in order** sets up a new Wix Portfolio site:
+- Starts from a **clean portfolio** — the install's default sample collection and projects are all removed first (projects before collections).
+- Contains the collections and projects called for by the request, with **collections created first** so each project's `collectionIds` holds a real, verified collection id (the array is not validated, so a wrong id would silently orphan the project).
+- Every collection and project is **shown** (`hidden` defaults to `false`) — nothing needs setting to be visible.
+- Cover images are attached only when `imagery` is on; otherwise everything stays text-only. All calls use the Portfolio **v1** API.

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

@@ -0,0 +1,229 @@
+---
+name: "Setup Pricing Plans"
+description: Initializes a Wix Pricing Plans backend with Plans V3 — creates recurring / one-time / free membership plans (billing cycle + flat-rate price), then (only when bookings is also in the run) attaches bookings services to a plan through the Benefit Programs API so a member's plan covers those services. Specifies the *how* (calls + format); counts and the specific plans/prices/cycles come from the request.
+---
+**RECIPE**: Business Recipe – Initial Setup for Wix Pricing Plans (Plans V3) + Bookings membership integration
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
+
+A concise checklist for turning a freshly provisioned Wix site with the **Wix Pricing Plans** app installed into a set of purchasable membership plans — and, when the site also has **Wix Bookings**, for wiring those plans to cover bookable services so members can book with their membership.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial Pricing Plans backend setup. (The frontend read/subscribe/book-with-plan contract is the sibling recipe `how-to-code-pricing-plans.md`.)
+
+> **This recipe is the *how*, not the *what*.** What to seed — how many plans, their names, prices, and billing cycles, and which bookings services a plan covers — is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide quantities, prices, or which plans to create.
+
+> **API surfaces:** plans use **Plans V3** on the **public** host `https://www.wixapis.com/pricing-plans/v3/...`. The bookings integration uses the **Benefit Programs V1** API (`https://www.wixapis.com/benefit-programs/v1/...`) — a *separate* API from Pricing Plans. Both APIs' method-article headers may show an internal `…/_api/…` form — **do not use that**; call the public non-`/_api/` form shown below. Relevant **app def ids** (constants the integration needs): Wix **Bookings** = `13d21c63-b5ec-5912-8397-c3a5ddb27a97`, Wix **Pricing Plans** = `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`.
+
+---
+
+## Article: Steps for Setting Up Wix Pricing Plans
+**YOU MUST** complete the following steps **in order** without skipping any and **without requiring additional user input**.
+
+There is **no clean-up step** — a fresh Wix Pricing Plans install ships **no sample plans**, so there is nothing to delete first.
+
+**⚠️ CRITICAL ORDER REQUIREMENT (integration only):** STEP 2 attaches **bookings service ids** to a plan. Those service ids come from the **Bookings seed** (`setup-bookings.md` → `seeded.bookings.serviceIds[]`). So when a run has **both** pricing-plans and bookings, **seed the bookings services first**, then create the plans (STEP 1), then attach (STEP 2). STEP 2 is **skipped entirely** when bookings is not in the run — a plans-only site stops after STEP 1.
+
+### STEP 1: Create the plan(s)
+
+Create **one plan per create call** (Plans V3 has **no bulk-create** for plans) against `POST https://www.wixapis.com/pricing-plans/v3/plans`. **How many plans, their names, prices, and billing cycles come from the request you're fulfilling** — this step only gives the call and the required format.
+
+**⚠️ The create body MUST include `plan.status: "ACTIVE"` and a valid, unique GUID `id` on every `pricingVariants[]` and every `perks[]` entry** — omitting any of them returns `400` (`status value is required` / `id is not a valid GUID` / `id must not be empty`). These `id`s are **client-supplied** (a confirmed won't-fix server-side gap: the Pricing-Plans team will not auto-generate them; only the plan's *own* top-level `id` comes back server-generated).
+
+**⚠️ Generate every GUID in the SHELL — never let the model type one.** A model emitting a UUID token-by-token isn't reliably valid or unique (→ `400`, or a duplicate-id collision across plans). Generate each in the shell and inject it via command substitution, so the value is always a real, fresh GUID regardless of which coding agent or OS runs this. This portable helper tries `uuidgen` → `python3` → `node`; **at least one is present in virtually every shell (a scaffolded Wix project always has `node`), so it effectively always succeeds — the fallback below covers the rare shell with none:**
+
+```bash
+gen_uuid() { uuidgen 2>/dev/null | tr 'A-Z' 'a-z' \
+  || python3 -c 'import uuid; print(uuid.uuid4())' 2>/dev/null \
+  || node -e 'console.log(require("crypto").randomUUID())'; }
+```
+
+Then create each plan with **fresh** ids (one `gen_uuid` call per field — never reuse a value across plans or perks). Body shown is a **recurring monthly** plan at a flat $20/month (the common membership case):
+
+```bash
+VID=$(gen_uuid); PERK1=$(gen_uuid); PERK2=$(gen_uuid)
+curl -sS -w "\nHTTP:%{http_code}" -X POST 'https://www.wixapis.com/pricing-plans/v3/plans' \
+  -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
+  -d "{
+    \"plan\": {
+      \"name\": \"Studio Membership\",
+      \"description\": \"Unlimited access to group classes.\",
+      \"status\": \"ACTIVE\",
+      \"visibility\": \"PUBLIC\",
+      \"buyable\": true,
+      \"buyerCanCancel\": true,
+      \"pricingVariants\": [
+        { \"id\": \"$VID\", \"name\": \"Monthly\",
+          \"billingTerms\": { \"billingCycle\": { \"period\": \"MONTH\", \"count\": 1 }, \"startType\": \"ON_PURCHASE\", \"endType\": \"UNTIL_CANCELLED\" },
+          \"pricingStrategies\": [ { \"flatRate\": { \"amount\": \"20.00\" } } ] }
+      ],
+      \"perks\": [ { \"id\": \"$PERK1\", \"description\": \"Unlimited group classes\" }, { \"id\": \"$PERK2\", \"description\": \"10% off workshops\" } ]
+    }
+  }"
+```
+
+> **Fallback — only if the shell has NO generator** (`uuidgen`, `python3`, **and** `node` all absent — effectively never in a Wix project): do **not** guess UUIDs. **Skip plan creation** and record a clear note for the user listing the plans to create by hand in the Wix dashboard (name, price, billing cycle). Failing loud beats seeding malformed plans.
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **Pricing lives under `pricingVariants[]`, NOT a top-level `price`.** Each variant carries `billingTerms` (the cycle) + `pricingStrategies` (the amount). Send **one** `pricingVariant` with **one** `pricingStrategy` — the schema nominally allows up to 20 variants but documents "currently limited to 1", so one is the norm.
+- **All amounts and money-ish values are decimal STRINGS**, not numbers: `flatRate.amount` = `"20.00"` (≥ `"0"`, ≤ 4 decimals). A number is rejected.
+- **`billingTerms` selects the plan type** (the request decides which):
+  - **Recurring** (subscription): `billingCycle: { "period": "DAY|WEEK|MONTH|YEAR", "count": 1 }`, `startType: "ON_PURCHASE"`, `endType: "UNTIL_CANCELLED"`. **Default to `MONTH`/`1`** unless the request names another cycle.
+  - **One-time** (bill once, then ends): `endType: "CYCLES_COMPLETED"` + `cyclesCompletedDetails: { "billingCycleCount": 1 }`. A one-time plan with *no* end date instead sets `"billingCycle": null` + `endType: "UNTIL_CANCELLED"`.
+  - **Free**: `pricingStrategies: [ { "flatRate": { "amount": "0" } } ]`; cap reuse with `"purchaseLimits": { "type": "PER_MEMBER_LIFETIME", "count": 1 }` (the older `maxPurchasesPerBuyer: 1` is deprecated — removal targeted 2026-11-30 — prefer `purchaseLimits`).
+- **Currency is NOT set in the request** — it's read-only in the response and derived from the site's business currency (like Bookings prices). Don't send a `currency`; don't fight the one that comes back.
+- **`visibility: "PUBLIC"` + `buyable: true`** make the plan appear on the public grid and be orderable. A `PRIVATE`/`buyable:false` plan is assign-only (only seed one if the request explicitly wants a hidden/manual plan).
+- **`name`** is required, 1–50 chars. **`perks[]`** are **display-only** (`{ description }`, ≤ 1400 chars each) — they are the bullet list shown on the plan card and have **no functional effect**. The actual bookings coverage is wired in STEP 2, **not** through `perks`.
+- **`plan.status: "ACTIVE"` is REQUIRED** — omitting it returns `400 status value is required` (undocumented but enforced; `ACTIVE` is the only value).
+- **`pricingVariants[].id` and `perks[].id` are REQUIRED, client-supplied GUIDs** — generate each in the shell (the `gen_uuid` helper above), never model-typed (→ malformed/duplicate → `400`), fresh per field. Only the plan's **own top-level `id`** is server-generated; it echoes the variant/perk ids you sent back in the response.
+- On partial failure across multiple plans, retry the **failed** plan(s) **once** with the same format — do not loop.
+
+**⚠️ Reading the response — the created plan is under `plan`, keep `plan.id`.** A successful create returns `200` with:
+
+```json
+{ "plan": {
+  "id": "<planId>",
+  "revision": "1",
+  "name": "Studio Membership",
+  "visibility": "PUBLIC",
+  "buyable": true,
+  "currency": "USD",
+  "pricingVariants": [ { "id": "<variantId>", "name": "Monthly", "billingTerms": { … }, "pricingStrategies": [ … ] } ],
+  "perks": [ { "id": "<perkId>", "description": "Unlimited group classes" } ]
+} }
+```
+
+Keep each plan's **`plan.id`** into `seeded.pricing-plans.planIds[]` — it's the id the frontend orders by, **and** the `externalId` the STEP 2 integration keys on.
+
+---
+
+### STEP 2: Attach bookings services to a plan (integration — SKIP when there is no bookings in the run)
+
+This is the **pricing-plans ↔ bookings membership link**: making a plan *cover* one or more bookable services so a member who holds the plan can book those services with their membership (frontend flow lives in `how-to-code-pricing-plans.md`). The link is **NOT** a field on the plan and **NOT** a perk — it goes through the separate **Benefit Programs API**, in three ordered sub-steps. Do this **per plan** that should cover services, using the plan's `plan.id` from STEP 1 and the **bookings service ids** from `setup-bookings.md`'s `seeded.bookings.serviceIds[]`.
+
+**⚠️ CRITICAL: the three sub-steps are strictly ordered — each consumes an id from the previous:** `plan.id` → `programDefinition.id` → `itemSetId` → items. Don't parallelize them.
+
+#### STEP 2a: Get the plan's program definition (READ — do not create it)
+
+When a plan is created, the Pricing Plans app **automatically creates a matching "program definition"** in Benefit Programs. You **read** it (you never create it) by the plan id + namespace:
+
+```bash
+curl -X GET 'https://www.wixapis.com/benefit-programs/v1/program-definitions/by-namespace-and-external-id?externalId=<PLAN_ID>&namespace=@wix/pricing-plans' \
+  -H 'Authorization: <AUTH>'
+```
+
+Response — keep **`programDefinition.id`** (this is the "programDefinitionId" STEP 2b needs):
+
+```json
+{ "programDefinition": {
+  "id": "<programDefinitionId>",
+  "namespace": "@wix/pricing-plans",
+  "externalId": "<PLAN_ID>",
+  "displayName": "…"
+} }
+```
+
+- **⚠️ `namespace` is literally `@wix/pricing-plans`** (with the `@` and the slash) in every sub-step 2a–2c. The generic Benefit Programs docs use placeholder namespaces (`gym_rewards`, `benefit_programs_app`) — **do not** use those.
+- **Provisioning is effectively immediate.** The program definition is created by the Plans app within ~1s of STEP 1. It's still created *asynchronously*, so if this GET returns `404`/empty right after creating the plan, **retry once after a short backoff** as insurance — do not loop.
+
+#### STEP 2b: Create the pool definition (one per integrating app)
+
+Create **one** pool definition holding **exactly one** benefit that names the Bookings app as the provider:
+
+```bash
+curl -X POST 'https://www.wixapis.com/benefit-programs/v1/pool-definitions' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "poolDefinition": {
+      "namespace": "@wix/pricing-plans",
+      "displayName": "Bookings benefit",
+      "programDefinitionIds": ["<programDefinitionId FROM 2a>"],
+      "details": {
+        "benefits": [
+          {
+            "benefitKey": "<RANDOM_UUID>",
+            "displayName": "Bookings sessions",
+            "providerAppId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
+            "price": "0"
+          }
+        ]
+      }
+    },
+    "cascade": "IMMEDIATELY"
+  }'
+```
+
+Response — keep the generated **`itemSetId`** for the benefit (matched by its `benefitKey`):
+
+```json
+{ "poolDefinition": {
+  "id": "<poolDefinitionId>",
+  "programDefinitionIds": ["<programDefinitionId>"],
+  "namespace": "@wix/pricing-plans",
+  "details": { "benefits": [
+    { "benefitKey": "<RANDOM_UUID>", "itemSetId": "<itemSetId>", "providerAppId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97", "price": "0" }
+  ] }
+} }
+```
+
+- **`benefitKey`** is a **freshly generated random UUID** you supply (any v4 UUID).
+- **`providerAppId`** is the **Bookings** app def id `13d21c63-b5ec-5912-8397-c3a5ddb27a97` (the same GUID used as the bookings app id in the cart/frontend recipes). It is **not** the Pricing Plans id.
+- **`price`** is credit-model, not money: **`"0"` = unlimited** sessions covered (leave `creditConfiguration` empty — the "unlimited membership" case, the default here); **`"1"` = limited credits**, which then requires a `details.creditConfiguration` (e.g. `{ "amount": "10" }` for a 10-session pack). Default to **`"0"` (unlimited)** unless the request names a session count.
+- **⚠️ Limited-credit plan (`price:"1"`): `creditConfiguration` goes at `details.creditConfiguration` — a SIBLING of `benefits[]`, NOT a field inside a benefit.** Nesting it inside the benefit makes the server treat the credit pool as "not set up" and reject the non-zero price with `400 "Price should be 0 when credit pool is not set up"`. The correct `details` shape for a limited pack (e.g. an 8-class pass):
+  ```json
+  "details": {
+    "creditConfiguration": { "amount": "8" },
+    "benefits": [
+      { "benefitKey": "<RANDOM_UUID>", "displayName": "Bookings sessions",
+        "providerAppId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97", "price": "1" }
+    ]
+  }
+  ```
+  (The unlimited case above keeps `price:"0"` and **no** `creditConfiguration`.)
+- **One pool definition per integrating app** — for a plan covering bookings, that's exactly one pool with one benefit. Don't create a second pool for the same app on the same plan.
+- **`itemSetId` path is `poolDefinition.details.benefits[i].itemSetId`** — pick the entry whose `benefitKey` matches the one you sent.
+
+#### STEP 2c: Bulk-create the benefit items (one per covered service)
+
+Attach the actual bookings services to the benefit — **one item per service** — via bulk create:
+
+```bash
+curl -X POST 'https://www.wixapis.com/benefit-programs/v1/bulk/items/create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "items": [
+      {
+        "namespace": "@wix/pricing-plans",
+        "category": "",
+        "providerAppId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
+        "itemSetId": "<itemSetId FROM 2b>",
+        "externalId": "<BOOKINGS_SERVICE_ID>"
+      }
+    ],
+    "returnEntity": true
+  }'
+```
+
+Response — standard bulk shape; each covered service lands under `results[].itemMetadata` (and `results[].item` because `returnEntity: true`):
+
+```json
+{ "results": [
+  { "itemMetadata": { "id": "<benefitItemId>", "originalIndex": 0, "success": true },
+    "item": { "id": "<benefitItemId>", "externalId": "<BOOKINGS_SERVICE_ID>", "itemSetId": "<itemSetId>" } }
+], "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0 } }
+```
+
+- **`externalId` is the bookings SERVICE id** (`item.id` from `setup-bookings.md` STEP 3) — one item per service the plan should cover. Up to **100** items per call.
+- **`category` is an empty string `""`**, and **`namespace`/`providerAppId`** repeat the STEP-2b values on every item.
+- **The public path is `POST …/benefit-programs/v1/bulk/items/create`.** Some docs examples show a bare `…/bulk/items`; ignore that and use the `/bulk/items/create` form shown here.
+- **Check `results[].itemMetadata.success` per item** (`false` populates `.error`); retry only the failed items **once** with the same format.
+
+Keep the linkage in the seed map so the coding handoff can reason about coverage: `seeded.pricing-plans.bookingsCoverage = { <planId>: { itemSetId, serviceIds: [ … ] } }`.
+
+---
+
+## Conclusion
+Following these steps **in order** sets up a Plans V3 Wix Pricing Plans site (and, when bookings is present, the membership integration):
+- Each plan is created **`visibility: PUBLIC` + `buyable: true`** with pricing under **`pricingVariants[].billingTerms` + `pricingStrategies[].flatRate.amount`** (decimal **strings**), the cycle (`MONTH`/`1` by default) and type (recurring / one-time / free) chosen from the request; currency is site-derived, `perks` are display-only.
+- **Bookings coverage is wired through the Benefit Programs API**, not the plan object: **read** the auto-created program definition (`programDefinition.id`) → create **one** pool definition with one benefit whose `providerAppId` is the **Bookings** app id (`price:"0"` = unlimited) → bulk-create **items** whose `externalId` is each covered **bookings service id**. This is **skipped** when bookings isn't in the run.
+- IDs kept for the coding handoff: `planIds[]`, and (integration) per plan `{ itemSetId, covered serviceIds[] }`.

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

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