@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -25,11 +25,13 @@ This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix
 Before inserting or updating items, you need to know the collection's field names and types. If you don't already know the schema:
 
 1. **Query existing items** - Fetch a few items to infer field names from the data
-2. **Get collection schema** - Use `GET /collections/{dataCollectionId}` for full field definitions
-3. **List collections** - Use `GET /collections?fields=displayName` to see what collections exist (see [Schema Management](cms-schema-management.md))
+2. **Get collection schema** - Use `GET /collections/{dataCollectionId}` for full field definitions, **including `plugins`** — don't omit the `plugins` field when fetching or listing schemas
+3. **List collections** - Use `GET /collections?fields=displayName,plugins` to see what collections exist (see [Schema Management](cms-schema-management.md))
 
 It may be, that user refers to schema by its `displayName` rather than `id`, if collection is not found list all collections to find the right `id` (`dataCollectionId`) to use.
 
+**Check for the Draft Items plugin.** If the collection's `plugins` include the Draft Items plugin, this collection gates items behind a draft/publish workflow. **Stop and load [CMS Draft & Publish Workflow](cms-publishing-flow.md)** before making any data changes, and follow its instructions instead of the plain CRUD flow below for that collection.
+
 ---
 
 ## Insert Data Item
@@ -367,7 +369,7 @@ curl -X DELETE \
 | `IMAGE` | Image reference (HTTP url or wix:image://v1/{mediaId}/{friendlyName}) | `"wix:image://v1/3f72369f2219e2ee853e9e3df0217ce1.jpg/Colorful%20Business%20Cards.jpg"` |
 | `VIDEO` | Video reference (HTTP url or wix:video://v1/{mediaId}/{friendlyName}) | `"wix:video://v1/11062b_484182533ede4b9a81329daf20238867/Sketching%20Design%20Concepts#posterUri=11062b_484182533ede4b9a81329daf20238867f000.jpg&posterWidth=1920&posterHeight=1080"` |
 | `DOCUMENT` | Document reference  (HTTP url or wix:document://v1/{mediaId}) | `"wix:document://v1/..."` |
-| `MEDIA_IMAGE` | Wix Media Image | `{ "url": "http://...", "height": 640, "width": 480, "alt": "Picture" }` |
+| `MEDIA_IMAGE` | Wix Media Image | `{ "id": "<mediaId>", "url": "http://...", "height": 640, "width": 480, "altText": "Picture" }` |
 | `MEDIA_VECTOR_ART` | Wix Media Vector Art | `{ "uri": "wix:vector://v1/...", "viewBox": "0 0 100 100", "contentType": "shape", "svgContent": "<svg>...</svg>" }` |
 | `URL` | Web URL | `"https://example.com"` |
 | `RICH_TEXT` | HTML content | `"<p>Rich text</p>"` |
@@ -429,6 +431,31 @@ curl -X DELETE \
 
 ## Error Handling
 
+### Recovering from WDE0110
+
+`WDE0110` means the Wix CMS (Wix Data) app is not installed on the site. If the user has
+explicitly asked to install it, install the app before retrying the data-item request:
+
+```http
+POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
+```
+
+```json
+{
+  "tenant": {
+    "tenantType": "SITE",
+    "id": "<SITE_ID>"
+  },
+  "appInstance": {
+    "appDefId": "e593b0bd-b783-45b8-97c2-873d42aacaf4"
+  }
+}
+```
+
+After the installation succeeds, retry the original `POST /wix-data/v2/items` request. If the
+user only asks what the error means or how to fix it, explain this installation step and ask for
+confirmation before performing the install.
+
 | Error | Cause | Solution |
 |-------|-------|----------|
 | `COLLECTION_NOT_FOUND` | Invalid collection ID | Check collection exists |
@@ -449,3 +476,4 @@ curl -X DELETE \
 - [CMS Schema Management](cms-schema-management.md) - Creating and modifying collections
 - [CMS References & Relationships](cms-references-and-relationships.md) - Linking collections
 - [CMS Data Operations Extended](cms-data-operations-extended.md) - Count, upsert, aggregate
+- [CMS Draft & Publish Workflow](cms-publishing-flow.md) - Collections gated behind a draft/publish (Draft Items plugin) workflow

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

@@ -0,0 +1,287 @@
+---
+name: "CMS Draft & Publish Workflow (Draft Items plugin)"
+description: "Interact with CMS collections that gate their items behind a draft/publish workflow via the Draft Items plugin. Covers detecting the plugin, locating the paired drafts collection, reading published vs draft items, authoring/editing drafts, and publishing, unpublishing, reverting, and deleting items. Key endpoints: /wix-data/v2/items/publish-draft, /wix-data/v2/items/unpublish, /wix-data/v2/collections/add-draft-items-plugin, and the paired drafts collection referenced by draftItemsPluginOptions.draftsCollectionId."
+---
+# CMS Draft & Publish Workflow
+
+> **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.
+
+This reference is for an agent that must **detect** whether a collection uses this workflow, **read** the right version of an item, and **drive item state transitions** (publish, unpublish, revert, delete) through the public Wix Data REST API.
+
+## Prerequisites
+
+1. Wix CMS enabled on the site.
+2. The collection already exists (see [CMS Schema Management](cms-schema-management.md)).
+3. API access with write permission on the collection's data items (reading, authoring drafts, and publishing all go through the Data Items API), plus collection-management permission to add or remove the Draft Items plugin.
+
+## Required APIs
+
+- **Data Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction) — includes Publish Data Item Draft and Unpublish Data Item.
+- **Data Collections API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction) — Add/Delete Data Collection Plugin.
+
+---
+
+## Mental model — where drafts live
+
+A collection with the Draft Items plugin has **two paired surfaces**:
+
+| Surface | Collection ID | Holds |
+|---------|---------------|-------|
+| Published (live) | the collection's own id (e.g. `articles`) | Items visible on the site |
+| Paired drafts | `draftItemsPluginOptions.draftsCollectionId` (conventionally `<collectionId>__drafts`, e.g. `articles__drafts`) | Pending drafts (new items not yet published, or edits to a published item) |
+
+**Read the drafts collection id from the plugin — do not assume the `__drafts` suffix.** The published collection's Draft Items plugin exposes `draftItemsPluginOptions.draftsCollectionId`; the drafts collection's plugin exposes `draftItemsPluginOptions.publishedCollectionId`. Resolve the pairing from those fields.
+
+Item **state** is derived from where the item exists:
+
+| State | Meaning | Where it lives |
+|-------|---------|----------------|
+| **DRAFT** | Not yet on the site | Only in the drafts collection |
+| **PUBLISHED** | Live on the site, no pending edit | Only in the published collection |
+| **CHANGED** | Live on the site **and** has a pending draft edit | In both the published and drafts collections |
+
+> Treat state as **server-authoritative**. Derive it from the published/draft surfaces (or the item the API returns) — never render an optimistic status before the write confirms.
+
+---
+
+## 1. Detect the workflow on a collection
+
+Read the collection and inspect its **plugins**. A collection with the **Draft Items plugin** uses the draft/publish workflow.
+
+```bash
+curl -X GET \
+'https://www.wixapis.com/wix-data/v2/collections/articles' \
+-H 'Authorization: <AUTH>'
+```
+
+- **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.
+
+---
+
+## 2. Read items
+
+Reads target a specific surface — there is no merged view:
+
+- **Published items**: query the published collection (`articles`).
+- **Drafts**: query the drafts collection resolved from `draftItemsPluginOptions.draftsCollectionId` (e.g. `articles__drafts`).
+
+**Endpoint**: `POST /wix-data/v2/items/query`
+
+```json
+{
+  "dataCollectionId": "articles__drafts",
+  "query": {
+    "filter": { "category": "news" },
+    "paging": { "limit": 50, "offset": 0 }
+  }
+}
+```
+
+- To read only **published** items, query with `dataCollectionId: "articles"`.
+- To read **drafts**, query with `dataCollectionId` set to the paired drafts collection id.
+- Compute **CHANGED** by checking whether an item id exists in **both** the published and drafts surfaces.
+
+---
+
+## 3. Write & transition items
+
+### Author a brand-new draft
+
+Insert into the **drafts** collection. The item starts as **DRAFT**.
+
+**Endpoint**: `POST /wix-data/v2/items`
+
+```json
+{
+  "dataCollectionId": "articles__drafts",
+  "dataItem": {
+    "data": { "title": "Draft headline", "body": "Work in progress" }
+  }
+}
+```
+
+### Edit a draft
+
+Update or patch against the **drafts** collection (`articles__drafts`). See [CMS Data Items CRUD](cms-data-items-crud.md) for Update/Patch shapes.
+
+### 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**).
+
+**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`).
+
+### 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.
+
+**Endpoint**: `POST /wix-data/v2/items/publish-draft`
+
+```bash
+curl -X POST \
+'https://www.wixapis.com/wix-data/v2/items/publish-draft' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+    "dataCollectionId": "articles",
+    "dataItemId": "5331fc15-9441-4fd4-bc7b-7f6870c69228"
+}'
+```
+
+**Response** — the newly-published item (the draft is gone):
+```json
+{
+  "dataItem": {
+    "id": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
+    "dataCollectionId": "articles",
+    "data": { "_id": "5331fc15-...", "title": "Draft headline" }
+  }
+}
+```
+
+- Returns `NOT_FOUND` if no pending draft exists for that id.
+
+### Unpublish a live item (PUBLISHED/CHANGED → DRAFT)
+
+Retracts a published item back to draft state. Pass the **published** collection id.
+
+**Endpoint**: `POST /wix-data/v2/items/unpublish`
+
+```bash
+curl -X POST \
+'https://www.wixapis.com/wix-data/v2/items/unpublish' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-d '{
+    "dataCollectionId": "articles",
+    "dataItemId": "5331fc15-9441-4fd4-bc7b-7f6870c69228",
+    "copyToDraft": true
+}'
+```
+
+`copyToDraft` controls the two "keep vs discard" variants:
+
+| `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" |
+
+- Response (`copyToDraft: true`) carries the **new draft**, not the removed live item.
+- Returns `NOT_FOUND` if no published item exists with that id.
+
+### Revert to live version (CHANGED → PUBLISHED, discard the pending edit)
+
+Discard the pending draft while keeping the live version as-is: **delete the item from the drafts collection**.
+
+```bash
+curl -X DELETE \
+'https://www.wixapis.com/wix-data/v2/items/5331fc15-...?dataCollectionId=articles__drafts' \
+-H 'Authorization: <AUTH>'
+```
+
+### Delete an item entirely (removes both versions)
+
+Deleting must remove **both** the live item and any pending draft.
+
+```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>'
+```
+
+---
+
+## 4. Enable / disable the workflow on a collection
+
+**Enable** — add the Draft Items plugin (requires collection-management permission). Use the dedicated endpoint; the Draft Items plugin cannot be added through the generic add-plugin call.
+
+**Endpoint**: `POST /wix-data/v2/collections/add-draft-items-plugin`
+
+```bash
+curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{
+        "dataCollectionId": "articles",
+        "publishPluginConflictAction": "FAIL_WHEN_PUBLISH_INSTALLED"
+  }'
+```
+
+`publishPluginConflictAction` controls what happens if the legacy Publish plugin is already installed:
+
+| Value | Behavior |
+|-------|----------|
+| `FAIL_WHEN_PUBLISH_INSTALLED` | Fail if the Publish plugin is already installed. |
+| `COPY_DRAFT_ITEMS_WITH_DRAFT_STATUS` | Copy draft items with draft status; where a published version already exists, discard the draft item. |
+
+**Disable** — remove the plugin:
+
+**Endpoint**: `POST /wix-data/v2/collections/delete-draft-items-plugin`
+
+```bash
+curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/delete-draft-items-plugin' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{
+        "dataCollectionId": "articles",
+        "draftItemsRemovalAction": "FAIL_IF_DRAFT_ITEMS_EXIST"
+  }'
+```
+
+`draftItemsRemovalAction` decides the fate of existing drafts:
+
+| Value | Behavior |
+|-------|----------|
+| `FAIL_IF_DRAFT_ITEMS_EXIST` | Fail if any draft items exist. |
+| `DISCARD_EXISTING_DRAFT_ITEMS` | Discard draft items (data loss). |
+| `PUBLISH_EXISTING_DRAFT_ITEMS` | Publish draft items, overwriting any currently published items with the same ids. |
+
+---
+
+## Permissions
+
+At the REST level, every read/author/publish/unpublish call here goes through the Data Items API and requires write access to the collection's data items. Beyond that, individual draft and publish actions may be further permission-restricted per caller on the collection, and there's no way to introspect those permissions ahead of time — so attempt the action and **handle authorization errors gracefully** if the write is rejected.
+
+---
+
+## Decision table — collection + desired action → API + permission
+
+| Collection state | Desired action | API call | Permission needed |
+|------------------|----------------|----------|-------------------|
+| Draft Items plugin absent | Any write | Normal insert/update — writes go live immediately | Write Data Items |
+| Draft Items enabled | Detect workflow | `GET /collections/{id}` → inspect plugins for the Draft Items plugin; read `draftItemsPluginOptions.draftsCollectionId` | (read) |
+| Draft Items enabled | Read published items | `POST /items/query` on the published id | read |
+| Draft Items enabled | Read drafts | `POST /items/query` on the drafts collection id | read |
+| 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 /items` on the drafts collection | Write Data Items |
+| DRAFT / CHANGED | Publish (→ PUBLISHED) | `POST /items/publish-draft` (published id) | Write Data Items |
+| PUBLISHED / CHANGED | Unpublish, keep as draft (→ DRAFT) | `POST /items/unpublish` `copyToDraft:true` | Write Data Items |
+| PUBLISHED / CHANGED | Unpublish, discard | `POST /items/unpublish` `copyToDraft:false` | Write Data Items |
+| CHANGED | Revert to live version (discard edit) | `DELETE /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 |
+| plain, no plugin | Enable workflow | `POST /collections/add-draft-items-plugin` | Manage Data Collections |
+
+---
+
+## Agent gotchas
+
+- **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.
+- **Publishing deletes the draft.** After `publish-draft`, the pending draft no longer exists; the returned item is the live one.
+- **Unpublish overwrites an existing draft** when `copyToDraft: true` — any pending edit for that id is replaced with the previously-published data.
+- **Refetch after publish/unpublish.** State changes across the published/draft surfaces are not guaranteed atomic; re-query rather than assuming local state. Wix Data is eventually consistent — use `consistentRead: true` if you must read immediately after a write.
+
+---
+
+## Related Documentation
+
+- [Publish Data Item Draft](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/publish-data-item-draft)
+- [Unpublish Data Item](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/unpublish-data-item)
+- [Data Collections API](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction) — plugin management
+- [CMS Data Items CRUD](cms-data-items-crud.md) — insert/update/patch/delete/query shapes
+- [CMS Schema Management](cms-schema-management.md) — creating and modifying collections
+- [Wix Data and Eventual Consistency](https://dev.wix.com/docs/api-reference/business-solutions/cms/eventual-consistency)

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -112,6 +112,31 @@ curl -X GET \
 }
 ```
 
+This works for `displayName`/`displayField`. **Permission updates currently fail with `WDE0075: Not recognized role provided in permissions.`** Use the full-replace endpoint below to update a collection's permissions.
+
+**To change permissions on an existing collection, use the full-replace endpoint instead** (`UpdateDataCollection`, not `PatchDataCollection`) — it requires the collection's current `revision` and full `fields` array (get both from a `GET` first), but it does work:
+
+**Endpoint**: `PUT /wix-data/v2/collections`
+
+```json
+{
+  "collection": {
+    "id": "Products",
+    "revision": "3",
+    "displayName": "Product Catalog",
+    "fields": [ /* the collection's full current non-system fields, from GET */ ],
+    "permissions": {
+      "insert": "ADMIN",
+      "update": "ADMIN",
+      "remove": "ADMIN",
+      "read": "SITE_MEMBER"
+    }
+  }
+}
+```
+
+Don't delete and recreate a collection just to change its permissions — this full-replace call is the working path.
+
 ## Field Types Reference
 
 | Type | Description | Example Value |
@@ -122,7 +147,7 @@ curl -X GET \
 | `DATE` | Date only | `"2024-01-15"` |
 | `DATETIME` | Date and time | `{ "$date": "2024-01-15T10:00:00.000Z" }` |
 | `IMAGE` | Image reference | `"wix:image://v1/..."` |
-| `MEDIA_IMAGE` | Wix Media Image | `{ "url": "http://...", "height": 640, "width": 480, "alt": "Picture" }` |
+| `MEDIA_IMAGE` | Wix Media Image | `{ "id": "<mediaId>", "url": "http://...", "height": 640, "width": 480, "altText": "Picture" }` |
 | `MEDIA_VECTOR_ART` | Wix Media Vector Art | `{ "uri": "wix:vector://v1/...", "viewBox": "0 0 100 100", "contentType": "shape", "svgContent": "<svg>...</svg>" }` |
 | `URL` | Web URL | `"https://example.com"` |
 | `RICH_TEXT` | HTML content | `"<p>Rich text</p>"` |
@@ -138,8 +163,15 @@ curl -X GET \
 | `ANYONE` | All visitors (including anonymous) |
 | `SITE_MEMBER` | Logged-in site members |
 | `SITE_MEMBER_AUTHOR` | Members who created the item |
+| `PRIVILEGED` | Access to collection is controlled per role |
 | `ADMIN` | Site admins only |
 
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `WDE0110` | Wix CMS (Wix Data) app is not installed on the site | Install it: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install` with body `{"tenant":{"tenantType":"SITE","id":"<SITE_ID>"},"appInstance":{"appDefId":"e593b0bd-b783-45b8-97c2-873d42aacaf4"}}`, then retry. See the [Install Wix Apps recipe](../app-installation/install-wix-apps.md). |
+
 ## Related Documentation
 
 - [Data Collections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)

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

@@ -0,0 +1,46 @@
+---
+name: "Contacts Dashboard Navigation"
+description: "Builds direct links to Wix Contacts (CRM) dashboard pages on manage.wix.com — the contacts list, a specific contact's view page, contact import, and the segments page. Pairs each main contacts entity 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."
+---
+
+# Contacts Dashboard Navigation
+
+Build direct links into the contacts (CRM) pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+Contacts pages are split across **two apps** with two URL namespaces:
+
+- **Contacts** (`74bff718-5977-47f2-9e5f-a9fd0047fd1f`) — the contact list, contact view, and import. Routes under `contacts/`.
+- **Segments** (`ee070097-0850-4f23-ad8c-3cdd4efd5244`) — contact segments. Routes under `segments/`.
+
+## Contacts Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Contacts list | `contacts` | All contacts (filter, label, search) |
+| Contact view | `contacts/view/{contactId}` | A specific contact's details and activity |
+| Import contacts | `contacts/contacts/import` | Import contacts (CSV, Gmail) |
+
+Older `contacts/import` links redirect to the current import route.
+
+## Segments Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Segments | `segments` | Contact segments (saved smart filters over contacts) |
+
+## 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.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Contact | `POST /contacts/v4/contacts/query` · `GET /contacts/v4/contacts/{id}` | `contacts/view/{contactId}` (view) or `contacts` (list) |
+| Label | `GET /contacts/v4/labels` · `POST /contacts/v4/labels/query` | `contacts` (labels filter the contacts list) |
+| Segment | Segments API (no public REST read endpoint) | `segments` |
+
+Example — after creating a contact, hand back its view link:
+
+```
+Created contact "Dana Cohen".
+View them here: https://manage.wix.com/dashboard/{metaSiteId}/contacts/view/{contactId}
+```

package/skills/wix-manage/references/contacts/create-a-contact.md

@@ -0,0 +1,82 @@
+---
+name: "Create a Contact"
+description: Creates a contact with the Contacts API. Covers the minimum identifying fields, the single-object shape of `email` and `phone`, and adding a physical address with the ISO 3166-2 subdivision format required for state, region, and province codes.
+---
+# Create a Contact
+
+## Description
+Creates a contact, optionally with a physical address in the same call.
+
+## API Endpoint
+`POST https://www.wixapis.com/contacts/v5/contacts`
+
+## Steps
+
+### 1. Create the contact
+
+At least one of `name.first`, `name.last`, `email.email`, or `phone.phone` must be present. Copy this body and change the values:
+
+```json
+{
+  "contact": {
+    "name": { "first": "Maria", "last": "Gomez" },
+    "email": { "email": "maria.gomez@example.com" },
+    "phone": { "phone": "+1 212 555 0134" }
+  }
+}
+```
+
+`email` is a single object, exactly as above. Send a list instead — `emails: [{ tag: 'MAIN', email: '…' }]` — and the request still returns `200`, but the field is discarded: the contact is created with no email at all. Nothing in the response reports this, so it surfaces only when something later reads the contact back and the email is missing. The same holds for `phone`. Read `contact.email.email` off the create response to confirm it was stored.
+
+### 2. Add an address (optional)
+
+Include `addresses` in the same create call when the user gave a street address:
+
+```json
+{
+  "contact": {
+    "name": { "first": "Maria", "last": "Gomez" },
+    "email": { "email": "maria.gomez@example.com" },
+    "addresses": [
+      {
+        "tag": "HOME",
+        "address": {
+          "addressLine": "350 Fifth Avenue",
+          "city": "New York",
+          "subdivision": "US-NY",
+          "postalCode": "10118",
+          "country": "US"
+        }
+      }
+    ]
+  }
+}
+```
+
+`addresses[].address` takes either `addressLine` as free text, or a structured `streetAddress` object — not both.
+
+`tag` is one of `OTHER`, `HOME`, `WORK`, `BILLING`, `SHIPPING`, and that list is closed — there is no "untagged" or "none" member. When the user did not say what kind of address it is, leave `tag` out and it defaults to `OTHER`; inventing a value for that case is rejected with `400`.
+
+### 3. Write `subdivision` in ISO 3166-2 form
+
+`subdivision` is the 2-letter country code, a hyphen, then 1-3 characters for the state, region, prefecture or province: `US-NY`, `GB-ENG`, `FR-976`. A bare state code is rejected:
+
+```
+HTTP 400 {"message":"contact is invalid:
+`-- addresses [at index 0] is invalid:
+    `-- address is invalid:
+       `-- subdivision is not a valid subdivision code",
+ "details":{"validationError":{"fieldViolations":[{
+   "field":"contact.addresses[0].address.subdivision",
+   "description":"is not a valid subdivision code","violatedRule":"FORMAT",
+   "data":{"type":"SUBDIVISION"}}]}}}
+```
+
+The Create Contact reference describes this field as a "short code (2 or 3 letters)" and gives `NY` as the example, which the server does not accept. Use the hyphenated form.
+
+`country` is the plain [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code — `US`, no hyphen. Only `subdivision` carries the country prefix.
+
+## Related
+
+- [Create Contact](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/create-contact)
+- [Update Contact](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/update-contact)

package/skills/wix-manage/references/contacts/update-a-contact.md

@@ -0,0 +1,119 @@
+---
+name: "Update a Contact"
+description: Updates an existing contact's email, phone, name, or address with the Contacts API. Covers locating the contact when the user identifies it by name, passing its current revision, and the ISO 3166-2 subdivision format required for state, region and province codes.
+---
+# Update a Contact
+
+## Description
+Changes fields on a contact that already exists — its email, phone, name, or address.
+
+## API Endpoints
+- `POST https://www.wixapis.com/contacts/v5/contacts/search` — locate the contact
+- `PATCH https://www.wixapis.com/contacts/v5/contacts/{contactId}` — change its fields
+- `POST https://www.wixapis.com/contacts/v5/contacts/{contactId}/addresses` — add one address
+
+Contacts has two live versions. Use the v5 endpoints above for updates; the v4 update takes a
+different, more deeply nested body, and mixing the two shapes is rejected with
+`400 {"message":"Expected an object"}`.
+
+## Steps
+
+### 1. Locate the contact with Search Contacts, not Query Contacts
+
+When the user identifies a contact by name — "my contact Jordan Lee" — the lookup is Search
+Contacts. Query Contacts filters on a small closed set of fields that does not include the
+contact's name, so a query filtered by name is rejected:
+
+```
+HTTP 400 {"message":"value Field 'name.first' is not declared as filterable",
+ "details":{"validationError":{"fieldViolations":[{"field":"value",
+   "description":"Field 'name.first' is not declared as filterable"}]}}}
+```
+
+Search Contacts takes a free-text expression, and matches on names. Note the doubled `search` —
+the outer one is the search request, the inner one is the free-text clause:
+
+```json
+{ "search": { "search": { "expression": "Jordan Lee" } } }
+```
+
+Read both `id` and `revision` off the contact it returns. Step 2 needs both. Query Contacts is
+still the right call when you already have an email address, a phone number or an id to filter on.
+
+### 2. Send the update with the contact's current revision
+
+Copy this body and change the values. Only the fields you send are being set; `id` and `revision`
+identify which contact and which version you are updating:
+
+```json
+{
+  "contact": {
+    "id": "<contact id from step 1>",
+    "revision": "<revision from step 1>",
+    "email": { "email": "jordan.lee@newmail.com" }
+  }
+}
+```
+
+Swap `email` for `phone` (`{ "phone": { "phone": "+1-212-555-0100" } }`) or `name` to change those
+instead. `revision` changes on every write, so re-read it if an update conflicts.
+
+### 3. Add an address with Add Contact Address
+
+To attach one more address, post it to the contact's `addresses` sub-resource rather than sending
+the whole contact — the address is appended, so existing addresses survive:
+
+```json
+{
+  "revision": "<revision from step 1>",
+  "address": {
+    "address": {
+      "addressLine": "350 Fifth Avenue",
+      "city": "New York",
+      "subdivision": "US-NY",
+      "postalCode": "10118",
+      "country": "US"
+    }
+  }
+}
+```
+
+Note the doubled `address` here too: the outer object is the contact's address entry, which can
+carry a `tag`, and the inner one is the postal address itself.
+
+`tag` is one of `OTHER`, `HOME`, `WORK`, `BILLING`, `SHIPPING`, and that list is closed — there is
+no "untagged" or "none" member. When the user did not say what kind of address it is, leave `tag`
+out, exactly as above; inventing a value for that case is rejected:
+
+```
+HTTP 400 {"message":"address is invalid:
+`-- tag enum must be in [UNKNOWN_ADDRESS_TAG(0), OTHER(1), HOME(2), WORK(3), BILLING(4), SHIPPING(5)]"}
+```
+
+### 4. Write `subdivision` in ISO 3166-2 form
+
+`subdivision` is the 2-letter country code, a hyphen, then 1-3 characters for the state, region,
+prefecture or province: `US-NY`, `GB-ENG`, `FR-976`. A bare state code is rejected, on updates as
+well as on creates:
+
+```
+HTTP 400 {"message":"address is invalid:
+`-- address is invalid:
+    `-- subdivision is not a valid subdivision code",
+ "details":{"validationError":{"fieldViolations":[{
+   "field":"address.address.subdivision",
+   "description":"is not a valid subdivision code","violatedRule":"FORMAT",
+   "data":{"type":"SUBDIVISION"}}]}}}
+```
+
+The Contacts reference describes this field as a "short code (2 or 3 letters)" and gives `NY` as
+the example, which the server does not accept. Use the hyphenated form.
+
+`country` is the plain [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code
+— `US`, no hyphen. Only `subdivision` carries the country prefix.
+
+## Related
+
+- [Update Contact](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/update-contact)
+- [Search Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/search-contacts)
+- [Add Contact Address](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/add-contact-address)