@wix/agent-skills 1.31.2 → 1.32.0

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

@@ -17,6 +17,8 @@ Change what a form collects — **add a field, relabel one, tighten a rule, reor
 
 ## The call
 
+**No `formId` yet** ("my contact form")? List the forms and pick it by `name`: `GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&fieldsets=METADATA` returns only names and IDs. That call skips disabled forms; if the form isn't there, call again with `&enabled=false`.
+
 ```bash
 # 1 · read the form back: you need its current revision, and every field you intend to keep
 curl -X GET \
@@ -40,6 +42,7 @@ curl -X PATCH \
 
 - **⚠️ `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.
+- **⚠️ Delete the legacy `fields` array before you send.** The read-back carries `fields` (the old field list) next to `formFields`. Send both and the old list wins: the `PATCH` returns `200` and bumps `revision`, but a field you added only to `formFields` is dropped, and only its layout item is kept. Spreading the whole form (`{ ...form, formFields }`) does exactly this. Remove `fields` and `deletedFields` first: `const { fields, deletedFields, ...body } = form`.
 - **⚠️ 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.
@@ -108,6 +111,7 @@ Then hand back the dashboard links ([Forms Dashboard Navigation](./forms-dashboa
 | `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 |
+| The `PATCH` returns `200` and bumps `revision`, but the new field is missing from the read-back (its layout item is there) | The body still carried the legacy `fields` array from the read-back, and the server applied that old list | Remove `fields` and `deletedFields` from the body, re-`GET`, and send again. Don't retry the same body |
 | 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) |
@@ -118,6 +122,7 @@ Then hand back the dashboard links ([Forms Dashboard Navigation](./forms-dashboa
 
 ## Related Documentation
 
+- [Read Forms and Submissions](./read-forms-and-submissions.md) — finding the form to update when you have no `formId` yet
 - [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

package/skills/wix-manage/references/seo/manage-url-redirects.md

@@ -1,6 +1,6 @@
 ---
 name: "Manage URL Redirects on a Wix Site"
-description: "Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, batches of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
+description: "Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, bulk creates of up to 100 and bulk deletes of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
 ---
 
 # Manage URL Redirects on a Wix Site
@@ -72,6 +72,12 @@ directly - do not go looking for the shapes in the docs first.
 | Bulk Create Redirects | `POST /bulk/redirects/create` |
 | Bulk Delete Redirects | `POST /bulk/redirects/delete` |
 
+**`POST /redirects` is not Create Redirect.** It looks like the standard create
+path, but it is not part of this API and rejects a `{ "redirect": ... }` body
+with a 400. Create one redirect with `POST /create-redirect` and many with
+`POST /bulk/redirects/create`. Do not build any other path from the method
+names: `/list-redirects` and `/redirects/query` return 404.
+
 Create Redirect takes the redirect nested under `redirect`. `options` and
 `language` are optional, `id` only when preserving an existing redirect's
 identity:
@@ -185,7 +191,7 @@ count as the same path.
 
 **There is no query endpoint and no search endpoint.** Most Wix APIs have one, so
 this is the second place an agent goes wrong. Do not call, construct, or go
-looking for `POST /v1/redirects/query`, a `/search` path, or any filtered variant:
+looking for `POST /v1/redirects/query`, `/list-redirects`, a `/search` path, or any filtered variant:
 they do not exist, and trying one wastes a turn and returns nothing useful.
 
 - **List Redirects** returns every redirect on the site in one response. It takes
@@ -213,8 +219,9 @@ redirect is not in effect, and if the create fails the old redirect is gone.
 
 ## Batches
 
-**Bulk Create Redirects** and **Bulk Delete Redirects** take 1 to 500 items and
-report each one separately **inside a successful response**:
+**Bulk Create Redirects** takes 1 to 100 redirects and **Bulk Delete Redirects**
+takes 1 to 500 IDs. A larger list is rejected as a whole with a 400, so split it
+first. Both report each item separately **inside a successful response**:
 
 - Read every outcome from `results[].itemMetadata`, matched to your request by
   `originalIndex`. A failed item carries `error.code`, such as `FROM_URL_EXISTS`
@@ -225,6 +232,28 @@ report each one separately **inside a successful response**:
 - A malformed request, such as an empty list, is rejected as a whole with a 400
   and returns no per-item results.
 
+There is no import endpoint. To migrate a list of old URLs, such as a CSV from
+another platform, follow this path and nothing else:
+
+1. Parse the whole list before any call. Skip the header row, trim whitespace,
+   and drop exact duplicate rows. Each row is one exact redirect unless the user
+   asked for a whole section.
+2. Call **List Redirects** once and run the checks above against every row. If
+   either check matches any row, the same rule applies as for a single create:
+   name every row and every existing redirect at stake, end your turn without
+   writing, and continue only after the user answers. A row whose `to` equals an
+   existing redirect's `from` is the dangerous one - Bulk Create deletes that
+   redirect with no error to catch afterwards. If nothing matched, continue in
+   the same turn.
+3. Split the rows into chunks of 100 and call **Bulk Create Redirects** once per
+   chunk, in order. 250 rows is three calls: 100, 100, then 50.
+4. Read each chunk's `results[].itemMetadata` and keep a running count. Never
+   delete a redirect that reported success in order to create it again, and
+   never resend a chunk that succeeded. A success with no `id` means the same
+   redirect was already on the site, not that the write was lost.
+5. Report the total from those results. Call List Redirects again only if
+   `bulkActionMetadata.undetailedFailures` was not `0`.
+
 Two more sharp edges to report truthfully:
 
 - A successful **Bulk Delete** item means the deletion was found and sent, not

package/skills/wix-manage/references/sites/create-headless-site.md

@@ -1,12 +1,21 @@
 ---
 name: "Create Headless Site"
-description: Creates a Wix Headless website: a site in the user's Wix account whose frontend is files uploaded to Wix hosting, with the Wix business backend behind it through APIs. Creating, uploading, updating and connecting a backend are one flow, in Upload a Website or HTML Files.
+description: Creates a Wix Headless website: a site in the user's Wix account whose frontend is files uploaded to Wix hosting, with the Wix business backend behind it through APIs. The site is created and its pages put live by Upload a Website or HTML Files; a Wix Business Solution (a store, blog, bookings and more) is then integrated into it by the Wix Headless kit, from its cold start.
 ---
 # Create Headless Site
 
 A Wix Headless site is a site in the user's Wix account whose frontend is files
 uploaded to Wix hosting and served at a `*.wix-site-host.com` URL, with the Wix
-business backend (stores, bookings, forms, a CMS) behind it through APIs.
-Creating it, uploading its files, changing it later and connecting a backend are
-one flow: [Upload a Website or HTML Files](upload-static-site.md), online at
-https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md
+business backend (stores, bookings, forms, a CMS) behind it through APIs. It comes
+to be in two steps:
+
+1. **Create the site and put its pages live**: [Upload a Website or HTML Files](upload-static-site.md),
+   online at https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md.
+   It holds the call that creates the site, then uploads the pages, the user's or
+   ones you write, and changes them later on the same site and URL.
+2. **Integrate Wix Headless into it**: a Wix Business Solution built on shipped code (a
+   store, a blog, bookings, events, a CMS, forms, members and more, with its pages,
+   data layer and seed) comes from the Wix Headless kit, starting at its cold start,
+   https://www.wix.com/skills/headless-cold-start/headless-kit.md. It takes a machine
+   from nothing (the skills, the Wix CLI sign-in) to a built, seeded, released site on
+   the same site and URL; the upload recipe says how to run it with no shell of your own.