@wix/agent-skills 1.14.0 → 1.15.0

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

@@ -0,0 +1,153 @@
+---
+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.
+
+> **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. Remove them **before** creating yours, so the site shows only your content. Do this **first** — cleaning before you create guarantees the ids you delete are the install's samples, never your own.
+
+**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-orders.md

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