@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,232 +0,0 @@
----
-name: "Setup Bookings"
-description: Initializes a Wix Bookings backend with Services V2 — resolves a staff resource + a category, then creates bookable services (APPOINTMENT/CLASS) with duration, price, and online booking enabled, and schedules sessions for classes. Specifies the *how* (calls + format); counts and the specific services/durations/prices come from the request.
----
-**RECIPE**: Business Recipe – Initial Setup for Wix Bookings (Services V2)
-
-> **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 Bookings** app installed into a populated catalog of bookable services.
-**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial Bookings backend setup. (The frontend read/booking contract is the sibling recipe `how-to-code-bookings.md`.)
-
-> **This recipe is the *how*, not the *what*.** What to seed — how many services, which are appointments vs classes, their durations and prices, whether there are named categories or multiple staff — 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 services to create.
-
-> **API surfaces:** services use **Services V2** on the **public** host `https://www.wixapis.com/bookings/v2/...`. The method page's schema header shows an internal `…/_api/bookings/v2/services` form — **do not use that**; call the public `…/bookings/v2/services` form shown below. Staff members are a **V1** API (`…/bookings/v1/staff-members`). Class sessions are **Calendar Events V3** (`…/calendar/v3/events`) — a different API from Bookings. The Wix Bookings **app id** (needed only by the frontend, kept here for reference) is `13d21c63-b5ec-5912-8397-c3a5ddb27a97`.
-
----
-
-## Article: Steps for Setting Up Wix Bookings
-**YOU MUST** complete the following steps **in the given order** (1-4) without skipping any and **without requiring additional user input**. The **Attach images** step runs **only when imagery is on** — skip it entirely otherwise.
-
-**⚠️ CRITICAL ORDER REQUIREMENT: resolve a staff resource (STEP 1) and a category (STEP 2) BEFORE creating services (STEP 3).** An APPOINTMENT service is rejected (`MISSING_APPOINTMENT_RESOURCES`) unless `staffMemberIds` is non-empty, and **any service without a `category.id` is invisible on the live site** (see STEP 3). For CLASS services, sessions are created **after** the service (STEP 4) because they need the service's returned `schedule.id`.
-
-**Check for pre-existing services first.** A freshly provisioned Wix Bookings app may ship demo/sample services (e.g. "Sample service" rows) that would otherwise appear in the live storefront alongside yours — so before STEP 1, check and clean up only if needed:
-1. **List** — `POST https://www.wixapis.com/bookings/v2/services/query` `<AUTH>` with body `{"query": {"paging": {"limit": 100}}}`; collect every `service.id`.
-2. **If any come back, delete them** — `DELETE https://www.wixapis.com/bookings/v2/services/<serviceId>` `<AUTH>` for each. If the list is empty, there's nothing to clean — move on.
-
-Clean the install's **own demo services** yourself via the API — that's part of this setup, so don't leave obvious sample services in place or push that work onto the user. But do **not** assume every existing service is a sample: the site may already hold the owner's **real services** (a connect/iterate run, or an owner-populated site). If what's there isn't obviously the install's demo data, or you're unsure, **do not delete it — ask the user first** (`SEED.md`: seeding is additive; deleting real content needs the owner's approval). When they clearly are install samples, delete them before creating yours. (The default **"Business Owner" staff resource** is a resource, **not** a service — leave it; you reuse it in STEP 1.)
-
-### STEP 1: Resolve a staff resource (REQUIRED for APPOINTMENT)
-
-An APPOINTMENT service needs at least one **resource** in `staffMemberIds`; an empty array is rejected with `MISSING_APPOINTMENT_RESOURCES` (*"service of type appointment requires at least one staff member or service resource"*). CLASS services do **not** need this.
-
-**Query the existing staff** to get a `resourceId` — a fresh install always has a default **Business Owner** resource:
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v1/staff-members/query' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "query": {}, "fields": ["RESOURCE_DETAILS"] }'
-```
-
-**⚠️ CRITICAL: `staffMemberIds` takes the `resourceId`, NOT the staff `id`.** Read `staffMember.resourceId` from the response (it's a different GUID from `staffMember.id`). Using `staffMember.id` is the most common cause of "service has no provider" at runtime. Keep the `resourceId` (and `staffMember.id` + `name`) of every staff you'll use.
-
-**When the request wants named staff** (e.g. a salon with multiple stylists — derived from the request, not invented), create them first, then use their `resourceId`s:
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v1/staff-members' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "staffMember": { "name": "<First Last>", "description": "<short brand-appropriate bio>" } }'
-```
-
-- **⚠️ Do NOT send `"email": ""` or `"phone": ""`** — V1 format-validates them and rejects empty strings (`is not a valid email/phone`). **Omit the keys** unless you have a real value.
-- **Do NOT configure custom working hours during seed.** New staff inherit the business working hours at creation time — that's enough for an initial build; the merchant sets custom hours from the dashboard. (The two-step custom-hours flow — `assignWorkingHoursSchedule` + `WORKING_HOURS` events — is fragile and out of scope here.)
-- If the query returns **"Business schedule not found"**, the Bookings app isn't installed/provisioned — **fail loudly** with the response verbatim; do not try to install it.
-
-### STEP 2: Resolve (or create) a category
-
-**⚠️ CRITICAL: every service needs a `category.id` or it is NOT visible on the live site.** This is the Bookings analog of the Stores `visible:true` trap — a service created without a category is created successfully but hidden. **A fresh Bookings install ships ZERO categories**, so you **must create at least one** and assign it to every service. Do **not** assume a default "Our Services" category exists to reuse — it does not.
-
-**Query existing categories first** (to reuse one if a prior step in this run already created it):
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v2/categories/query' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "query": {} }'
-```
-
-On a fresh site this returns `count: 0`. **Create a category** — one is enough (name it "Our Services" or something brand-appropriate). Create *additional* named categories only when the request wants grouping/filtering (the frontend shows a category bar only when more than one category exists). One call per category (they're independent — no shared revision, unlike Stores categories):
-
-```bash
-curl -X POST 'https://www.wixapis.com/bookings/v2/categories' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "category": { "name": "Our Services" } }'
-```
-
-The response is `{ "category": { "id": "<categoryId>", … } }` — keep each `id`. A service belongs to **one** category; when you create several, distribute services across them so the filter is meaningful.
-
-### STEP 3: Create the services
-
-Create **all the services in a single bulk call** against the **public** endpoint `POST https://www.wixapis.com/bookings/v2/bulk/services/create` (up to **100** services per call — `services[]`). **How many services, their types, durations, and prices come from the request you're fulfilling** — this step only gives the call and the required format. (A single-service `POST …/bookings/v2/services` with a top-level `service` object also exists, but prefer the bundled bulk call.)
-
-**⚠️ CRITICAL: the V2 service payload is FLAT — name/description/tagLine are top-level on each service object, NOT nested under `info`.** The V1 `info.name`/`info.description` shape is rejected by V2. Price uses `value` (a **string**), not `amount`.
-
-**Request body shape** (one paid 60-minute APPOINTMENT shown — repeat service objects inside the `services` array; APPOINTMENT and CLASS may be mixed in one call):
-
-```json
-{
-  "services": [
-    {
-      "type": "APPOINTMENT",
-      "name": "Consultation",
-      "description": "A brand-appropriate description of the service.",
-      "tagLine": "Short tagline",
-      "defaultCapacity": 1,
-      "onlineBooking": { "enabled": true, "requireManualApproval": false, "allowMultipleRequests": false },
-      "schedule": { "availabilityConstraints": { "sessionDurations": [60] } },
-      "payment": {
-        "rateType": "FIXED",
-        "fixed": { "price": { "value": "75.00", "currency": "USD" } },
-        "options": { "online": true, "inPerson": false }
-      },
-      "category": { "id": "<CATEGORY_ID_FROM_STEP_2>" },
-      "locations": [ { "type": "BUSINESS" } ],
-      "staffMemberIds": ["<RESOURCE_ID_FROM_STEP_1>"]
-    }
-  ],
-  "returnEntity": true
-}
-```
-
-**⚠️ CRITICAL FORMAT REQUIREMENTS:**
-- **`category.id` is mandatory for visibility** (STEP 2). Assign one to every service.
-- **`onlineBooking: { "enabled": true }` is required** for all services — V2 rejects the create without it, even though it reads as optional.
-- **`defaultCapacity` is required for ALL types** — `1` for APPOINTMENT; the max participants for CLASS (e.g. `20`).
-- **`payment.options` — at least one of `online`/`inPerson` must be `true`** (see the validation table below). This holds even for **free** services.
-- **`schedule.availabilityConstraints.sessionDurations`** — required for **APPOINTMENT only** (an array with one integer in minutes). Do **not** send it for CLASS/COURSE.
-- **`staffMemberIds`** — required and **non-empty for APPOINTMENT** (pass the `resourceId`(s) from STEP 1; the default Business-Owner `resourceId` when the request names no staff). **Ignored for CLASS/COURSE** — omit it.
-- **`locations[].type`** — use **`"BUSINESS"`**, never `"OWNER_BUSINESS"` (the services endpoint rejects it; `OWNER_BUSINESS` is valid only on `createBooking`'s slot location — same field name, different enum).
-- **Currency** — the **site's business currency wins**: a EUR-locale site stores `EUR` even if you send `USD`. This is not an error; don't fight it (the frontend formats from the returned `currency`).
-- **Imagery is opt-in** (`SEED.md` § "Entity images"). Seed **text-only** by default — omit `media` here. When imagery is on, attach the image in the dedicated pass-2 **Attach images** step after the service exists.
-
-**Payment-options validation** (rejecting combos return `INVALID_PAYMENT_OPTIONS`):
-
-| `rateType` | `options.online` | `options.inPerson` | Valid? |
-|---|---|---|---|
-| FIXED / VARIED | true | false / true | ✓ |
-| FIXED / VARIED | false | true | ✓ |
-| **NO_FEE** (free) | **false** | **true** | ✓ |
-| NO_FEE (free) | true | — | ✗ — online is only for FIXED/VARIED |
-| any | false | false | ✗ — at least one must be true |
-
-A **free** service therefore omits `fixed` and uses `"rateType": "NO_FEE"`, `"options": { "online": false, "inPerson": true }`.
-
-**⚠️ Reading the response — created services are under `results[]`, each as `results[].item` with per-item `results[].itemMetadata`.** A successful bulk create returns `200` with:
-
-```json
-{ "results": [
-  {
-    "itemMetadata": { "id": "<serviceId>", "originalIndex": 0, "success": true },
-    "item": {
-      "id": "<serviceId>",
-      "name": "…",
-      "type": "APPOINTMENT",
-      "mainSlug": { "name": "<url-slug>", "custom": false },
-      "schedule": { "id": "<scheduleId>", "availabilityConstraints": { … } },
-      "payment": { … }
-    }
-  }
-], "bulkActionMetadata": { "totalSuccesses": 1, "totalFailures": 0 } }
-```
-
-(`item` is present only because you sent `"returnEntity": true`.) Keep each service's **`item.id`**, **`item.mainSlug.name`** (the frontend links by slug — if absent, derive it from the name: lowercase, non-alphanumerics → hyphens, dedupe), and — for CLASS — **`item.schedule.id`** (needed for STEP 4). **Check `itemMetadata.success` per item** (`false` populates `itemMetadata.error`); retry only the **failed** services **once** with the exact same format — do not loop, and don't re-create the ones that already succeeded.
-
-**Service modeling judgment** (the *what* still comes from the request, but model it correctly):
-- **APPOINTMENT** = a customer picks a time (1-on-1: consults, haircuts, treatments). Availability comes from staff working hours — no extra step.
-- **CLASS** = a recurring group session many customers book (yoga, workshops). Needs `defaultCapacity` and **scheduled sessions** (STEP 4) or its calendar is permanently empty.
-- **COURSE** is out of scope for a basic seed (it requires booking + calendar events + whole-course enrollment) — use CLASS for group offerings unless the request explicitly needs fixed multi-session courses.
-
-### STEP 4: Schedule sessions for CLASS services (CLASS only — skip for APPOINTMENT)
-
-Creating a CLASS service does **not** create any bookable sessions; the frontend lists sessions via `eventTimeSlots`, which returns scheduled **session events**. A freshly created CLASS has none — its calendar is a dead end until you add sessions. Sessions are **Calendar Events V3**, created from each CLASS's returned `schedule.id`. Create **all sessions across all classes in a single bulk call** to `POST https://www.wixapis.com/calendar/v3/bulk/events/create` (a few upcoming sessions per class, e.g. 3 over the next ~2 weeks):
-
-```json
-{
-  "events": [
-    {
-      "event": {
-        "scheduleId": "<item.schedule.id of a CLASS FROM STEP 3>",
-        "type": "CLASS",
-        "start": { "localDate": "<FUTURE_DATE>T09:00:00" },
-        "end":   { "localDate": "<FUTURE_DATE>T10:00:00" },
-        "resources": [ { "id": "<RESOURCE_ID_FROM_STEP_1>", "permissionRole": "WRITER" } ],
-        "totalCapacity": 12
-      }
-    }
-  ]
-}
-```
-
-**⚠️ CRITICAL: each element of `events` MUST be wrapped in `{ "event": { … } }`** — a bare event object is rejected. Other requirements:
-- **`resources` must be non-empty** for a CLASS event (a session with no resource is rejected), and **`resources[].permissionRole` must be `"WRITER"`** (or `"COMMENTER"`) — omitting it defaults to `UNKNOWN_ROLE` → `400 "resources.permissionRole must not be UNKNOWN_ROLE"`. Use the same `resourceId` from STEP 1.
-- **`start`/`end` use `{ "localDate": "YYYY-MM-DDThh:mm:ss" }`** — local time, **no `Z`** (seconds ignored). Use **today-or-future** dates.
-- One bulk call can mix sessions for **different classes** — each event carries its own `scheduleId`. The response is the standard bulk shape (`results[]` with per-item `itemMetadata.success` + a `bulkActionMetadata` tally); retry only failed events once.
-- For a recurring weekly schedule instead of one-off sessions, add `event.recurrenceRule` (`{ "frequency": "WEEKLY", "interval": 1, "days": ["MONDAY"], "until": { "localDate": "…" } }`) — only `WEEKLY` and a **single** day per rule are supported. One-off sessions are simpler and sufficient for a seed.
-- `totalCapacity` defaults to the schedule's `defaultCapacity` if omitted; set it explicitly to the class size.
-
-Keep each session's event id — it's `results[].itemMetadata.id` (the events bulk sends no `returnEntity`, so there is **no `item`** in its response, only `itemMetadata`) — under `seeded.services[].sessionEventIds` if the frontend will deep-link. If STEP 4 is skipped or fails, record a `notes` entry so it's surfaced: *"CLASS sessions not scheduled — add session times in the Bookings dashboard before sign-up works."*
-
-### Attach images (imagery ON only — skip otherwise)
-
-**Only when `imagery` is on** (`SEED.md` § "Entity images"). This is the bookings entry in the required pass-2 "attach the image to the entity" flow — the service was created text-only in STEP 3; now write the image onto it. Obtain the image per `references/IMAGE_GENERATION.md` (generate + import, or import an existing URL) → keep `file.url` and its `file.id`, then patch the service.
-
-**The image is written under `media.mainMedia` and `media.coverMedia`, each `{ "image": { "id", "url", "width", "height" } }`.** Per the Services V2 reference (`references/bookings/create-and-update-booking-services.md`): `media.mainMedia` is shown in the services list, `media.coverMedia` on the service page, and `media.items[]` is the service-page gallery. The binding field is the image **`id`** (the Wix Media file id); `url` and dimensions are descriptive. Write shape:
-
-```json
-{
-  "service": {
-    "id": "<serviceId>",
-    "revision": "<current revision>",
-    "media": {
-      "mainMedia":  { "image": { "id": "<file.id>", "url": "<file.url>", "width": 1024, "height": 1024 } },
-      "coverMedia": { "image": { "id": "<file.id>", "url": "<file.url>", "width": 1024, "height": 1024 } }
-    }
-  }
-}
-```
-
-```bash
-# GET the service first for its current revision (a stale/omitted revision → conflict):
-curl -X PATCH 'https://www.wixapis.com/bookings/v2/services/<serviceId>' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{ "service": { "id": "<serviceId>", "revision": "<current revision>", "media": { "mainMedia": { "image": { "id": "<file.id>", "url": "<file.url>", "width": 1024, "height": 1024 } }, "coverMedia": { "image": { "id": "<file.id>", "url": "<file.url>", "width": 1024, "height": 1024 } } } } }'
-```
-
-- **Fetch the current `revision` first** (`GET https://www.wixapis.com/bookings/v2/services/<serviceId>`, or reuse the `item.revision` from STEP 3's `returnEntity` response) and echo it back — a services V2 update is revision-checked.
-- **⚠️ Writing the image under `media.image` (an `image` object directly under `media`) returns `HTTP 200` but silently drops it — the `revision` increments and no image lands.** Because the failure is a silent `200`, not a `400`, a successful status code is **not** on its own proof the image attached: **confirm by re-querying the service** (`GET …/bookings/v2/services/<serviceId>`) and checking `media.mainMedia` is populated.
-- **Never block on image failure** (`SEED.md` § "Entity images" / IMAGE_GENERATION "Credits, cost & the not-generating fallback") — on failure, skip and leave the service text-only.
-
----
-
-## Conclusion
-Following these steps **in order** sets up a new Services V2 Wix Bookings site:
-- Every service is assigned a **`category.id`** so it appears on the live site (the visibility invariant) — a fresh install has **no** categories, so at least one is **created** (extra named categories only when the request wants a filter).
-- Every APPOINTMENT carries a non-empty **`staffMemberIds`** of staff **`resourceId`** values (the default Business-Owner resource when no staff are named), so it isn't rejected with `MISSING_APPOINTMENT_RESOURCES`.
-- Services use the correct **flat Services V2** shape on the **public** host, with `onlineBooking.enabled`, `defaultCapacity`, a valid `payment.options` combo, and `sessionDurations` for appointments.
-- Every CLASS has scheduled **Calendar Events V3** sessions, so its calendar is bookable rather than empty.
-- **When imagery is on**, each service's image is attached by the **Attach images** step (pass-2) via `PATCH …/services/{id}` under `media.mainMedia`/`media.coverMedia` (each `{ image: { id, url, width, height } }`), revision-checked and confirmed with a follow-up query — writing under `media.image` returns `200` but silently drops the image; on failure the service stays text-only.
-- IDs kept for the coding handoff: `serviceIds[]`, service `slug`s (`mainSlug.name`), staff `resourceId`s, category ids, and CLASS `sessionEventIds`.

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

@@ -1,200 +0,0 @@
----
-name: "Setup CMS"
-description: Initializes a Wix CMS (Wix Data) backend — creates each collection with a public-read permissions block and the field schema, then bulk-inserts items (real field values) and verifies they persisted; wires multi-reference links when collections relate. Specifies the *how* (calls + format); which collections, fields, and counts come from the request.
----
-**RECIPE**: Business Recipe – Initial Setup for Wix CMS (Wix Data v2)
-
-> **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 **Wix CMS** (Wix Data) to hold content collections (team directory, FAQ, portfolio items, resources, recipes — any repeated structured content).
-**Notice** this recipe is for **initial backend setup ONLY**, not for coding the frontend.
-
-> **This recipe is the *how*, not the *what*.** Which collections to create, their fields, and how many items each holds is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide the schema or quantities.
-
-> **API surfaces:** Wix CMS uses the **Wix Data v2** API on `https://www.wixapis.com/wix-data/v2/...` — collections under `/collections`, items under `/items` and `/bulk/items/*`. The CMS (Wix Data) app's `appDefId` is `e593b0bd-b783-45b8-97c2-873d42aacaf4` (an unmet `WDE0110` error means the app isn't installed). There is no V1/V3 split here — everything is `/wix-data/v2/`.
-
----
-
-## Article: Steps for Setting Up Wix CMS
-**YOU MUST** complete the steps in order, without requiring additional user input: create each collection (STEP 1) before inserting its items (STEP 2), and verify (STEP 3) before wiring any references (STEP 4). Items can only be inserted into a collection that already exists. The **Attach images** step runs **only when imagery is on** — skip it entirely otherwise.
-
-### STEP 1: Create each collection (public-read)
-
-Create one collection per entry the request names. **How many collections, their `id`/`displayName`, and their field schema come from the request you're fulfilling — this step only gives the call and the required format.**
-
-Use the **Create Data Collection** endpoint: `POST https://www.wixapis.com/wix-data/v2/collections`.
-
-```json
-{
-  "collection": {
-    "id": "team-members",
-    "displayName": "Team Members",
-    "fields": [
-      { "key": "name",  "displayName": "Name",  "type": "TEXT" },
-      { "key": "role",  "displayName": "Role",  "type": "TEXT" },
-      { "key": "bio",   "displayName": "Bio",   "type": "RICH_TEXT" },
-      { "key": "order", "displayName": "Order", "type": "NUMBER" }
-    ],
-    "permissions": {
-      "insert": "ADMIN",
-      "update": "ADMIN",
-      "remove": "ADMIN",
-      "read":   "ANYONE"
-    }
-  }
-}
-```
-
-The response returns the created collection — its `id` is the value you sent (Wix does not rename it). Keep that `id` and the exact field `key`s; the items step and the frontend both bind by them.
-
-**⚠️ CRITICAL: the `permissions` block is mandatory, and for a PUBLIC collection `read` MUST be `"ANYONE"`.** A headless frontend reads with an **anonymous visitor token** and **cannot elevate** (a pure SPA/static site has no server; even on Astro the read path is visitor-scoped). If a **public** collection's `read` is anything but `ANYONE`, the visitor query returns **zero items with no error** — the page looks empty and it reads like a query bug when it's really a permissions bug. So default to `read: "ANYONE"`. **The one exception is a deliberately member-scoped collection** (opt-in, members login in the run) — see "Member-scoped collections" below, where `read` is `SITE_MEMBER`/`SITE_MEMBER_AUTHOR` on purpose and an anonymous empty read is the gate, not a bug. Omitting the whole `permissions` object fails the create either way.
-
-**⚠️ Write permissions: `ADMIN` by default; open them ONLY for a collection the site lets visitors write.** Most collections hold **admin-owned content** (the catalog, the team, the articles) — visitors only read them, so keep `insert`/`update`/`remove` at `"ADMIN"` (only this seed token writes; a visitor write to an `ADMIN` collection 403s). But when the request models **visitor-written, shared data** — a guestbook, a community board, a collaborative list anyone can add to and edit — that collection must be **visitor-writable**, so set the verbs the site uses to `"ANYONE"`:
-
-```json
-"permissions": { "read": "ANYONE", "insert": "ANYONE", "update": "ANYONE", "remove": "ANYONE" }
-```
-
-Which collection (if any) is visitor-writable comes from the request; this step only gives the permission shape.
-
-**⚠️ With an ANONYMOUS visitor token there is NO per-user identity — an `ANYONE`-writable collection is SHARED and unscoped.** Every anonymous visitor authenticates as the same kind of identity, so on the **anonymous** path the only open-write level that works is **`ANYONE`**, which means **any visitor can edit or delete any row** (the data is global/shared, not per-user, not per-device). That's correct for a collaborative board. **For per-user-private data, use the member-scoped variant below** — it needs a logged-in member. Don't open `insert`/`update`/`remove` to `ANYONE` on a collection that shouldn't be globally editable.
-
-#### Member-scoped collections (opt-in — only when the run includes members login)
-
-**Only create these when the request calls for per-user or member-only data AND members login is part of the run** (an account area, "my saved items", "members-only content"). Otherwise stay with the public-read / collaborative shapes above — this is **not** a default. A member-scoped collection needs a **logged-in member**; it runs on the **member token (the identity layer — login, no Members Area app install, no `auth.elevate`)**, and the platform enforces the scoping server-side from the caller's member identity. The role vocabulary the `permissions` block accepts, highest-to-lowest: `ADMIN` › `SITE_MEMBER_AUTHOR` › `SITE_MEMBER` › `ANYONE`. Two member shapes:
-
-```jsonc
-// Per-user-private ("my …" data — each member sees/edits only their OWN rows, scoped by the item's _owner)
-"permissions": { "read": "SITE_MEMBER_AUTHOR", "insert": "SITE_MEMBER", "update": "SITE_MEMBER_AUTHOR", "remove": "SITE_MEMBER_AUTHOR" }
-
-// Shared member-only (any logged-in member reads; only the seed/admin writes — gated content)
-"permissions": { "read": "SITE_MEMBER", "insert": "ADMIN", "update": "ADMIN", "remove": "ADMIN" }
-```
-
-- **`SITE_MEMBER_AUTHOR`** = a signed-in member, **restricted to items they created** (the platform matches the item's `_owner` to the caller). `insert` is `SITE_MEMBER` (a member can create — the insert stamps them as owner; **don't set `_owner` yourself**), while `read`/`update`/`remove` are `SITE_MEMBER_AUTHOR` so each member touches only their own rows. This is the clean solution to per-user-private data — **no server code, no elevation, works on a pure SPA**, because the member token carries the identity the visitor token lacked.
-- **`SITE_MEMBER`** = **any** signed-in member (not owner-scoped) — use for content every member may read but only the site writes.
-- **An anonymous visitor reading a member-scoped collection gets ZERO items — that is the gate working, not the empty-page bug above.** Only treat an empty read as a seed defect on an `ANYONE`-read collection; on a `SITE_MEMBER*` collection an empty anonymous read is expected (the frontend must gate it behind login — see `how-to-code-cms.md`). Seeding items into a `SITE_MEMBER_AUTHOR` collection with the **admin/seed token** makes their `_owner` the admin, so no member will see them — seed such a collection **empty** (members populate it themselves) unless the brief wants admin-owned member-readable rows (then use the shared `SITE_MEMBER` shape).
-
-**⚠️ CRITICAL: collection `id` has NO namespace.** A user-created (`NATIVE`) collection's `id` is just the name you choose (`"team-members"`, `"faq"`, `"Projects"`) — the `<namespace>/<name>` form (`Members/PublicData`) is **only** for Wix App collections. Use the exact `id` you set here everywhere downstream; the dashboard display name may differ from the `id`, so never guess it — keep the one you sent.
-
-**Field types** (set `type` per field): `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `DATETIME`, `URL`, `EMAIL`, `IMAGE`, `RICH_TEXT` / `RICH_CONTENT` (Ricos), `ARRAY_STRING`, `OBJECT`, `REFERENCE` (single), `MULTI_REFERENCE`. Use `RICH_TEXT`/`RICH_CONTENT` for formatted body copy and `TEXT` for plain strings. A `RICH_TEXT` field accepts an **HTML string** (`"<p>…</p>"`) at insert — it is stored verbatim, not coerced.
-
-**⚠️ CRITICAL: a `MULTI_REFERENCE` (or single `REFERENCE`) field needs a `typeMetadata` binding, and the key is `referencedCollectionId` — NOT `referencedCollection`.** A reference field declared with only `{ "type": "MULTI_REFERENCE" }` (no metadata) creates a field whose target is **empty**, and every later reference wiring (STEP 4) reports success but **never resolves** — the links are silently dead. The binding lives under `typeMetadata.multiReference`:
-
-```json
-{
-  "key": "categories",
-  "displayName": "Categories",
-  "type": "MULTI_REFERENCE",
-  "typeMetadata": {
-    "multiReference": {
-      "referencedCollectionId": "recipe-categories",
-      "referencingFieldKey": "recipes",
-      "referencingDisplayName": "Recipes"
-    }
-  }
-}
-```
-
-`referencedCollectionId` is the **target** collection's id (so that collection must be created first — order your STEP 1 creates accordingly); `referencingFieldKey`/`referencingDisplayName` name the auto-created back-reference on the target. **Beware: the official Create-Data-Collection docs example uses `referencedCollection` — the API accepts that payload with `200` but silently stores an empty `referencedCollectionId`, leaving a broken field.** Use `referencedCollectionId`. (A single `REFERENCE` field uses `typeMetadata.reference.referencedCollectionId` likewise.)
-
-**⚠️ A fresh site's Wix Data backend can fail the FIRST few calls transiently while it propagates — retry the failed call ONCE, then proceed.** On a brand-new site the data backend may not be fully provisioned for the opening calls, surfacing as either of two same-root-cause errors that **self-heal within a few seconds**:
-- **`403`** on collection-create (STEP 1), or
-- **`400 WDE0117: "MetaSite not found"`** on a bulk item-insert (STEP 2).
-
-Both are provisioning races, not payload bugs (the identical body succeeds on retry). On a `403` / `400 WDE0117` / `5xx` for any create or insert, wait briefly and **retry the failed call once with the same body**. **Do not loop** — a spiralling retry is a wasted headless run. If the single retry still fails, surface the response verbatim and fail loud.
-
-### STEP 2: Bulk-insert each collection's items (with field data)
-
-Populate each collection in a **single bulk call** per collection. **How many items and their content come from the request you're fulfilling — this step only gives the call and the required format.**
-
-Use **Bulk Insert Data Items**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert` (one call per collection; `dataCollectionId` is single-valued, so fire one bulk call per collection — these can run in parallel across collections). For a collection with a **single** item, the single-insert endpoint `POST /wix-data/v2/items` (body `{ "dataCollectionId": "...", "dataItem": { "data": {...} } }`) is equivalent.
-
-```json
-{
-  "dataCollectionId": "team-members",
-  "dataItems": [
-    { "data": { "name": "Ada Lovelace", "role": "Founder", "bio": "<p>Builds the things.</p>", "order": 1 } },
-    { "data": { "name": "Alan Turing",  "role": "Engineer", "bio": "<p>Breaks the things.</p>", "order": 2 } }
-  ],
-  "returnEntity": true
-}
-```
-
-**⚠️ CRITICAL: every field goes inside `data`, with real values — an empty `data: {}` creates an empty record.** The collection schema existing is not the same as the item having content. Populate **every** field the page will render (`name`, `role`, `bio`, …) in the `data` object. An item inserted with missing fields ships a "content coming soon"–looking blank on the live page, and the API accepts it without error — the failure is invisible until STEP 3.
-
-**⚠️ CRITICAL: the `data` keys MUST match the collection's field `key`s exactly.** A key the schema doesn't have is silently dropped (or rejected as a validation error); a mismatched case/spelling reads back as a missing field. Use the exact `key`s from STEP 1.
-
-**⚠️ CRITICAL: do NOT set a MULTI_REFERENCE value at insert — it is SILENTLY DROPPED (no error).** Putting a `categories: ["<id>"]` array in `data` does **not** raise an error (it does **not** throw `WDE0303` on the bulk endpoint) — the insert returns `200 success`, but the multi-reference value is **silently discarded** (absent from the stored item). So a multi-reference left in `data` looks like it worked and isn't there. Insert the items first with **plain fields only**, then wire multi-references in STEP 4. A **single** `REFERENCE` field *can* be set at insert by passing the referenced item's `_id` string as the field value (`"venue": "<referenced-item-id>"`).
-
-**⚠️ Reading the response — created items are under `results[].dataItem`, NOT `results[].item`.** A successful bulk insert returns the standard Wix bulk shape (note the per-item wrapper is **`dataItem`**, not `item`):
-
-```json
-{ "results": [
-    { "action": "INSERT",
-      "itemMetadata": { "id": "<itemId>", "originalIndex": 0, "success": true },
-      "dataItem": { "id": "<itemId>", "dataCollectionId": "team-members",
-                    "data": { "_id": "<itemId>", "name": "Ada Lovelace", "role": "Founder", "_createdDate": { "$date": "..." } } } }
-  ],
-  "bulkActionMetadata": { "totalSuccesses": 2, "totalFailures": 0 }
-}
-```
-
-(The **single**-insert endpoint returns the same wrapper for one item: `{ "dataItem": { "id": "<itemId>", "data": { "_id": "<itemId>", ... } } }`.) The item id is the wrapper's top-level **`id`** (mirrored as `data._id`) — read it from `results[].dataItem.id` (bulk) or `dataItem.id` (single). There is **no** `results[].item` key — reading it finds nothing and makes a successful insert look empty. If part of the bulk request fails (`bulkActionMetadata.totalFailures > 0`), retry the failed items **once** with the same format; do not loop.
-
-### STEP 3: Verify the inserts (mandatory)
-
-A POST without an error does **not** prove the content persisted. After inserting, **query each collection once** and confirm every field you sent is present in the stored items.
-
-Use **Query Data Items**: `POST https://www.wixapis.com/wix-data/v2/items/query` with body `{ "dataCollectionId": "<collection>" }`. For every returned item, confirm its `data` carries every field you POSTed. If a field is missing, re-insert that item once (DELETE then insert is safest — a PUT replaces the whole record) and re-verify; if it still fails, surface the missing-field error verbatim rather than reporting success.
-
-### STEP 4: Wire multi-references (only if collections relate)
-
-**Skip this step unless the request models a relationship** (e.g. a project → its team members, an article → its tags) as a `MULTI_REFERENCE` field. Single `REFERENCE` fields were already set in STEP 2.
-
-Use **Bulk Insert Reference Data Items**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert-references` — link a referring item's multi-reference field to one or more referenced item ids. (`/items/replace-references` replaces the whole set; `/bulk/items/remove-references` unlinks.) Both ids come from the STEP 2 responses.
-
-**⚠️ CRITICAL: the body key is `dataItemReferences`, and each entry uses `referringItemFieldName` / `referringItemId` / `referencedItemId`.** The natural-looking shape (`references: [{ referencingItemId, referencedItemId }]` + a top-level `referenceProperty`) is **rejected with `400 WDE0080` "dataItemReferences must not be empty"**. Use exactly:
-
-```json
-{
-  "dataCollectionId": "recipes",
-  "dataItemReferences": [
-    { "referringItemFieldName": "categories", "referringItemId": "<recipeId>", "referencedItemId": "<categoryId>" }
-  ]
-}
-```
-
-`referringItemFieldName` is the multi-reference field's key on the **referring** collection (`recipes.categories`); `referringItemId` is that item's id; `referencedItemId` is the target item's id.
-
-**⚠️ References only resolve if the field was created with a non-empty `referencedCollectionId` (STEP 1).** This call can return `200` / `totalSuccesses` even when the field's target binding is empty — but then a read with `.include("categories")` (or `query-referenced`) returns nothing (and `query-referenced` errors `WDE0020 "Provided property [] is not a multi-reference field"`). If references insert "successfully" but never appear on reads, the field's `referencedCollectionId` was empty at create time — fix the STEP 1 field definition, not this call.
-
-### Attach images (imagery ON only — skip otherwise)
-
-**Only when `imagery` is on** (`SEED.md` § "Entity images"). This is the CMS entry in the required pass-2 "attach the generated image to the entity" flow — items were inserted text-only earlier (any `IMAGE` field left blank); now write the image onto each. It presumes the collection has an `IMAGE`-type field (from the field schema at create time). Generate + import per `references/IMAGE_GENERATION.md` and keep `file.url` (the permanent `wixstatic.com` URL — an `IMAGE` field stores the URL string).
-
-**⚠️ Use read-merge-PUT, not PATCH.** A partial JsonPatch is fragile here; instead query the item, merge the image URL into its `data`, and PUT the **whole** record back:
-
-1. **Read** the item — `POST https://www.wixapis.com/wix-data/v2/items/query` with `{ "dataCollectionId": "<collection>" }` (or filter to the one item). Keep its full `data` (including `_id`).
-2. **Merge** the image URL into the item's image field key (e.g. `data.photo = "<file.url>"`), leaving every other field intact.
-3. **PUT** the whole record — `PUT https://www.wixapis.com/wix-data/v2/items/<itemId>`:
-
-```json
-{ "dataCollectionId": "<collection>", "dataItem": { "data": { "_id": "<itemId>", "name": "…", "role": "…", "photo": "<file.url>" } } }
-```
-
-- **PUT replaces the entire record** — you must send back **all** existing fields (from step 1), not just the image, or the omitted fields are wiped. This is why you read-merge-PUT rather than sending the image alone.
-- **Never block on image failure** (`SEED.md` § "Entity images" / IMAGE_GENERATION "Credits, cost & the not-generating fallback") — on failure, skip and leave the item text-only.
-
----
-
-## Conclusion
-Following these steps **in order** sets up a Wix CMS backend:
-- Every collection is created with a `permissions` block whose **`read` is `ANYONE`**, so the headless visitor frontend can read it (the single most common "empty page" cause).
-- Write verbs are **`ADMIN` by default** (visitor reads only); a collection the site lets visitors write is created with `insert`/`update`/`remove` at **`ANYONE`** (the only open-write level the anonymous visitor token supports — the data is then global/shared, with no per-user scoping).
-- **(Opt-in, members only)** a per-user-private or member-only collection is created with a **member-scoped** `permissions` block — `SITE_MEMBER_AUTHOR` (own rows only, `_owner`-matched) or `SITE_MEMBER` (any logged-in member) — which runs on the **member token** (login/identity layer, no Members Area install, no elevate). This is the per-user scoping the anonymous path can't do; add it only when the brief asks and members login is in the run, and expect anonymous reads to return empty (the gate).
-- Native collection `id`s carry **no namespace** and are kept verbatim for the frontend to bind to.
-- Every item is bulk-inserted with **real field values** in `data` (keys matching the schema) and **verified to have persisted**.
-- Reference fields are created with a non-empty `typeMetadata…referencedCollectionId` (the working key, not the docs' stale `referencedCollection`); multi-references are then wired with the reference endpoint's `dataItemReferences[]` shape (never set at insert — they're silently dropped there), and single references by item-id at insert.
-- **When imagery is on**, each item's `IMAGE` field is filled by the **Attach images** step (pass-2) via **read-merge-PUT** (`PUT …/items/{id}` with the full merged record — a partial PUT wipes omitted fields), storing `file.url`; on failure the item stays text-only.
-- **Keep** per collection: the `collectionId`, the field `key`s, and the `itemIds[]` — these are the producer for the coding handoff.

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

@@ -1,15 +0,0 @@
----
-name: "Set Up Donations"
-description: Set up Wix Donations campaigns through the shared management recipe; reuse existing campaigns and keep configuration separate from the donor-facing implementation.
----
-# Set up Donations
-
-Read [Create and Update Donation Campaigns](../../../wix-manage/references/donations/create-and-update-donation-campaigns.md)
-and execute its read-before-write flow with this project's owner-authorized credentials and site ID.
-If the sibling skill is not installed, read
-`https://www.wix.com/skills/wix-manage/references/donations/create-and-update-donation-campaigns.md`.
-
-Reuse the supplied site's campaigns. Only create/edit the causes and settings the user approved;
-do not manufacture a goal, deadline or impact claim. Keep any created campaign IDs only for setup
-verification/media attachment; the frontend discovers campaigns live. The donation form and checkout
-are [How to Code Donations](how-to-code-donations.md), not this setup operation.