@wix/agent-skills 1.18.0 → 1.18.1

package/skills/wix-manage/references/forms/forms-dashboard-navigation.md

@@ -1,6 +1,6 @@
 ---
 name: "Forms Dashboard Navigation"
-description: "Builds direct links to Wix Forms dashboard pages on manage.wix.com — the forms list, the submissions table, the form builder for a specific form, standalone forms, templates, and forms settings. Pairs each main Forms entity (form, submission) with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+description: "Builds direct links to Wix Forms dashboard pages on manage.wix.com. The paths are not guessable and appear in no API reference, so take them from here: under `https://manage.wix.com/dashboard/{metaSiteId}/`, the forms list is `wix-forms`, a form's builder is `wix-forms/form/{formId}`, and that form's submissions are `wix-forms/form/{formId}/submissions` — there is no site-wide submissions page, and nothing lives under `contacts/forms`, `forms`, `form-builder` or `wix-forms-and-payments` (the legacy app). Also standalone forms, and each Forms entity paired with its read API so you can fetch one and hand back a 'view it in your dashboard' link."
 ---
 
 # Forms Dashboard Navigation
@@ -9,36 +9,39 @@ Build direct links into the Wix Forms pages of a site's dashboard. For the gener
 
 ## Main Pages
 
+**Never goess or answer a Forms dashboard-link request from memory** because the routes below are the only correct ones.
+
 | Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
 |---|---|---|
 | Forms list | `wix-forms` | All forms on the site |
 | Form builder | `wix-forms/form/{formId}` | Edit a specific form (fields, rules, submit settings) |
+| Submissions | `wix-forms/form/{formId}/submissions` | That form's submissions table |
 | Standalone form | `wix-forms/standalone-form` | Create a standalone form (has its own shareable page, not embedded in a site page) |
-| Submissions | `wix-forms-and-payments/submissions` | Submissions table across forms |
-| Templates | `wix-forms-and-payments/templates` | Create a form from a template |
-| Forms settings | `wix-forms-and-payments/settings` | Forms-level settings |
 
-Two URL namespaces appear here because the forms management pages and the form builder are registered by two apps (`14ce1214-b278-a7e4-1373-00cebd1bef7c` and `225dd912-7dea-4738-8688-4b8c6955ffc2`); `wix-forms` also redirects to the forms list, so it's the stable entry point.
+**Every Forms page is under `wix-forms`** — the namespace **Wix Forms (New)** `225dd912-7dea-4738-8688-4b8c6955ffc2` registers, the app that owns the Form Schemas v4 API. A `wix-forms-and-payments/...` path belongs to the legacy **Wix Forms (Old)** app `14ce1214-b278-a7e4-1373-00cebd1bef7c`: don't build one, and never install or target that app (see [Create Form](./create-form.md) § Silent breakers).
+
+**Submissions are per form**, hanging off that form's builder path — there is no site-wide submissions page to link to. With no `{formId}` in hand, link the forms list and let the owner pick.
 
-Entity-specific links (`{formId}`) accept the entity's ID appended as an extra path segment. Query params can follow.
+Entity-specific links (`{formId}`) take the entity's ID as a path segment, and query params can follow. The dashboard appends its own view state to the submissions URL — `folder` (a JSON-encoded breadcrumb), `sort` (e.g. `createdDate+desc`) and `selectedColumns` (a comma-separated list of field **`target`**s) — none of which you need to construct: the bare path opens the table with the owner's defaults.
 
 ## Pairing Entities with Their Read APIs
 
-Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header. Dashboard forms use the `wix.form_app.form` namespace.
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header. Dashboard forms live in the **`wix.form_app.form`** namespace — every Forms call that takes a namespace, as a query parameter or inside a filter, takes that exact value.
 
 | Entity | Read API | Dashboard link |
 |---|---|---|
 | Form | `GET /form-schema-service/v4/forms` · `POST /form-schema-service/v4/forms/query` · `GET /form-schema-service/v4/forms/{formId}` | `wix-forms/form/{formId}` (edit) or `wix-forms` (list) |
-| Submission | `POST /form-submission/v4/submissions/namespace/query` (filter must include the `namespace`) · `GET /form-submission/v4/submissions/{submissionId}` | `wix-forms-and-payments/submissions` |
+| Submission | `POST /form-submission-service/v4/submissions/namespace/query` (the filter must carry `"namespace": "wix.form_app.form"`) · `GET /form-submission-service/v4/submissions/{submissionId}` | `wix-forms/form/{formId}/submissions` — the `formId` comes off the submission |
 
 Example — after creating a form, hand back its links:
 
 ```
 Created "Contact Form".
 Edit it here: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}
-See submissions: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms-and-payments/submissions
+See submissions: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}/submissions
 ```
 
 ## Notes
 
-- Creating forms via the [Create Form](./create-form.md) recipe (Form Schemas API) makes them appear in the forms list above.
+- Creating forms via the [Create Form](./create-form.md) recipe (Form Schemas API) makes them appear in the forms list above — **but only when the form was created under the `wix.form_app.form` namespace with Wix Forms (New) installed.** A form created under any other namespace is reachable over the API and completely absent from these pages.
+- **Before handing back a `wix-forms/form/{formId}` link, confirm the form actually renders**: `GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary` must return a non-empty `formSummary.fields` whose count matches every input field. An empty summary means the owner will open this link to a blank form (Create Form, STEP 3).

package/skills/wix-manage/references/forms/update-form.md

@@ -0,0 +1,122 @@
+---
+name: "Update Form"
+description: "Changes a Wix form that already exists, with Form Schemas v4 `PATCH` — add a field to my form, add a dropdown, make a field required or optional, rename a label, reorder or retire a question. Covers reading the form back for its `revision` (and the required `namespace` query parameter), the whole-form body that a `PATCH` needs, the wholesale `formFields` replace that silently soft-deletes anything you omit, changing a field's component type in place, retiring a field that already has submissions, and the read-back that proves what was stored. Use whenever the form exists and the request changes what it collects; use Create Form when there is no form yet."
+---
+# RECIPE: Update a Wix Form
+
+> **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>` when the token is account-scoped.
+
+Change what a form collects — **add a field, relabel one, tighten a rule, reorder, retire one** — on a form that already exists. **Composing the field itself is not here**: [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) owns the `identifier` / `inputType` / `componentType` table and the options/enum shapes, and [Create Form](./create-form.md) § Silent breakers apply to an added field exactly as to a created one.
+
+**A `PATCH`, never a delete-and-recreate.** An update keeps the `formId` everything downstream already holds — a frontend binding, an automation, a saved dashboard view — and spends no slot against the site's form cap.
+
+---
+
+## The call
+
+```bash
+# 1 · read the form back: you need its current revision, and every field you intend to keep
+curl -X GET \
+  'https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}' \
+  -H 'Authorization: <AUTH>'
+
+# 2 · send that form back with your change applied
+curl -X PATCH \
+  'https://www.wixapis.com/form-schema-service/v4/forms/{formId}' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{ "form": {
+      "id": "{formId}",
+      "revision": "<the revision you just read>",
+      "name": "<the form name>",
+      "namespace": "wix.form_app.form",
+      "formFields": [ ...every field, with your change applied... ],
+      "steps": [ ...every step, with the layout item for a new field... ]
+  } }'
+```
+
+- **⚠️ `namespace` is a REQUIRED query parameter on the read, and this is what a revise run trips over.** Without it the read returns `400 namespace has size 0, expected 10 or more, namespace must not be empty` — a violation naming a *field*, so it reads like a body problem. Fix the call, don't reshape the payload. (The filter on `POST .../v4/forms/query` needs it too.)
+- **The read-back is the body.** Apply your change to what the `GET` returned and send that as `form`. `namespace` is **immutable** and travels along; **there is no `fieldMask`**, and no `revision` outside `form` — inventing either is a silent partial write.
+- **⚠️ Append to `formFields`; never rebuild the entries you read.** `[...form.formFields, newField]` works. Mapping the array to "clean up" each field — dropping `fieldType`, re-shaping an options block — fails with `fieldType cannot be provided with any these fields: input_options, display_options` on **every** field at once. The read-back's field objects are already a valid write shape: pass them through untouched and touch only the one field you are changing.
+- **`formFields` is replaced wholesale.** Wix: *"Any field that's missing from the array you send is moved to `deletedFormFields`, so resend every field you want to keep."* Same for `steps[].layout` — miss an item and that field goes unplaced, which renders empty. Drops are recoverable from `deletedFormFields`, but nothing announces them.
+- **A stale `revision` is rejected** — re-`GET` and re-apply; never guess or increment it.
+- **Plan caps apply to an added field.** `Field count reached its limit of N` on a `PATCH` is the site's premium cap: reduce or upgrade, with the choice put to the user ([Create Form](./create-form.md) § Plan caps). Never split the form across schemas to dodge it.
+
+---
+
+## Adding a field
+
+**Start by reading [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) § Field types and § Choice fields** for the field kind you're adding: it gives the `identifier` / `inputType` / `componentType` triple — take all three from one row, and note that a dropdown or radio is `inputType: "STRING"` — plus the options/enum shape and the GUID every option needs. [Create Form](./create-form.md) § Choice fields carries a complete dropdown body to copy. Composing a field from memory is what turns one `PATCH` into eight.
+
+Then four things are yours to generate:
+
+- **`id`** — a fresh lowercase GUID (`uuidgen | tr 'A-Z' 'a-z'`), unique in the form.
+- **`target`** — the immutable submission key, unique across the form: snake_case plus a short random suffix (`job_industry_7f2b`). **A duplicate `target` is accepted and silently stores nothing** for every field but one.
+- **one GUID per choice option** — `options[]` each need their own, exactly like the field's; a readable slug is rejected ([Create Form](./create-form.md) § Choice fields). Generate them with `uuidgen`, never by hand.
+- **the choices, declared twice** — every option needs `id` + `value` + `label`, and `validation.enum` must list every one of those `value`s. **An empty `validation` is a free-text field, not a dropdown**; the general "always include `validation`, even as `{}`" rule does not apply here, and getting it wrong is accepted with a `200`.
+- **the layout item** — append to `steps[<n>].layout.large.items`, mirroring into `medium` / `small` if the form has them:
+
+```json
+{ "fieldId": "<the new field's id>", "row": <next row>, "column": 0, "width": 12, "height": 1 }
+```
+
+A field missing from the layout isn't dropped, but it sorts last and has no defined position in the owner's builder. To place it mid-form, insert at that `row` and bump every item at or after it — `row` restarts at 0 in each step.
+
+**A choice field's `identifier` is its kind** — `DROPDOWN`, `RADIO_GROUP`, `CHECKBOX_GROUP`, `TAGS` — never `TEXT_INPUT`, which is accepted and stored as a plain text input ([Create Form](./create-form.md) § Choice fields).
+
+---
+
+## The other changes
+
+| Change | How |
+|---|---|
+| Label, placeholder, options, validation, order | Patch them and stop — nothing downstream needs updating |
+| A field's component type, in place | Send that field with the **choice `identifier`** and only the new options block; leaving `textInputOptions` beside `dropdownOptions` reads back as the text-input fallback |
+| Retire a field the form has submissions for | Set `hidden: true` — "hidden from submitters": the field stops rendering, and the submissions already collected under it keep their meaning. Dropping it from the array soft-deletes it instead |
+| Remove a field added by mistake this run | Drop it from `formFields`; it lands on `deletedFormFields` |
+| Rename a `target` | **Never.** It is the storage key, so a rename orphans every submission already collected under the old one. Change the *label* instead |
+
+---
+
+## Verify — an update regresses a form exactly as a create can
+
+**A `200` on the `PATCH` proves the body parsed, nothing about what was stored.** Read the form back, every time:
+
+```
+GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}
+GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary
+```
+
+Assert on that read-back, not on the `PATCH` response:
+
+- the changed field is there, carrying the `identifier` and `componentType` you sent — **a choice field with a non-empty `options[]`**, which is where a dropdown that degraded to a text input shows up;
+- every field you meant to keep is still present, and every `inputOptions.required` still reads back as sent;
+- `formSummary.fields` still holds one entry per input field — that is what the owner's dashboard renders.
+
+Then hand back the dashboard links ([Forms Dashboard Navigation](./forms-dashboard-navigation.md)): the form builder at `wix-forms/form/{formId}`, and that form's submissions at `wix-forms/form/{formId}/submissions`. New submissions carry the new field; past ones don't.
+
+---
+
+## Troubleshooting
+
+| Error / symptom | Cause | Fix |
+|---|---|---|
+| `400 namespace has size 0, expected 10 or more` / `namespace must not be empty` on a read | The `namespace` **query parameter** was omitted — it is required on every listing read, and the violation naming a field makes it look like a body problem | Add `?namespace=wix.form_app.form` to the read; leave the payload alone |
+| `fieldType cannot be provided with any these fields: input_options, display_options` — on every field | The read-back's `formFields` were re-mapped or "cleaned" before sending | Send the fields exactly as read and append the new one: `[...form.formFields, newField]` |
+| `inputType enum must be in [UNKNOWN_INPUT_TYPE, STRING, NUMBER, …]` | An invented `inputType` such as `ENUM` (with an `enumOptions` block) for a choice field | A dropdown or radio is `inputType: "STRING"` with `stringOptions.componentType`; multi choice is `ARRAY` |
+| The `PATCH` is rejected for a `revision` mismatch | Someone (or an earlier call) updated the form since your read | Re-`GET` and re-apply the change; never increment the revision yourself |
+| Fields that were on the form are gone after the update | `formFields` was sent partial — the omitted fields moved to `deletedFormFields` | Re-send them in a further `PATCH`, from `deletedFormFields` in the read-back; always send the whole array |
+| Surviving fields render empty for the owner | `steps[].layout` was sent without their items | Re-send every layout item, including `SUBMIT_BUTTON`'s; re-verify with `/summary` |
+| The added dropdown/radio reads back as a text input with `textInputOptions` | `identifier` was `TEXT_INPUT` rather than the choice kind — `componentType` alone doesn't route the renderer | Set `identifier` to the choice kind and re-send. Deleting and re-adding the field with the same `identifier` reproduces it ([Create Form](./create-form.md) § Choice fields) |
+| The update lands but the field never appears in submissions | The new field shares a `target` with an existing one — the server keeps one and the rest store nothing | Give it a unique `target` and `PATCH` again |
+| `Field count reached its limit of N` | The site's premium field cap, counting `INPUT` fields | Reduce, or put the upgrade choice to the user ([Create Form](./create-form.md) § Plan caps) |
+
+---
+
+## Related Documentation
+
+- [Create Form](./create-form.md) — composing fields, the identifier table, choice fields, the layout rules, plan caps
+- [Forms Dashboard Navigation](./forms-dashboard-navigation.md) — the builder and submissions links to hand back
+- [Update Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form) — the `PATCH` contract and its replace semantics
+- [Form object](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object) — `revision`, `hidden`, `deletedFormFields`, `steps[].layout`
+- [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) — every field-level rule

package/skills/wix-manage/references/media/generate-image-with-ai.md

@@ -0,0 +1,86 @@
+---
+name: "Generate an Image with AI"
+description: Generates an image from a text prompt with the Wix AI APIs (Runware). Returns a short-lived URL that must be imported to be kept — importing is Upload Media to Wix's job, and this recipe hands off to it. Covers choosing a model and its cost/latency/content-filter trade-off, the accepted output sizes, per-model batching limits, the AI credit each call spends, and why a content refusal arrives as a success response with no image.
+---
+# RECIPE: Generate an Image with AI
+
+For an image the user does not have. An image they supplied — an attachment or a public URL — is uploaded instead: [Upload Media to Wix](upload-media-to-wix.md).
+
+**API reference:** [About the Wix AI APIs](https://dev.wix.com/docs/api-reference/articles/ai-tools/ai-apis/about-the-wix-ai-apis), *Generating images* — endpoint, auth, and the full model table. Developer Preview, so confirm the contract there.
+
+---
+
+## AI credits
+
+Each call spends roughly **one AI credit**, billed to the site owner, or to the Wix user who installed the calling app. `numberResults: n` spends n. Importing is free.
+
+Generate one image per entity that needs one, and say how many a run will generate before starting it. Regenerate only when the user asks.
+
+---
+
+## Step 1: Generate
+
+```bash
+curl -X POST 'https://www.wixapis.com/runwareschemaless/v1/request' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-H 'wix-site-id: <METASITE_ID>' \
+-d '[{
+    "taskType": "imageInference",
+    "taskUUID": "3f8c1e42-9b7a-4d16-8a5e-2c0f7b9d4e11",
+    "outputType": "URL",
+    "outputFormat": "PNG",
+    "positivePrompt": "a ceramic pour-over coffee dripper on a walnut counter, morning light",
+    "width": 1024,
+    "height": 1024,
+    "model": "runware:400@1",
+    "numberResults": 1
+}]'
+```
+
+| Parameter | Value |
+|---|---|
+| `taskUUID` | A real UUIDv4. Anything else returns `400 invalidTaskUUID` |
+| `width` / `height` | `1024×1024` (square — products, services, menu items), `1376×768` (16:9 hero), `1200×896` (4:3 editorial). Free-form sizes return 400 |
+| `model` | See below |
+| `numberResults` | `1` |
+
+Omit `steps` and `CFGScale`: Runware accepts them, other models return `400 unsupportedParameter`.
+
+### Models
+
+| `model` | Latency | Content filter |
+|---|---|---|
+| `runware:400@1` | ~5s | Loosest — the default |
+| `google:4@2` | ~25s | Medium, best fidelity |
+| `bfl:5@1` | — | Strictest; refuses trademark-ish prompts |
+
+Any Runware-supported model works — the reference's *Suggested models* table has the current AIR IDs.
+
+### Read the response
+
+```json
+{ "data": [ { "imageURL": "https://im.runware.ai/image/ws/2/ii/<id>.png" } ] }
+```
+
+**A refusal is a success response with no `imageURL`** — test for the field, not the status. On a refusal, reword the prompt or switch model, and report the image as not created.
+
+---
+
+## Step 2: Import
+
+`imageURL` expires, so import it as it lands. [Upload Media to Wix](upload-media-to-wix.md) owns that endpoint and its `PENDING` / `READY` rules; pass the `imageURL` as `url` and `image/png` as `mimeType`.
+
+The result is the returned `file.id` / `file.url` — permanent, and what an entity field takes.
+
+---
+
+## Batches
+
+`runware:400@1` and `bfl:5@1` take several tasks in one body. `google:4@2` returns 504 at three or more, so fire parallel single-task requests for it.
+
+Failure is per image: attach the ones that succeeded, create the rest of the entities text-only, and name which entities have no image and why. A failed image stays missing rather than being swapped for another.
+
+---
+
+For JavaScript callers there is an SDK path — `generateImage()` from the Vercel AI SDK with `runware.image(...)` from `@wix/ai`: [Set up the Wix AI SDK](https://dev.wix.com/docs/api-reference/articles/ai-tools/ai-apis/set-up-the-wix-ai-sdk).

package/skills/wix-manage/references/stores/create-product-catalog-v3.md

@@ -20,6 +20,19 @@ Canonical example:
 - Assistant: “What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.”
 - Result: **Stop. Do not request structured product fields yet.**
 
+## Sections
+
+- [Preflight](#preflight-respond-and-return-before-mutation) — whether this turn may mutate at all, and what to answer when it may not
+- [Core flow](#core-flow) — the order the rest of this recipe runs in
+- [Choose the endpoint](#choose-the-endpoint) — single vs bulk, with or without inventory
+- [Build each product](#build-each-product) — the product object: type, media, options, variants, prices, SKUs
+- [Generated descriptions and SEO](#generated-descriptions-and-seo) — what copy written from an image may claim
+- [Add images](#add-images) — uploading a supplied image, or generating one
+- [Wrap the request](#wrap-the-request) — the envelope the chosen endpoint expects
+- [Request projected media](#request-projected-media-when-validating-images) — which fields to project so images are proven on create
+- [Validate before reporting success](#validate-before-reporting-success) — what counts as proof, and what may be claimed
+- [Failure guide](#failure-guide) — reading a rejection
+
 ## Preflight: respond and return before mutation
 
 Name and price are mandatory **workflow inputs for every product**, even when the API schema accepts an omitted price or initializes it to zero. Evaluate the cases below in order. When a case says **RETURN**, end the turn immediately: do not call a create endpoint, do not continue to examples, and do not create first and ask afterward.
@@ -180,7 +193,9 @@ With no file supplied, create the product and report it as not sellable until on
 
 ## Add images
 
-Skip this step when no image was supplied. Prefer the available dedicated Wix image-upload capability and upload all attachments and public image URLs together. Do not reconstruct that capability inside a general API-execution call. When no dedicated uploader is available, use `POST /site-media/v1/files/import` with the external URL in the body field named exactly `url`—not `importUrl`:
+Skip this step when no image was supplied — unless the user asked for one to be generated, in which case create it first with [Generate an Image with AI](../media/generate-image-with-ai.md) and continue below with the Media Manager file it returns. Do not offer generation unprompted, and never generate a substitute for a supplied image that failed to upload.
+
+Prefer the available dedicated Wix image-upload capability and upload all attachments and public image URLs together. Do not reconstruct that capability inside a general API-execution call. When no dedicated uploader is available, use `POST /site-media/v1/files/import` with the external URL in the body field named exactly `url`—not `importUrl`:
 
 ```json
 {"url":"https://example.com/product.jpg","mimeType":"image/jpeg","displayName":"Product.jpg","mediaType":"IMAGE"}

package/skills/wix-vibe-headless/platforms/base44.md

@@ -114,4 +114,8 @@ Seeding is **admin-only** — not part of the client, which is built solely per
 For any later admin/management request, work as in STEP 4: your vertical's seed module first, else
 `wix-base44-connector` doc discovery — all over the connector.
 
+**A change to what the business data COLLECTS is one of these, however UI it sounds** — a new form
+field, product option or service setting. Change it on Wix first per the vertical's `seed/SEED.md`,
+then edit the client against the verified result.
+
 version: v1341

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

@@ -15,6 +15,12 @@ field — the shipped utils supply the schema behind it, the state, the validati
 > 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 |
@@ -24,7 +30,7 @@ field — the shipped utils supply the schema behind it, the state, the validati
 | `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. |
+| `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
@@ -384,6 +390,9 @@ Don't reach for `role="form"`, an `aria-label` on an input that already has a `<
 ## 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.
@@ -412,8 +421,8 @@ Don't reach for `role="form"`, an `aria-label` on an input that already has a `<
 
 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. Calling an endpoint the helpers don't wrap is fine via `wixApiRequest` — look up the exact
-method and body first (or use the `wix-docs` skill), never guess.
+authored, and REVISE for changing one. Calling an endpoint the helpers don't wrap is fine via
+`wixApiRequest` — look up the exact method and body first (or the `wix-docs` skill), 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
@@ -438,21 +447,28 @@ checks the dashboard summary, sends and deletes one real submission), then write
 `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}` → add,
-  relabel, reorder or require fields; every change reflects on the site with no code change.
-- **Submissions** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-forms-and-payments/submissions`
-- **Forms settings** (incl. notifications) — `https://manage.wix.com/dashboard/{metaSiteId}/wix-forms-and-payments/settings`
+- **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.

package/skills/wix-vibe-headless/references/forms/seed/SEED.md

@@ -1,11 +1,23 @@
 # Forms — seeding (Form Schemas v4 REST)
 
-Creating a form is an **admin/build-time** job, in six sequential steps. Each has a section below.
+**Two actions live in this doc — decide which one you're doing before reading on.** Both are
+**admin/build-time** work over an elevated credential, and both run through the same six steps:
+
+| action | when | the steps it uses |
+|---|---|---|
+| **CREATE a form** — `POST` | there's no form yet: the app needs a contact / quote / application form and nothing has been created for it | all six, in order |
+| **REVISE a form** — `PATCH` | the form already exists and a request changes **what it collects**: *"add a dropdown for job industry"*, *"make the phone optional"*, *"add a file upload"*, *"drop the budget question"* | 1 (auth) → 3 (author just the new field) → **4b · Revising a form later** → 5 (re-verify) → 6 (rewrite the config, then wire the control) |
+
+A field the visitor can fill that isn't in the schema is **silent data loss** — no submission, no
+inbox, no contact, and the submit still resolves `true`. So never local component state, and never
+delete-and-recreate a live form: **`PATCH` it**, keeping the `formId` the UI already imports.
+
+The six steps, each with a section below:
 
 1. **Authenticate** — get an elevated credential; the public client ID cannot write.
-2. **Install the Wix Forms app** — idempotent, and nothing works until it's there.
+2. **Install the Wix Forms app** — idempotent, and nothing works until it's there. *(create only.)*
 3. **Author the form body** — adapt the every-field payload to what the request asks for.
-4. **Create the form** — POST each body; a `200` here means almost nothing.
+4. **Create the form** — POST each body; a `200` here means almost nothing. *(revising: **4b**.)*
 5. **Verify it works** — read the form back, and **submit to it once** for real.
 6. **Hand off** — the verified `formId` + field `target`s are written to a file the UI imports.
 
@@ -22,7 +34,7 @@ live Wix API reference.
 | 3 | Create Form | https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/create-form.md | the create call, plus 10 complete request examples — the source of the payload below |
 | 3 | Form object | https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object.md | each property individually, incl. form-level settings this doc doesn't cover |
 | 4 | Form Schemas API | https://dev.wix.com/docs/api-reference/crm/forms/form-schemas.md | every schema method (get, list, delete, enable/disable) |
-| 4 | Update Form | https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form.md | revising a form without losing its `formId` |
+| 4b | Update Form | https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form.md | the `PATCH`: revising a form without losing its `formId`, and the whole-array replace semantics |
 | 4 | List Forms Providers Configs | https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms-providers-configs.md | the Forms **app's** ceiling on fields and forms — **not** the site's plan cap, which this call cannot tell you (see step 4) |
 | 5 | Create Submission | https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission.md | the submission call used to prove the form accepts data |
 | 5 | About Submission Values | https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md | the value shape each `inputType` submits — string, array, address object, … |
@@ -77,8 +89,10 @@ costs nothing.
 ## 3 · Author the form body — every field type
 
 There is **one** create call:
-`POST https://www.wixapis.com/form-schema-service/v4/forms` with `{ "form": { … } }`.
-**You author that body**, starting from the payload below and adapting it to the request.
+`POST https://www.wixapis.com/form-schema-service/v4/forms` with
+`{ "form": { "namespace": "wix.form_app.form", … } }` — that namespace is the Wix Forms app's, and
+the only one the owner's dashboard shows. **You author that body**, starting from the payload below
+and adapting it to the request.
 
 The payload is one form holding **every field type Wix Forms supports**. Each field block is copied
 verbatim from the official Create Form examples, so the `identifier` / `inputType` / `componentType`
@@ -155,10 +169,18 @@ owner's dashboard, or on the first real submission.
 - **`required` lives at `inputOptions.required`**, never inside a validation block.
 - **`validation` is always present**, even as `{}`, and nests under the **`inputType`** options
   object — not the `componentType` one.
+- **A choice field's `identifier` IS its kind** — `DROPDOWN`, `RADIO_GROUP`, `CHECKBOX_GROUP`,
+  `TAGS` — matching the `componentType`, never `TEXT_INPUT`: the identifier routes the field to its
+  renderer, so `TEXT_INPUT` + `componentType: DROPDOWN` is accepted and stored as a text input. (A
+  long answer is `TEXT_AREA` for the same reason.)
 - **A choice field declares its options twice** — the component's `options[]` and the validation
   `enum` (`STRING`) or `items.stringOptions.enum` + `itemType` (`ARRAY`) — and the two must agree.
   Get it wrong and the create still returns `200`: the field is created as a **plain text box**,
   losing its choices. Only the 5a component check catches it.
+- **A choice field that came back as a text box: read which options block came home.**
+  `textInputOptions` where you sent `dropdownOptions` is that fallback — and with a well-formed block
+  and `enum`, the cause is the `identifier`. Re-sending it, or delete-and-re-add with the same
+  identifier, reproduces it.
 - **`target` is the immutable submission key**: starts with an ASCII letter, letters/digits/`_`
   only, no `__`, unique within the form. Use field's label converted to snake_case with _ and 6 random alphanumeric  
   characters as the field target, e.g. "First name" -> `first_name_a689be`.
@@ -1578,7 +1600,7 @@ always on the public host, never `/_api/`:
 
 ```
 POST https://www.wixapis.com/form-schema-service/v4/forms
-{ "form": { … the body from step 3 … } }
+{ "form": { "namespace": "wix.form_app.form", … the rest of the body from step 3 … } }
 ```
 
 Read **`form.id`** from the response — that's the `formId` the rest of the run carries. **Record it
@@ -1625,16 +1647,64 @@ proves the form works. Two failures worth recognizing before you retry:
   than discovering the limit after a full authoring pass, and count every entry in `formFields`, the
   `SUBMIT_BUTTON` included.
 
-**Revising a form later** — add a field, relabel one, tighten a rule:
+## 4b · Revising a form later
+
+Add a field, relabel one, tighten a rule, retire one — a `PATCH`, never a second create. Everything
+above still applies; this is the delta.
+
+**Read the form back first — you need its `revision`.** The `formId` comes from
+`src/rest/wix-forms.config.js` (`WIX_FORMS.<key>.formId`), never typed by hand:
 
 ```
+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": { …, "revision": "<the form's current revision>" } }
+{ "form": { …the whole object you just read, with your change…, "revision": "<its current revision>" } }
 ```
 
-Never delete-and-recreate: a `PATCH` keeps the `formId` the UI already holds and spends no extra slot
-against the site's form cap. Re-run step 5 afterwards — an update regresses a layout exactly as a
-create can.
+- **`namespace` is a required query parameter on the read**, hence the `?namespace=` above. Without it
+  the read `400`s with `namespace has size 0, expected 10 or more` — a violation naming a *field*, so
+  it reads like a body problem. Fix the call, not the payload.
+- **The read-back is the `PATCH` body.** Apply the change to what the `GET` returned and send that.
+  `namespace` is immutable and travels along; **there is no `fieldMask`**, and no `revision` outside
+  `form`. Inventing either is a silent partial write.
+- **`formFields` replaces wholesale.** Wix: *"Any field that's missing from the array you send is
+  moved to `deletedFormFields`, so resend every field you want to keep."* `steps` behaves the same
+  way. Drops are recoverable from `deletedFormFields` — if you notice, which is step 5's job.
+- **A stale `revision` is rejected** — re-`GET` and re-apply; never guess or increment it.
+- **A new field needs three things generated**: a fresh UUID `id`, a `target` unique in the form
+  (`job_industry_7f2b`), and — for a choice field — an options block whose `enum` and `options[]`
+  agree. Step 3 is the shape, and its warnings still hold.
+
+**Add the layout item too** — append to `steps[<n>].layout.large.items`, mirroring into `medium` /
+`small` if the form has them:
+
+```json
+{ "fieldId": "<the new field's id>", "row": <next row>, "column": 0, "width": 12, "height": 1 }
+```
+
+A field missing from the layout isn't dropped, but it sorts last and has no defined position in the
+owner's builder. To place it mid-form, insert at that `row` and bump every item at or after it — `row`
+restarts at 0 per step.
+
+**Changing a field's component type in place** — a text input that should have been a dropdown — means
+the choice `identifier` and **only** the new options block; don't leave `textInputOptions` beside
+`dropdownOptions`. A read-back still showing `textInputOptions` is the identifier, not the block.
+
+**The other revisions:**
+
+- **label, placeholder, options, validation, order** — patch and stop. The client reads all of those
+  live from the schema, so no config rewrite and no code change follows.
+- **retiring a field the form has submissions for** — set `hidden: true` ("hidden from submitters":
+  the field stops being rendered, and the submissions already collected under it keep their meaning)
+  rather than dropping it from the array. Drop only a field added by mistake in this same run.
+- **never rename a `target`** — it's the storage key, so a rename orphans every submission already
+  collected under the old one. Change the *label* instead.
+
+**Then re-run step 5 in full** — a `PATCH` regresses a form exactly as a create does, and §5a is where
+a dropdown that silently became a text input gets caught. Then step 6, revising: add the read-back
+`target` to `src/rest/wix-forms.config.js` (the one sanctioned edit to that file outside a seed run,
+and only *after* step 5 passes) and wire the control per `INSTRUCTIONS.md`. The field is live for new
+submissions; past ones don't carry it. Step 4's plan gates apply to an added field too.
 
 ## 5 · Verify it works
 
@@ -1671,6 +1741,9 @@ against the returned `form.formFields`:
 GET https://www.wixapis.com/form-schema-service/v4/forms/<formId>/summary
 ```
 
+*(The summary and the single-form `GET` take the id in the path, so neither needs the `namespace`
+query parameter — every **listing** read does.)*
+
 Assert `formSummary.fields` is **non-empty**, with one entry per input field you sent (everything in
 `formFields` except the `SUBMIT_BUTTON`). The summary is exactly what the Wix dashboard renders, so a
 short or empty count means the form is blank — or partly blank — **for the owner**, even while the
@@ -1735,8 +1808,8 @@ DELETE https://www.wixapis.com/form-submission-service/v4/submissions/<id>
 The id comes from the 5c response as **`submission.id`**: REST returns `id`, not the `_id` the
 reference schema shows (that's the SDK's shape). Do this every time — the owner's inbox is a real
 business inbox, and a probe left in it looks like a real enquiry. If a probe ever escapes, find it
-with `POST /form-submission-service/v4/submissions/namespace/query` filtered by `formId` +
-`namespace`.
+with `POST /form-submission-service/v4/submissions/namespace/query`, filtered by `formId` and
+`"namespace": "wix.form_app.form"`.
 
 ## 6 · Hand off
 
@@ -1745,8 +1818,9 @@ form, keyed by the form's name lowercased with each run of non-alphanumerics col
 `_` (`"Quote request"` → `quote_request`):
 
 ```js
-// Written by the seed run once step 5 passed. Do not hand-edit, and do not create it early:
-// its existence is what proves the form schemas were created AND verified.
+// Written by the seed run once step 5 passed. Do not create it early: its existence is what proves
+// the form schemas were created AND verified. Its only later edit is a verified schema change —
+// see step 4b; never a hand-typed field.
 export const WIX_FORMS = {
   contact: { formId: "…", name: "Contact", targets: { email: true, message: true } },
 };