@wix/agent-skills 1.15.1 → 1.16.1

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

@@ -0,0 +1,63 @@
+---
+name: "Bookings Dashboard Navigation"
+description: "Builds direct links to Wix Bookings dashboard pages on manage.wix.com — services list, edit a specific service, calendar, booking list, staff, availability, resources, and settings pages. Pairs each main Bookings 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."
+---
+
+# Bookings Dashboard Navigation
+
+Build direct links into the Wix Bookings pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+All Wix Bookings (app ID `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) pages live under:
+
+```
+https://manage.wix.com/dashboard/{metaSiteId}/bookings/{route}
+```
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Services list | `bookings/services` | All services (appointments, classes, courses) |
+| Create service | `bookings/services/form` | New service form |
+| Edit service | `bookings/services/form/{serviceId}` | A specific service |
+| Service templates | `bookings/services/templates-catalog` | Create a service from a template |
+| Calendar | `bookings/calendar` | Sessions and daily schedule |
+| Booking list | `bookings/bookings/bookings-list` | All bookings in a table view |
+| Staff list | `bookings/staff` | Staff members |
+| Staff details | `bookings/staff/details/{staffMemberId}` | A specific staff member |
+| Availability | `bookings/availability` | Staff working hours / availability management |
+| Default business hours | `bookings/availability/default-hours` | The default weekly hours |
+| Resources | `bookings/resource-management/resource-types` | Resource types (rooms, equipment) |
+| Bookings settings | `bookings/settings` | Settings hub |
+| Booking policies | `bookings/settings/policies` | Cancellation / booking policies |
+| Reminders | `bookings/settings/reminders` | Email & SMS reminders |
+| Booking form | `bookings/settings/booking-form-page` | The customer booking form |
+| Apps & integrations | `bookings/integrations` | Bookings integration channels |
+
+Entity-specific links (`{serviceId}`, `{staffMemberId}`) accept the entity's ID appended as an extra path segment. Query params can follow (e.g. `?referralInfo=...`).
+
+Older link formats (`bookings/scheduler/owner/...`) still redirect to the current pages, so links found in existing content keep working.
+
+## 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 |
+|---|---|---|
+| Service | `POST /bookings/v2/services/query` · `GET /bookings/v2/services/{serviceId}` | `bookings/services/form/{serviceId}` (edit) or `bookings/services` (list) |
+| Booking | `POST /bookings/v2/extended-bookings/query` | `bookings/bookings/bookings-list` |
+| Staff member | `POST /bookings/v1/staff-members/query` | `bookings/staff/details/{staffMemberId}` |
+| Session / event | `POST /calendar/v3/events/query` | `bookings/calendar` |
+| Resource type | Resources v2 APIs (`/bookings/v2/resources/...`) | `bookings/resource-management/resource-types` |
+| Booking policy | Services API `bookingPolicy` fields | `bookings/settings/policies` |
+
+Example — after creating a service, hand back its edit link:
+
+```
+Created "Deep Tissue Massage".
+Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/bookings/services/form/{serviceId}
+```
+
+## Notes
+
+- Pages marked with an entity ID also work without it (they fall back to the list/create state).

package/skills/wix-manage/references/bookings/diagnose-availability-issues.md

@@ -27,9 +27,13 @@ Don't diagnose by default. If the owner just wants to know the status and the se
 
 - Owner asks whether an **appointment-based** service has availability / bookable times → [Step 1](#step-1--report-the-current-availability-status).
 - Owner reports the service has **no bookable times**, or that **customers can't book (or can't even find) it** → Step 1 will come back empty, so go on to diagnose ([Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking) onward). For "can't book / can't find," start diagnosis at Step 2 even if Step 1 returned slots — a hidden service still lists slots (see the note in Step 1).
+- Owner **narrows to a specific date/time** ("why nothing on 3 Aug from 4pm?") and the slot check for that window comes back **empty** → this **is** a "why" question. Run the diagnosis (Step 2 → [Step 3](#step-3--run-the-diagnosis)). **Do not answer it from the empty slot list alone.**
 
 > **Scope:** appointment-based services.
 
+> ## 🚫 Never invent the cause (read first)
+> An empty `ListAvailabilityTimeSlots` tells you **there is no availability — not *why*.** The reason for an empty result comes **only** from the checks in Steps 2–4 (`service.hidden` / `onlineBooking`, then `DiagnoseAvailability`, then policy/capacity). **Never state a cause you didn't get from them** — do not guess "the staff aren't scheduled," "it's outside working hours," a date-range problem, or anything else from a zero slot count. If you haven't run the diagnosis, you don't know the reason yet: run it, then report what it returns.
+
 ---
 
 ## Prerequisites
@@ -56,7 +60,7 @@ Interpret the result:
 |-----------------|---------------------|------------|
 | One or more **bookable** slots | **Bookable.** | Tell the owner in a sentence and stop — no diagnosis needed unless they ask why/how to change something. |
 | Slots exist but **none are bookable** (`nonBookableReasons` / `bookingPolicyViolations` set) | **Not bookable — policy/capacity.** | This is the cause. Surface it directly ([policy/capacity causes](#booking-policy--capacity-slots-exist-but-arent-bookable)). No need to run `DiagnoseAvailability`. |
-| **No slots at all** | **No availability.** | Diagnose: go to [Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking). |
+| **No slots at all** | **No availability.** | Diagnose: go to [Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking), then [Step 3](#step-3--run-the-diagnosis). **Don't guess the reason from the empty list** — an empty result isn't a cause. |
 
 > **The hidden-service trap.** A service that's **hidden** from the site, or has **online booking turned off**, can still list slots here — so bookable slots do **not** prove customers can book it. When the complaint is "customers can't book / can't find this service" (as opposed to "the calendar is empty"), **run [Step 2](#step-2--rule-out-service-level-blockers-visibility--online-booking) before trusting the slot count** — it's the single most common cause and neither `ListAvailabilityTimeSlots` nor `DiagnoseAvailability` detects it.
 
@@ -174,6 +178,7 @@ curl -X POST 'https://www.wixapis.com/_api/service-availability/v2/time-slots/di
 | `RESOURCE_HAS_NO_WORKING_HOURS` | `CHECK_STAFF_WORKING_HOURS` | The staff member has no working-hours schedule. Configure working hours — see [Bookings Staff Setup](bookings-staff-setup.md). |
 | `RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION` | `CHECK_WORK_LOCATIONS` | Assigned resources have availability windows, but none at a location the service offers. Add working hours at an offered location, offer the service where the staff works, or assign a provider who works at the offered location. |
 | `NO_RESOURCE_AVAILABILITY_WINDOWS` | `CHECK_STAFF_WORKING_HOURS` | No availability windows exist anywhere in the diagnosed range. Add working hours, or widen the range. |
+| `REQUESTED_DATE_OUTSIDE_SERVICE_AVAILABILITY_RANGE` | `CHECK_SERVICE_AVAILABILITY_RANGE` | The dates being checked fall **outside the date range the service itself is offered on** (its own availability window) — so no slots exist there, whatever the staff's hours. Covers both *before* the range starts and *after* it ends. Deterministic: returned on the **standard call** (no `deep` needed) and **ahead of** the working-hours/blocked reasons, so trust it over `RESOURCE_NOT_IN_WORKING_HOURS`. Fix: extend the service's available date range, or check dates within it. (The exact bounds aren't in `resolvedContext`; if you need to state the start date, read `service.schedule.firstSessionStart` via [Services V2 Get Service](#step-2--rule-out-service-level-blockers-visibility--online-booking).) |
 | `REQUESTED_LOCATION_NOT_OFFERED_BY_SERVICE` | `CHECK_SERVICE_LOCATIONS` | A requested `locations` filter isn't offered by the service. Drop the filter or fix the service's locations. |
 | `DURATION_TOO_LONG_FOR_AVAILABLE_WINDOWS` | `REDUCE_DURATION_OR_BUFFER` | The service is longer than every free window. Shorten it or lengthen working hours. |
 | `BUFFER_TIME_ELIMINATES_WINDOWS` | `REDUCE_DURATION_OR_BUFFER` | Buffer time consumes all otherwise-free windows. Reduce the buffer or lengthen working hours. |
@@ -241,6 +246,7 @@ Whether you're reporting status or a cause, reply in plain, friendly language an
 | Provider has no working hours | "The staff for this service don't have any working hours set, so there are no times to offer. Let's set their hours." |
 | Provider works only at other locations | "Your staff have working hours, but not at the location(s) this service is offered at. We can either add hours at one of the service's locations, or offer the service where they already work." |
 | No working-hours windows in range | "None of the staff for this service have working hours in the dates you're checking. Let's add or extend their hours — or try a different date range." |
+| Dates outside the service's available range | "This service isn't offered on the dates you're looking at — it's only available during a set date range. Want me to extend the dates it's offered, or check a date inside that range?" |
 | Outside working hours (deep) | "For those dates, your staff simply aren't scheduled to work, so there's nothing to offer. Let's add working hours in that period." |
 | Within hours but blocked/busy (deep) | "Your staff are scheduled to work then, but that time is already taken up — by existing bookings or events on their calendar. Freeing some of it up will open slots." |
 | Service too long / buffer too large | "The service is longer than any open gap in your staff's schedule (the duration plus buffer doesn't fit). Shortening it a bit, or widening working hours, would open up slots." |
@@ -269,6 +275,7 @@ Popular reasons a service shows no availability, and where each surfaces:
 | Provider has no working hours | `RESOURCE_HAS_NO_WORKING_HOURS` | Configure working hours. |
 | Provider works only at other locations | `RESOURCE_NOT_AVAILABLE_AT_SERVICE_LOCATION` | Align staff work locations with the service's offered locations. |
 | No working-hours windows in range | `NO_RESOURCE_AVAILABILITY_WINDOWS` | Add working hours / widen the range. |
+| Dates fall outside the service's own offered date range | `REQUESTED_DATE_OUTSIDE_SERVICE_AVAILABILITY_RANGE` | Extend the service's available date range, or check dates within it. |
 | No windows — outside working hours (deep) | `RESOURCE_NOT_IN_WORKING_HOURS` (`deep: true`) | Add or extend working hours in the range. |
 | No windows — within hours but blocked/busy (deep) | `RESOURCE_BLOCKED` (`deep: true`) | Free up blocked time / check the external calendar. |
 | Service too long / buffer too large for the windows | `DURATION_TOO_LONG_FOR_AVAILABLE_WINDOWS`, `BUFFER_TIME_ELIMINATES_WINDOWS` | Shorten duration/buffer or lengthen hours. |
@@ -285,6 +292,8 @@ Popular reasons a service shows no availability, and where each surfaces:
 - **`hasAvailability: false` + empty `reasons` ≠ a confirmed problem.** It means "no blocking cause detected." Always confirm with `ListAvailabilityTimeSlots`.
 - **`DiagnoseAvailability` is ALPHA and feature-toggled.** If it returns nothing for an obviously broken service, the `diagnoseAvailabilityEndpoint` toggle may be off — fall back to Step 4.
 - **A 403 is an auth problem, not a diagnosis.** The action needs the `bookings:availability:v2:time_slot:diagnose_availability` permission; a caller without it gets a 403 with an empty body. Don't read that as "no cause found" — confirm the caller has the permission (see [Prerequisites](#prerequisites)).
+- **Never state a cause you didn't diagnose.** A zero slot count from `ListAvailabilityTimeSlots` means "no availability," not a reason. Guessing "the staff aren't scheduled to work" (or any other cause) from an empty list is the failure this recipe exists to prevent — run `DiagnoseAvailability` and report the code it returns. This applies especially when the owner narrows to a specific date/time and it comes back empty: that's a diagnosis trigger, not a status reply.
+- **A date-range restriction is a distinct cause — don't blame staff hours for it.** When a service is only offered within a set date range and the owner asks about a date outside it, `DiagnoseAvailability` returns `REQUESTED_DATE_OUTSIDE_SERVICE_AVAILABILITY_RANGE` on the **standard call**, ahead of the deep working-hours/blocked reasons. If you see it, say the service isn't offered on those dates — **not** that staff aren't scheduled (they may well work then; the service just isn't offered). It covers dates both before and after the range.
 - **`deep: true` needs a `serviceId`** (resource-only + `deep` → `MISSING_ARGUMENTS`) and only refines a "no windows" result — it does nothing when windows already exist.
 - **`DiagnoseAvailability` ignores booking policy and capacity** — those come from `ListAvailabilityTimeSlots` (Step 1 / Step 4).
 - **Resource-only diagnosis is lighter.** Passing `resourceId` without `serviceId` catches missing/empty working hours but skips the window, location, and deep checks, so it can return "inconclusive" for service-dependent problems. Valid when there's no service context (e.g. the staff editor); otherwise pair the resource with a service.

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

@@ -0,0 +1,44 @@
+---
+name: "CMS Dashboard Navigation"
+description: "Builds direct links to the Wix CMS (Content Manager) dashboard pages on manage.wix.com — the collections list and a specific collection's items view. Pairs collections and data items with their read APIs so you can fetch data 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."
+---
+
+# CMS Dashboard Navigation
+
+Build direct links into the CMS (Content Manager) pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+All CMS (app ID `e593b0bd-b783-45b8-97c2-873d42aacaf4`) pages live under:
+
+```
+https://manage.wix.com/dashboard/{metaSiteId}/wix-cms/{route}
+```
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Collections list | `wix-cms` | All CMS collections on the site |
+| Collection items | `wix-cms/data/{collectionId}` | A specific collection's items table |
+
+Older links (`database`, `developer-tools/database`) redirect to `wix-cms`. `{collectionId}` is the collection's ID (e.g. `Stores/Products` for app collections, or the ID you set when creating the collection).
+
+## 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 |
+|---|---|---|
+| Collection (schema) | `GET /wix-data/v2/collections/{collectionId}` · `GET /wix-data/v2/collections` (list) | `wix-cms/data/{collectionId}` |
+| Data item | `POST /wix-data/v2/items/query` (body includes `dataCollectionId`) · `GET /wix-data/v2/items/{itemId}?dataCollectionId=...` | `wix-cms/data/{collectionId}` (the collection's items table) |
+
+Example — after creating a collection and inserting items:
+
+```
+Created the "Recipes" collection with 12 items.
+Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/wix-cms/data/Recipes
+```
+
+## Notes
+
+- There is no per-item dashboard URL; link the collection's items table.
+- Unknown deeper paths fall back to the longest matching route, so a wrong collection ID lands on the CMS home rather than a 404.

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,6 +163,7 @@ 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

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}
+```