@wix/agent-skills 1.31.0 → 1.31.2

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/custom-apps/use-app-skills-and-app-tools.md

@@ -1,6 +1,6 @@
 ---
 name: "Use App Skills and App Tools"
-description: "Discovers and runs what the apps installed on a Wix site add for AI agents: app skills, which are an app's instructions for a task (for example pricing a product for customers in another country, or checking a property listing before it is published), and app tools, which are actions and lookups an app exposes. Use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app, skill or tool. Covers reading a chosen skill's instructions and running the app tools it allows, or running a single app tool directly."
+description: "Discovers and runs what the apps installed on a Wix site add for AI agents: app skills, which are an app's instructions for a task (for example pricing a product for customers in another country, or checking a property listing before it is published), and app tools, which are actions and lookups an app exposes. Use every time a site has custom apps installed, before acting on the user's request: knowing which apps are installed doesn't tell what they can do, so only this skill's discovery calls show whether one of them handles the request. Also use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app, skill or tool. Covers reading a chosen skill's instructions and running the app tools it allows, or running a single app tool directly."
 ---
 # Use App Skills and App Tools
 
@@ -28,6 +28,8 @@ The `www.wixapis.com/_api/...` URLs below are these APIs' public endpoints; the
 
 Make both calls. They are independent, so run them in parallel.
 
+Whenever the site has custom apps installed, make both calls before deciding how to handle the user's request, even if the request doesn't seem to involve an app: you can tell whether an app handles it only from what these calls return. Make them once per site in a conversation.
+
 **List App Skills**: `GET https://www.wixapis.com/_api/app-skills/v1/app-skills`
 
 ```bash

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/send-feedback-to-wix.md

@@ -0,0 +1,92 @@
+---
+name: "Send Feedback to Wix"
+description: Relay the user's feedback about building with Wix — the APIs, docs, recipes, Wix MCP and tooling — to Wix, attributed to the authenticated user. Covers when to offer it, how to compose a message Wix can act on, and the call that sends it. Use when the user asks to report something to Wix, is frustrated with a Wix API or flow, or a recipe's flow fell short. Not a support channel, and not for the user's own site content.
+---
+
+# Send Feedback to Wix
+
+Feedback reaches the Wix teams that own the APIs, docs, recipes and tooling.
+It is about the experience of building with Wix, not the user's site content,
+and it is not support.
+
+## When to offer it
+
+Sending is the user's call; offering is yours. Offer once per issue, in plain
+prose, and send only after the user says yes.
+
+- **The user asks** to tell Wix something. Confirm the wording, then send.
+- **The user is frustrated** with Wix, or reports a Wix bug. Acknowledge it,
+  then offer.
+- **The run hit friction**: a call that failed or needed retries, an error that
+  didn't explain itself, a doc or recipe that was wrong, missing or ambiguous, a
+  workaround you had to invent, a flow that fell back to a worse route.
+- **At the end of a run** that hit any of these, even ones you recovered from.
+
+When you offer, invite the user to add their own words. Never send without a
+yes, never twice for the same issue, and never for a single transient error.
+
+## Compose the message
+
+Wix receives free text. A bare sentence can't be triaged, so send a summary of
+the whole run in four parts.
+
+**Provenance**, as labeled lines; drop the ones that don't apply:
+
+```
+Agent / model: <the agent and model you are>
+Wix tooling: <Wix MCP, Wix CLI, REST from a shell, ...>
+Recipes: <the recipes this run followed>
+Wix products and APIs: <Stores, headless drop, the upload tool, ...>
+Site: <metaSiteId> · dashboard: <url> · live: <url>
+Other ids: <request ids, upload ids, execution ids>
+```
+
+**Narrative**:
+
+- In the user's words: what they added, verbatim. Skip when empty.
+- What the user set out to do, and how the run went: what worked and what
+  fought back.
+- A condensed play-by-play: the key calls, what came back, and the decisions
+  you made. Distilled, not a transcript.
+
+**Friction points**, the heart of it. For each: the step or endpoint, the HTTP
+status and error text, the request id, what you expected, and what you did
+instead. Add your best guess at where the fault lives, from API behavior, API
+schema, API docs, docs articles or examples, a recipe, the Wix MCP, Wix
+tooling, or unsure, and say whether you confirmed it. "Unsure" beats a wrong
+guess.
+
+**Bottom line**: one or two sentences naming the most important problem and
+its impact.
+
+Show the user the final wording before sending. Leave out tokens, API keys and
+credentials, and any personal data the feedback doesn't need.
+
+## Send it
+
+The call identifies the user, so it takes a user identity: a token from
+`npx @wix/cli@latest token`, or account scope in a script. A site-scoped token
+is refused as anonymous.
+
+```bash
+curl -sS -X POST "https://www.wixapis.com/mcp-serverless/v1/headless-feedback" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
+  -d '{"message":"<the composed message>"}'
+```
+
+In an `ExecuteWixAPI` script, with the message as one text file in the `files`
+param:
+
+```javascript
+async function run() {
+  return await wix.request({ scope: 'account', method: 'POST',
+    url: 'https://www.wixapis.com/mcp-serverless/v1/headless-feedback',
+    body: { message: files[0].content } });
+}
+```
+
+| Response | Meaning |
+| --- | --- |
+| `200` with `{}` | Sent. Tell the user. |
+| `500` "Unable to determine target user id, anonymous messages are not allowed" | The token was site-scoped. Get a user token and send once more. |
+| `401` or `403` | The CLI login expired. Run `npx @wix/cli@latest login`, get a new token, and send once more. If it fails again, show the user the response. |