@wix/agent-skills 1.14.0 → 1.15.0

package/skills/wix-manage/references/marketing/generate-and-publish-marketing-plan.md

@@ -0,0 +1,209 @@
+---
+name: "Generate a Marketing Plan and Schedule Its Posts"
+description: "End-to-end flow to generate an AI-powered social media marketing plan for a site and schedule its generated posts for publishing, using the Wix Marketing Plan API. Recommends configuring marketing settings (goal, tone, cadence, content pillars) before the first generation, generates the plan asynchronously, polls until it's ready, then schedules the DRAFT posts. Includes generating posts for additional activities. Use for 'generate a marketing plan', 'create a social media plan/calendar', or 'schedule my plan's posts' requests."
+---
+# RECIPE: Generate a Marketing Plan and Schedule Its Posts
+
+This recipe generates a site's AI marketing plan — a schedule of marketing activities (social campaigns, blog posts, emails) from today through the end of next month — and schedules the social posts it generates. Generation is **asynchronous and non-deterministic**: you fire it, poll until it's ready, then act on the results.
+
+Base URL for all endpoints: `https://www.wixapis.com/promote/marketing-plan-service/v1`.
+
+**Prerequisites:**
+- The site must be **published** — generation draws on the published site. This isn't validated at call time; an unpublished site yields a `FAILED` plan or an `ACTIVE` plan with no posts. Verify before generating.
+- For posts to be **scheduled/published**, the target channels must be connected through the Publisher (see the [Create and Publish a Social Media Post](https://dev.wix.com/docs/api-reference/business-management/marketing/skills) recipe for the connect flow). Drafts for unconnected channels silently stay as drafts (STEP 4).
+
+---
+
+## STEP 1 (recommended before your first plan): Tailor the plan with marketing settings
+
+For a first-time plan, configure marketing settings **before** generating (STEP 2), so the first plan reflects the brand's goal, voice, and cadence. Settings are optional — the service applies per-site defaults if you skip this — but they're read **only at generation time**, so a plan generated with defaults won't change until you regenerate. After a plan exists, changing settings requires a regenerate (STEP 2) to take effect.
+
+**API Endpoint:** `POST https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-settings`
+
+Both `marketingSettings` and `fieldMask` are **required**. `fieldMask` lists the paths to write, and **every path in `fieldMask` must be present** in `marketingSettings` (otherwise the call fails with `INVALID_FIELD_MASK_ERROR`).
+
+**Language and location cannot be set here.** If the request targets a language or a place ("posts in Spanish", "customers near Berlin"), those are site-derived, read-only fields on marketing settings — never put `language`, `targetLocations`, or `businessLocation` in the request, and never tell the user this call changed them. Set the fields that do belong here (goal, tone, audience description), and direct the user to the site-level settings for the rest — see **What you can't set here** below.
+
+```json
+{
+  "marketingSettings": {
+    "settings": {
+      "marketingPlanGoal": { "goalKey": "BOOST_SALES" },
+      "marketingTools": ["SOCIAL_MARKETING"],
+      "topics": { "included": ["handmade ceramics", "studio life"], "excluded": ["politics"] },
+      "toneOfVoice": "warm and playful",
+      "pointOfView": "SECOND_PERSON",
+      "businessProfile": { "valueProposition": "hand-thrown stoneware for everyday rituals", "targetAudience": "design-conscious home cooks" }
+    },
+    "overrides": {
+      "socialMarketing": { "frequency": { "interval": "WEEK", "count": 3 } }
+    }
+  },
+  "fieldMask": [
+    "settings.marketingPlanGoal",
+    "settings.marketingTools",
+    "settings.topics",
+    "settings.toneOfVoice",
+    "settings.pointOfView",
+    "settings.businessProfile",
+    "overrides.socialMarketing.frequency"
+  ]
+}
+```
+
+**What each field shapes.** Generation has two stages, and fields feed different stages:
+- **The activities** (what to post about, and when): `marketingPlanGoal` (`goalKey` ∈ `DRIVE_TRAFFIC`, `BRAND_AWARENESS`, `BOOST_SALES`, `COLLECT_LEADS`, or `customGoal` free text), `topics.included`/`topics.excluded` (content pillars), `businessProfile` (`valueProposition`, `targetAudience`, `businessGoal`), `calendar.ids` (which calendars feed the plan), and per-tool cadence `overrides.<socialMarketing|emailMarketing|blogs>.frequency` (`{ interval: WEEK | MONTH | YEAR, count: 1–30 }`).
+- **The post drafts** (captions and images): `toneOfVoice` (free text), `pointOfView` (`FIRST_PERSON`/`SECOND_PERSON`/`THIRD_PERSON`), `customContentGuidelines` (free text), `imageGuidelines` (free text), and `businessProfile.targetAudience`.
+- `marketingTools` must include `SOCIAL_MARKETING` for social post drafts to be generated (also `BLOGS`, `EMAIL_MARKETING`).
+
+**`socialChannels` does not limit channels.** The plan generates post drafts for **all** supported channels; `settings.socialChannels` is only a hint to the caption generator, not a filter. To avoid publishing to a channel, simply don't schedule (or connect) it in STEP 4 — don't rely on `socialChannels` to exclude it. Supported channels: `FACEBOOK`, `INSTAGRAM`, `LINKEDIN`, `PINTEREST`, `GBP`, `TIKTOK`, `TWITTER` (X, sunset — no longer functional after **July 31, 2026**).
+
+**What you can't set here (site-derived, read-only).** Several inputs that shape the plan are **not** part of marketing settings and can't be changed through this endpoint — they come from the site, and setting them via Upsert Marketing Settings has no effect:
+- **Language / region** — from the site's Language & Region settings (`settings.language` is read-only here). The plan's activities and captions are generated in the site language, so "write my posts in French" means changing the site language, not marketing settings.
+- **Business / target locations** — from the site's SEO business-location settings (`settings.businessLocation` / `settings.targetLocations` are read-only here).
+- **Industry, SEO summary, and published site content** (products, blog posts, events) — from the published site itself.
+
+To change any of these, edit them at the site level (or tell the user where: Language & Region for language, SEO business-location settings for locations), then (re)generate the plan (STEP 2) so it picks them up.
+
+To fetch selectable values at runtime, call `GET .../marketing-settings/plan-goal-options` (goals) and `GET .../marketing-settings/defaults` (the site's default goal, channels, and frequency); point-of-view values are the fixed enum above. (Two fields are accepted but currently ignored by generation: `settings.imageGenerationSettings` and `topics.coreTopic`.)
+
+**Note — settings only take effect on (re)generation.** Editing settings never changes an existing plan on its own. To apply changes to an existing plan, regenerate it (STEP 2, `regenerate-marketing-plan`). **If you changed `topics`, use `RegenerateMarketingPlanWithKeywordResearch` instead** (`POST .../marketing-plan/regenerate-marketing-plan-with-keyword-research`) so keyword research reruns for the new content pillars.
+
+---
+
+## STEP 2: Generate the plan
+
+**API Endpoint:** `POST https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-plan/generate-marketing-plan`
+
+No body is required:
+
+```json
+{}
+```
+
+**Expected response** — generation runs in the background:
+
+```json
+{ "status": "GENERATING" }
+```
+
+If the site already has a plan and you want to refresh it, call `POST .../marketing-plan/regenerate-marketing-plan` instead (same response shape).
+
+---
+
+## STEP 3: Poll until the plan is ready
+
+Poll this endpoint until `status` is `ACTIVE` (ready) or `FAILED`. Poll about every **5 seconds**, and stop after ~15 minutes as a safety timeout.
+
+**API Endpoint:** `GET https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-plan?timeframe.startDate=2026-07-01T00:00:00.000Z&timeframe.endDate=2026-08-31T23:59:59.999Z` (example dates — compute the timeframe from today's date through the end of next month)
+
+`timeframe` is optional; omit it to return all activities from today onward.
+
+**Expected response when ready:**
+
+```json
+{
+  "status": "ACTIVE",
+  "marketingActivities": [
+    {
+      "marketingActivityId": "b3f9d2e1-7a4c-4d68-9f02-1c5e8a6b4d30",
+      "date": "2026-07-08T09:00:00.000Z",
+      "title": "Summer collection launch",
+      "description": "Announce the new handmade ceramic mugs summer collection with a 20% launch discount.",
+      "items": [
+        {
+          "id": "834dc801-3e5c-416a-bd14-b130a95d100e",
+          "channel": { "name": "INSTAGRAM", "accountId": "17841405822304914" },
+          "type": "POST",
+          "status": "DRAFT",
+          "instagramPost": {
+            "mediaWrapper": { "media": [ { "type": "IMAGE", "url": "https://static.wixstatic.com/media/....jpg" } ] },
+            "caption": "Summer collection just dropped! Shop the look now. #summerstyle #newarrivals"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+`PlanStatus` values: `NEVER_CREATED`, `GENERATING` (keep polling), `ACTIVE` (ready), `INACTIVE` (auto-deactivated after ~6 weeks idle — and calling this endpoint on a stale plan can itself trigger the transition; regenerate to reactivate), `FAILED` (retry with STEP 2).
+
+Posts are generated automatically only for the **near-term** activities (how far ahead depends on the site's premium plan). Later activities have no `items` yet — see STEP 5 to generate them.
+
+---
+
+## STEP 4: Schedule the draft posts
+
+Collect the `id` of every `item` whose `status` is `DRAFT` from the activities you want to publish. **Before scheduling, show the user what will be published** — each draft's caption and media (render the image inline if the surface supports it, otherwise post its URL as a clickable link) — and get their approval. The drafts are AI-generated and scheduling publishes them, so never schedule content the user hasn't reviewed. Skip `TWITTER` drafts whose activity date falls after **July 31, 2026** — X is sunset then, and a post scheduled past the cutoff will never publish.
+
+**API Endpoint:** `POST https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-plan/schedule-drafts`
+
+`draftIds` are item IDs; 1–20 per call:
+
+```json
+{ "draftIds": ["834dc801-3e5c-416a-bd14-b130a95d100e"] }
+```
+
+**Expected response:** the scheduled items (`status` now `SCHEDULED`):
+
+```json
+{ "items": [ { "id": "834dc801-3e5c-416a-bd14-b130a95d100e", "status": "SCHEDULED", "channel": { "name": "INSTAGRAM" } } ] }
+```
+
+**Check the response — scheduling can partially and silently succeed:**
+- Only `DRAFT` items are scheduled; non-draft IDs are silently ignored.
+- **Only drafts for Publisher-connected channels are scheduled; drafts for unconnected channels are silently skipped and stay `DRAFT` — with no error.** A `200` does not mean everything was scheduled. **Diff the returned `items` against the `draftIds` you sent:** any id not returned as `SCHEDULED` is still a draft. Tell the user which channels those drafts belong to and that the channel needs connecting — connect it via the [Create and Publish a Social Media Post](https://dev.wix.com/docs/api-reference/business-management/marketing/skills) recipe's connect flow, then reschedule those ids.
+- Requires the site's plan to include the schedule-posts premium feature; otherwise the call returns `FAILED_PRECONDITION` (advise upgrading the social media marketing plan).
+
+The scheduled posts are managed by the Publisher and appear on the site's Social Media Marketing page.
+
+---
+
+## STEP 5 (optional): Generate posts for more activities
+
+For activities that have no `items` yet, generate their posts, then schedule them.
+
+1. **Generate** — `POST https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-plan/generate-social-posts` (1–20 activity IDs; returns `{}` immediately, async):
+
+   ```json
+   { "marketingActivityIds": ["b3f9d2e1-7a4c-4d68-9f02-1c5e8a6b4d30"] }
+   ```
+
+   Note: this generates drafts for **all** supported channels (it ignores `socialChannels`) and doesn't re-check `SOCIAL_MARKETING` in `marketingTools`.
+
+2. **Poll** — `POST https://www.wixapis.com/promote/marketing-plan-service/v1/marketing-activity-posts` with the same activity IDs until posts appear:
+
+   ```json
+   { "marketingActivityIds": ["b3f9d2e1-7a4c-4d68-9f02-1c5e8a6b4d30"] }
+   ```
+
+   Response: `{ "marketingActivities": [ { "marketingActivityId": "...", "items": [ { "id": "...", "status": "DRAFT", ... } ] } ] }`.
+
+3. **Schedule** — collect the new `DRAFT` item IDs and call `schedule-drafts` as in STEP 4.
+
+---
+
+## Error handling
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Plan `status: FAILED`, or `ACTIVE` with no posts | Site not published, or `SOCIAL_MARKETING` not enabled in settings | Publish the site; ensure `settings.marketingTools` includes `SOCIAL_MARKETING`, then regenerate (STEP 2) |
+| `INVALID_FIELD_MASK_ERROR` on Upsert Marketing Settings | A `fieldMask` path is missing from `marketingSettings` | Include every `fieldMask` path in the `marketingSettings` body |
+| Language, region, or location "won't change" via Upsert Marketing Settings | Those fields are read-only here (site-derived) | Change them in the site's Language & Region / SEO business-location settings, then regenerate |
+| `FAILED_PRECONDITION` on Schedule Drafts | Plan lacks the schedule-posts premium feature | Advise upgrading the social media marketing plan |
+| `FAILED_PRECONDITION` / `PLAN_ALREADY_GENERATING_ERROR` on Regenerate | A generation is already in progress | Wait for STEP 3 to reach `ACTIVE` or `FAILED` before regenerating |
+| Drafts remain `DRAFT` after Schedule Drafts | Their channels aren't connected through the Publisher | Connect those channels (Publisher Accounts API), then reschedule |
+| Polling never reaches `ACTIVE` | Generation stuck or very slow | Stop after ~15 minutes and retry generation |
+| `GetSocialMarketingPlan` returns `INACTIVE` with no activities | Plan auto-deactivated after long inactivity | Call generate/regenerate (STEP 2) to reactivate |
+
+## References
+
+- [Marketing Plan API introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/introduction)
+- [Marketing Plan API sample flows](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/sample-flows)
+- [Generate Marketing Plan](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/marketing-plan-v1/generate-marketing-plan)
+- [Get Social Marketing Plan](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/marketing-plan-v1/get-social-marketing-plan)
+- [Schedule Drafts](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/marketing-plan-v1/schedule-drafts)
+- [Generate Social Posts](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/marketing-plan-v1/generate-social-posts)
+- [Get Marketing Activity Posts](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/marketing-plan-v1/get-marketing-activity-posts)
+- [Upsert Marketing Settings](https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/marketing-settings-v1/upsert-marketing-settings)

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

@@ -0,0 +1,249 @@
+---
+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.
+---
+
+# Author Ricos Rich Content
+
+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).
+
+## Universal rules for every node
+
+- **`type` is always a bare string** — `"type": "PARAGRAPH"`, never an object like `"type": { "type": "PARAGRAPH" }`. An object-valued `type` may pass a shallow validation but renders as a broken/uneditable block.
+- 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 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`:
+
+```json
+{
+  "type": "PARAGRAPH",
+  "nodes": [
+    { "type": "TEXT", "textData": { "text": "Body copy.", "decorations": [] } }
+  ],
+  "paragraphData": { "textStyle": { "textAlignment": "AUTO" } }
+}
+```
+
+**HEADING** — same TEXT-in-container shape as PARAGRAPH, with the level (1–6) in `headingData`:
+
+```json
+{
+  "type": "HEADING",
+  "nodes": [
+    { "type": "TEXT", "textData": { "text": "Section Title", "decorations": [] } }
+  ],
+  "headingData": { "level": 2, "textStyle": { "textAlignment": "AUTO" } }
+}
+```
+
+**BULLETED_LIST / ORDERED_LIST** — nesting is `LIST → LIST_ITEM → PARAGRAPH → TEXT`. Ordered lists use `orderedListData` in place of `bulletedListData`:
+
+```json
+{
+  "type": "BULLETED_LIST",
+  "nodes": [
+    {
+      "type": "LIST_ITEM",
+      "nodes": [
+        {
+          "type": "PARAGRAPH",
+          "nodes": [
+            { "type": "TEXT", "textData": { "text": "First item", "decorations": [] } }
+          ]
+        }
+      ]
+    }
+  ],
+  "bulletedListData": { "indentation": 0 }
+}
+```
+
+**BLOCKQUOTE** — wraps a PARAGRAPH (never a bare TEXT):
+
+```json
+{
+  "type": "BLOCKQUOTE",
+  "nodes": [
+    {
+      "type": "PARAGRAPH",
+      "nodes": [
+        { "type": "TEXT", "textData": { "text": "A quoted line.", "decorations": [] } }
+      ]
+    }
+  ],
+  "blockquoteData": { "indentation": 1 }
+}
+```
+
+**DIVIDER** — a standalone horizontal rule (no children). `lineStyle`: `SINGLE`·`DOUBLE`·`DASHED`·`DOTTED`; `width`: `LARGE`·`MEDIUM`·`SMALL`:
+
+```json
+{
+  "type": "DIVIDER",
+  "dividerData": { "lineStyle": "SINGLE", "width": "LARGE", "alignment": "CENTER" }
+}
+```
+
+**TABLE** — nesting is `TABLE → TABLE_ROW → TABLE_CELL → PARAGRAPH → TEXT`. `tableData.dimensions.colsWidthRatio` sets relative column widths. Fill a header row or zebra-stripe body rows with `tableCellData.cellStyle.backgroundColor` (a hex string):
+
+```json
+{
+  "type": "TABLE",
+  "nodes": [
+    {
+      "type": "TABLE_ROW",
+      "nodes": [
+        {
+          "type": "TABLE_CELL",
+          "tableCellData": { "cellStyle": { "verticalAlignment": "MIDDLE", "backgroundColor": "#116DFF" }, "borderColors": {} },
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Header A", "decorations": [] } } ] }
+          ]
+        },
+        {
+          "type": "TABLE_CELL",
+          "tableCellData": { "cellStyle": { "verticalAlignment": "MIDDLE", "backgroundColor": "#116DFF" }, "borderColors": {} },
+          "nodes": [
+            { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Header B", "decorations": [] } } ] }
+          ]
+        }
+      ]
+    }
+  ],
+  "tableData": { "dimensions": { "colsWidthRatio": [50, 50], "colsMinWidth": [120, 120], "rowsHeight": [47] } }
+}
+```
+
+**CODE_BLOCK** — children are TEXT nodes (one per line, or `\n`-joined):
+
+```json
+{ "type": "CODE_BLOCK", "nodes": [ { "type": "TEXT", "textData": { "text": "const x = 1;", "decorations": [] } } ], "codeBlockData": { "textStyle": { "textAlignment": "AUTO" } } }
+```
+
+**IMAGE** — references a Wix Media `id` (upload/import the image first via Media Manager; a raw external URL will not render). Requires `width` and `height`. An optional `CAPTION` child holds a TEXT node:
+
+```json
+{
+  "type": "IMAGE",
+  "nodes": [
+    { "type": "CAPTION", "nodes": [ { "type": "TEXT", "textData": { "text": "Figure 1", "decorations": [] } } ] }
+  ],
+  "imageData": {
+    "containerData": { "width": { "size": "CONTENT" }, "alignment": "CENTER" },
+    "image": { "src": { "id": "mediaId" }, "width": 900, "height": 600 },
+    "altText": "Descriptive alt text"
+  }
+}
+```
+
+## 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:
+
+```json
+{
+  "type": "TEXT",
+  "textData": {
+    "text": "Bold, colored, and linked",
+    "decorations": [
+      { "type": "BOLD", "fontWeightValue": 700 },
+      { "type": "COLOR", "colorData": { "foreground": "#116DFF" } },
+      { "type": "LINK", "linkData": { "link": { "url": "https://example.com", "target": "BLANK" } } }
+    ]
+  }
+}
+```
+
+| Decoration | Data field |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| `BOLD`                                     | `fontWeightValue: 700`                                     |
+| `ITALIC`                                   | `italicData: true`                                         |
+| `UNDERLINE`                                | _(none)_                                                   |
+| `STRIKETHROUGH`                            | `strikethroughData: true`                                  |
+| `COLOR`                                    | `colorData: { foreground: "#hex" }` (add `background` for highlight) |
+| `LINK`                                     | `linkData: { link: { url, target: "BLANK" } }`             |
+| `FONT_SIZE`                                | `fontSizeData: { unit: "PX", value: 24 }`                  |
+
+- **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.
+- **No `\n` inside `textData.text`** — one visual line is one node. Emit separate sibling PARAGRAPH/HEADING nodes for separate lines.
+
+## A complete worked example
+
+Assemble the shapes above into one valid `richContent` document. This example exercises **every** common node type — heading, bulleted list, ordered list, blockquote, filled-header table, divider, code block, and a paragraph with mixed bold + link runs — all correctly nested. Copy its **structure**; replace the placeholder text with real content.
+
+```json
+{
+  "nodes": [
+    { "type": "HEADING", "nodes": [ { "type": "TEXT", "textData": { "text": "What's New in v2.1", "decorations": [] } } ], "headingData": { "level": 2, "textStyle": { "textAlignment": "AUTO" } } },
+    { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "This release focuses on speed and clarity.", "decorations": [] } } ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } },
+
+    { "type": "HEADING", "nodes": [ { "type": "TEXT", "textData": { "text": "Highlights", "decorations": [] } } ], "headingData": { "level": 3 } },
+    { "type": "BULLETED_LIST", "nodes": [
+      { "type": "LIST_ITEM", "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Faster page loads", "decorations": [] } } ] } ] },
+      { "type": "LIST_ITEM", "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Redesigned dashboard", "decorations": [] } } ] } ] }
+    ], "bulletedListData": { "indentation": 0 } },
+
+    { "type": "HEADING", "nodes": [ { "type": "TEXT", "textData": { "text": "How to upgrade", "decorations": [] } } ], "headingData": { "level": 3 } },
+    { "type": "ORDERED_LIST", "nodes": [
+      { "type": "LIST_ITEM", "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Back up your data", "decorations": [] } } ] } ] },
+      { "type": "LIST_ITEM", "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Run the migration", "decorations": [] } } ] } ] }
+    ], "orderedListData": { "indentation": 0 } },
+
+    { "type": "BLOCKQUOTE", "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "The new dashboard cut our reporting time in half.", "decorations": [] } } ] } ], "blockquoteData": { "indentation": 1 } },
+
+    { "type": "DIVIDER", "dividerData": { "lineStyle": "SINGLE", "width": "LARGE", "alignment": "CENTER" } },
+
+    { "type": "HEADING", "nodes": [ { "type": "TEXT", "textData": { "text": "Plan comparison", "decorations": [] } } ], "headingData": { "level": 3 } },
+    { "type": "TABLE", "nodes": [
+      { "type": "TABLE_ROW", "nodes": [
+        { "type": "TABLE_CELL", "tableCellData": { "cellStyle": { "verticalAlignment": "MIDDLE", "backgroundColor": "#116DFF" }, "borderColors": {} }, "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Plan", "decorations": [ { "type": "BOLD", "fontWeightValue": 700 }, { "type": "COLOR", "colorData": { "foreground": "#FFFFFF" } } ] } } ] } ] },
+        { "type": "TABLE_CELL", "tableCellData": { "cellStyle": { "verticalAlignment": "MIDDLE", "backgroundColor": "#116DFF" }, "borderColors": {} }, "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Price", "decorations": [ { "type": "BOLD", "fontWeightValue": 700 }, { "type": "COLOR", "colorData": { "foreground": "#FFFFFF" } } ] } } ] } ] }
+      ] },
+      { "type": "TABLE_ROW", "nodes": [
+        { "type": "TABLE_CELL", "tableCellData": { "cellStyle": { "verticalAlignment": "MIDDLE" }, "borderColors": {} }, "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "Starter", "decorations": [] } } ] } ] },
+        { "type": "TABLE_CELL", "tableCellData": { "cellStyle": { "verticalAlignment": "MIDDLE" }, "borderColors": {} }, "nodes": [ { "type": "PARAGRAPH", "nodes": [ { "type": "TEXT", "textData": { "text": "$0", "decorations": [] } } ] } ] }
+      ] }
+    ], "tableData": { "dimensions": { "colsWidthRatio": [50, 50], "colsMinWidth": [120, 120], "rowsHeight": [47, 47] } } },
+
+    { "type": "CODE_BLOCK", "nodes": [ { "type": "TEXT", "textData": { "text": "npm install @wix/sdk@latest", "decorations": [] } } ], "codeBlockData": { "textStyle": { "textAlignment": "AUTO" } } },
+
+    { "type": "PARAGRAPH", "nodes": [
+      { "type": "TEXT", "textData": { "text": "Read the ", "decorations": [] } },
+      { "type": "TEXT", "textData": { "text": "full release notes", "decorations": [ { "type": "BOLD", "fontWeightValue": 700 }, { "type": "LINK", "linkData": { "link": { "url": "https://example.com/release-notes", "target": "BLANK" } } } ] } },
+      { "type": "TEXT", "textData": { "text": " for details.", "decorations": [] } }
+    ], "paragraphData": { "textStyle": { "textAlignment": "AUTO" } } }
+  ]
+}
+```
+
+Note the mixed-run paragraph at the end: the linked words are their own TEXT node carrying `BOLD` + `LINK`, while the surrounding words are separate plain TEXT runs — that is how you apply formatting to *part* of a sentence.
+
+## Nesting rules
+
+| Parent | Valid children |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| Root `nodes`                         | PARAGRAPH, HEADING, BULLETED_LIST, ORDERED_LIST, BLOCKQUOTE, DIVIDER, IMAGE, TABLE, CODE_BLOCK         |
+| 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)                                                                                    |
+
+## Self-audit before returning the document
+
+All decidable from the JSON itself — check before handing the document to a consuming API:
+
+1. **Every `type` is a bare string** — search for `"type": {`; there should be zero hits.
+2. **TEXT wrapping** — no TEXT node sits directly in the root array, a `LIST_ITEM`, a `BLOCKQUOTE`, or a `TABLE_CELL`.
+3. **Container nesting is complete** — `LIST → LIST_ITEM → PARAGRAPH → TEXT` and `TABLE → TABLE_ROW → TABLE_CELL → PARAGRAPH → TEXT`, no level skipped.
+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`.

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

@@ -10,6 +10,57 @@ Learn how to create a Wix store product with customizable options like colors, s
 
 ## Article: Steps for creating a Wix Store Product with Options
 
+## STEP 0: Conversation — gather what's needed for a "ready-to-sell" product
+
+The goal of this step is not just to create *a* product, but to help the user create a **complete, ready-to-sell** product. Before jumping to the API call in STEP 1, run a short conversation to fill the important gaps — but keep it brief.
+
+> **CRITICAL — ASK AT MOST 1–2 FOLLOW-UP QUESTIONS.** Never interrogate the user. Ask no more than one or two follow-up questions total before creating the product. If the user is disengaged or says "just create it", proceed with sensible generated values rather than asking again.
+
+### 0a. Opening the conversation
+
+**If the user hasn't named a product yet, open the conversation with this question up front:**
+
+> **What product would you like to create?**
+
+If the user already gave you product details, skip the opening question and go straight to the gap check in 0b.
+
+**Offer a starting path.** When opening the conversation (and the user hasn't already committed to a method), let them choose how to provide the product details:
+
+> "You can either **upload a product image** and I'll create the product info from it, or just **describe the product in text** and I'll take it from there. Which would you prefer?"
+
+- If the user wants to start from an image → follow the **[Create Product from Image](https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-from-image)** recipe to extract the product name, description, price, and any visible options from the image(s), then continue the conversation from 0b with whatever that recipe couldn't fill in.
+- If the user prefers text / a prompt → continue with the gap check in 0b as usual.
+
+> **Count this toward the 1–2 question budget.** If you ask the image-vs-text question, keep the remaining follow-ups to one so the total conversation stays short.
+
+### 0b. Gap check — decide what (if anything) to ask
+
+**Mandatory inputs are `name` and `price`.** Check what the user has already provided:
+
+**Case 1 — a mandatory input is missing (no name and/or no price):**
+Ask for the missing mandatory field(s), and in the same message offer to generate it for them. Combine both missing fields into a single question. For example:
+
+> "What would you like to call this product, and what price should I set? I can also suggest a name and price for you if you'd like."
+
+If the user asks you to generate them (or doesn't provide them after being asked once), generate a sensible name and price based on the product context and proceed — do not ask a second time.
+
+**Case 2 — both mandatory inputs are provided:**
+You may ask **one** enrichment question to make the product more complete. Ask about whichever is most relevant, and offer to do the work for them. For example:
+
+> "Does this product come in different **sizes or colors** (e.g. options customers choose from)? And would you like me to generate a **SEO description** and/or **info sections** to make it ready to sell?"
+
+- If the user wants options/choices → collect them and build the options + variants per STEP 1.
+- If the user wants generated SEO description and/or info sections → generate them and include them in the product.
+- If the user declines or says "just create it" → proceed with what you have.
+
+> **Do NOT ask about options AND enrichment as two separate rounds.** Bundle them into the single enrichment question above so the total stays within the 1–2 question budget.
+
+### 0c. Stay focused on the product until it's saved
+
+> **CRITICAL — ONCE A PRODUCT-CREATION CONVERSATION HAS STARTED, STAY ON IT.** Do not switch to other topics, suggest unrelated tasks, or start new workflows until the product has actually been created (saved) via STEP 1 — **unless the user explicitly asks to do something else**. If the user goes off-topic, briefly answer if needed, then steer back to finishing and saving the product.
+
+After the product is saved, you're free to suggest next steps (e.g. adding more products, setting up the store).
+
 ## STEP 1: create the product with options and variants
 
 1. create the product with options and create variants for them - Wix REST API: [Create Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/create-product) **CRITICAL: USE THIS WORKING EXAMPLE**