@wix/agent-skills 1.31.1 → 1.31.2

package/skills/wix-manage/references/bookings/booking-service-policy-setup.md

@@ -5,6 +5,9 @@ description: Sets up booking policies, cancellation rules, and waitlist configur
 
 # Technical Step-by-Step Instructions: Configuring Wix Bookings Service Policies (Real-World, API-First)
 
+> These calls need the Wix Bookings app on the site (`appDefId` `13d21c63-b5ec-5912-8397-c3a5ddb27a97`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 ## Description
 
 Below are the recommended steps to successfully configure booking, cancellation, and waitlist policies for Wix Bookings services. This recipe covers policy inheritance, service-specific overrides, and common policy configurations for different business models.

package/skills/wix-manage/references/bookings/external-calendar-integration.md

@@ -4,6 +4,9 @@ description: OAuth-based integration with Google Calendar, Microsoft Outlook, an
 ---
 # Technical Step-by-Step Instructions: Connecting External Calendars (Google, Microsoft, Apple) to Wix Bookings (Real-World, API-First)
 
+> These calls need the Wix Bookings app on the site (`appDefId` `13d21c63-b5ec-5912-8397-c3a5ddb27a97`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 ## Description
 
 Below are the recommended steps to successfully connect and sync external calendars (Google Calendar, Microsoft Outlook, Apple Calendar) with Wix Bookings, with real-world troubleshooting and fixes for common API issues. This recipe covers the complete OAuth flow, sync configuration, and verification procedures.

package/skills/wix-manage/references/bookings/multi-resource-service-creation.md

@@ -4,6 +4,9 @@ description: Creates resource types and individual resources using Resources API
 ---
 # Technical Step-by-Step Instructions: Creating Multi-Resource Bookings Services (Rooms, Equipment, Staff) - Real-World, API-First
 
+> These calls need the Wix Bookings app on the site (`appDefId` `13d21c63-b5ec-5912-8397-c3a5ddb27a97`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 ## Description
 
 Below are the recommended steps to successfully create Wix Bookings services that require multiple resource types (e.g., Room + Equipment + Instructor). This recipe covers the **gaps** in individual API documentation: resource architecture planning, entity relationship patterns, availability dependencies, and real-world coordination challenges that aren't clear from reading individual API references.

package/skills/wix-manage/references/cms/cms-data-items-crud.md

@@ -4,6 +4,9 @@ description: "Add, query, update, and delete items in CMS collections, one at a
 ---
 # CMS Data Items CRUD
 
+> These calls need the Wix CMS app on the site (`appDefId` `e593b0bd-b783-45b8-97c2-873d42aacaf4`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 > **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`.
 
 This recipe covers Create, Read, Update, Delete (CRUD) operations for Wix CMS data items, plus count, upsert, truncate, aggregate, and reference-field links.
@@ -175,6 +178,8 @@ curl -X GET \
 
 **Endpoint**: `PUT https://www.wixapis.com/wix-data/v2/items/{itemId}`
 
+> **Warning**: This replaces the entire item — fields not in `dataItem.data` are deleted. To change only some fields, use [Patch Data Item](#patch-data-item-partial-update---single-item).
+
 **Request Body**:
 ```json
 {
@@ -233,6 +238,8 @@ Unlike Update, this only modifies the specified fields — all other fields rema
 
 > There is no update-by-filter endpoint. To update the items matching a filter, query them first (see [Query Data Items](#query-data-items)), then send their ids to bulk update or bulk patch.
 
+> **Note**: This replaces the entire item. Include all fields you want to keep, not just the ones you're changing.
+
 > **Important**: Use `id` (not `_id`) at the element level. The `data` object should NOT contain `_id`.
 
 ```json
@@ -242,14 +249,18 @@ Unlike Update, this only modifies the specified fields — all other fields rema
     {
       "id": "item-guid-1",
       "data": {
+        "title": "Wireless Headphones Pro",
         "price": 159.99,
+        "description": "Premium wireless headphones",
         "inStock": true
       }
     },
     {
       "id": "item-guid-2",
       "data": {
+        "title": "Wired Earbuds",
         "price": 89.99,
+        "description": "Compact wired earbuds",
         "inStock": false
       }
     }
@@ -257,8 +268,6 @@ Unlike Update, this only modifies the specified fields — all other fields rema
 }
 ```
 
-> **Note**: This replaces the entire item. Include all fields you want to keep, not just the ones you're changing.
-
 ## Bulk Patch Items (Partial Update)
 
 **Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/patch`

package/skills/wix-manage/references/cms/cms-publishing-flow.md

@@ -4,6 +4,9 @@ description: "Interact with CMS collections that gate their items behind a draft
 ---
 # CMS Draft & Publish Workflow
 
+> These calls need the Wix CMS app on the site (`appDefId` `e593b0bd-b783-45b8-97c2-873d42aacaf4`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 > **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`.
 
 Some CMS collections gate their items behind a **draft/publish workflow** instead of writing straight to the live site. Such a collection has the **Draft Items plugin** installed. Each item is in one of three states — **DRAFT**, **PUBLISHED**, or **CHANGED** (a published item with a pending draft edit) — and edits are staged as drafts until explicitly published.
@@ -59,6 +62,8 @@ curl -X GET \
 - **Draft Items plugin present** → the collection gates items behind draft/publish. Its `draftItemsPluginOptions.draftsCollectionId` gives the paired drafts collection to author and edit drafts against.
 - **Draft Items plugin absent** → plain collection; every insert/update goes straight live. No draft surface exists.
 
+Once the Draft Items plugin is installed, do not insert, update, patch, remove, or save items directly in the published collection. Read `draftItemsPluginOptions.draftsCollectionId` from the plugin and write new items and pending edits to that drafts collection. Then call **Publish Data Item Draft** (`POST /wix-data/v2/items/publish-draft`) to publish an item to the published collection. This lifecycle operation takes the published collection ID; it is the supported way to move a draft into the live collection.
+
 ---
 
 ## 2. Read items
@@ -90,7 +95,7 @@ Reads target a specific surface — there is no merged view:
 
 ### Author a brand-new draft
 
-Insert into the **drafts** collection. The item starts as **DRAFT**.
+Insert into the **drafts** collection. Do not insert into the published collection while the Draft Items plugin is installed. The item starts as **DRAFT** and becomes live only after you call **Publish Data Item Draft**.
 
 **Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items`
 
@@ -109,13 +114,30 @@ Update or patch against the **drafts** collection (`articles__drafts`). See [CMS
 
 ### Edit a PUBLISHED item → produces CHANGED
 
-Editing a live item does **not** overwrite the live copy — it stages a **pending draft**, leaving the published version untouched until published. The live item then has a pending draft (state **CHANGED**).
+**PUT and PATCH against the published collection fail while the Draft Items plugin is installed.** Create a draft of the published item, then edit that draft in the paired drafts collection. The published version remains live and unchanged until the draft is published.
 
-**Create the draft first, then edit it.** To edit a published item, explicitly create the draft via the **create-draft** flow (`createDataItemDraft`) rather than relying on an implicit draft-on-update. Create-draft seeds a full draft copy of the currently-published item into the drafts collection under the same item id; you then apply your edits to that draft. This is the more reliable path — a bare partial update straight to the drafts collection risks producing a draft that is missing the fields you didn't touch. So: create-draft for the published item id, then Update/Patch that draft on the drafts collection (`articles__drafts`).
+1. Call [Create Data Item Draft](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/create-data-item-draft) with the published collection ID and item ID. It returns `dataItem`, a full draft copy with the same item ID; `dataItem.dataCollectionId` identifies the paired drafts collection. The item is now CHANGED.
+2. Update or patch the returned draft using the drafts collection ID. Use Patch Data Item to preserve fields you did not change; Update Data Item replaces the draft's entire payload.
+3. Call Publish Data Item Draft with the published collection ID to make the edits live.
+
+```bash
+# Create a draft of a PUBLISHED item; the lifecycle call takes the published collection ID.
+curl -X POST 'https://www.wixapis.com/wix-data/v2/items/create-draft' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{"dataCollectionId":"articles","dataItemId":"<id>"}'
+# Patch the resulting draft; use its returned dataCollectionId, not the published collection ID.
+curl -X PATCH 'https://www.wixapis.com/wix-data/v2/items/<id>' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{"dataCollectionId":"<draftsCollectionId>","patch":{"dataItemId":"<id>","fieldModifications":[{"fieldPath":"body","action":"SET_FIELD","setFieldOptions":{"value":"Revised article body"}}]}}'
+```
+
+For a CHANGED item, edit its existing draft directly. Create Data Item Draft returns `ALREADY_EXISTS` if a draft already exists; query the paired drafts collection when the item's state is unknown.
 
 ### Publish a pending draft (DRAFT/CHANGED → PUBLISHED)
 
-Replaces the published item's data with the draft's content; the draft is then deleted. Pass the **published** collection id.
+Call **Publish Data Item Draft** to publish the pending draft. It replaces the published item's data with the draft's content; the draft is then deleted. Pass the **published** collection ID. This lifecycle operation is the allowed way to write the draft's content to the published collection.
 
 **Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/publish-draft`
 
@@ -161,12 +183,12 @@ curl -X POST \
 }'
 ```
 
-`copyToDraft` controls the two "keep vs discard" variants:
+`copyToDraft` controls whether the published data is copied into the drafts collection:
 
 | `copyToDraft` | Behavior | Use for |
 |---------------|----------|---------|
-| `true` (default) | Removes the live copy, creates a draft seeded with the previously-published data. Any existing pending draft for that id is **overwritten**. | "Unpublish and keep changes" |
-| `false` | Removes the live copy **without** creating a draft. No `dataItem` returned. | "Unpublish and discard" |
+| `true` (default) | Removes the live copy and copies its data into a draft. Any existing pending draft for that ID is **overwritten**, discarding its unpublished edits. | Take the item offline and retain the previously-published content as a draft. |
+| `false` | Removes the live copy **without** creating a draft. Any existing pending draft is **preserved unchanged**. No `dataItem` is returned. | Remove the live version while leaving any pending draft intact. |
 
 - Response (`copyToDraft: true`) carries the **new draft**, not the removed live item.
 - Returns `NOT_FOUND` if no published item exists with that id.
@@ -181,17 +203,38 @@ curl -X DELETE \
 -H 'Authorization: <AUTH>'
 ```
 
-### Delete an item entirely (removes both versions)
+### Delete a published item permanently
 
-Deleting must remove **both** the live item and any pending draft.
+> Permanent deletion is irreversible. Confirm with the user before calling Unpublish Data Item with `copyToDraft: false` or deleting a draft, unless the request already names the items to remove.
+
+To permanently delete a published item, call **Unpublish Data Item** with `copyToDraft: false` to remove it from the published collection. This preserves any existing pending draft, so query the paired drafts collection for that item ID next. Delete the draft only if the query returns it; when no draft exists, skip the DELETE call. For a CHANGED item, this deletes its preserved pending draft. For a PUBLISHED item with no pending draft, unpublishing completes the deletion.
 
 ```bash
-# live version
-curl -X DELETE 'https://www.wixapis.com/wix-data/v2/items/<id>?dataCollectionId=articles' -H 'Authorization: <AUTH>'
-# drafts collection, if a draft exists
-curl -X DELETE 'https://www.wixapis.com/wix-data/v2/items/<id>?dataCollectionId=articles__drafts' -H 'Authorization: <AUTH>'
+# Stop on HTTP failures, malformed query responses, or failed deletes.
+set -euo pipefail
+# remove the published version without creating a draft
+curl --fail --silent --show-error -X POST 'https://www.wixapis.com/wix-data/v2/items/unpublish' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{"dataCollectionId":"articles","dataItemId":"<id>","copyToDraft":false}'
+# Query the paired drafts collection for this ID. Use the draftsCollectionId read from the plugin.
+ITEM_ID='<id>'
+DRAFTS_COLLECTION_ID='<draftsCollectionId>'
+drafts=$(curl --fail --silent --show-error -X POST 'https://www.wixapis.com/wix-data/v2/items/query' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d "{\"dataCollectionId\":\"$DRAFTS_COLLECTION_ID\",\"consistentRead\":true,\"query\":{\"filter\":{\"_id\":\"$ITEM_ID\"},\"paging\":{\"limit\":1}}}")
+# Require a valid dataItems array; a failed query must not be treated as an empty result.
+draft_count=$(printf '%s' "$drafts" | jq -er '.dataItems | if type == "array" then length else error("Expected dataItems array") end')
+# Delete only when the query found the draft; an empty dataItems array means there is nothing to delete.
+if [ "$draft_count" -gt 0 ]; then
+  curl --fail --silent --show-error -X DELETE "https://www.wixapis.com/wix-data/v2/items/$ITEM_ID?dataCollectionId=$DRAFTS_COLLECTION_ID" \
+    -H 'Authorization: <AUTH>'
+fi
 ```
 
+If an item was never published and exists only in the drafts collection (DRAFT), delete it directly from the paired drafts collection. Do not call Unpublish Data Item; it returns `NOT_FOUND` when no published item exists.
+
 ---
 
 ## 4. Enable / disable the workflow on a collection
@@ -206,6 +249,7 @@ curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/add-draft-items-pl
   -H 'Authorization: <AUTH>' \
   -d '{
         "dataCollectionId": "articles",
+        "draftItemsOptions": {},
         "publishPluginConflictAction": "FAIL_WHEN_PUBLISH_INSTALLED"
   }'
 ```
@@ -258,16 +302,19 @@ At the REST level, every read/author/publish/unpublish call here goes through th
 | PUBLISHED | Edit into a pending draft (→ CHANGED) | Create the draft (`createDataItemDraft`), then edit it on the drafts collection | Write Data Items |
 | — | Create new draft (→ DRAFT) | `POST https://www.wixapis.com/wix-data/v2/items` on the drafts collection | Write Data Items |
 | DRAFT / CHANGED | Publish (→ PUBLISHED) | `POST https://www.wixapis.com/wix-data/v2/items/publish-draft` (published id) | Write Data Items |
-| PUBLISHED / CHANGED | Unpublish, keep as draft (→ DRAFT) | `POST https://www.wixapis.com/wix-data/v2/items/unpublish` `copyToDraft:true` | Write Data Items |
-| PUBLISHED / CHANGED | Unpublish, discard | `POST https://www.wixapis.com/wix-data/v2/items/unpublish` `copyToDraft:false` | Write Data Items |
+| PUBLISHED / CHANGED | Remove from live collection, keep as draft (→ DRAFT) | **Unpublish Data Item** — `POST https://www.wixapis.com/wix-data/v2/items/unpublish`, `copyToDraft:true` | Write Data Items |
+| PUBLISHED / CHANGED | Remove live copy without creating a draft; preserve any existing draft | **Unpublish Data Item** — `POST https://www.wixapis.com/wix-data/v2/items/unpublish`, `copyToDraft:false` | Write Data Items |
 | CHANGED | Revert to live version (discard edit) | `DELETE https://www.wixapis.com/wix-data/v2/items/{id}?dataCollectionId=<drafts id>` | Write Data Items |
-| any | Delete entirely (both versions) | Delete on the published id (+ drafts id if a draft exists) | Write Data Items |
+| PUBLISHED / CHANGED | Permanently delete (confirm first unless the request names the item) | `POST https://www.wixapis.com/wix-data/v2/items/unpublish` with `copyToDraft:false` (published id), then query and delete any remaining draft | Write Data Items |
+| DRAFT (never published) | Permanently delete (confirm first unless the request names the item) | `DELETE https://www.wixapis.com/wix-data/v2/items/{id}?dataCollectionId=<drafts id>` | Write Data Items |
 | plain, no plugin | Enable workflow | `POST https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin` | Manage Data Collections |
 
 ---
 
 ## Agent gotchas
 
+- **Never write item data directly to the published collection while Draft Items is installed.** Create and edit items in the paired drafts collection, then call **Publish Data Item Draft** to publish. Lifecycle calls such as publish still take the published collection ID.
+- **Choose the permanent-delete path from the item's state, and confirm first.** Permanent deletion is irreversible: confirm with the user before Unpublish Data Item with `copyToDraft: false` or a draft DELETE unless the request already names the items to remove. For PUBLISHED or CHANGED items, call Unpublish Data Item with the published collection ID and `copyToDraft: false`, then query and delete any remaining draft from the paired drafts collection. For a DRAFT that was never published, delete it directly from the paired drafts collection; Unpublish Data Item would return `NOT_FOUND`.
 - **Resolve the drafts collection from the plugin.** Read `draftItemsPluginOptions.draftsCollectionId` off the published collection's Draft Items plugin rather than assuming a `__drafts` suffix.
 - **Status is server-authoritative.** Derive DRAFT/PUBLISHED/CHANGED from the published + drafts surfaces (or the value the API returns). Never compute it locally, and never render an optimistic status before the write confirms (**confirm-then-render**).
 - **Pass the *published* collection id** to `publish-draft` and `unpublish` — not the drafts collection id. Author and edit drafts against the drafts collection id.

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

@@ -4,6 +4,9 @@ description: "Changes a Wix form that already exists, with Form Schemas v4 `PATC
 ---
 # RECIPE: Update a Wix Form
 
+> These calls need the Wix Forms app on the site (`appDefId` `225dd912-7dea-4738-8688-4b8c6955ffc2`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 > **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.

package/skills/wix-manage/references/pricing-plans/create-and-update-pricing-plans.md

@@ -4,6 +4,9 @@ description: Creates subscription and one-time payment plans using Plans API. Co
 ---
 # Technical Step-by-Step Instructions: Creating or Updating a Wix Pricing Plans (Real-World, API-First)
 
+> These calls need the Wix Pricing Plans app on the site (`appDefId` `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 ## Description
 Below are the recommended steps to successfully create or update a Wix Pricing Plans (or several at once) on Wix and attach a booking session to a pricing plan, with real-world troubleshooting and fixes for common API issues.
 

package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md

@@ -4,6 +4,9 @@ description: Configures restaurant menus, sections, and items using Menus API. C
 ---
 # Wix Restaurants Setup API Reference
 
+> These calls need the Wix Restaurants Menus app on the site (`appDefId` `b278a256-2757-4f19-9313-c05c783bec92`; online ordering is Wix Restaurants Orders `9a5d83fd-8570-482e-81ab-cfa88942ee60`, reservations Wix Table Reservations `f9c07de2-5341-40c6-b096-8eb39de391fb`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds one by that id.
+
+
 This recipe covers setting up and configuring Wix Restaurants using the REST API, including menus, items, and ordering configuration.
 
 ## Prerequisites

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

@@ -1,55 +1,12 @@
 ---
 name: "Create Headless Site"
-description: Creates a Wix Headless site (headless business) with one account-level API call — site, Wix Business Solution apps, and a configured OAuth client.
+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.
 ---
 # Create Headless Site
 
-Headless sites are not created from templates. One account-level call creates the site, installs the requested Wix Business Solution apps, and creates and configures the site's OAuth client.
-
-> Do NOT use the [Create Site from Template](create-site-from-template.md) API for headless sites — it only tags the site's namespace and skips the headless setup entirely.
-
-## Prerequisites
-
-- Wix account with site creation permissions
-- Account-level API access
-
-## Provision a Headless Business
-
-**Endpoint**: `POST https://www.wixapis.com/headless-business-setup/v1/headless-business/provision`
-
-**Request Body**:
-```json
-{
-  "origin": "agent-<your-agent-id>",
-  "newMetasite": {
-    "namingStrategy": { "metaSiteName": "My Headless Business" },
-    "seedOptions": [
-      { "businessSolution": "STORES", "clearTemplateContent": true, "seedDemoContent": false }
-    ]
-  },
-  "synchronousSteps": ["SET_METASITE_NAME", "CONFIGURE_HEADLESS_APP"]
-}
-```
-
-- `origin` — `agent-` followed by your own identifier: a short, stable, lowercase-hyphenated slug for the coding agent or tool you are (e.g. `claude-code`, `cursor`, `codex-cli`, `windsurf`, `github-copilot`, or your product's name; `unknown-agent` if you can't name yourself). It records which agent created the site
-- `namingStrategy` — exactly one of: `metaSiteName` (exact display name), `llmPromptBasedName: {}` (name derived from the top-level `prompt` field), or `defaultName: {}`
-- `seedOptions` — Wix Business Solution apps to install at creation: `STORES`, `BLOG`, `BOOKINGS`, `EVENTS`, `PORTFOLIO`, `PRICING_PLANS`. Each entry takes `clearTemplateContent` (remove sample content) and `seedDemoContent` (seed demo content). Empty installs none
-- `synchronousSteps` — steps to complete before the call returns: `SET_METASITE_NAME`, `CONFIGURE_HEADLESS_APP`, `SEED_CONTENT`. Omitted steps run asynchronously. Include `CONFIGURE_HEADLESS_APP` when the OAuth client must be usable immediately
-
-**Response**:
-```json
-{ "metaSiteId": "<SITE_ID>", "appId": "<OAUTH_CLIENT_ID>" }
-```
-
-`appId` is the site's OAuth client ID — do NOT create a separate OAuth app.
-
-## Existing Sites
-
-To provision headless onto an existing site, pass `"existingMetasite": {}` instead of `newMetasite`. This is a site-level call in the context of that site.
-
-## Next Steps
-
-After creating the site:
-- Install additional apps using [Install Wix Apps](../app-installation/install-wix-apps.md)
-- Add content (products, services, blog posts, etc.)
-- Use the `appId` as the `client_id` to mint visitor tokens and make buyer-facing API calls — see [Manage OAuth Apps](manage-oauth-apps.md)
+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

package/skills/wix-manage/references/sites/manage-oauth-apps.md

@@ -147,8 +147,8 @@ Use the `access_token` as the `Authorization` header on subsequent API calls.
 
 ## API Reference
 
-- [OAuth Apps — Create](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-o-auth-app)
-- [OAuth Apps — Get](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/get-o-auth-app)
-- [OAuth Apps — Query](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/query-o-auth-apps)
-- [OAuth Apps — Update](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-o-auth-app)
+- [OAuth Apps — Create](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-oauth-app)
+- [OAuth Apps — Get](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/get-oauth-app)
+- [OAuth Apps — Query](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/query-oauth-apps)
+- [OAuth Apps — Update](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-oauth-app)
 - [Retrieve Tokens — `/oauth2/token` contract, all grant types](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens)

package/skills/wix-manage/references/sites/read-site-context.md

@@ -51,6 +51,10 @@ Response:
 - **Wix Blog** (ID: `14bcded7-0066-7c35-14d7-466cb3f09103`)
 ```
 
+The app list reflects installs after a delay: an app installed a few minutes ago can be missing here
+while its own API already answers. To check an install you just made, read the site's instances with
+[List Installed Apps](../app-installation/list-installed-apps.md), which is immediate.
+
 ### Without siteId
 
 ```bash

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -1,17 +1,37 @@
 ---
 name: "Upload a Website or HTML Files"
-description: Publish a user's ready-made website — an index.html, a static build, or a zip exported from an AI builder or any other tool — as a live Wix site. Covers every way to get there — publishing straight into the user's Wix account when you hold their identity, publishing anonymously with a save link when you don't, and handing the user the Wix Headless drop page, or releasing it as a Wix Headless project — and how to get the user's identity through the Wix CLI. Use whenever the user wants to upload, publish, deploy, or host their own HTML/CSS/JS as a NEW site, including files generated for them earlier in the conversation, or to update a site published this way (replace its files on the same site and URL). Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+description: Create and update a Wix Headless website by uploading its files — an index.html, a static build, a zip exported from an AI builder or any other tool, or pages you write for the user — as a live site in the user's Wix account. Covers every route: uploading with the user's identity (curl with a Wix CLI token, or the Wix MCP), publishing anonymously with a save link when you don't hold it, and the Wix Headless drop page; then updating the same site and URL, and connecting a Wix backend (stores, bookings, forms) through the headless skill. Use when the user wants to upload, publish, deploy or host HTML/CSS/JS as a new Wix site, their own or written for them, or to change a site published this way. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
 ---
 
 # Upload a Website or HTML Files
 
-The user has a finished website — hand-written HTML, a static build, a zip, a
-project an AI builder exported — and wants it live on Wix. Every route below ends
-the same way: a headless site in the user's Wix account that serves those files
-at a `*.wix-site-host.com` URL.
+A website goes live on Wix as a Wix Headless site: its files are uploaded to a
+site in the user's Wix account and served at a `*.wix-site-host.com` URL. The
+files are ones the user has (hand-written HTML, a static build, a zip, a project
+an AI builder exported) or ones you write for them as you upload. Later changes
+upload to [the same site](#change-it-later), and the URL stays.
+
+The flow: pick the route that fits where you run, create the site, upload the
+files, and give the user the live URL. Later changes go to the same site, and a
+backend, when the site needs one, comes once it is live.
+
+- [What decides the route](#what-decides-the-route): which route fits where you run
+- [Before the calls](#before-the-calls): the user's token, the Wix MCP, the attribution slug
+- [Create the site](#create-the-site): one call, the site in the user's account
+- Upload the files [with curl](#drop-with-curl) or [through the Wix MCP](#drop-through-the-wix-mcp)
+- [Change it later](#change-it-later): edits on the same site and URL
+- [Connect a backend](#connect-a-backend): stores, bookings, forms and more through the headless skill
+- [Images](#images): how images reach the site
+- [Publish anonymously](#publish-anonymously): no login, a temporary site the user claims or saves
+- [The drop page](#the-drop-page): the user uploads the files when no route reaches Wix
+- [Limits and failures](#limits-and-failures), [Send feedback to Wix](#send-feedback-to-wix), [Route the request correctly](#route-the-request-correctly)
 
 ## What decides the route
 
+The user's request to publish is the consent to create the site and upload: do
+not ask again before either. Ask only where this recipe says to (connecting a
+backend, replacing a frontend that is serving).
+
 Three things about where you run decide it:
 
 - **Does your shell reach Wix?** `curl -sI https://www.wixapis.com` answers with an
@@ -58,8 +78,9 @@ page whole. A web fetch is the fallback.
 
 ## Create the site
 
-The [Create Headless Site](create-headless-site.md) call with no Wix Business
-Solutions. Name it after the page's `<title>` and keep `"origin": "drop"`.
+One account-level call creates the headless site, with no Wix Business
+Solutions. Name it after the page's `<title>`, at most 40 characters (a longer
+name is rejected), and keep `"origin": "drop"`.
 
 ```bash
 curl -sS -X POST "https://www.wixapis.com/headless-business-setup/v1/headless-business/provision" \
@@ -172,11 +193,15 @@ On the same `metaSiteId`, never a new site. Each drop replaces every file, and
 
 - **With a shell that reaches Wix**, edit the files and drop the full set with
   `curl`.
-- **Through the MCP**, change the site in one `ExecuteWixAPI` script: download
-  what it serves, edit in code, and drop the full set back. Only the edit is
-  written; images travel back as they are. When your files travel as files, a
-  new zip of the whole site through the upload tool works as well. A full
-  rewrite of the text bundle is for a site rewritten wholesale.
+- **Through the MCP**, by the kind of change:
+  - **An edit to files the site serves** (a price, a line, a link): one
+    `ExecuteWixAPI` script downloads what it serves, edits in code, and drops the
+    full set back. Only the edit is written; images travel back as they are.
+  - **New or rewritten files**: when your files travel as files, zip the whole
+    site, images included, and send it through the upload tool. When they don't,
+    the script carries them in its `files` param and adds them to the download
+    before the drop.
+  - **A site rewritten wholesale**: a full text bundle through the upload tool.
 
 For a site from an earlier conversation, find its `metaSiteId` with
 [Query Sites](#claim-it-into-the-users-account), matching the name or `viewUrl`.
@@ -213,7 +238,7 @@ the same site, appId and URL.
 **A mock that shows a business solution: publish it, then ask before connecting.**
 Any control on the page that promises what static files can't deliver —
 something to buy, book, order, join, submit or pay — is a Wix Business Solution
-the page pretends to have. First get the site live from what the user gave you.
+the page pretends to have. First get the site live from the pages as they are.
 Then, with the live URL, name each such control, the solution that would make it
 work, and what connecting it involves: what gets created from the page's own
 content (the products, services or form). Ask whether to go ahead, and connect only after the user says
@@ -245,15 +270,22 @@ Its commands run:
 
 ## Images
 
-You never write an image's bytes yourself, as base64 or in any other form: model
-output corrupts them past a few thousand characters, and every byte costs tokens.
-An SVG is text and goes in like a page. Every other image reaches Wix one of four
-ways:
+An SVG is text and goes in like a page. Every other image is bytes, and bytes
+reach Wix one of these ways, in this order of preference:
 
 1. **With a shell that reaches Wix**, in the `curl` drop, from disk.
 2. **When your files travel as files**, inside the zip you pass the upload tool.
-3. **A public URL**: the page keeps the absolute URL.
-4. **The user uploads it** to the site's Media Manager. This is the way for images
+3. **A public URL**: the page keeps the absolute URL, or the Wix MCP's
+   `UploadImageToWixSite` imports it into the site's media (`imageUrls`) and the
+   page points at the returned `static.wixstatic.com` address. A share page
+   (Dropbox, Drive) is not a file URL; a direct link is.
+4. **`imageBase64` on `UploadImageToWixSite`**, when you can read the file and
+   encode it yourself (a shell, a file API): one image per call, the raw base64
+   with its `mimeType`. Encoding it from a file works; typing it out does not: a
+   model cannot reproduce a long base64 string faithfully, so a string that was
+   not produced by a tool comes back as an `atob` error or a corrupt image.
+   Never put image bytes in the `files` bundle beyond a few KB (an icon).
+5. **The user uploads it** to the site's Media Manager. This is the way for images
    that exist only as files you can't send. Publish the pages first, then name
    the missing files, give the user
    `https://manage.wix.com/dashboard/{metaSiteId}/media-manager`, and ask them to
@@ -261,9 +293,12 @@ ways:
    match each to the page's reference by `displayName`, point the reference at the
    file's `static.wixstatic.com` URL, and drop again.
 
-Never stand in drawings or placeholders of your own for the user's images, and
-never shrink or re-encode them. The closing message names every image still
-missing.
+`attachments` on a Wix MCP tool carries a file only from ChatGPT or Codex, which
+swap it for a download URL before the call reaches Wix. From any other client it
+arrives as the path you wrote, and Wix cannot read a path on your machine; the
+answer does not change on a retry. An image you could not send is named in the
+closing message. Never stand in drawings or placeholders of your own for the
+user's images, and never shrink or re-encode them.
 
 ## Publish anonymously
 
@@ -309,14 +344,15 @@ curl -sS -X POST \
 
 Claim last: it ends the anonymous record, and later changes are
 [drops](#change-it-later). **The URL changes on claim.** Read the new `viewUrl`
-with Query Sites in the `HEADLESS` namespace; the default query omits headless
-sites and rejects an `id` filter, so match the id yourself, paging with
-`metadata.cursors.next`:
+with Query Sites in the `HEADLESS` namespace (the default query omits headless
+sites). An `id` filter takes the `$in` form; a bare `"id": "<uuid>"` is a `400`:
 
 ```bash
 curl -sS -X POST "https://www.wixapis.com/site-list/v2/sites/query" \
   -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-  -d '{"query":{"filter":{"namespace":"HEADLESS"},"cursorPaging":{"limit":100}}}'
+  -d '{"query":{"filter":{"namespace":"HEADLESS","id":{"$in":["'$META_SITE_ID'"]}},"cursorPaging":{"limit":10}}}'
+# sites[0].viewUrl is the live address; the same query without the id filter lists every
+# headless site with its viewUrl, which is how a site is found from a URL the user gives
 ```
 
 ## The drop page
@@ -336,7 +372,7 @@ plugin or connector in a chat client).
 
 - **A top-level HTML file.** A lone one of any name is the homepage; with more
   than one, `index.html` must be among them.
-- **3 MB per file, 20 MB per site.**
+- **20 MB per file and per site.** The Wix MCP's upload tool takes 10 MB per call.
 - **Static files only** in a drop. A project that needs a build is built first,
   and its build output is dropped.
 
@@ -344,7 +380,7 @@ plugin or connector in a chat client).
 | --- | --- |
 | `400` `MISSING_INDEX_HTML`, `FILE_TOO_LARGE`, `TOTAL_TOO_LARGE` | In `details.applicationError.code`; fix the files. |
 | `403 PERMISSION_DENIED` on a drop | The token expired or is missing, or the site isn't the caller's. An anonymous site takes upload and release, not a drop. |
-| `500` on a drop or upload | A malformed multipart body; rebuild it as shown. The same body fails again. |
+| `500` on a drop or upload | A failure on Wix's side, with a request id and no body. Retry once; if it fails again, keep the request id for feedback and hand over the drop page. A body built by hand (not `wix.multipart()`) can also answer `500`: rebuild it as shown. |
 | `404` on the anonymous route | The hour passed or the site was claimed. |
 
 ## Send feedback to Wix
@@ -357,7 +393,7 @@ workaround.
 
 ## Route the request correctly
 
-- **A new site from the user's files**: [What decides the route](#what-decides-the-route).
+- **A new site from files, the user's or ones you write**: [What decides the route](#what-decides-the-route).
 - **A change to a site published this way**: the [same site](#change-it-later);
   upload and release while it's anonymous.
 - **An anonymous site the user wants to keep**: [claim it](#claim-it-into-the-users-account), or the save link.
@@ -368,5 +404,5 @@ workaround.
   custom code in the editor.
 - **Images, videos or documents for a site's media**: [Upload Media to Wix](../media/upload-media-to-wix.md).
 
-Don't create the site from a template: that makes an empty site, not a copy of
-the user's files.
+Don't create the site from a template: that makes an empty site, not the site's
+files.

package/skills/wix-manage/references/stores/add-store-pages-to-site.md

@@ -4,6 +4,9 @@ description: Adds missing checkout and cart pages to a site when Stores app is i
 ---
 # Add Store Pages to Site
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 This recipe demonstrates how to add checkout and cart pages to a Wix site when the Stores app is installed but pages are missing.
 
 ## Overview

package/skills/wix-manage/references/stores/change-store-currency.md

@@ -5,6 +5,9 @@ description: "Changes the store's payment currency through Site Properties and e
 
 # Change Store Currency
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 Use the [Change a Site's Regional Properties (Currency, Time Zone, Language) via Site Properties API](../site-properties/change-payment-currency-site-properties.md) recipe to set the requested payment currency and read it back. Confirm the change with the user before updating it.
 
 Catalog product responses may temporarily show the previous currency after carts and checkout use the new one. Allow time for propagation, then recheck.

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

@@ -5,6 +5,9 @@ description: Mandatory first recipe for every Wix Stores Catalog V3 create-produ
 
 # Create Product (Catalog V3)
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 Use this recipe for one or multiple Catalog V3 products. Catalog V1 remains supported through [Create Product (Catalog V1)](create-product-catalog-v1.md).
 
 > [!IMPORTANT]

package/skills/wix-manage/references/stores/find-products-query-and-search-catalog-v3.md

@@ -5,6 +5,9 @@ description: Find, search, query, and list products from a Wix Store using Catal
 
 # RECIPE: Business Recipe – Find Products in a Wix Store (Query and Search, Catalog V3)
 
+> These calls need the Wix Stores app on the site (`appDefId` `215238eb-22a5-4c36-9e7b-e7c08025e04e`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 Find products in a Wix store using the Catalog V3 Search Products and Query Products APIs.
 
 ## Article: How to Find Products