@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-vibe-headless/references/forms/INSTRUCTIONS.md

@@ -1,487 +0,0 @@
-# Wix Forms — client utils (you build the UI)
-
-**Intent:** contact / enquiry / lead / signup / waitlist / application / feedback / survey / quote
-request / intake or registration — any form a visitor fills in and submits. Whether the submission
-also becomes a CRM contact is a per-field mapping, not a different vertical.
-
-This vertical ships **no UI**: the owner picks the fields in their dashboard, so every form has a
-different field set and no "contact form" component could ship for it. You write one control per
-field — the shipped utils supply the schema behind it, the state, the validation and the submit. Everything runs on the public `WIX_CLIENT_ID`
-(anonymous visitor token) — no SDK, no backend, no elevated credential.
-
-> **⚠️ A visitor-fillable form is FORMS, not CMS.** Wiring one to `insertDataItem` works, and is the
-> wrong call: it gives up the dashboard form builder, spam protection, notifications and contact
-> mapping, and needs the owner to set collection permissions before a visitor can submit at all.
-> Use **`cms`** only when the app must **read the entries back** (a gallery, a listing, "my
-> submissions") — a visitor cannot read Forms submissions. Submit-only → forms.
-
-> **⚠️ "Add a field" is a SCHEMA change.** *"Add a dropdown for job industry"*, *"make the phone
-> optional"*, *"drop the budget question"* — all reads like UI work and all are a `PATCH` to the live
-> schema (`seed/SEED.md`, REVISE): patch it, verify, rewrite `wix-forms.config.js`, **then** wire the
-> control. A field the visitor can fill that isn't in the schema is **silent data loss** — the value
-> reaches no submission, inbox or contact, and the submit still resolves `true`.
-
-## What ships (utils only)
-
-| file | what it is |
-|---|---|
-| `lib/wix-form-schema-utils.js` | **Reading the raw schema** — `orderedInputs`, `submitTextOf`, and per field `targetOf`, `labelOf`, `isRequired`, `validationOf`, `componentOf`, `optionsOf`, `inputTypeOf`, `componentTypeOf`, `choicesOf`, `addressPartsOf`, `phoneCountryOf`, `isMulti`/`isFile`/`isNumber`/`isAddress`. No React, no REST; the hook hands them back as `read`. |
-| `rest/wix-forms.js` | Schema transport: `getForm`, `listForms`, plus `phoneExample` (what a visitor is shown), `normalizePhone` (what goes on the wire), `setSiteCountry`. |
-| `rest/wix-forms-submissions.js` | Write transport: `toSubmissionValues`, `createSubmission`, `SUBMITTED_OK`, the file flow (`getMediaUploadUrl`, `uploadSubmissionFile`, `uploadFormFiles`), `submissionViolations`. |
-| `hooks/useWixForm.js` | The form's non-visual half: `useWixForm(formId)` → `{ form, values, setValues, bind, submit, validate, errors, loading, read }`. Also exports `validateField`, `mapSubmissionErrors`, `FORM_ERROR`. Not on React? Those plus `lib/` are the load-bearing part; port the state around them. |
-| `wix-config.js` *(shared)* | the two ids, written by the install step. |
-| `wix-forms.config.js` *(generated)* | **the gate** — `WIX_FORMS`: each form's `formId` + read-back `targets`, written by the seed after verification. Its one later edit is a verified schema change (REVISE), never a hand-typed field. |
-| `WixManageBanner` *(shared)* | Dev-only manage banner — mount it in your Layout. |
-
-## Prerequisites — a HARD GATE
-
-- **`src/rest/wix-forms.config.js` must exist.** No file → the seed hasn't succeeded → **stop and
-  run the seed**. It's the one vertical whose client can't be built in parallel with its seed.
-- **Never invent a `formId`, and never write that file early.** Its only value is as proof that a
-  verified schema exists; the seed writes it after creating *and* verifying each schema.
-- **The Wix Forms app installed, with at least one form.** This vertical doesn't provision forms.
-- **No permission setup** — unlike CMS, a visitor can read a published form's schema and submit to it
-  out of the box.
-
-## Build the UI
-
-**The schema is the source of truth, whatever the markup looks like.** Every `target`, label,
-`required` flag, constraint and choice option comes from it, and so does the submission map — nothing
-about a field is yours to invent.
-
-**The markup is yours to author.** Write a JSX element per field (step 5) when the layout matters,
-which on a designed page it usually does. Loop over `read.orderedInputs(form)` with a branch per
-control type instead when the owner will keep editing the form, and a dashboard change should reach
-the site with no code touch. The per-field wiring is identical either way.
-
-The JSDoc in `hooks/useWixForm.js` and `lib/wix-form-schema-utils.js` covers what each util does;
-this covers which control a field wants and where the obvious implementation is wrong. Markup and
-styling are yours (on base44: shadcn + `src/index.css`).
-
-### 1 · Load the form
-
-```jsx
-import { useWixForm, FORM_ERROR } from "@/hooks/useWixForm";
-import { WIX_FORMS } from "@/rest/wix-forms.config";   // written by the seed — never by hand
-
-const { form, values, setValues, submit, validate, errors, loading, read } =
-  useWixForm(WIX_FORMS.contact.formId);
-
-const fields = read.orderedInputs(form);   // what the form contains, in the owner's layout order
-```
-
-| | |
-|---|---|
-| `form` | the Form exactly as Wix returned it (`null` until loaded). Nothing stripped or renamed. |
-| `values` | state, keyed by `target`: string for text/choice/date, **array** for multi-choice and files, **object** for an address. Seeded from the schema's defaults. |
-| `setValues` | plain React setter — `setValues((v) => ({ ...v, [name]: value }))`. |
-| `bind(target)` | the props a text-ish control needs, ready to spread: `name`, `value`, `onChange`, `onBlur`, `aria-describedby`, `aria-invalid`. |
-| `submit(event)` | use as `onSubmit`; resolves **`true`** only when the submission was created. |
-| `validate(target?)` | one field, one address subfield, or the whole form. Returns whether it passed. |
-| `errors` | control name → visitor-facing message; `errors[FORM_ERROR]` is form-level. |
-| `loading` | loading the schema (`form` still `null`) **or** submitting (`form` set). |
-| `read` | the schema accessors, so the UI needs one import. |
-
-Fields are the raw objects Wix sent, so anything the accessors don't cover is still on them —
-`pii`, `showLabel`, `buttonText`, `explanationText`, `options[].image`, the `steps[]` a multi-page
-form would need.
-
-**`contact` is this example's key.** The seed names each form — `waitlist`, `quote`, `application` —
-so use the keys `wix-forms.config.js` actually contains.
-
-**Several forms on one page?** The hook loads one schema each. Past two, call
-`listForms({ formIds: [...] })` once (up to 100 ids) and run `orderedInputs` over each result.
-
-**Set the site's country once at app start**, so locale-derived examples match the business, not the
-visitor's browser:
-
-```js
-import { setSiteCountry } from "@/rest/wix-forms";
-setSiteCountry("GB");
-```
-
-### 2 · Render one control per field
-
-Author them or loop over them — every control carries the same four things, and `bind(target)` from
-the hook supplies the first three:
-
-1. **`name` = the field's `target`** — the immutable storage key, and also the state key, the error
-   key and the submission key. Keying everything by it makes the submission right by construction;
-   it's how a blocked submit finds the control to focus, and it drives autofill.
-2. **`value` from `values[target]`, written back through `setValues`.** (A choice group carries
-   `checked` instead; a file input can't be controlled at all and takes only `onChange`.)
-3. **`onBlur` → `validate(target)`** — not on the first keystroke of an untouched field, which
-   reddens a required field before the visitor types. Once flagged, re-check as they type from an
-   **effect on the value**: React hasn't committed the new value when `onChange` runs, so a check
-   there judges the value they just replaced.
-4. **A real `<label>`, and an error node** — see step 6 for the wiring both need. `bind` sets the
-   error node's `aria-describedby`/`id` pair (`err-${target}`); you render the node itself.
-
-**Stamp the schema's constraints as native attributes.** They reinforce the JS checks and drive
-mobile keyboards:
-
-| from the schema | onto the control |
-|---|---|
-| `isRequired(field)` | `required` |
-| `validationOf(field).minLength` / `.maxLength` | `minLength` / `maxLength` |
-| `validationOf(field).pattern` | `pattern` |
-| `validationOf(field).minimum` / `.maximum` | `min` / `max` (number and rating) |
-| `validationOf(field).format` | input `type` — `EMAIL`→`email`, `PHONE`→`tel`, `URL`→`url`, `DATE`→`date`, `TIME`→`time`, `DATE_TIME`→`datetime-local`, else `text`; `isNumber(field)`→`number` |
-| the resolved `type` | `inputMode` — `number`→`decimal`, `tel`/`email`/`url` as themselves; omit for date/time (native picker) |
-| `componentOf(field).placeholder` | `placeholder` |
-| `validationOf(field).fileLimit` | `multiple`, when above 1 |
-| `validationOf(field).uploadFileFormats` | `accept` — map the media kinds a browser knows (`IMAGE`→`image/*`, `VIDEO`, `AUDIO`, `DOCUMENT`); omit `accept` when the owner allows anything |
-| `field.identifier` for `CONTACTS_*` kinds | `autoComplete` — `email`, `tel`, `given-name`, `family-name`, `organization`, `bday`; address subfields take `address-line1`, `address-level2`, `postal-code`, `country` |
-
-**A constrained field with no placeholder gets a synthesized one:** PHONE →
-`phoneExample(read.phoneCountryOf(field))` (that country's regulator-reserved fictional number,
-falling back to the site's), URL → `https://…`. It prevents the `must match format "phone"` rejection
-without a hint line under every field.
-
-#### Which control
-
-`identifier` and `componentType` are **independent axes** — several fields share one component — so
-branch on whichever distinguishes the control, and **never on the `target` name**, which an owner's
-rename silently breaks.
-
-| control | branch on | `values[target]` |
-|---|---|---|
-| `<textarea>` | `field.identifier === "TEXT_AREA"` | string |
-| `<select>` | `read.componentTypeOf(field) === "DROPDOWN"` | string |
-| radios | `read.componentTypeOf(field) === "RADIO_GROUP"` | string |
-| checkbox group | `read.isMulti(field)` | **array** of checked values |
-| address group | `read.isAddress(field)` | **object** keyed by subfield |
-| file / signature | `read.isFile(field)` | **`File` objects** until submit |
-| text / email / tel / url / date / time / number | `validationOf(field).format`, `isNumber` | string |
-
-Two that bite: `componentType` is `TEXT_INPUT` for short **and** long answer, so keying a textarea
-off it renders every long field single-line; and `IMAGE_CHOICE` is indistinguishable from multi
-choice except by `identifier` — it falls out as plain checkboxes, and its pictures are on
-`componentOf(field).options[].image`.
-
-**Coverage check — every field kind an owner can add:**
-
-| dashboard field | `identifier` | renders as | `values[target]` |
-|---|---|---|---|
-| Short answer, Link, Company, Position, Tax ID, First/Last name, Email, single-line Address | `TEXT_INPUT`, `URL_INPUT`, `CONTACTS_*` | text input, `type` from `format` | string |
-| Long answer | `TEXT_AREA` | `<textarea>` | string |
-| Phone | `CONTACTS_PHONE` | `type="tel"` + reserved example | string (E.164 on submit) |
-| Number, Rating | `NUMBER_INPUT`, `RATING_INPUT` | `type="number"` (or your stars) | string in state, number on the wire |
-| Dropdown | `DROPDOWN` | `<select>` | string |
-| Single choice | `RADIO_GROUP` | radios | string |
-| Multi choice, Tag picker, Image choice | `CHECKBOX_GROUP`, `TAGS`, `IMAGE_CHOICE` | checkboxes (or a chip / image control) | **array** |
-| Date, Date picker, Date and time, Time, Birthdate | `DATE_INPUT`, `DATE_PICKER`, `DATE_TIME_INPUT`, `TIME_INPUT`, `CONTACTS_BIRTHDATE` | native date/time input | string |
-| Multi-line address | `MULTILINE_ADDRESS` | fieldset of subfields | **object** |
-| File upload, Signature | `FILE_UPLOAD`, `SIGNATURE` | file input (a signature deserves a canvas) | **`File` objects** |
-| Checkbox, Subscribe checkbox | `CHECKBOX`, `CONTACTS_SUBSCRIBE` | not covered here — `BOOLEAN`, and its label is Ricos rich content, not a string | boolean |
-| Product, Fixed price, Custom price, Donation | `PRODUCT_LIST`, `FIXED_PAYMENT`, `PAYMENT_INPUT`, `DONATION` | not covered here — `PAYMENT` | array of product objects |
-| Appointment | `APPOINTMENT` | not covered here — `SCHEDULING` | appointment object |
-| Service picker, Multi-service picker | `SERVICES_DROPDOWN`, `SERVICES_MULTI_CHOICE` | `<select>` / checkboxes, options from the connected app | string / **array** |
-
-`orderedInputs` returns the uncovered types too — nothing is filtered for you. Write the control, or
-have the owner drop the field; a **required** field you don't render makes the form unsubmittable.
-
-**Display fields never reach this loop.** `RICH_TEXT` blocks and the submit button are
-`fieldType: "DISPLAY"`, so `orderedInputs` drops them. If a form uses rich-content blocks as section
-copy between fields, read them off `form.formFields` yourself — their content is Ricos, not a string.
-
-Wix's [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md)
-is the spec behind this table. `seed/SEED.md` carries the same identifiers from the authoring side
-(which JSON creates each field); this one is the rendering side (which control, which value shape) —
-they join on `identifier`.
-
-#### Controls that need more than an input
-
-**Choice groups** go in a `<fieldset>` with a `<legend>`; the group's `aria-describedby`,
-`aria-invalid` and `aria-required` go on the fieldset, since no single radio can carry them. Options
-come from `read.choicesOf(field)` (`{ value, label }`, label falling back to value). A checkbox
-group's value is an array — toggle values in and out of it.
-
-**A dropdown** needs a disabled `<option value="">` first (state starts empty, so otherwise the first
-real option looks pre-selected); use `componentOf(field).placeholder` for its text.
-
-**An address** is a group whose value is a nested object. Subfields come from
-`read.addressPartsOf(field)` (`{ sub, required }`, hidden `addressLine2` already dropped); name each
-control **`${target}/${sub}`**, which is exactly the server's error path for a nested field, so
-rejections land on the right control with no mapping of your own. Subfield keys are storage keys —
-humanize them (`postalCode` → "Postal code"). **`country` and `subdivision` are country-dependent
-enums the schema doesn't enumerate**: render `country` as a select over ISO-3166 alpha-2 codes,
-narrowed to `validationOf(field).allowedCountries` when set. Keeping `subdivision` free text means
-leaving it optional and relying on the mapped error.
-
-#### File uploads — the value is the upload URL
-
-The hook's `submit` runs this before it sends anything:
-
-1. **`getMediaUploadUrl(formId, filename, mimeType)`** → a signed `uploadUrl`. This Forms-scoped
-   wrapper is what makes a visitor upload possible at all: `site-media` directly needs a Manage-Media
-   credential and 403s for a visitor.
-2. **`PUT` the bytes to it** with the file's `Content-Type`, via plain `fetch` — the URL is
-   pre-signed, and adding the visitor's `Authorization` header turns a working upload into a 400.
-3. **Submit that same `uploadUrl` as the value** — not the CDN URL the upload returns, not a file id.
-   One file submits the string; several submit an array.
-
-So `values[target]` holds `File` objects until submit, and validation checks the count (`required`,
-`fileLimit`) since no string rule applies. Three render consequences: the input can't be controlled
-(wire `onChange`, list the picked filenames yourself); clearing it after success needs a `key` you
-bump in `handleSubmit`, because resetting state leaves the browser's own "1 file selected" text; and uploads run inside
-`loading`, so the button's progress state matters more here.
-
-**A signature** shares `WIX_FILE`, so a file input accepts one — but the honest control is a canvas:
-`canvas.toBlob(...)` → a `File` named `signature.png` in `values[target]`, same upload path.
-
-**Never base64 a file into a value.** It stores no real file and blows past the submission size
-limit. A form with no file field at all is a plan gate — file, signature and payment fields need a
-Core-or-above plan — fixed by the owner's plan, never an inlined blob.
-
-### 3 · Validation — schema-driven on the client, authoritative on the server
-
-`validate(target?)` applies only rules the schema states:
-
-| rule | from |
-|---|---|
-| required | `isRequired(field)` — including a multi-choice or file field with nothing picked, and each required address subfield |
-| length | `validationOf(field).minLength` / `.maxLength` |
-| shape | `.pattern`, and `.format` — EMAIL, PHONE (E.164 after stripping spaces/dashes/parens), URL |
-| range | `.minimum` / `.maximum` on number and rating, parsed before comparing |
-
-Call it as `validate("email")` (the `onBlur` wiring), `validate("address/city")` for one subfield, or
-`validate()` for everything — `submit` already does the last, so reach for it only to gate something
-else. It reads `values`, and it clears what now passes as well as flagging what doesn't. An address
-subfield gets the `required` check only; `country`/`subdivision` content is the server's call.
-
-**Show invalid state on the control**, keyed off the same `aria-invalid` the render sets, so visual
-and assistive-tech state can't drift — no parallel `.has-error` class:
-
-```css
-input[aria-invalid="true"], select[aria-invalid="true"], textarea[aria-invalid="true"],
-fieldset[aria-invalid="true"] { border-color: var(--destructive); outline-color: var(--destructive); }
-.error:empty { display: none; }
-```
-
-**Never key a check on a field's name** (the classic slip: keying the email check on
-`target === "email"`) — derive it from `format` and the schema's constraints, as `validateField`
-does. And a client rule **laxer** than the server's is worse than none: the visitor
-then learns about the problem after a round trip, in Wix's wording instead of yours.
-
-### 4 · Submit
-
-`submit(event)` client-validates → uploads picked files → builds the submission map (empty optionals
-dropped, PHONE normalized to E.164, NUMBER coerced; it walks the *schema*, so a stray key in `values`
-can't reach the API) → creates the submission → maps server violations onto controls and focuses the
-first invalid one. On success it resets `values` to the schema's defaults.
-
-**The resolved `true` is the only success signal there is.** Submissions are write-only from the
-browser — reading them back needs an owner scope and 403s for a visitor. The submission lands in the
-owner's dashboard.
-
-`CONFIRMED`, `PENDING` and `PAYMENT_WAITING` all mean created. A `PAYMENT_WAITING` form leaves the
-visitor a payment step: surface it **inside** the success state, never as a failed submit.
-
-**No captcha** at the default protection level — don't add captcha plumbing speculatively.
-
-### 5 · The whole component
-
-Author one JSX element per field, using the `target`s the seed wrote and the constraints the schema
-states. `bind(target)` supplies the wiring every control shares — `name`, `value`, `onChange`,
-`onBlur`, `aria-describedby`, `aria-invalid` — so a field is a label, a control and its error node:
-
-```jsx
-export default function ContactForm() {
-  const { form, values, bind, setValues, submit, validate, errors, loading, read } =
-    useWixForm(WIX_FORMS.contact.formId);
-  const [sent, setSent] = useState(false);
-
-  async function handleSubmit(event) {
-    setSent(await submit(event));   // true only when the submission was created
-  }
-
-  if (loading && !form) return <p>Loading…</p>;
-  // A form that can't load is a setup problem — say so; never fall through to a hand-built form,
-  // which silently drops real enquiries.
-  if (!form) return <p role="alert">This form isn't available right now. {errors[FORM_ERROR]}</p>;
-  // Swapping the form out is a silent DOM change, so the success state announces itself.
-  if (sent) {
-    return (
-      <div role="status">
-        <h3 tabIndex={-1}>Thank you</h3>
-        <p>We'll be in touch shortly.</p>
-        <button type="button" onClick={() => setSent(false)}>Send another</button>
-      </div>
-    );
-  }
-
-  return (
-    <form onSubmit={handleSubmit} noValidate>
-      <label>
-        <span>Your email<span aria-hidden="true"> *</span></span>
-        <input {...bind("email_a1b2")} type="email" required autoComplete="email" />
-        <p className="error" id="err-email_a1b2" role="alert">{errors.email_a1b2}</p>
-      </label>
-
-      <label>
-        <span>How can we help?</span>
-        <textarea {...bind("message_c3d4")} rows={5} maxLength={500} />
-        <p className="error" id="err-message_c3d4" role="alert">{errors.message_c3d4}</p>
-      </label>
-
-      {/* A choice group carries `checked` rather than `value`, so wire it by hand — same name,
-          same onBlur, and the aria-* on the fieldset because no single radio can hold them. */}
-      <fieldset aria-describedby="err-budget_e5f6" aria-invalid={Boolean(errors.budget_e5f6) || undefined}>
-        <legend>Budget</legend>
-        {["Under £5k", "£5k–£20k", "Over £20k"].map((option) => (
-          <label key={option}>
-            <input type="radio" name="budget_e5f6" value={option}
-                   checked={values.budget_e5f6 === option}
-                   onChange={() => setValues((v) => ({ ...v, budget_e5f6: option }))}
-                   onBlur={() => validate("budget_e5f6")} />
-            {option}
-          </label>
-        ))}
-        <p className="error" id="err-budget_e5f6" role="alert">{errors.budget_e5f6}</p>
-      </fieldset>
-
-      <p role="alert">{errors[FORM_ERROR]}</p>
-      <button type="submit" disabled={loading}>
-        {loading ? "Sending…" : (read.submitTextOf(form) || "Submit")}
-      </button>
-    </form>
-  );
-}
-```
-
-The `target`s (`email_a1b2`, …) come from `WIX_FORMS.<key>.targets` — **never invent or shorten one**,
-since a key that isn't an exact schema `target` 400s the whole submission. Everything else on each
-control comes from that field's schema entry (step 2): its label, its `required`, its length/pattern
-bounds, its choice options. `noValidate` keeps your messages instead of the browser's bubbles; the
-native constraints still drive keyboards and assistive tech.
-
-**Authoring beats looping here**, because the layout is the point: a two-column name row, a budget
-group styled as cards, copy between sections. **Loop instead when the owner will keep editing the
-form** — `read.orderedInputs(form).map(...)` with a branch per control type keeps a dashboard change
-reaching the site with no code touch. Either way the wiring per field is what's above.
-
-Two things the shell doesn't show:
-
-- **Server violations land on controls**, keyed exactly like the client's (`target`, or `target/sub`
-  for an address subfield). The copy comes from the violation's `errorType` plus the field's schema;
-  an unmapped type degrades to safe copy, and Wix's internal `errorMessage` goes to `console.debug`.
-  Only a failure with no per-field violations sets `errors[FORM_ERROR]`.
-- **A required field you didn't render** blocks submit with a message that has no control to display
-  it. Check `read.orderedInputs(form)` against your branches before shipping.
-
-### 6 · Accessibility — the controls are generated, so one slip hits every field
-
-- **The error node renders always**, empty or filled, with `role="alert"` and a deterministic id
-  (`err-${target}`) the control points at via `aria-describedby`. `aria-describedby` alone only reads
-  on focus; conditional rendering (`{error && …}`) destroys the live region entirely. Hide the empty
-  state with CSS.
-- **`aria-invalid` only when invalid** — `undefined`, never `"false"`.
-- **A group's error and `aria-*` go on the `<fieldset>`** — choice groups and addresses have no
-  single control to describe.
-- **Required is programmatic**: the `required` attribute (or `aria-required` on a group) carries the
-  meaning, the `*` is `aria-hidden` decoration. Both, never the glyph alone.
-- **Every control has a real `<label>`** — a placeholder disappears on input and fails contrast.
-- **The success state is announced** (`role="status"`, or focus its heading).
-
-Don't reach for `role="form"`, an `aria-label` on an input that already has a `<label>`, or a custom
-`role="radio"` — native radios in a `<fieldset>` are already a radiogroup.
-
-## Hard rules
-
-- A visitor-fillable form is this vertical, not `cms`.
-- **Never hold a form field in local component state** — a value outside the hook's `values` submits
-  nothing. Adding a field is a schema change: `seed/SEED.md`, REVISE.
-- **Never answer a field request with a dashboard link** — that link is for the owner's own edits.
-- Read and write only through the shipped helpers — never hand-build a Wix Forms URL.
-- Never invent a `target`, label, option or constraint — every one comes from the schema (authored
-  markup included). Never detect a control by its `target` name either.
-- Read fields through the accessors, not by reaching into `inputOptions` — the block names are enum
-  derived, and the accessors map every one of them.
-- Key every control by `target`: `values[target]`, `errors[target]`, `name`. Address subfields use
-  `target/sub`.
-- Derive validation from the schema, and keep every client rule at least as strict as the server's.
-- **Never add `auth.elevate`, a backend function or a connector token to make a form work.** The
-  visitor token reads the schema and creates the submission; the API spec's owner scopes are wrong
-  for the published-site path. This is the most common wrong turn on this vertical.
-- Submissions are write-only from the browser — the resolved `createSubmission` **is** the success
-  signal. Listing entries back needs `cms`.
-- Every status the submit resolves on is a created submission: show the thank-you, and put a payment
-  step inside it. Treating one as failure costs the owner duplicates.
-- Order comes from `steps[]`, not `formFields[]`; take the order only, not the geometry.
-- Render every field `orderedInputs` returns, or confirm what you skip isn't `required`.
-- A file field submits the URL from `getMediaUploadUrl` — never base64, never a Manage-Media
-  credential, never the CDN URL the upload returns.
-- `UNKNOWN_VALUE_ERROR` / `NOT_ALLOWED_VALUE_ERROR` are seed bugs — fix the schema, don't mangle the
-  key or value.
-- Never mock a form. No `formId`, or a form that won't load, is a setup problem to surface.
-- Never show a locale-wrong example, and never submit the reserved one you display.
-
-## Fallback
-
-Three sources answer what this file doesn't: the **JSDoc** in `hooks/useWixForm.js` and
-`lib/wix-form-schema-utils.js`; the **Wix reference** below; and `seed/SEED.md` for how a field was
-authored, and REVISE for changing one. Calling an endpoint the helpers don't wrap is fine via
-`wixApiRequest` — first look up the exact method and body in official Wix API documentation using
-the documentation skill available in your environment; never guess.
-
-- Form object (the shape `form` and its fields arrive in): https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object.md
-- Form Schemas API: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas.md
-- About Form Fields (every field-level rule): https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
-- Form Submissions API: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions.md
-- About Submission Values (per-`inputType` value shapes): https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
-- Validation errors: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction#validation-errors
-- Get Media Upload URL: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/get-media-upload-url.md
-- Uploading to a generated URL: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/upload-api.md
-
-## Not this vertical
-
-An event **RSVP** → `events` (it ships its own registration form). A **bookable service's** form →
-`bookings`. Content the app **lists back** — reviews, galleries, "my items" → `cms`. A form only
-logged-in members may reach → `members` for the gate, forms for the form. `SKILL.md`'s routing table
-is the deciding copy.
-
-## Seeding
-
-Seed per `seed/SEED.md`: it installs the Forms app, creates each schema, verifies it (reads it back,
-checks the dashboard summary, sends and deletes one real submission), then writes
-`src/rest/wix-forms.config.js`. Needs an elevated credential, and **does not run in parallel with the
-client** — see Prerequisites.
-
-**Changing a form that already exists** — a new field, a relabel, a tightened rule — is that doc's
-**REVISE** action: `PATCH` on the current `revision`, re-verify, rewrite the config, wire the
-control. Never a second create.
-
-## Point the user to their dashboard
-
-Substitute the site's `metaSiteId`:
-
-- **Forms list** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-forms`
-- **Form builder** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}` → where
-  the **owner** edits fields; a relabel or new option reaches a looped form with no code change, a new
-  field still needs a control. **Asked to change the form yourself? REVISE, not this link.**
-- **Submissions** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}/submissions`
-  → per form, off its builder path; there's no site-wide submissions page to link
-- **Contacts** — `https://manage.wix.com/dashboard/{metaSiteId}/contacts` → contact-mapped fields
-  create or update a contact automatically.
-
-## Verify
-
-- [ ] `wix-forms.config.js` exists; every `formId` comes from `WIX_FORMS`, none typed by hand.
-- [ ] Every control's `name` inside the `<form>` is a target in `WIX_FORMS.<key>.targets`, and its
-      value lives in the hook's `values` — **no field is backed by local state**.
-- [ ] `WIX_CLIENT_ID` set (not the placeholder).
-- [ ] Looped form: relabel a field in the dashboard, reload, the new label appears with no code
-      change. Authored form: every `target` in the JSX matches `WIX_FORMS.<key>.targets` exactly.
-- [ ] Every field `read.orderedInputs(form)` returns has a control — long answer is a `<textarea>`,
-      choice groups render their options, an address renders its subfields — or what you skipped
-      isn't `required`.
-- [ ] Required fields show inline errors on blur, in your wording, before any round trip.
-- [ ] A deliberately invalid email/phone is rejected inline, on the right control.
-- [ ] A real submission shows the thank-you, then appears in the owner's **submissions inbox** and
-      (for contact-mapped fields) as a **contact**.
-- [ ] Has a file field? Attached a real file, submitted, and opened the attachment from the
-      dashboard — a submission recording an unusable attachment still "succeeds".
-- [ ] Keyboard pass: a blocked submit focuses the first invalid control, errors are announced, every
-      control has a real label.
-- [ ] No `auth.elevate`, backend function or connector token in the submit path.