@wix/agent-skills 1.35.1 → 1.36.1

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

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

@@ -1,288 +0,0 @@
----
-name: "Setup Forms"
-description: Initializes a Wix Forms backend with Form Schemas v4 for any visitor-fillable form — contact, survey, application, waitlist or custom data capture — by cleaning the install's sample forms, creating one form schema per requested form, then verifying each renders via the form summary; revises an existing form with `PATCH` + its `revision`. Specifies the *how* (calls + format); which forms and what they collect 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. Wix Forms backs
-**any form a visitor fills in** — a contact or enquiry form, a signup or waitlist, an application, a
-feedback form or survey, a quote request, an intake or registration questionnaire, or any custom data
-capture. Lead capture is the most common case, not the only one: the schema is a generic
-field-definition store, and whether a submission becomes a CRM contact is just the optional per-field
-`contactMapping` (STEP 2). This recipe is for **initial backend setup ONLY**, not for coding the
-frontend.
-
-> **Two boundaries.** Forms does **not** own **RSVP to an event or occasion** (that is the `events`
-> vertical, which ships its own registration form) or the **per-service booking form** (`bookings`).
-> Route there when an event or a bookable service is involved; use `forms` for everything else.
-
-> **This recipe is the *how*, not the *what*.** How many forms, and what each one collects, come
-> from the request you're fulfilling. This recipe only specifies the calls and the request format;
-> it does not decide which forms to create.
-
-> **API surfaces:** Wix Forms is a **standalone CRM API**. A form **schema** (the field definitions)
-> lives on **Form Schemas v4** at `https://www.wixapis.com/form-schema-service/v4/forms` — docs
-> portal **CRM ▸ Forms ▸ Form Schemas**, *not* 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).
->
-> **API reference:**
-> - Create Form: <https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/create-form> — its
->   examples are complete requests for common form types (contact, survey, order, booking, …). Copy
->   the one closest to what you need.
-> - About Form Fields:
->   <https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields>
-> - Form object: <https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object>
-
----
-
-## Article: Steps for Setting Up Wix Forms
-
-**⚠️ 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 keeps you clear of the site's low form cap.
-**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&fieldsets=METADATA`,
-   then again with `&enabled=false`. Collect every `form.id` from both responses (`forms[].id`).
-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 — the form cap.** Leftovers plus your new forms can
-exhaust the site's form allowance (read it from
-[List Forms Providers Configs](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms-providers-configs)),
-which is also why you must **never create throwaway forms to probe the shape.**
-
-> **⚠️ `providers-config` tells you which namespaces the site can create in — NOT its limits.** A
-> provider app declares `restrictions` **once, for all sites**, in its app dashboard; the Wix Forms
-> app separately derives the site's real form/field/step limits from its **premium plan** and
-> enforces them on every create. (A missing `restrictions` means default platform limits, not
-> unlimited.) That is why free and unpublished sites report `maxFields: 150` / `maxForms: 150` here
-> while the create rejects with `Field count reached its limit of 10` and
-> `Steps count reached its limit of 3`. **The create call is the only authority** — when it returns
-> a count error, go to "Plan gates" below.
-
-### STEP 2: Create each form schema
-
-**One POST per form** to `https://www.wixapis.com/form-schema-service/v4/forms`. How many forms, and
-each form's fields and labels, come from the request you're fulfilling; this step gives the call and
-the required format. Forms are independent (no shared revision), so concurrent creates are safe.
-
-**Every body carries `"namespace": "wix.form_app.form"`** — the same literal the reads below take as
-their required `?namespace=`. A form created under anything else is reachable over the API and
-invisible in the dashboard and Editor.
-
-**⚠️ Generate every `id` in the shell as a lowercase UUID v4 — never type one from memory**
-(`uuidgen | tr 'A-Z' 'a-z'`). Supply them at create rather than omitting them: `steps` must
-reference each field by `fieldId` in the same request.
-
-**Assemble the request** from the closest Create Form example, building each `formFields[]` entry —
-including the `SUBMIT_BUTTON` — per
-**[About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields)**,
-which owns every field-level rule, including placing every field in the layout — **with one
-documented gap: where `required` goes (next paragraph). The guide never says, so don't infer it from
-its "Validation" section.**
-**Geometry (`row`/`column`/`width`) does not matter on headless** — the frontend renders its own
-layout from `formFields[]` and never reads `steps[].layout` (`how-to-code-forms.md`) — so the layout
-is a *correctness* requirement, not a design one: assert presence and coverage only. Use a single
-step unless the request needs multiple pages.
-
-**⚠️ `required` goes at `inputOptions.required` — NOT inside the field's `validation` block.** It sits
-beside `target`/`inputType`:
-
-```jsonc
-"inputOptions": {
-  "target": "first_name",
-  "required": true,                                    // HERE — beside target/inputType
-  "pii": true,
-  "contactMapping": { "contactField": "FIRST_NAME" },  // per field; this is what creates the contact
-  "inputType": "STRING",
-  "stringOptions": {
-    "validation": {},                                  // always present, even empty — never `required`
-    "componentType": "TEXT_INPUT",
-    "textInputOptions": { "label": "First name", "showLabel": true }
-  }
-}
-```
-
-A `required` key inside `stringOptions.validation` — or any `<inputType>Options.validation`, since no
-input type's validation object defines it — is **accepted at create and then silently discarded**:
-`200`, the form lists, the summary returns every field, and every field still reads back
-`required: false`. The form ships publicly with nothing mandatory and **no error anywhere in the
-response**, so STEP 3's read-back diff is the only signal. `validation` carries value constraints
-only (`format`, `enum`, `minimum`, `minLength`, `items`). The lone exception is the multi-line address
-field, whose per-subfield flags genuinely live at
-`addressOptions.validation.fields.<sub>.required`.
-
-**⚠️ Any example value you author into the schema follows the site's country, not your default.** A
-`placeholder` (or label/hint) carrying a phone number, postcode, currency or date is **visible to
-every visitor**, so a `+44`- or US-shaped example on a site in another market is a locale bug. Resolve
-the site's country and, for an illustrative phone number, take it from that country's
-regulator-reserved fictional range — the resolution order and the vetted per-country map live in
-`how-to-code-forms.md` ("Validation"). Leaving a constrained field's `placeholder` empty is fine: the
-frontend synthesizes the example from the field's `format` at render time.
-
-**⚠️ A `200` proves nothing: always run STEP 3.** Most mistakes here are accepted at create and only
-surface in the dashboard or on the first real submission.
-
-#### Plan gates — surface the choice, never engineer around it
-
-Three plan-tier limits return a real `400` on create. **Do not work around any of them; tell the user
-to reduce or upgrade.**
-
-- **Field count — two caps, counting different things.** `Field count reached its limit of N` is the
-  **premium** cap the Wix Forms app enforces from the site's plan, and it counts **`INPUT` fields
-  only** (display elements and the `SUBMIT_BUTTON` don't count). `FORM_FIELDS_COUNT_EXCEEDED` /
-  `FIELDS_COUNT_RESTRICTIONS_ERROR` is the schema-service cap, which counts **every** field
-  including display elements. **Do NOT split the form into multiple schemas** to dodge either — that
-  trades one submission record for several and consumes more of the site's form allowance. Reduce
-  the field count, or upgrade.
-- **`Steps count reached its limit of N`** — the premium cap on `steps.length`. Collapse the form
-  into fewer pages, or upgrade. Conditions (`formRules`) are capped the same way. Neither has a
-  schema-service equivalent, so neither appears in the Create Form error table.
-- **`FILE_UPLOAD_RESTRICTIONS_ERROR`** — a file upload, signature, or payment field on a plan below
-  Core. **Do NOT suggest inlining files as base64** — it stores no real file, gives the owner nothing
-  usable, and blows past submission size limits. Drop the field, or upgrade.
-- **`FORMS_COUNT_RESTRICTIONS_ERROR`** / **`NAMESPACE_FORMS_COUNT_EXCEEDED`** (and
-  `NAMESPACE_DELETED_FORMS_COUNT_EXCEEDED` for the trash bin) — the site hit its plan's total-form cap. Upgrade, or free a
-  slot (STEP 1's list-then-delete — but only delete forms that are clearly install sample data; ask
-  before deleting anything that could be the owner's real form).
-
-**⚠️ A plan gate is a HARD BLOCK on the run — not a soft "record it and continue" precondition like
-paid tickets or online reservations.** Those leave a working schema and fail only at runtime; here the
-schema doesn't exist, so its `formId`/field `target`s don't either. **Put the choice to the user
-(reduce, or upgrade — with the MSID + dashboard link), wait for their confirmation, then create and
-verify the schema (STEP 2 → STEP 3) BEFORE any frontend work.** Do **not** build the frontend "in the
-meantime": its inputs bind to those targets, so every binding would be a guess to rewrite.
-
-Read `form.id` from the response as the `formId` to keep.
-
-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.
-
-### STEP 3: Verify each form persisted (mandatory)
-
-A `200` on create is not proof the form is queryable or that the dashboard will render it.
-
-1. **List once** —
-   `GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds=<id1>&formIds=<id2>`
-   — **`formIds` narrows the list to exactly the forms you just created**, so you assert against them
-   directly instead of filtering a whole-namespace listing. For each form, confirm its `id` appears,
-   its **`formFields[]`** covers every field you sent, and its **`steps` is non-empty and places
-   every field** (per About Form Fields). **Also diff every field's `inputOptions.required` against
-   what you sent** — a misplaced `required` is dropped silently (STEP 2), and this read-back is the
-   only signal. If a flag came back `false`, fix it with STEP 4's `PATCH` (moving the flag to
-   `inputOptions.required`) rather than deleting and re-creating: the `formId` survives and it costs
-   no extra slot against the form cap.
-2. **⚠️ Then verify the dashboard will actually render —
-   `GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary` and assert
-   `formSummary.fields` is NON-EMPTY**, with a count equal to **every input field you sent** (i.e.
-   `formFields[]` minus the `SUBMIT_BUTTON`). A 6-input form returns all 6 — **including non-contact
-   `DROPDOWN` and `TEXT_AREA` fields** — so do *not* expect only the contact-mapped ones. This is
-   the dashboard-truth check for *placement*. A `summary.fields: []`, or a count short of your
-   inputs, means the form renders blank (or partly blank) for the owner even though the public site
-   submits fine — **do not report success; fix the layout placement or the GUID casing and
-   re-create.**
-
-   **⚠️ This step does NOT prove the `identifier`s are right, so check them in step 1.** An
-   unrecognized `identifier` is accepted and stored: it comes back in `formFields[]` and accepts
-   submissions, so every API-level check passes — but the **Wix Forms editor cannot render a field
-   it doesn't recognize**, so the owner can't see or edit it, and a form built entirely from
-   invented identifiers opens **empty** in the editor. Whether such a field is also omitted from
-   `formSummary.fields` is unverified, so don't rely on this count to catch it. Assert every
-   returned `formFields[].identifier` against the known values in About Form Fields — a plain string
-   comparison, no extra call.
-
-3. **⚠️ If the form has a multi-choice ARRAY field (`CHECKBOX_GROUP` / `TAGS`), the two checks above
-   are NOT enough — send one real `createSubmission`.** A malformed `arrayOptions.validation.items`
-   (missing `itemType`, or an empty/omitted `items`) still lists fine and still counts in the
-   summary, so steps 1–2 pass while **every** submission to the form `400`s form-wide (see "Choice
-   fields"). The only proof is a live submission:
-   `POST https://www.wixapis.com/form-submission-service/v4/submissions` with the standard call
-   shape (`<AUTH>`, `Content-Type`, `wix-site-id`) and a minimal valid body — `formId` plus a
-   `submissions` map keyed by each field's `target`, the ARRAY field as an **array** of enum values:
-
-   ```jsonc
-   { "submission": { "formId": "<formId>",
-       "submissions": { "email": "test@example.com", "multi_choice": ["Option 1"] } } }
-   ```
-
-   Assert it returns `200`, not `400 SUBMISSION_VALIDATION`. A `400` here means the ARRAY `items`
-   shape is wrong — fix it (both `itemType` and `stringOptions.enum`) and re-create. Delete the test
-   submission afterward
-   (`DELETE https://www.wixapis.com/form-submission-service/v4/submissions/{submissionId}`, the `_id`
-   from the response) so the owner's dashboard stays clean.
-
-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.
-
-### STEP 4 (when revising): update an existing form
-
-To change a form the request has since revised — add a field, relabel one, tighten a rule — follow
-[Update Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form):
-
-```
-GET   https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}
-PATCH https://www.wixapis.com/form-schema-service/v4/forms/{formId}
-{ "form": { …the whole object you just read, with your change…, "revision": "<its current revision>" } }
-```
-
-**Read the form back first** — the `PATCH` needs its current `revision`, and `formFields` is replaced
-wholesale (anything missing from the array you send moves to `deletedFormFields`), so the read-back
-*is* the body. The read needs the **required** `?namespace=wix.form_app.form`; without it it `400`s
-with `namespace must not be empty` — a violation naming a field, so it misreads as a body problem.
-
-**Prefer updating over delete-and-recreate.** An update keeps the `formId` the handoff already
-carries and consumes no additional slot against the site's form cap. **Re-run STEP 3 after any update**
-— it can regress the layout or the dashboard summary exactly as a create can.
-
----
-
-## Keep — what crosses into the handoff
-
-**Per form: the `formId` + each form's field `target` keys.**
-
-The `target`s are *structural* — the frontend binds each input's `name` to a field's `target` to
-submit (the same carve-out shape as cms's `collectionId` + field keys). Everything else — the field
-set, order, labels, `required` flags, validation formats and dropdown options — is **read live from
-the schema at render time** (visitor token, no `auth.elevate` — `how-to-code-forms.md`), so a field
-the owner adds, removes or relabels reflects on the site with no code change. See
-`SDK_HANDOFF.md` §4.
-
----
-
-## Conclusion
-
-Following these steps **in order** sets up a Wix Forms backend:
-
-- Starts from a **clean form list** — pre-existing forms are listed-then-deleted first (a safe no-op
-  when none exist), keeping clear of the site's form cap.
-- Contains exactly the forms the request calls for, created on **Form Schemas v4** in the
-  **`wix.form_app.form`** namespace, each field built per **About Form Fields**, with lowercase GUID
-  ids and a `steps` layout placing every field plus a `SUBMIT_BUTTON`.
-- Is **verified via `GET .../forms/{formId}/summary`** (non-empty, count equal to every input field
-  — contact-mapped or not) — not merely by a `200` on create, and not merely by `steps` being
-  present.
-- Revises forms with **`PATCH` + the current `revision`** rather than delete-and-recreate, keeping
-  the `formId` and the form slot.
-- **Keeps** per form the **`formId` + field `target`s** (the immutable submission keys) — the
-  frontend reads everything else (labels, options, order) live from the schema.