@wix/agent-skills 1.16.2 → 1.17.0

package/skills/wix-manage/references/bookings/booking-system-integration-gaps.md

@@ -51,7 +51,7 @@ The Wix Bookings system contains **fundamental undocumented integration patterns
 - ❌ **NOT** documented booking status vs order status separation
 - ❌ **NOT** documented service properties preservation in checkout
 - ❌ **NO** mention of `BACKOFFICE_MERCHANT` channel requirement
-- ❌ **NO** explanation of why checkout/order APIs are needed for bookings
+- ❌ **NO** explanation of why the cart/order APIs are needed for bookings
 
 **Additional Service-Specific Gaps**:
 - ❌ **Courses**: Dual API requirement (booking + calendar events) completely undocumented
@@ -69,7 +69,7 @@ The Wix Bookings system contains **fundamental undocumented integration patterns
 - Create booking → Booking system creates reservation only
 - Use booking ID as catalog item in ecom system
 - Ecom system handles all pricing, tax, discount calculations
-- Create checkout and order for actual payment processing
+- Create a cart and place the order for actual payment processing
 - Async messaging system handles payment confirmation
 - Booking status (CONFIRMED) independent of payment status
 
@@ -125,7 +125,7 @@ Actual Required Flow: Booking API → Ecom Integration → Payment ✓
 
 **Universal Pattern** (Works for ALL Service Types):
 ```
-Create Booking → Extract Booking ID → Use as Catalog Item ID → Create Checkout → Create Order → Process Payment
+Create Booking → Extract Booking ID → Use as Catalog Item ID → Create Cart → Place Order → Process Payment
 ```
 
 ### 2. Identify Service Type-Specific Booking Patterns
@@ -266,26 +266,33 @@ Create calendar events using `POST https://www.wixapis.com/calendar/v3/bulk/even
 
 **MAJOR DISCOVERY**: ALL booking payments use identical ecommerce integration pattern.
 
-**Step 6A: Create Checkout with Booking ID as Catalog Item**
+**Step 6A: Create Cart with Booking ID as Catalog Item**
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout))
+Cart V2 unifies cart and checkout — there is no separate checkout entity, so the created cart's `id` is what later steps use as the cart/checkout id.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart))
 
 ```json
 {
-  "lineItems": [{
+  "catalogItems": [{
     "catalogReference": {
       "catalogItemId": "<BOOKING_ID>",
       "appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97"
     },
     "quantity": 1
-  }],
-  "channelType": "WEB"
+  }]
 }
 ```
 
-**Step 6B: Create Order for Payment Processing**
+**Step 6B: Place Order for Payment Processing**
+
+First calculate the cart to obtain a price-verification token:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/calculate` — read `summary.priceVerificationToken` from the response.
+
+Then place the order, passing that token:
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder`
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/place-order` (body `{ "priceVerificationToken": "<TOKEN>" }`)
 
 **Critical Architecture Discoveries**:
 - **Automatic ID Transformation**: Booking IDs automatically valid as catalog item IDs
@@ -297,7 +304,7 @@ Create calendar events using `POST https://www.wixapis.com/calendar/v3/bulk/even
 
 **Payment Processing Architecture**:
 ```
-Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
+Booking (CONFIRMED) → Cart → Place Order → Payment Processing (async)
                                               ↓
                                         Messaging System
                                               ↓
@@ -322,7 +329,7 @@ Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
 **Service Packages**: Multi-service booking + ecom integration
 
 **Universal Integration Considerations**:
-- All service types use same checkout/order creation pattern
+- All service types use the same cart/order creation pattern
 - Pricing calculations always handled by ecom system
 - Async payment confirmation applies to all booking types
 - Service properties preserved across all integration points
@@ -406,7 +413,7 @@ Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
 * [Standard Booking Flow](https://dev.wix.com/docs/api-reference/business-solutions/bookings/flow-single-service-booking) - Missing payment integration
 * [Create Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking) - No payment processing guidance
 * [Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types) - Missing integration patterns
-* [Ecommerce Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/introduction) - No booking integration mention
+* [Ecommerce Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) - No booking integration mention
 
 **Completely Undocumented**:
 * **Booking→Ecom Integration**: Universal pattern affecting all booking payments

package/skills/wix-manage/references/bookings/create-class-service.md

@@ -149,7 +149,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `defaultCapacity` is **required** — sets max participants per session
 - After creation, class sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 
-Save the `serviceId` from the response: `results[0].item.service.id`
+**Response:** Save the service ID from `results[0].itemMetadata.id`
 
 ---
 

package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md

@@ -19,7 +19,7 @@ Step-by-step flow for implementing a complete booking experience using REST APIs
 - **Services API**: [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
 - **Time Slots V2 API**: [List Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots)
 - **Bookings API**: [Create Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking), [Confirm Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/confirm-booking)
-- **eCommerce API**: [Create Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout)
+- **eCommerce API**: [Create Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart)
 
 ---
 
@@ -226,15 +226,17 @@ Use the `id` and `revision` from the Create Booking response. Set `paymentStatus
 
 **Result**: Booking status changes to `CONFIRMED` and is visible in the booking calendar.
 
-### For online payments: Create checkout
+### For online payments: Create a cart
 
-**4a. Create Checkout**
+Cart V2 unifies cart and checkout — there is no separate checkout entity. The created cart's `id` is what you use for the checkout URL and for placing the order.
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts`
+**4a. Create Cart**
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts`
 
 ```json
 {
-  "lineItems": [
+  "catalogItems": [
     {
       "catalogReference": {
         "catalogItemId": "<BOOKING_ID>",
@@ -242,22 +244,33 @@ Use the `id` and `revision` from the Create Booking response. Set `paymentStatus
       },
       "quantity": 1
     }
-  ],
-  "channelType": "WEB"
+  ]
 }
 ```
 
-Use the booking ID as `catalogItemId` with the Wix Bookings app ID.
+Use the booking ID as `catalogItemId` with the Wix Bookings app ID. Save `cart.id` from the response.
 
 **4b. Get Checkout URL**
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/getCheckoutUrl`
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/get-checkout-url`
 
 Redirect the user to the returned `checkoutUrl`. After payment, the booking is automatically confirmed.
 
-**4c. Create Order (alternative, server-to-server)**
+**4c. Place Order (alternative, server-to-server)**
+
+First calculate the cart to get a price-verification token:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/calculate`
+
+Save `summary.priceVerificationToken` from the response, then place the order:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/place-order`
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder`
+```json
+{
+  "priceVerificationToken": "<PRICE_VERIFICATION_TOKEN>"
+}
+```
 
 Creates an order directly without redirect.
 

package/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md

@@ -10,7 +10,7 @@ This recipe documents how to convert CMS collections into sellable product catal
 
 Converting a CMS collection to a catalog enables:
 - Items in the collection become purchasable products
-- Integration with Wix Cart and Checkout APIs
+- Integration with the Wix Cart API (Cart V2, which unifies cart and checkout)
 - Real-time price and availability from your CMS data
 
 ## Prerequisites
@@ -73,7 +73,7 @@ POST https://www.wixapis.com/wix-data/v2/collections/add-plugin
 Most Wix sites with Stores, Bookings, or similar apps already have eCommerce installed. Check by querying the Cart API:
 
 ```
-POST https://www.wixapis.com/ecom/v1/carts
+POST https://www.wixapis.com/ecom/v2/carts
 ```
 
 ## Step 3: Use Catalog Items in Cart
@@ -87,12 +87,12 @@ e593b0bd-b783-45b8-97c2-873d42aacaf4
 ### Add CMS Catalog Item to Cart
 
 ```
-POST https://www.wixapis.com/ecom/v1/carts/{cartId}/add-to-cart
+POST https://www.wixapis.com/ecom/v2/carts/{cartId}/add-line-items
 ```
 
 ```json
 {
-  "lineItems": [
+  "catalogItems": [
     {
       "catalogReference": {
         "appId": "e593b0bd-b783-45b8-97c2-873d42aacaf4",
@@ -133,4 +133,4 @@ CMS Catalogs are best for simple product catalogs. For complex eCommerce needs,
 
 - [CMS Schema Management](cms-schema-management.md)
 - [CMS Data Operations](cms-data-items-crud.md)
-- [Wix Cart API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/introduction)
+- [Wix Cart API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction)

package/skills/wix-manage/references/rich-content/author-ricos-rich-content.md

@@ -1,10 +1,12 @@
 ---
 name: "Author Ricos Rich Content"
-description: Hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) used across Wix Blog posts, Stores product descriptions, Events, and CMS rich-text fields. Covers every common node shape — paragraphs, headings, lists, blockquotes, dividers, tables (with cell fills), code blocks, images — plus inline text decorations and the nesting rules the format enforces.
+description: Authoritative recipe for hand-authoring valid Ricos rich-content JSON (the richContent/nodes tree) used across Wix Blog posts, Stores product descriptions, Events, and CMS rich-text fields. Use whenever a user asks to create, output, or return Ricos, richContent, or nodes-tree JSON; retrieve and read this full recipe before API schema search or constructing the JSON. Covers paragraphs, headings, lists, blockquotes, dividers, tables, code blocks, images, buttons, audio, video, galleries, collapsible lists, HTML embeds, inline decorations, and nesting rules.
 ---
 
 # Author Ricos Rich Content
 
+> **Routing rule (READ FIRST).** When hand-authoring or returning Ricos / `richContent` JSON, use **this recipe** — the shapes, nesting rules, spacer paragraphs, and plugin nodes below. Do not rely on API schema search alone; it misses those details. After this recipe loads, do not perform additional schema or documentation searches for node types covered here; compose and self-audit the JSON from this file. When the user only wants JSON output, **do not** call Ricos convert/validate APIs.
+
 Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON. The same structure is embedded by many products: a Blog post's `draftPost.richContent`, a Store product's rich description, an Events description, and CMS rich-text fields all expect a Ricos document. This recipe is the **authoring reference for that node tree**: the valid shape of each node, how nodes nest, and how to format text. It is intentionally product-agnostic — the consuming API decides *where* the document goes; this recipe governs *what a valid document looks like*.
 
 > A Ricos document is an object with a `nodes` array: `{ "nodes": [ /* block nodes */ ] }`. Whatever field the consuming API exposes (e.g. `richContent`), it holds this object. For validating or converting an existing document to/from HTML/Markdown, see [Ricos Converter Service](ricos-converter-service.md).
@@ -15,10 +17,58 @@ Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON.
 - Every node carries a `type`, an optional `id`, and (for container nodes) a `nodes` array of children. Node `id`s are optional when authoring for a create request — the API generates them; the examples below omit `id` for brevity.
 - **TEXT is a leaf.** A TEXT node only ever lives inside a `PARAGRAPH`, `HEADING`, or `CODE_BLOCK`. It must **never** sit directly in the root `nodes` array or inside a `LIST_ITEM`, `BLOCKQUOTE`, or `TABLE_CELL` — those must contain a `PARAGRAPH` (or `HEADING`) that then contains the TEXT. See [Nesting rules](#nesting-rules).
 - Failing to wrap TEXT correctly produces the parse error **"Expected a paragraph node but found TEXT"**.
+- **Block nodes do not get automatic vertical gap when rendered** — insert empty `PARAGRAPH` spacer nodes between sibling blocks when you need breathing room. See [Vertical spacing between blocks](#vertical-spacing-between-blocks).
+
+## Required plugin shape checklist
+
+Use this checklist while composing and again before returning JSON. Treat every path below as required for the described request:
+
+- **Button CTA:** emit a root-level `BUTTON`, never a `PARAGRAPH` with an inline `LINK`. Include `buttonData.type: "LINK"`, `buttonData.text`, `buttonData.link.url`, `buttonData.link.target`, and `buttonData.containerData`.
+- **Hosted audio:** emit `{ "type": "AUDIO", "nodes": [], "audioData": { ... } }`. The empty `nodes` array is on the AUDIO node beside `audioData` — never inside `audioData`. Include `audioData.containerData.alignment`, `width`, and `textWrap`, plus `audioData.audio.src.id`.
+- **Video with thumbnail:** place `videoData.video.src` and `videoData.video.duration` inside `video`; place `videoData.thumbnail` beside `video`, with `src.id`, `width`, and `height`.
+- **Gallery:** emit one root-level `GALLERY`. Put images in `galleryData.items`, not as child IMAGE nodes. Every item uses `image.media` with `src`, `width`, and `height`; include `galleryData.options.layout.type` and `numberOfColumns`.
+- **Collapsible FAQ:** use `COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT`. Every PARAGRAPH includes `paragraphData`, and every item includes both title and body.
+- **HTML embed:** emit a root-level `HTML` with `htmlData.source`, either `url` or `html`, and `htmlData.containerData.width`, `height`, and `alignment`.
+
+## Vertical spacing between blocks
+
+The renderer does **not** add margin between stacked block nodes. Adjacent paragraphs, headings, images, videos, tables, collapsible lists, buttons, galleries, and other blocks will sit flush against each other unless you separate them explicitly.
+
+**Use an empty `PARAGRAPH` as a spacer** — a paragraph with no `nodes` (no TEXT children):
+
+```json
+{ "type": "PARAGRAPH" }
+```
+
+Place spacer paragraphs at the root `nodes` level (or inside a `CARD` page) wherever layout needs vertical rhythm:
+
+- **After headings** — before the following body copy or media block.
+- **Between paragraphs** — when two text blocks should not run together visually.
+- **After block plugins** — images, videos, audio, galleries, tables, collapsible lists, HTML embeds, buttons, dividers, and lists often need a spacer before the **next distinct section** (not between every adjacent block in a minimal snippet the user enumerated).
+- **After blockquotes** — only when the following block is a separate section; skip the spacer when the user asked for a blockquote immediately followed by a specific paragraph in one compact output.
+- **Before major sections** — optional extra spacer when transitioning from one content group to another.
+
+When the user requests **only** specific nodes in one JSON output (e.g. "a blockquote and then a paragraph"), include exactly those nodes — do not add spacer paragraphs they did not ask for.
+
+Do **not** rely on `\n` inside `textData.text` for spacing — that does not create a real line break between blocks. Do **not** expect `paragraphData` margins or `containerData` alone to separate unrelated sibling nodes; the empty paragraph is the supported spacing mechanism.
+
+**Example — spacer after an image and before a table:**
+
+```json
+{
+  "nodes": [
+    { "type": "IMAGE", "imageData": { /* … */ } },
+    { "type": "PARAGRAPH" },
+    { "type": "TABLE", "nodes": [ /* … */ ], "tableData": { /* … */ } },
+    { "type": "PARAGRAPH" },
+    { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Next section.", "decorations": [] } } ], "paragraphData": {} }
+  ]
+}
+```
 
 ## Block node shapes
 
-**PARAGRAPH** — the base text container. An empty paragraph — `{ "type": "PARAGRAPH" }` — acts as a vertical spacer. `paragraphData.textStyle.textAlignment` accepts `AUTO`·`LEFT`·`CENTER`·`RIGHT`·`JUSTIFY`:
+**PARAGRAPH** — the base text container. An empty paragraph — `{ "type": "PARAGRAPH" }` — is the **vertical spacer** between block nodes (the renderer adds no gap on its own). See [Vertical spacing between blocks](#vertical-spacing-between-blocks). `paragraphData.textStyle.textAlignment` accepts `AUTO`·`LEFT`·`CENTER`·`RIGHT`·`JUSTIFY`:
 
 ```json
 {
@@ -142,6 +192,122 @@ Ricos is Wix's rich-content format — a tree of typed nodes serialized as JSON.
 }
 ```
 
+**BUTTON** — a standalone call-to-action block. **Not the same as an inline `LINK` decoration** on TEXT (that is hyperlinked body copy; this is a labeled button control). **`buttonData.type` is required** on every BUTTON node — use `"LINK"` for URL navigation or `"ACTION"` for viewer click handlers (never omit `type` even when `link` is present). Two `buttonData.type` values:
+
+- **`LINK`** — navigates to a URL when clicked (`link.url`, `link.target`: `BLANK`·`SELF`, optional `link.rel`).
+- **`ACTION`** — triggers a viewer `onClick` handler (store the node in JSON; behavior is configured in the Ricos viewer, not in the document body).
+
+```json
+{
+  "type": "BUTTON",
+  "buttonData": {
+    "type": "LINK",
+    "text": "Get Started",
+    "link": { "url": "https://example.com", "target": "BLANK", "rel": { "nofollow": true } },
+    "containerData": { "alignment": "CENTER", "width": { "size": "ORIGINAL" }, "textWrap": true },
+    "styles": { "borderRadius": 4, "borderWidth": 0, "backgroundColor": "#116DFF", "textColor": "#FFFFFF" }
+  }
+}
+```
+
+**AUDIO** — uploaded audio via Wix Media `src.id`, or an embed variant whose `audioData.html` holds an iframe (SoundCloud, Spotify). Include `audioData.containerData` with `alignment` and width settings, and use an empty `nodes: []` array because AUDIO has no child nodes. Optional fields include `coverImage` (`src.id`, `width`, `height`), `name`, `authorName`, and `disableDownload`:
+
+```json
+{
+  "type": "AUDIO",
+  "nodes": [],
+  "audioData": {
+    "containerData": { "alignment": "CENTER", "width": { "size": "CONTENT" }, "textWrap": true },
+    "audio": { "src": { "id": "mp3/f0f74f_48772df0375c41cd88e8e29370ccf899" } },
+    "disableDownload": true,
+    "coverImage": { "src": { "id": "f0f74f_2973832f552e4002b58ec6abbe7fce71~mv2.png" }, "width": 436, "height": 524 },
+    "name": "Track title",
+    "authorName": "Artist name"
+  }
+}
+```
+
+**VIDEO** — Wix Media `video.src.id`, `duration` (seconds), and a `thumbnail` (`src.id`, `width`, `height`). YouTube and other embeds use the same `VIDEO` node shape with the appropriate media id:
+
+```json
+{
+  "type": "VIDEO",
+  "videoData": {
+    "containerData": { "width": { "size": "CONTENT" }, "alignment": "CENTER" },
+    "video": { "src": { "id": "video/11062b_a552731f40854d16a91627687fb8d1a6/1080p/mp4/file.mp4" }, "duration": 14.08 },
+    "thumbnail": { "src": { "id": "media/11062b_a552731f40854d16a91627687fb8d1a6f000.jpg" }, "width": 1920, "height": 1080 }
+  }
+}
+```
+
+**GALLERY** — multiple images in one block. Each `items[]` entry wraps `image.media` with `src` (`id` or `url`), `width`, and `height`. `galleryData.options` controls layout (`layout.type`: `GRID`, `numberOfColumns`, `orientation`; `item.ratio`, `item.crop`; `thumbnails.placement`):
+
+```json
+{
+  "type": "GALLERY",
+  "galleryData": {
+    "containerData": { "width": { "size": "CONTENT" }, "alignment": "CENTER", "textWrap": true },
+    "items": [
+      { "image": { "media": { "src": { "id": "8bb438_36726a2d14ec44ee9edc5693bade1092.jpg" }, "width": 3648, "height": 5472 } } },
+      { "image": { "media": { "src": { "id": "8bb438_6bbf8e82fe8f4b79b6e03ee79b66fd6a.jpg" }, "width": 1920, "height": 1280 } } }
+    ],
+    "options": {
+      "layout": { "type": "GRID", "horizontalScroll": false, "orientation": "COLUMNS", "numberOfColumns": 3 },
+      "item": { "ratio": 1, "crop": "FILL" },
+      "thumbnails": { "placement": "NONE" }
+    }
+  }
+}
+```
+
+**COLLAPSIBLE_LIST** — FAQ-style expandable items. Nesting is `COLLAPSIBLE_LIST → COLLAPSIBLE_ITEM → COLLAPSIBLE_ITEM_TITLE | COLLAPSIBLE_ITEM_BODY → PARAGRAPH → TEXT` (body cells may also contain other supported block plugins such as IMAGE or VIDEO). The item wrapper type is **`COLLAPSIBLE_ITEM`** — not `COLLAPSIBLE_LIST_ITEM` or other variants:
+
+```json
+{
+  "type": "COLLAPSIBLE_LIST",
+  "nodes": [
+    {
+      "type": "COLLAPSIBLE_ITEM",
+      "nodes": [
+        {
+          "type": "COLLAPSIBLE_ITEM_TITLE",
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Question?", "decorations": [] } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } }
+          ]
+        },
+        {
+          "type": "COLLAPSIBLE_ITEM_BODY",
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Answer text.", "decorations": [] } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } }
+          ]
+        }
+      ]
+    }
+  ],
+  "collapsibleListData": {
+    "containerData": { "alignment": "CENTER", "textWrap": true },
+    "expandOnlyOne": false,
+    "initialExpandedItems": "FIRST",
+    "direction": "LTR"
+  }
+}
+```
+
+`initialExpandedItems`: `NONE`·`FIRST`·`ALL`. Set `isQapageData: true` in list metadata when the list should render as FAQ structured data in search results.
+
+**HTML** — embeds external content in an iframe. Provide either `url` (page URL) or inline `html` markup; `source` is typically `"HTML"`. Size via `containerData.width` / `height` (`custom` pixel strings or `size`):
+
+```json
+{
+  "type": "HTML",
+  "htmlData": {
+    "containerData": { "width": { "custom": "550" }, "height": { "custom": "550" }, "alignment": "CENTER" },
+    "url": "https://example.com/embed",
+    "source": "HTML"
+  }
+}
+```
+
 ## Inline text formatting (decorations)
 
 Apply formatting with the `decorations` array on a TEXT node. Each decoration is an object with a `type` and (for some types) a data field:
@@ -169,6 +335,7 @@ Apply formatting with the `decorations` array on a TEXT node. Each decoration is
 | `COLOR`                                    | `colorData: { foreground: "#hex" }` (add `background` for highlight) |
 | `LINK`                                     | `linkData: { link: { url, target: "BLANK" } }`             |
 | `FONT_SIZE`                                | `fontSizeData: { unit: "PX", value: 24 }`                  |
+| `SPOILER`                                  | _(none — `{ "type": "SPOILER" }` hides text behind a reveal control)_ |
 
 - **Mixed formatting in one paragraph → split into multiple TEXT nodes** (one per style run) inside the same PARAGRAPH. A single TEXT node carries one consistent set of decorations.
 - Use a plain hex string in `foreground` for colors.
@@ -229,12 +396,16 @@ Note the mixed-run paragraph at the end: the linked words are their own TEXT nod
 
 | Parent | Valid children |
 | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| Root `nodes`                         | PARAGRAPH, HEADING, BULLETED_LIST, ORDERED_LIST, BLOCKQUOTE, DIVIDER, IMAGE, TABLE, CODE_BLOCK         |
+| Root `nodes`                         | PARAGRAPH, HEADING, BULLETED_LIST, ORDERED_LIST, BLOCKQUOTE, DIVIDER, IMAGE, TABLE, CODE_BLOCK, BUTTON, AUDIO, VIDEO, GALLERY, COLLAPSIBLE_LIST, HTML |
 | PARAGRAPH / HEADING / CODE_BLOCK     | TEXT                                                                                                  |
 | BULLETED_LIST / ORDERED_LIST         | LIST_ITEM                                                                                             |
 | LIST_ITEM / BLOCKQUOTE               | PARAGRAPH (which then contains TEXT)                                                                  |
 | TABLE → TABLE_ROW → TABLE_CELL       | cell contains PARAGRAPH / HEADING / IMAGE                                                              |
-| IMAGE                                | CAPTION (optional)                                                                                    |
+| IMAGE / VIDEO                        | CAPTION (optional)                                                                                    |
+| COLLAPSIBLE_LIST                     | COLLAPSIBLE_ITEM                                                                                      |
+| COLLAPSIBLE_ITEM                     | COLLAPSIBLE_ITEM_TITLE, COLLAPSIBLE_ITEM_BODY                                                        |
+| COLLAPSIBLE_ITEM_TITLE / _BODY       | PARAGRAPH (and other plugins supported inside collapsible cells — see COLLAPSIBLE_LIST above)           |
+| BUTTON / AUDIO / GALLERY / HTML      | _(leaf — `nodes: []` or omit)_                                                                        |
 
 ## Self-audit before returning the document
 
@@ -246,4 +417,10 @@ All decidable from the JSON itself — check before handing the document to a co
 4. **Headings carry a `level`** (1–6) and nest logically (don't jump H2 → H4).
 5. **No `\n` inside `textData.text`** — split into sibling nodes; mixed inline formatting → split into multiple TEXT runs.
 6. **Images** use a Wix Media `id` (not a raw URL), with `width`, `height`, and meaningful `altText`.
-7. **Links** — every `LINK` decoration has a valid `url` and `target`.
+7. **Links** — every `LINK` decoration has a valid `url` and `target`. Use a `BUTTON` block with `buttonData.type: "LINK"` for CTAs — not an inline `LINK` decoration styled to look like a button.
+8. **Buttons** — every BUTTON includes **`buttonData.type`** (`LINK` requires `link.url`; `ACTION` has no URL). Omitting `type` is invalid even when `link` is set. `LINK` buttons and inline `LINK` decorations serve different purposes.
+9. **Media blocks** — AUDIO has root-level `nodes: []` and `audioData.containerData`; VIDEO keeps `thumbnail` beside `video` under `videoData`; every GALLERY item is under `galleryData.items` and carries `image.media.src`, `width`, and `height`.
+10. **Collapsible lists** — every item has both `_TITLE` and `_BODY`, each wrapping content through `PARAGRAPH → TEXT`, and every PARAGRAPH has `paragraphData`.
+11. **HTML embeds** — `htmlData` includes `source`, `containerData.width`, `containerData.height`, and either `url` or `html` (not both empty).
+12. **Spoiler** — `SPOILER` is a decoration on `TEXT` (or `containerData.spoiler` on some block plugins in editor output); preserve it verbatim on edit.
+13. **Vertical spacing** — stacked block nodes that should not appear cramped are separated by empty `{ "type": "PARAGRAPH" }` spacers — especially after images, videos, tables, collapsible lists, galleries, buttons, and between consecutive paragraphs. Missing spacers produce a wall-of-blocks layout with no renderer-added margin.