@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -0,0 +1,196 @@
+---
+name: "Setup Events"
+description: Initializes a Wix Events (Events V3) backend — creates one or more events (each TICKETING or RSVP) as drafts with future dates, adds ticket definitions for ticketed events, then publishes. Specifies the *how* (calls + format); counts, which events are ticketed vs RSVP, dates, and ticket tiers come from the request.
+---
+**RECIPE**: Business Recipe – Initial Setup for Wix Events (Events 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 turning a freshly provisioned Wix site with the **Wix Events** app installed into a populated set of published, registerable events.
+**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial Events backend setup. (The frontend read/registration contract is the sibling recipe `how-to-code-events.md`.)
+
+> **This recipe is the *how*, not the *what*.** What to seed — how many events, which are ticketed vs free (RSVP), their dates/locations, and which ticket tiers and prices a ticketed event has — is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide quantities, types, or which events to create.
+
+> **API surfaces:** events, ticket definitions, and publish all use **Events V3** on the **public** host `https://www.wixapis.com/events/v3/...`. The Wix Events **app id** (needed only by the frontend, kept here for reference) is `140603ad-af8d-84a5-2c80-a0f60cb47351`. The app is **pre-installed** by setup — do **not** reinstall it; if a create call returns `403`/app-not-installed, **fail loudly** with the response verbatim rather than trying to install it.
+
+---
+
+## Article: Steps for Setting Up Wix Events
+**YOU MUST** complete all the following steps **in the given order** (1-3) without skipping any and **without requiring additional user input**. The **Attach images** step runs last, only when `imagery` is on.
+
+**⚠️ CRITICAL ORDER REQUIREMENT: create each event as a DRAFT (STEP 1) → add its ticket definitions (STEP 2, ticketed only) → PUBLISH (STEP 3).** Two one-way constraints force this order:
+- **`registration.initialType` is immutable after create** — a `TICKETING` event can never become `RSVP` (or vice-versa). Decide the type at create time from the request; never plan to convert.
+- **Publishing is one-way** — once published, an event can't return to draft. So attach the ticket definitions to the *draft* first; publishing a ticketed event before its tickets exist ships a ticketed event with nothing to buy.
+
+There is **no clean-up step** — a fresh Wix Events install ships **no** sample events, so there is nothing to delete first.
+
+### STEP 1: Create the event(s) as a draft
+
+Create one event per the request's event count (default 1). Each event is **either** `TICKETING` (paid tickets) **or** `RSVP` (free registration) — read which from the request. Create with `"draft": true` so STEP 2 can attach ticket definitions before the event goes live.
+
+**⚠️ CRITICAL: dates MUST be in the future.** A past event is neither purchasable nor registerable and won't show in the live listing (the frontend filters to upcoming). Convert any human date from the request to a **future** ISO-8601 UTC instant; if none is given, default to a plausible near-future date (~60–90 days out) and note it in the kept output so the user can adjust.
+
+**Ticketed event** (`TICKETING`) — `POST https://www.wixapis.com/events/v3/events`:
+
+```bash
+curl -X POST 'https://www.wixapis.com/events/v3/events' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "draft": true,
+    "event": {
+      "title": "Summer Synth Festival",
+      "shortDescription": "One night of analog sound under the stars.",
+      "location": {
+        "name": "The Echo Lot",
+        "type": "VENUE",
+        "address": { "addressLine": "120 Harbor St", "city": "Seattle", "subdivision": "US-WA", "postalCode": "98101", "country": "US" }
+      },
+      "dateAndTimeSettings": {
+        "startDate": "<FUTURE_DATE>T03:30:00.000Z",
+        "endDate":   "<FUTURE_DATE>T07:00:00.000Z",
+        "timeZoneId": "America/Los_Angeles",
+        "showTimeZone": true
+      },
+      "registration": {
+        "initialType": "TICKETING",
+        "tickets": { "ticketLimitPerOrder": 8, "currency": "USD", "reservationDurationInMinutes": 20 }
+      }
+    },
+    "fields": ["DETAILS", "TEXTS", "REGISTRATION", "URLS"]
+  }'
+```
+
+**Free / RSVP event** (`RSVP`) — same call; only the `registration` block changes (no `tickets`):
+
+```json
+"registration": {
+  "initialType": "RSVP",
+  "rsvp": { "responseType": "YES_ONLY" }
+}
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **`registration.initialType` is `"TICKETING"` or `"RSVP"` and is immutable** — set it correctly at create time.
+- **RSVP events seed NO form fields.** The registration form is **built-in** (first name + last name + email, required, can't be removed). Use `"responseType": "YES_ONLY"`, or `"YES_AND_NO"` to let guests decline. Do not seed custom fields.
+- **`location`** — for a real venue use `"type": "VENUE"` with an `address` (`subdivision` is an ISO-3166-2 code like `US-WA`; `country` is ISO alpha-2). For an online event use `"type": "ONLINE"` with just a `name`. For an undecided venue use `"location": { "locationTbd": true, "name": "<placeholder>" }` instead of an address.
+- **Dates** — `startDate`/`endDate` are ISO-8601 UTC (`...Z`), future, `endDate` after `startDate`; `timeZoneId` is an IANA tz.
+
+**⚠️ Reading the response — the created event is under `event`, with `event.id` and `event.slug`.** A successful create returns `200` with this shape (REST view → `id`/`slug`):
+
+```json
+{ "event": {
+  "id": "<eventId>",
+  "slug": "summer-synth-festival",
+  "title": "Summer Synth Festival",
+  "status": "DRAFT",
+  "registration": { "initialType": "TICKETING", "status": "CLOSED_MANUALLY" },
+  "dateAndTimeSettings": { … },
+  "location": { … }
+} }
+```
+
+Keep each event's **`event.id`** (the GUID — needed for STEP 2 and STEP 3) and **`event.slug`** (defaults to the kebab-cased title — the frontend routes and the checkout redirect bind to it). `slug` is the URL identifier; do **not** confuse it with `id`.
+
+### STEP 2: Create ticket definitions (TICKETING events only — skip for RSVP)
+
+A ticketed event needs at least one **ticket definition** (a purchasable tier) or there's nothing to buy. Create **one tier per ticket tier in the request** (default a single `"General Admission"` tier if none named) against `POST https://www.wixapis.com/events/v3/ticket-definitions`. The tier-creates for one event are independent — they may be fired as one parallel batch.
+
+```bash
+curl -X POST 'https://www.wixapis.com/events/v3/ticket-definitions' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "ticketDefinition": {
+      "eventId": "<eventId FROM STEP 1>",
+      "name": "General Admission",
+      "description": "Standing-room access to the full lineup.",
+      "initialLimit": 200,
+      "pricingMethod": { "fixedPrice": { "value": "65.00", "currency": "USD" } },
+      "feeType": "FEE_INCLUDED"
+    },
+    "fields": ["SALES_DETAILS"]
+  }'
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **`pricingMethod.fixedPrice.value` is a decimal STRING** (`"65.00"`), not a number (`65`) — a number fails validation.
+- **`name` is capped at 30 characters** — keep tier names short (`"Premium Floor"`, not `"Premium Floor Standing Pit Access"`).
+- **`feeType`** — `"FEE_INCLUDED"` (guest pays exactly the listed price; the Wix fee is deducted from your payout) or `"FEE_ADDED_AT_CHECKOUT"` (fee shown on top). Pick one and be consistent. `"NO_FEE"` is valid **only** for free tickets (a `fixedPrice.value` of `"0"` — rare; prefer an RSVP event for free admission).
+- **`initialLimit`** is the integer inventory cap for the tier; **omit it for unlimited** tickets.
+- The event currency is set on the event (`registration.tickets.currency`, STEP 1); keep the tier currency consistent with it.
+
+**⚠️ Reading the response — the created tier is under `ticketDefinition`, id at `ticketDefinition.id`:**
+
+```json
+{ "ticketDefinition": {
+  "id": "<ticketDefinitionId>",
+  "eventId": "<eventId>",
+  "name": "General Admission",
+  "initialLimit": 200,
+  "pricingMethod": { "fixedPrice": { "value": "65.00", "currency": "USD" } },
+  "feeType": "FEE_INCLUDED"
+} }
+```
+
+Keep each **`ticketDefinition.id`** (the frontend lists tiers and reserves by it). On a partial failure, retry only the **failed** tier-creates **once** with the same format; do not loop.
+
+### STEP 3: Publish the event
+
+Once the event (and, for ticketed events, its ticket definitions) exists, publish it to go live: `POST https://www.wixapis.com/events/v3/events/{eventId}/publish` with body `{}`.
+
+```bash
+curl -X POST 'https://www.wixapis.com/events/v3/events/<eventId>/publish' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+A `200` with `status: "UPCOMING"` (plus `OPEN_TICKETS` on the registration for a ticketed event) means it's live. **Publishing is one-way** — there's no un-publish — so confirm the tickets are created (STEP 2) before publishing a ticketed event.
+
+### STEP 4 (optional): Group events by a format / track — Event Categories
+
+**Only when the request wants events grouped or filtered by a format/track** (e.g. talk / workshop / social). Wix Events has a first-class **Categories** API for this — use it; do **not** invent an endpoint. **⚠️ It is `v1`, NOT `v3`**, and the assign path is specific:
+
+1. **Create one category per group** — `POST https://www.wixapis.com/events/v1/categories` with `{ "category": { "name": "Talks" } }` → keep `category.id`. One call each.
+2. **Assign events to a category** — `POST https://www.wixapis.com/events/v1/categories/{categoryId}/events` with `{ "eventId": ["<eventId>", …] }`. **⚠️ The path is `/{categoryId}/events`, NOT `/assign`** (and `v1`, not `v3/categories`) — the wrong forms `404`.
+3. **Verify via the EVENT read, not the category list.** Assignment can lag a few seconds — `listEventsByCategory` may briefly return `[]`, so don't gate on it. Confirm with `queryEvents` (or `getEventBySlug`) requesting **`fields: ["CATEGORIES"]`** — each event then carries `categories.categories[]` with the assigned `{ id, name }` (REST view — the id key is `id`, not `_id`).
+
+Nothing else in the seed depends on categories, and the frontend filters **client-side** off the category name (`how-to-code-events.md`) — skip this step entirely if the request has no grouping.
+
+### Attach images (imagery ON only — skip otherwise)
+
+**Only when `imagery` is on** (`SEED.md` § "Entity images"). Events were created text-only; this pass-2 step writes a generated hero image onto each event's **`mainImage`**. Generate + import per `references/IMAGE_GENERATION.md` → keep `file.url` and its `file.id`, then update the event. This works **before or after publish** — updating an event (unlike publishing) is not one-way — so run it here regardless of an event's status.
+
+**`mainImage` is an `Image` OBJECT `{ id, url, height, width, altText }`.** The binding field is the image **`id`** (the WixMedia image id); `url`/`altText` are descriptive. **⚠️ `height` and `width` are REQUIRED for the image to render** — the schema states the image only appears when both are defined, so always send them (use the generated dimensions, e.g. `1024`×`1024`). Events V3 uses **no `revision`** — this is a partial update keyed by `event.id`; pass only the field you're setting.
+
+`PATCH https://www.wixapis.com/events/v3/events/{eventId}`:
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/events/v3/events/<eventId>' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "event": { "id": "<eventId>", "mainImage": { "id": "<file.id>", "url": "<file.url>", "height": 1024, "width": 1024, "altText": "<alt>" } }, "fields": ["DETAILS"] }'
+```
+
+- **`mainImage` reads back only under the `DETAILS` fieldset** — pass `"fields": ["DETAILS"]` (as above, and on any confirming `getEvent`/`queryEvents`) or the response omits it and a confirm check looks empty.
+- **Never block on image failure** (`SEED.md` § "Entity images" / IMAGE_GENERATION "Credits, cost & the not-generating fallback") — on failure, skip and leave the event text-only.
+
+### Paid-ticket precondition — record it, do NOT block
+
+Seeding **succeeds** and the event goes live regardless of payment setup. But **completing a paid purchase** later requires, in the site dashboard, both:
+- a **premium plan**, and
+- at least one **configured payment method** (Wix Payments / Stripe / PayPal).
+
+Free / RSVP events need neither. This is **not** a seeding failure and **not** something to fix here — record it in the kept `notes` so it's surfaced plainly (*"Paid tickets require a premium plan + a configured payment method in the dashboard to complete a purchase."*). Never imply tickets are payable when no payment method is configured, and never fail the seed over it.
+
+---
+
+## Conclusion
+Following these steps **in order** sets up a published Events V3 site:
+- Every event is created with its **immutable `registration.initialType`** (`TICKETING` or `RSVP`) chosen up front, with **future** dates so it's purchasable/registerable and appears in the live listing.
+- Every **ticketed** event has at least one **ticket definition** (price as a decimal string, name ≤ 30 chars, a valid `feeType`) created **before** publish; **RSVP** events seed no tickets and no form fields (the name + email form is built-in).
+- Every event is **published** (one-way) so it's live, after its tickets exist.
+- IDs kept for the coding handoff: `eventIds[]`, event `slug`s, and per ticketed event its `ticketDefinitionIds[]` (`[]` for RSVP).
+- The paid-ticket precondition (premium plan + payment method) is **noted**, not treated as a failure.
+- Events are seeded **text-only**; when `imagery` is on, the **Attach images** step writes a `mainImage` **object** onto each (`{ id, url, height, width }` — `height`/`width` REQUIRED or it won't render; no revision; PATCH `/events/v3/events/{eventId}`).

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

@@ -0,0 +1,174 @@
+---
+name: "Setup Forms"
+description: Initializes a Wix Forms backend — deletes the install's default sample form, then creates one lead-capture form schema per requested form (fields + human-readable `target` keys + each INPUT's `CONTACTS_*` system `identifier` + a `steps` layout, so the form and its submissions render in the dashboard, `namespace` wix.form_app.form) and verifies each persisted via the form summary. Specifies the *how* (calls + format); which forms, their fields, and counts come from the request.
+---
+**RECIPE**: Business Recipe – Initial Setup for Wix Forms (Form Schemas v4)
+
+> **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`. Send `wix-site-id: <SITE_ID>` on every call.
+
+A concise checklist for preparing any new Wix site that uses the **Wix Forms** app to capture leads (contact / inquiry / signup / RSVP-style forms).
+**Notice** this recipe is for **initial backend setup ONLY**, not for coding the frontend.
+
+> **This recipe is the *how*, not the *what*.** How many forms, each form's fields, and their labels come from the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide which forms or fields to create.
+
+> **API surfaces:** Wix Forms is a **standalone CRM API** — a form **schema** (the field definitions) is created on the **Form Schemas v4** service at `https://www.wixapis.com/form-schema-service/v4/forms`. In the docs portal this lives under **CRM ▸ Forms ▸ Form Schemas**, *not* under Business Solutions. This is **NOT** the events/bookings per-event registration form (a different thing). The Forms app's `appDefId` is `225dd912-7dea-4738-8688-4b8c6955ffc2`; an `UNSUPPORTED_FORM_NAMESPACE` error means the app isn't installed. Call the **public** host shown above (no `/_api/` prefix). There is no bulk endpoint — one POST per form.
+
+---
+
+## Article: Steps for Setting Up Wix Forms
+**YOU MUST** complete the steps in order, without requiring additional user input: clean the default form (STEP 1) **before** creating yours (STEP 2), then verify (STEP 3).
+
+**⚠️ CRITICAL ORDER REQUIREMENT: clean the install's default sample form FIRST (STEP 1), before creating any form.** Listing-then-deleting before you create guarantees every id you delete is a pre-existing form, never one you just created — and it prevents a name collision (see STEP 1). **But only delete forms that are obviously the install's own default sample form:** the site may already hold the owner's **real forms** (a connect/iterate run, or an owner-populated site). 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).
+
+### STEP 1: Clean — remove any pre-existing (install-default) forms
+
+A freshly installed Wix Forms app **may ship a default "Get in touch" form** (a contact form with `first_name` / `email` / `message` fields). Its presence is **not deterministic** — some fresh installs ship it and others don't, so it appears provisioning/timing-dependent. Rather than assume, **list what's actually there and delete whatever comes back** — this is a safe no-op when the list is empty.
+
+1. **List the existing forms** — `GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form`. `namespace` is a **required** query param. Collect every `form.id` from the response (`forms[].id`). On a fresh install this is **either empty or the single default form** — both are fine.
+2. **Delete each** — `DELETE https://www.wixapis.com/form-schema-service/v4/forms/{formId}` (one call per id; returns `200 {}`). Because the list ran **before** any create, every id returned is a pre-existing form — safe to delete. If the list was empty, issue no DELETE (a correct no-op).
+
+**⚠️ Why clean even though it's often a no-op: when the default "Get in touch" form IS present, form names collide and the service silently auto-suffixes.** Form names must be unique; if the request's form is also called "Get in touch" and a default exists that you didn't clean, the create succeeds but your form is renamed **"Get in touch 1"**, quietly diverging from the name the frontend expects. Cleaning first removes that hazard whenever the default happens to be present. (With the default present, a second "Get in touch" create comes back renamed "Get in touch 1".)
+
+### STEP 2: Create each form schema (fields + targets)
+
+Create the forms the request names — **one POST per form** to `POST https://www.wixapis.com/form-schema-service/v4/forms`. **How many forms, and each form's fields/labels, come from the request you're fulfilling — this step only gives the call and the required format.** (There is no bulk-create; issue one call per form. Forms are independent — no shared revision — so concurrent creates are safe, but typically it's just one form.)
+
+**⚠️ CRITICAL: every field needs a client-generated LOWERCASE GUID `id` — GENERATE IT IN THE SHELL, never type one from memory.** Each `formFields[].id` must be a distinct valid GUID (two the same → `400 DUPLICATED_FIELD_IDS`). Generate one per INPUT field **plus** one for the submit button and one for the layout step. **Generate them LOWERCASE** — each id is referenced twice (once as `formFields[].id`, once as the layout's `steps[].layout.large.items[].fieldId`) and they must match, but the server **lowercases** stored field ids; an uppercase `uuidgen` id in the layout would no longer match the stored field id and the dashboard layout would break. So lowercase at generation:
+
+```bash
+# lowercase GUIDs — uuidgen (lowercased), with python3 / node fallbacks (both already lowercase)
+lc() { uuidgen 2>/dev/null | tr 'A-Z' 'a-z' || python3 -c 'import uuid;print(uuid.uuid4())' || node -e 'console.log(crypto.randomUUID())'; }
+F1=$(lc); F2=$(lc); F3=$(lc)   # one per INPUT field
+SUBMIT=$(lc)                   # the submit-button (DISPLAY) field
+STEP=$(lc)                     # the layout step (page)
+```
+
+**Request body shape** (a 3-field contact form — repeat/adjust the INPUT `formFields[]` and the matching layout `items[]` per the request):
+
+```json
+{
+  "form": {
+    "name": "Get in touch",
+    "namespace": "wix.form_app.form",
+    "formFields": [
+      { "id": "$SUBMIT", "hidden": false, "identifier": "SUBMIT_BUTTON", "fieldType": "DISPLAY",
+        "displayOptions": { "displayFieldType": "PAGE_NAVIGATION", "pageNavigationOptions": { "nextPageText": "Next", "previousPageText": "Back", "submitText": "Submit" } } },
+      { "id": "$F1", "hidden": false, "identifier": "CONTACTS_FIRST_NAME", "fieldType": "INPUT", "inputOptions": {
+          "target": "first_name", "pii": true, "required": true, "inputType": "STRING", "readOnly": false,
+          "stringOptions": { "validation": { "format": "UNKNOWN_FORMAT", "enum": [] }, "componentType": "TEXT_INPUT", "textInputOptions": { "label": "First name", "showLabel": true } } } },
+      { "id": "$F2", "hidden": false, "identifier": "CONTACTS_EMAIL", "fieldType": "INPUT", "inputOptions": {
+          "target": "email", "pii": true, "required": true, "inputType": "STRING", "readOnly": false,
+          "stringOptions": { "validation": { "format": "EMAIL", "enum": [] }, "componentType": "TEXT_INPUT", "textInputOptions": { "label": "Email", "showLabel": true } } } },
+      { "id": "$F3", "hidden": false, "identifier": "CONTACTS_PHONE", "fieldType": "INPUT", "inputOptions": {
+          "target": "phone", "pii": true, "required": false, "inputType": "STRING", "readOnly": false,
+          "stringOptions": { "validation": { "format": "PHONE", "enum": [] }, "componentType": "TEXT_INPUT", "textInputOptions": { "label": "Phone", "showLabel": true } } } }
+    ],
+    "steps": [
+      { "id": "$STEP", "name": "Page 1", "layout": { "large": { "items": [
+        { "fieldId": "$F1", "row": 0, "column": 0, "width": 12, "height": 1 },
+        { "fieldId": "$F2", "row": 1, "column": 0, "width": 12, "height": 1 },
+        { "fieldId": "$F3", "row": 2, "column": 0, "width": 12, "height": 1 },
+        { "fieldId": "$SUBMIT", "row": 3, "column": 0, "width": 12, "height": 1 }
+      ], "sections": [] } } }
+    ],
+    "enabled": true
+  }
+}
+```
+
+**⚠️ CRITICAL FORMAT REQUIREMENTS:**
+- **`namespace` MUST be `"wix.form_app.form"`** (the Wix Forms namespace) — any other value fails with `400 UNSUPPORTED_FORM_NAMESPACE`. It is immutable after create.
+- **Every INPUT field MUST carry a non-empty `target`** — the human-readable key the frontend binds to (input `name` = `target`). An empty/missing target fails with `400 UNSUPPORTED_FIELD_TARGETS_NAME` (`MISSING_FIELD_TARGETS`). Targets are **immutable** (set once).
+- **Targets MUST be unique within a form** — two fields sharing a target → `400 DUPLICATED_FIELD_TARGETS`. Use lowercase snake_case keys the frontend can reuse verbatim (`first_name`, `email`, `phone`, `message`).
+- **Field envelope:** each field is `{ id, hidden: false, identifier: "<CONTACTS_*>", fieldType: "INPUT", inputOptions: { target, readOnly: false, inputType: "STRING", stringOptions: { validation: { format, enum: [] }, componentType: "TEXT_INPUT", textInputOptions: { label, showLabel } } } }`. The `identifier` is MANDATORY for dashboard rendering — see the CRITICAL identifier block below. Use `inputType: "STRING"` + `componentType: "TEXT_INPUT"` for text fields. Set `required: true` on the fields the form must collect (defaults to `false`); mark `pii: true` on personal fields (name/email/phone).
+
+**Dropdown (enum) fields — concrete envelope.** A dropdown is still `inputType: "STRING"`; only the `componentType` and its options block change. Set `componentType: "DROPDOWN"` and put the choices under `stringOptions.dropdownOptions.options` as `{ id, label, value }` — the `value` is what a submission stores (keep it a stable machine key), and **every option needs its own lowercase GUID `id`** (see the CRITICAL below). Keep the `validation` block as with any field (a plain dropdown reads back `format: UNDEFINED`, so write `UNKNOWN_FORMAT`):
+
+```jsonc
+// generate an option GUID per choice in the shell, same lc() helper as the field ids:
+//   O1=$(lc); O2=$(lc); O3=$(lc)
+{ "id": "$F4", "hidden": false, "identifier": "budget", "fieldType": "INPUT", "inputOptions": {
+    "target": "budget", "required": false, "inputType": "STRING", "readOnly": false,
+    "stringOptions": {
+      "validation": { "format": "UNKNOWN_FORMAT", "enum": [] },
+      "componentType": "DROPDOWN",
+      "dropdownOptions": {
+        "label": "Budget", "showLabel": true, "placeholder": "Select a range",
+        "options": [
+          { "id": "$O1", "label": "Under $1k", "value": "under_1k" },
+          { "id": "$O2", "label": "$1k–$5k",   "value": "1k_5k" },
+          { "id": "$O3", "label": "$5k+",      "value": "5k_plus" }
+        ]
+      } } } }
+```
+
+Add a matching `steps[].layout.large.items[]` entry for its `fieldId` like any other field.
+
+**⚠️ CRITICAL: every dropdown `options[]` entry MUST carry its own lowercase GUID `id` — a create without it 400s `options[N].id is not a valid GUID / must not be empty`.** The API spec marks the option `id` optional (it's for Multilingual translation), but the create validator **rejects an option with no `id`**. Generate one GUID per option in the shell (the same `lc()` helper used for field ids), exactly as you do for field/step ids — never type one from memory.
+
+**⚠️ A custom dropdown's options round-trip in `fields[].view.options`, NOT `formFields[]` — and the frontend reads them from there.** Verified live (2026-07-12): a dropdown whose `identifier` is a plain custom key (like `"budget"` — dropdowns rarely map to a `CONTACTS_*` system field) is **dropped from `formFields[]` by the identifier→dashboard rule below**, so it does **not** show in the Wix dashboard summary — *but its data is fully captured and its options survive under `form.fields[].view.options` as `[{ id, label, value }]`* (alongside `view.label` / `view.placeholder`). That's exactly where the schema-driven frontend reads dropdown choices from (`how-to-code-forms.md` projects `fields[]`, not `formFields[]`), so **a custom dropdown renders and submits correctly on the headless site even though the dashboard doesn't list it.** So: seed the dropdown as the request needs; verify persistence on the GET round-trip (STEP 3) by asserting the field appears in `fields[]` with a non-empty `view.options`; and — as with any custom (non-`CONTACTS_*`) field — do **not** claim the dashboard fully renders it (platform limitation, same as the CRITICAL identifier block). If a dropdown *does* map cleanly to a contact field, give it the matching `CONTACTS_*` identifier and it will also show in the dashboard.
+
+Other richer types (number, checkbox group, date) follow the same envelope with a different `inputType`/`stringOptions`/`arrayOptions` — but plain STRING text + dropdowns cover the lead-capture case.
+
+**⚠️ CRITICAL: every field MUST carry a `stringOptions.validation` block, or the field is NOT submittable — a visitor submission of it fails with `400 "must NOT have additional properties"`.** The submission validator builds its allowed-keys schema **only from fields that have a `validation` block**. A field created without one exists on the form and even renders, but any submission that includes its `target` is rejected as an unknown property (and `required` is silently dropped too) — the form looks fine but silently rejects real submissions. So give **every** field a `validation` block:
+  - Plain text / name / message → `"validation": { "format": "UNKNOWN_FORMAT", "enum": [] }`.
+  - Email → `"validation": { "format": "EMAIL", "enum": [] }`; phone → `"PHONE"`; URL → `"URL"`. (Full `format` enum: `UNKNOWN_FORMAT`, `DATE`, `TIME`, `DATE_TIME`, `EMAIL`, `URL`, `UUID`, `PHONE`, `URI`, `HOSTNAME`, `COLOR_HEX`, `CURRENCY`, `LANGUAGE`, `DATE_OPTIONAL_TIME`.)
+  - **Use `UNKNOWN_FORMAT`, NOT `UNDEFINED`, on write.** The create/GET response echoes an unconstrained format back as `"UNDEFINED"` (and the docs' create example shows `"format": "UNDEFINED"`), but sending `"UNDEFINED"` on **create** fails with `400 "format enum must be in […]"` — `UNDEFINED` is the read-back value, not a writable one. Write `UNKNOWN_FORMAT`; it stores and reads back as `UNDEFINED`.
+  - **Length & pattern constraints go in the SAME `validation` block — seed them when the request asks for field rules.** `stringOptions.validation` also accepts `minLength` (int), `maxLength` (int), and `pattern` (a regex string) alongside `format`/`enum`. A request like "first name 2–40 chars", "message at least 20 chars", or "note capped at 500" maps directly to these. Verified live (2026-07-12): `"validation": { "format": "UNKNOWN_FORMAT", "enum": [], "minLength": 2, "maxLength": 12, "pattern": "^[A-Za-z ]+$" }` persists and reads back under `validation.string.{minLength,maxLength,pattern}`. **These constraints are enforced server-side by `createSubmission`** — a violating submit is rejected with a field violation (`errorPath` = the field's `target`, e.g. message `"must have between 2 and 12 characters"`), which the frontend surfaces inline (see `how-to-code-forms.md`). The frontend also reads them from the schema to pre-validate client-side, so seeding them is what makes owner-set field rules flow through with no code change. `pattern` is a standard JS-style regex; omit it unless the request calls for a specific character rule.
+- `required` (at `inputOptions` level) lands in `validation.required` — but **only takes effect if the field has a `validation` block** (no block ⇒ `required` is dropped along with the field's submittability). This is another reason every field needs the block.
+- If a create fails transiently on a fresh site (`5xx`, or an identity/propagation error right after install — the install returns `appInstance.status: "UNKNOWN"` until it propagates), retry the same call **once**; do not loop. (Creates typically succeed immediately, but keep the retry-once safety net.)
+
+**⚠️ CRITICAL: include a `steps` layout + a `SUBMIT_BUTTON` DISPLAY field, or the Wix dashboard shows every submission EMPTY.** The form is technically submittable with INPUT fields alone — the submission *data* stores fine either way, and the headless frontend renders its own UI — BUT the Wix **Forms dashboard** (`Customers & Leads ▸ Forms & Submissions`) renders each submission's values against the form's **layout** (`formFields` + `steps`). A form seeded **without** a layout stores complete submissions that the dashboard displays as **blank** ("—" summary, empty details panel), so the site owner can't read their leads in the UI — it looks broken even though the data is intact. So always seed the layout:
+  - Add a **`SUBMIT_BUTTON`** DISPLAY field (`fieldType: "DISPLAY"`, `displayOptions.displayFieldType: "PAGE_NAVIGATION"`) to `formFields`.
+  - Add a **single `steps` entry** whose `layout.large.items[]` places **every** field (each INPUT + the submit button) by `fieldId`, one per row.
+  - **Each `items[].fieldId` MUST equal the corresponding `formFields[].id`** — this is why the ids are generated **lowercase** up front (the server lowercases stored field ids; an uppercased layout `fieldId` would no longer match and the dashboard layout silently breaks).
+  - A **single create call with the layout persists it** — no follow-up PATCH needed. (Omitting the layout is the cause of blank dashboard submissions; adding it via PATCH to an already-created form also fixes them retroactively.)
+
+**⚠️⚠️ CRITICAL: every INPUT field MUST carry a system `identifier`, or it is DROPPED FROM `formFields[]` and NEVER shows in the dashboard.** This is the #1 dashboard-blank cause and it is SEPARATE from (and stronger than) the layout requirement above — a form can have a perfect `steps` layout and still be blank. On create, the server keeps an INPUT field's component in `formFields[]` **only if its `identifier` is a recognized system value.** Without a recognized identifier (no identifier, a custom string, an extended-field key like `custom.x`, or a GUID — all fail) the field is normalized into the legacy `fields[]` array **only**, `formFields[]` comes back holding just the `SUBMIT_BUTTON`, and `GET .../{formId}/summary` returns **zero fields** → the Wix dashboard renders the form and every submission **blank**. (The public headless site still submits fine — the submission service matches by `target` — so this defect is invisible from the frontend; you must verify it server-side in STEP 3.)
+  - **Map each field to its contact identifier.** Set `identifier` on every INPUT field to the `CONTACTS_*` value for what it collects. Verified working: `CONTACTS_FIRST_NAME`, `CONTACTS_LAST_NAME`, `CONTACTS_EMAIL`, `CONTACTS_PHONE`. (The contacts schema has more system fields — address, company, birthdate, etc.; use the matching `CONTACTS_*` identifier. `SUBMIT_BUTTON` is the identifier for the DISPLAY submit field.)
+  - **⚠️ Custom (non-contact) fields do NOT render in the dashboard via this API.** A field with no matching `CONTACTS_*` identifier (e.g. "medical conditions", "fitness goal", a waiver checkbox) cannot be made to appear in the Wix Forms dashboard through `form-schema-service/v4/forms` — registering a Contacts extended field and referencing its `custom.<key>` does **not** work. Such fields still store submission data correctly (frontend + `fields[]` + submission records) but the owner won't see them in the dashboard UI. **So: for lead-capture forms the request should lean on contact-mappable fields (name / email / phone / address / company / birthdate). If the request genuinely needs custom fields, seed them anyway (data is captured) but do NOT report the dashboard as fully rendering — only the contact-mapped fields will show.** This is a platform limitation, not a seed bug; surface it rather than silently shipping a half-blank dashboard.
+  - Also set `hidden: false` on each field and `readOnly: false` in `inputOptions` (matches the shape shown in the docs).
+
+**⚠️ Do NOT rely on `postSubmissionTriggers.upsertContact` (contact mapping) through this endpoint — it is SILENTLY DROPPED.** The docs' create example includes a `postSubmissionTriggers.upsertContact.fieldsMapping` block to auto-create a CRM contact from a submission. Live, the create returns `200` **but the trigger is not persisted** (absent from a follow-up GET — the same silent-drop pattern as CMS multi-refs at insert). Don't depend on it in the seed. You don't need it: **form submissions are recorded against the schema regardless**, so leads are captured by the seeded form's `formId` on their own. The seed's job ends at the schema + targets.
+
+**⚠️ Reading the response — read the field `target`s from `form.fields[]`; the layout persists under `form.formFields[]` + `form.steps[]`.** A successful create returns `200` with:
+
+```json
+{ "form": {
+    "id": "<formId>",
+    "fields": [
+      { "id": "<field-id>", "target": "first_name", "view": { "label": "First name" }, "pii": true },
+      { "id": "<field-id>", "target": "email", "validation": { "string": { "format": "EMAIL" }, "required": true } }
+    ],
+    "formFields": [ /* the field components incl. the submit button */ ],
+    "steps": [ /* the layout you sent */ ],
+    "namespace": "wix.form_app.form", "name": "Get in touch", "enabled": true
+} }
+```
+
+Read the **`form.id`** (→ the `formId` to keep and hand to the frontend) and each **`form.fields[].target`** (→ the input `name`s the frontend renders). **All** field definitions are normalized into **`fields[]`** (read `target`s here) — but **`formFields[]` only echoes back the components the server materialized: the `SUBMIT_BUTTON` plus each INPUT that carried a recognized `CONTACTS_*` identifier** (see the CRITICAL identifier block above). `steps` echoes the layout you sent. So `fields[]` having all N fields does NOT mean the dashboard will render them — `formFields[]` / summary is the dashboard-truth source. The field `id`s are echoed **lowercased** — which is exactly why you generated them lowercase, so the `steps[].…fieldId`s still match. Downstream, the frontend binds by **`target`**, never by field id.
+
+### STEP 3: Verify each form persisted (mandatory)
+
+A `200` on create is not proof the form is queryable. After creating, **list once** and confirm every seeded form is present with its targets:
+
+`GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form` — for each form you created, confirm its `id` appears, its `fields[].target` set matches what you sent, and its **`steps`** is non-empty (a `steps: []` means the layout didn't persist).
+
+**⚠️ Then verify the dashboard will actually render — call `GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary` and assert `formSummary.fields` is NON-EMPTY and its count equals the number of contact-mapped INPUT fields you seeded.** This is the reliable dashboard-truth check: the summary returns exactly the fields the Wix dashboard shows (i.e. the `formFields[]` components, minus the submit button). A `summary.fields: []` (or a count short of your contact-mapped inputs) means the identifier mapping failed and the dashboard is blank for those fields — **do not report success; fix the `identifier`s (STEP 2 CRITICAL block) and re-create.** Expect the summary count to equal your contact-mappable fields only; if the form has custom (non-`CONTACTS_*`) fields, they will be legitimately absent from the summary (platform limitation) — call that out in the handoff rather than treating it as a pass or a hard failure.
+
+If a form is missing, its layout didn't persist, or its summary is unexpectedly empty, re-create it once and re-verify; if it still fails, surface the response verbatim rather than reporting success.
+
+**Keep** per form: the **`formId`** and the ordered list of field **`target`** keys (with each field's label and `required`) — that map is the producer for the coding handoff (the frontend sets each input's `name` = `target` and submits against the `formId`).
+
+---
+
+## Conclusion
+Following these steps **in order** sets up a Wix Forms backend:
+- Starts from a **clean form list** — any pre-existing form (the install's occasional default "Get in touch") is listed-then-deleted first (a safe no-op when none exists), avoiding the silent name-collision auto-suffix when a default is present.
+- Contains exactly the forms the request calls for, each created in the **`wix.form_app.form`** namespace with unique, non-empty, immutable **`target`** keys per field.
+- **Every field carries a `stringOptions.validation` block** (`UNKNOWN_FORMAT` for plain text, `EMAIL`/`PHONE`/… otherwise) — without it the field is created but **not submittable** (visitor submissions 400 as "additional properties"). This is what makes the seeded form actually accept the frontend's submissions.
+- Each form is created **with a `steps` layout + a `SUBMIT_BUTTON`**, AND **every INPUT field carries its `CONTACTS_*` system `identifier`** — both are required for the site owner's **Wix dashboard to render** the form and its submissions. A field with no recognized identifier is dropped from `formFields[]`/summary and shows blank (the data is still stored). Custom (non-contact) fields cannot render in the dashboard via this API (platform limitation) — captured as data only.
+- Dashboard rendering is **verified via `GET .../forms/{formId}/summary`** (non-empty, count == contact-mapped inputs), not merely by `steps` being present.
+- Contact-mapping (`postSubmissionTriggers`) is **not** relied upon (silently dropped here); submissions are captured against the schema regardless.
+- Every form is **verified present** via a namespace list before completion.
+- **Keep** per form the `formId` and its field `target` keys — the producer for the coding handoff.

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

@@ -0,0 +1,192 @@
+---
+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`).
+
+**⚠️ 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.
+- **Physical products MUST set `"productType": "PHYSICAL"` and an empty `"physicalProperties": {}`** (on the product and on each variant).
+- **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 `file.url`, then PATCH the product.
+
+**The exact working call — do this per product (getting it right first time avoids a multi-round debug loop):**
+
+1. **`GET https://www.wixapis.com/stores/v3/products/{id}`** → read `revision`, `options`, and `variantsInfo` from **`response.product.*`**. The product is **nested under a `product` key** — the GET response is *not* flat.
+2. **`PATCH https://www.wixapis.com/stores/v3/products/{id}`** with the body below. **⚠️ Everything nests under a `product` wrapper.** Putting `id` / `revision` / `media` at the **root** fails `400 "product is invalid: revision must not be empty"` — the #1 cause of the loop here. **Do not send a field mask** (the validator runs before masking → `428`):
+
+   ```json
+   {
+     "product": {
+       "id": "<product id>",
+       "revision": "<revision from the GET — required; omitting it is the 400 above>",
+       "media": { "itemsInfo": { "items": [ { "url": "<static.wixstatic.com/…>", "altText": "…" } ] } },
+       "options":      "<echo the GET's product.options, unchanged>",
+       "variantsInfo": "<echo the GET's product.variantsInfo, unchanged>"
+     }
+   }
+   ```
+   The image may be referenced by a `static.wixstatic.com` **`url`** or by its Wix Media **`id`** (`<hash>~mv2.png`) — either works.
+
+- The field that persists is **`media.itemsInfo.items`**, NOT `media.main`. **⚠️ `media.main` set ALONE silently no-ops** — a `200` comes back but re-query shows no image; that is the trap. The server promotes the first `itemsInfo.items` entry to `media.main` for you, so **verify success by reading `media.main.image.url`** — it must resolve to a `static.wixstatic.com` URL. Check that nested string, **not** the presence of `media.main` (which can be a non-null object with no image and makes a failed attach look successful). Conversely `media.itemsInfo` is **write-only** — it comes back `null` on read, so never assert on it.
+- Send **one image per product** (primary); a larger gallery is out of scope for the seed.
+- **Never block on image failure** — skip and leave the product text-only.
+
+---
+
+## 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.