@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,214 +0,0 @@
----
-name: "Setup Online Store"
-description: Initializes a Stores catalog with Catalog V3 — cleans default sample products, then bulk-creates products with options/variants/inventory (visible), and creates + assigns categories. Specifies the *how* (calls + format); counts and the specific products/categories come from the request being fulfilled.
----
-**RECIPE**: Business Recipe – Initial Setup for a Wix Online Store (Catalog V3)
-
-> **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 preparing any new Wix site that uses the Online Stores app with Catalog V3.
-**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial catalog setup.
-
-> **This recipe is the *how*, not the *what*.** What to seed — how many products, which are in/out of stock, which categories — 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 items to create.
-
-> **API surfaces:** products use Catalog V3 (`https://www.wixapis.com/stores/v3/...`). The Categories API is the exception — it lives on a `v1` endpoint (`https://www.wixapis.com/categories/v1/categories`). Don't mix in any pre-V3 product endpoints.
-
----
-
-## Article: Steps for Setting Up a Wix Online Store
-**YOU MUST** complete the following steps **in the given order** (1-4) and **without requiring additional user input**. One conditional: **the category steps (3-4) run only when the request names categories** — if `intent.stores.categoriesNamed` is empty, **create none** (skill policy, per `SEED.md` § "What to seed per capability") and skip the category steps. Products (steps 1-2) always run; the **Attach images** step runs last, only when `imagery` is on.
-
-**⚠️ CRITICAL ORDER REQUIREMENT: Do the product operations FIRST (clean + create, Steps 1-2), then categories (Steps 3-4). Categories API might take some time to be fully available after Stores installation, so always finish products before attempting category operations.**
-
-### STEP 1: Clean the store — remove the default sample products
-
-A freshly provisioned Wix Stores app comes pre-seeded with demo/sample products. **Only remove products that are obviously the install's own demo/sample data on a fresh install.** Do **not** assume the existing products are samples: the site may already hold the owner's **real catalog** (a connect/iterate run, or an owner-populated store). If what's there isn't obviously install demo data, or you're unsure, **do not delete it — ask the user first** (`SEED.md`: seeding is additive; deleting real content needs the owner's approval). When they clearly are the install's samples, remove them **before** creating yours so the storefront shows only the intended catalog.
-
-1. **List the existing products** — `POST https://www.wixapis.com/stores/v3/products/query` with body `{"query": {"paging": {"limit": 50}}}`. Collect every `product.id` from the response.
-2. **Bulk-delete them in one call** — `POST https://www.wixapis.com/stores/v3/bulk/products/delete` with body `{"productIds": ["<id1>", "<id2>", …]}` (the ids from step 1; up to 100 per call). On a fresh install the query returns only the install's sample products — delete those. **If it returns anything that could be the owner's real catalog, stop and ask first** (above).
-
-### STEP 2: Bulk-create the products (with options)
-
-Create the products in a **single bulk request** to `POST https://www.wixapis.com/stores/v3/bulk/products-with-inventory/create`. **How many products, and which are in or out of stock, are set by the request you're fulfilling — this step only gives the call and the required format.** Each product needs a real web image URL relevant to it, and `price` via `actualPrice` (+ optional `compareAtPrice`).
-
-**First decide each product's type by what the buyer receives:** shipped → `PHYSICAL` (the JSON below); a file the buyer downloads and keeps → `DIGITAL` (the digital block below — carries a file, no `quantity`). *Access* — a membership or an online course/program the buyer enrolls in — is **Pricing Plans**, not a Stores product.
-
-**⚠️ CRITICAL: PRODUCT & VARIANT VISIBILITY — set `"visible": true` explicitly.**
-Storefront product queries (`searchProducts` / `queryProducts`) return **only visible products** to site visitors. A product created without `"visible": true` is created successfully but will **NOT appear** on the live site — the catalog looks empty. So:
-- Set `"visible": true` on **every product** (product level).
-- Set `"visible": true` on **every variant**. A variant with `inventoryItem.quantity > 0` is buyable; a variant that should be out-of-stock stays `"visible": true` with `"quantity": 0`.
-- Never rely on a default — always include `visible`.
-
-**Request body shape** (one representative product shown — repeat product objects inside the `products` array):
-
-```json
-{
-  "products": [
-    {
-      "name": "Pro Basketball Sneaker",
-      "productType": "PHYSICAL",
-      "physicalProperties": {},
-      "visible": true,
-      "visibleInPos": true,
-      "description": {
-        "nodes": [
-          {
-            "type": "PARAGRAPH",
-            "id": "desc1",
-            "nodes": [{ "type": "TEXT", "textData": { "text": "High-performance basketball sneaker with superior ankle support." } }],
-            "paragraphData": { "textStyle": { "textAlignment": "AUTO" } }
-          }
-        ],
-        "metadata": { "version": 1, "id": "basketball-desc-001" }
-      },
-      "options": [
-        {
-          "name": "Size",
-          "optionRenderType": "TEXT_CHOICES",
-          "choicesSettings": { "choices": [ { "choiceType": "CHOICE_TEXT", "name": "8" }, { "choiceType": "CHOICE_TEXT", "name": "9" } ] }
-        },
-        {
-          "name": "Color",
-          "optionRenderType": "SWATCH_CHOICES",
-          "choicesSettings": { "choices": [ { "choiceType": "ONE_COLOR", "name": "Red", "colorCode": "#FF0000" }, { "choiceType": "ONE_COLOR", "name": "Blue", "colorCode": "#0000FF" } ] }
-        }
-      ],
-      "variantsInfo": {
-        "variants": [
-          {
-            "choices": [
-              { "optionChoiceNames": { "optionName": "Size", "choiceName": "8", "renderType": "TEXT_CHOICES" } },
-              { "optionChoiceNames": { "optionName": "Color", "choiceName": "Red", "renderType": "SWATCH_CHOICES" } }
-            ],
-            "price": { "actualPrice": { "amount": "159.99" }, "compareAtPrice": { "amount": "200.00" } },
-            "visible": true,
-            "inventoryItem": { "quantity": 25, "preorderInfo": { "enabled": false } },
-            "physicalProperties": {}
-          }
-        ]
-      }
-    }
-  ],
-  "returnEntity": true
-}
-```
-
-**⚠️ CRITICAL FORMAT REQUIREMENTS:**
-- **Description MUST be rich-text nodes**, not a plain string — a plain string causes an `"Expected an object"` error. Use the `{ "nodes": [...], "metadata": {...} }` shape shown.
-- **Media — gated by the `imagery` policy (`SEED.md` § "Entity images"), no exception for stores.** **Always create products text-only here** — omit `media`. When `imagery` is **on**, the **Attach images** step below writes generated brand images in a second pass; it does **not** happen at create time.
-- **Choose the product type from what the buyer receives:** a shipped item is `PHYSICAL` (default); a downloadable file they keep — ebook, PDF, template, preset pack, track, downloadable video — is `DIGITAL`. Selling *access* rather than a file — a membership, subscription, or an online course/program the buyer enrolls in — is **Pricing Plans**, not a Stores product.
-- **Physical products MUST set `"productType": "PHYSICAL"` and an empty `"physicalProperties": {}`** (on the product and on each variant).
-- **Digital products (`"productType": "DIGITAL"`) drop `physicalProperties` and are sellable only when each variant carries both a file and stock** — miss either and the product is created fine, reads back `visible: true`, and is rejected at add-to-cart. Upload the file first (`POST /site-media/v1/files/generate-upload-url` → `PUT` the bytes → `file.id`):
-
-  ```json
-  { "productType": "DIGITAL", "visible": true,
-    "variantsInfo": { "variants": [ {
-      "price": { "actualPrice": { "amount": "12.00" } }, "visible": true,
-      "inventoryItem": { "inStock": true },
-      "digitalProperties": { "digitalFile": { "id": "<file.id>" } }
-    } ] } }
-  ```
-- **Options:** text options use `"optionRenderType": "TEXT_CHOICES"` + `"choiceType": "CHOICE_TEXT"`; color options use `"optionRenderType": "SWATCH_CHOICES"` + `"choiceType": "ONE_COLOR"` + a `colorCode`.
-- **Variants = the full Cartesian product** of all option choices; each variant references **all** options via `optionChoiceNames`, sets `price.actualPrice.amount` (+ optional `compareAtPrice.amount`) as **strings**, and `inventoryItem.quantity`.
-- If part of the bulk request fails, retry the failed products **once** with the exact same format; do not loop.
-
-**⚠️ CRITICAL: options/variants are for things the buyer *selects and buys* — not for attributes you only filter or display by.** Make something an `option` (and thus a variant) **only if the buyer picks it to purchase a distinct SKU** (Size, Color, Format). An attribute you merely **filter, badge, or display by** — roast level, material, genre, "new arrival" — is **not** a variant: encode it in the **product name**, its **category**, or `description`, and never as an option. Modeling a display-only attribute as an option multiplies the variant Cartesian product for nothing (slower seeding, larger payload) and produces a buyer-facing selector that shouldn't exist. (A single-variant product is fine — give it one variant with no options.) **Default cardinality — keep it small:** unless the request names specific options, give each product **at most one option with ≤3 choices** (≤3 variants); many products legitimately have **none** (a single variant). This is a floor, not a cap — honor a larger/explicit option set when intent names one. The two-option example above shows the multi-option *format*; it is not the default shape to reach for.
-
-**⚠️ Reading the response — created products are under `productResults.results[]`, NOT a top-level `results`.** A successful bulk create returns `200` with this shape:
-
-```json
-{ "productResults": { "results": [
-  { "itemMetadata": { "id": "<productId>", "originalIndex": 0, "success": true },
-    "item": { "id": "<productId>", "slug": "<slug>", "name": "…", "visible": true, … } }
-] } }
-```
-
-Read each product's **`id`** (→ the `catalogItemId` you'll assign to categories in STEP 4 and the frontend will use) and **`slug`** from `productResults.results[].item`. There is **no** top-level `results` key — reading `response.results` finds nothing and makes a successful create look like it returned zero products. Check `productResults.results` first; **do not re-create on an empty top-level `results`**.
-
-### STEP 3: Create the store's categories
-
-Create the categories for the store — **the categories that fit the user's request.** Which categories (and how many) are set by the request you're fulfilling; this step only gives the call and format.
-
-Use the **Create Category** endpoint: `POST https://www.wixapis.com/categories/v1/categories`. **There is no bulk-create endpoint for `/categories/v1/`** (the `events/v1/bulk/categories/create` URL is for the Events product, not Stores).
-
-**⚠️ CRITICAL: create the categories SEQUENTIALLY — one call at a time, never concurrently.** Every category lives in the single shared `@wix/stores` category tree, which carries **one revision**. Firing the creates concurrently makes them race on that revision: all but one fail with `409 INVALID_REVISION` ("Outdated revision for entity id @wix/stores"), and the failed-then-retried calls can leave **duplicate categories** behind. So issue each create, wait for its response, then issue the next. (There are only a handful of categories — the serial cost is negligible.)
-
-The request body must include a top-level `treeReference` field — it must **not** be nested inside the `category` object:
-
-```json
-{
-  "category": {
-    "name": "Drinkware",
-    "description": "The Drinkware category includes a wide range of containers designed for holding beverages",
-    "visible": true
-  },
-  "treeReference": {
-    "appNamespace": "@wix/stores",
-    "treeKey": null
-  }
-}
-```
-
-### STEP 4: Add Each Product to a Category
-
-Add each product to the category it belongs to (per the request you're fulfilling). Acquire the product ids (from STEP 2's response) first. Use the **Bulk Add Items To Category** endpoint — products are the `items`: `POST https://www.wixapis.com/categories/v1/bulk/categories/{categoryId}/add-items` (one call per `categoryId` — the path parameter is single).
-
-**Issue these add-items calls SEQUENTIALLY too** — one call at a time, waiting for each response before the next. They mutate the same shared `@wix/stores` tree as the creates above, so concurrent calls risk the same `409 INVALID_REVISION` race. Serial is the safe, deterministic choice (the category count is small).
-
-The request body is `items` (each with the product's `catalogItemId` and the Stores `appId`) plus a `treeReference` at the **same level** as `items` (not nested):
-
-```json
-{
-  "items": [
-    { "catalogItemId": "<productId>", "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e" }
-  ],
-  "treeReference": {
-    "appNamespace": "@wix/stores",
-    "treeKey": null
-  }
-}
-```
-
-### Attach images (imagery ON only — skip otherwise)
-
-**Only when `imagery` is on** (`SEED.md` § "Entity images"). Products were created text-only above; this pass-2 step writes a generated brand image onto each. Generate + import per `references/IMAGE_GENERATION.md`, keep each image's `url`.
-
-**Attach every product in ONE call** — `POST https://www.wixapis.com/stores/v3/bulk/products/update` (up to 100 products). You already hold each product's `id` **and `revision`** from STEP 2's bulk-create response (`productResults.results[].item`), so **no per-product `GET` is needed**. Each entry nests under a `product` wrapper carrying just `id`, `revision`, and `media` — options, variants, and every other field are left untouched (it's a partial update):
-
-```json
-{
-  "products": [
-    { "product": {
-        "id": "<product id>",
-        "revision": "<from the create response>",
-        "media": { "itemsInfo": { "items": [ { "url": "<static.wixstatic.com/… or Wix Media id>", "altText": "…" } ] } }
-    } }
-  ]
-}
-```
-
-- **`revision` is required on every entry** — omitting it fails `400 "revision must not be empty"`. Use the revision from the create response (or a fresh query); a stale one fails the optimistic-concurrency check.
-- **Everything nests under `product`** — `id` / `revision` / `media` at the entry root fails validation. **Send no field mask** (the validator runs before masking → `428`).
-- **Write the image via `media.itemsInfo.items`**; the server derives `media.main` from it. One primary image per product (a larger gallery is out of scope for the seed). The image may be referenced by a `static.wixstatic.com` **`url`** or by its Wix Media **`id`** (`<hash>~mv2.png`) — either works.
-- **Success shape** — `bulkActionMetadata` totals the run, and each result carries an `itemMetadata`:
-
-  ```jsonc
-  {
-    "results": [ { "itemMetadata": { "id": "<product id>", "originalIndex": 0, "success": true } } ],
-    "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0, "undetailedFailures": 0 }
-  }
-  ```
-  Read `itemMetadata.success` per product (the result carries no product body). **Retry only the failed ids once**, then move on.
-- **Confirm by requery** — `POST …/stores/v3/products/query` with `"fields": ["MEDIA_ITEMS_INFO"]`; the attached image is at `media.main.image.url`. Wix **re-hosts** the image on attach, so that URL is a **new** `wixstatic.com` id — verify it's *a* wixstatic URL, never string-equality against the one you sent. The read-back can lag a beat; one empty read right after success isn't a failure.
-- **Never block on image failure** — a product that won't attach stays text-only.
-
-**One-off fix (single product).** To (re)attach a single image later, `PATCH https://www.wixapis.com/stores/v3/products/{id}` with the same `{ "product": { "id", "revision", "media": {…} } }` body — same rules apply (revision required, no field mask, media-only is a partial update that leaves options/variants intact). Read the current `revision` from `GET …/products/{id}` → `response.product.revision` (the GET is not flat); the `200` response carries the image at `media.main.url`.
-
----
-
-## Conclusion
-Following these steps **in order** sets up a new V3 Wix Online Store site:
-- Starts from a **clean catalog** — the install's default sample products are removed first.
-- Contains the products and categories called for by the request, all created **`visible: true`** so they appear on the live site.
-- Each product is connected to the category it belongs to.
-- All products follow the correct Catalog V3 API format specified in STEP 2.

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

@@ -1,155 +0,0 @@
----
-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

@@ -1,229 +0,0 @@
----
-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[] }`.