@wix/agent-skills 1.34.0 → 1.35.0

package/README.md

@@ -75,6 +75,7 @@ npx skills add wix/skills -g
 | [wix-docs](skills/wix-docs/SKILL.md) | Look up the Wix API/SDK docs (shared fallback) | Confirming an exact Wix endpoint, method schema, field, or enum before writing code — `curl` doc-search + the `.md`-twin trick, or the Wix MCP tools. Referenced by the other skills as their docs-lookup fallback |
 | [wix-export](skills/wix-export/SKILL.md) | Export or create a Wix Studio 2 site | Exporting an existing Studio 2 site or creating a new one into its own folder, installing or signing in to the origami CLI only when that is missing, and continuing straight into the change the user asked for. Not for Wix Editor or Studio 1 sites, or for content and business changes (use wix-manage) |
 | [wix-import](skills/wix-import/SKILL.md) | Import local site code into a Wix Studio 2 site | Saving an exported Origami site back to Wix, or bringing code from any other project into an existing or new Studio 2 site — sets up the origami CLI when missing, validates the files, and confirms what the import replaces before uploading images or saving. Not for Wix Editor or Studio 1 sites, or for content and business changes (use wix-manage) |
+| [wix-readme](skills/wix-readme/SKILL.md) | Index of the plugin: its skills and the Wix MCP tools | Right after installing the plugin, or when asking what the plugin can do and which skill or tool fits a task |
 | [wix-replatform](wix-replatform/README.md) | Migrate sites from WordPress and other platforms into Wix | Migrating an existing business from another platform into Wix. Both backend data and website. `npx skills add wix/skills/wix-replatform` |
 
 ## Supported Agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-headless-kit/install/pins.json

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.34.0"
+    "ref": "v1.35.0"
   }
 }

package/skills/wix-manage/SKILL.md

@@ -50,7 +50,7 @@ Read and update SEO titles and tags at the right level. For "change my site's SE
 "Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, bulk creates of up to 100 and bulk deletes of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
 
 ### [Generate and Read a Wix Site's Content Plan](references/seo/manage-content-plan.md)
-Generate an SEO content plan and read its blog post topics, or troubleshoot an existing content plan flow stuck at KEYWORD_RESEARCH while polling GetContentPlanFlow. Use this recipe for both generation and stalled-flow questions: it explains the intentional pause, the Create Content Plan release request, missing flow IDs, and the exact public API paths and response fields.
+Generate an SEO content plan for a Wix site, read suggested blog post topics and keywords, or diagnose and continue an existing stalled generation flow, including requests with missing flow identifiers.
 
 ### [Manage Google Search Console for a Wix Site](references/seo/manage-google-search-console.md)
 "Connect a Wix site to Google Search Console and drive its setup through the public GSC Connection and Site Readiness APIs: check connection and readiness, start the Google authorization, verify ownership, add the property, submit the sitemap, request indexing, read search performance, run URL inspection, recover a stale connection, or disconnect. The site owner authorizes in their own browser via a single-use connect URL."

package/skills/wix-manage/references/blog/how-to-create-blog-posts.md

@@ -118,6 +118,8 @@ You have two endpoints:
      }'
    ```
 
+   **With `publish: true`, the post is live once this call returns 200, even if the response reads `draftPost.status: "UNPUBLISHED"`.** The same response carries `changeOrigin: "PUBLISH"` and `hasUnpublishedChanges: false`. Do not call Publish Draft Post, search for a publish endpoint, or create the post again. To confirm it is live, read it back with [Get Post](https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-post): `GET https://www.wixapis.com/blog/v3/posts/{draftPost.id}` returns 200 with `post.id` equal to `draftPost.id` and a `post.firstPublishedDate`.
+
 #### Bulk-create endpoint (preferred for multiple posts)
 
 > **⚠️ Body shape — read this carefully. Each item in `draftPosts` is a FLAT post object: `{title, memberId, richContent, media?, ...}`. Do NOT wrap each item in a `draftPost` field.** Unlike the single-post endpoint (which uses `{draftPost: {...}}` because the request is one post), the bulk endpoint puts each post DIRECTLY inside the `draftPosts` array.

package/skills/wix-manage/references/seo/manage-content-plan.md

@@ -1,293 +1,278 @@
 ---
 name: "Generate and Read a Wix Site's Content Plan"
-description: "Generate an SEO content plan and read its blog post topics, or troubleshoot an existing content plan flow stuck at KEYWORD_RESEARCH while polling GetContentPlanFlow. Use this recipe for both generation and stalled-flow questions: it explains the intentional pause, the Create Content Plan release request, missing flow IDs, and the exact public API paths and response fields."
+description: "Generate an SEO content plan for a Wix site, read suggested blog post topics and keywords, or diagnose and continue an existing stalled generation flow, including requests with missing flow identifiers."
 ---
 
 # Generate and Read a Wix Site's Content Plan
 
-A **content plan** is a set of suggested blog post briefs, including titles,
-keywords, and the existing site pages they support. A **content plan flow** is
-the asynchronous job that generates those briefs. Its `contentPlanFlowId` is
-a flow UUID, distinct from the site's ID, and its `status` reports progress.
-Generation creates briefs, not published posts.
-
-`KEYWORD_RESEARCH` means keyword research is complete and the job is waiting
-for the **Create Content Plan** request to generate the briefs. This request
-releases the intentional pause; polling alone does not advance it.
-
-Use the selected site's authorization context. Trigger and Create Content Plan
-are writes requiring **Manage SEO Settings**; execute them when the user has
-requested generation or explicitly confirmed it.
-
-## Resume or read an existing flow
-
-An existing flow is a job already started by a previous trigger, including one
-discussed earlier in the conversation. To finish it or read its results:
-
-1. Find its actual `contentPlanFlowId` in the conversation or a previous
-   trigger/status response. A site ID is not a flow ID, even though both are
-   UUIDs. If the ID is missing, explain the intentional pause when the user
-   reports `KEYWORD_RESEARCH`, ask for the flow ID, and end the turn without an
-   API call. Never submit a placeholder. Do not offer a new flow or a different
-   site as an alternative to recovering the ID.
-2. Read that flow with
-   `GET https://www.wixapis.com/promote/seo/v1/content-plan-flows/{contentPlanFlowId}`.
-   Read `contentPlanFlow.status`; see the response and status table in
-   [Check the flow status](#2-poll-until-keyword_research).
-3. At `SUCCESS`, go directly to [Read the briefs](#5-read-the-briefs).
-   At `KEYWORD_RESEARCH`, when completion is requested, call
-   [Create Content Plan](#3-release-the-flow) once with this flow ID.
-   For an earlier in-progress status, continue checking this same flow until
-   it reaches the pause. If already at `CONTENT_PLAN`, continue to step 4
-   without calling Create Content Plan again. For a terminal or unmet-requirement
-   status, follow the status table and stop.
-4. After Create Content Plan succeeds, retain its returned flow ID and
-   [check until SUCCESS](#4-poll-until-success), then
-   [read the briefs](#5-read-the-briefs). Do not trigger a replacement or release
-   a successful flow just to retrieve its results.
-
-## Generate a new plan
-
-When the user requests a new plan, follow these steps in order. The request and
-response examples for each step are in [API steps](#api-steps).
-
-1. [Trigger](#1-trigger) once and retain the returned flow ID.
-2. [Check the flow status](#2-poll-until-keyword_research) until `KEYWORD_RESEARCH`.
-3. [Call Create Content Plan](#3-release-the-flow) once to continue generation.
-4. [Check until SUCCESS](#4-poll-until-success).
-5. [Read the briefs](#5-read-the-briefs) and report the actual returned topics.
-
-Only Trigger and Create Content Plan write data in the generation path. Do not
-change the site's business profile, name, description, categories, or publication
-state to accelerate it. Those are separate tasks requiring real user data and
-authorization. `CREATED` can mean queued work, not missing setup.
-
-## Polling without losing progress
-
-**One API execution makes one HTTP request and returns.** The sequence below
-is a series of separate calls, with a decision after each response. It is not
-one code block containing the entire workflow. Never wrap API calls in a
-`for`/`while` loop, a timer, or a function that polls until a target status.
-
-Retain each response's flow ID before the next call. Wait between status checks
-using the client's supported waiting capability, outside the API execution;
-do not assume timers exist inside that execution or busy-wait there.
-
-Keep checking while work progresses. If waiting cannot continue, report the
-flow ID and last observed status as incomplete; do not claim success or merely
-promise to finish later. Identify trigger and release as writes if asked
-whether an execution changes data.
-
-## API steps
-
-### 1. Trigger
+A content plan contains suggested blog post briefs, not published posts.
+`contentPlanFlowId` identifies the generation job, not the site.
+
+For an existing job, require its `contentPlanFlowId` before any API call. Ask
+for it; if no user can answer, report incomplete and stop. A site ID, an ID-less
+flow GET or the latest successful flow cannot identify the user's job. Explain
+that continuation follows [step 3](#3-check-research-and-release-once): check the
+flow's own `keywordResearchId` research for `SUCCESS`, then release once only if
+a fresh flow read still shows `KEYWORD_RESEARCH`.
+
+`KEYWORD_RESEARCH` means research has started, not finished. Some flows advance
+automatically; `CONTENT_PLAN` or `SUCCESS` needs no release. Polling alone does
+not release a flow that is waiting for Create Content Plan.
+
+Use the selected site's authorization context. Writes require **Manage SEO
+Settings**; execute them when the user requests the change or confirms it. Never
+change business data or publication state just to accelerate generation.
+
+Use only IDs and values that the API returned or the user supplied; every example
+value is a placeholder. If a request tool needs `siteId`, use the selected or
+supplied site ID, never `contentPlanFlowId`.
+
+Each path below is the endpoint shown on its linked public reference, except
+Get Site Keyword Research, whose own page is not public yet (see
+[step 3](#read-the-matching-research)). All use the
+`https://www.wixapis.com/seo-content-plan-service/v1` base. Every call here was
+sent live on this base. Trigger, Get Content Plan Flow, Get Site Keyword
+Research, List Blog Post Candidates and List Keyword Research Items returned
+data. Create Content Plan and Update Keyword Research Item were sent with IDs
+that match no record and returned the service's own errors (for example
+`CONTENT_PLAN_FLOW_NOT_FOUND`), not a missing-route error. A `404` on one of
+these paths is an error to report, not a reason to try another base.
+
+## 1. Trigger or inspect an existing flow
+
+For new generation, trigger once:
 
 ```
-POST https://www.wixapis.com/promote/seo/v1/content-plan-flows/trigger
+POST https://www.wixapis.com/seo-content-plan-service/v1/content-plan-flows/trigger
 {}
 ```
 
-Response:
+Response: `{ "contentPlanFlowId": "<flow-uuid>" }`. Save the ID.
+[Trigger Content Plan Generation Flow](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/trigger-content-plan-generation-flow).
 
-```json
-{ "contentPlanFlowId": "<flow-uuid>" }
-```
+For an existing flow, apply the entry gate above. Keep its ID, last observed
+status and release history for a later resume.
 
-`<flow-uuid>` and other angle-bracket values in these examples are placeholders;
-substitute actual returned values before making requests. Return this response
-and end this execution here. Save the ID before making any status request.
-Do not append step 2 to the trigger script.
-See [Trigger Content Plan Generation Flow](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/trigger-content-plan-generation-flow).
-
-### 2. Poll until KEYWORD_RESEARCH
+## 2. Read status with bounded waiting
 
 ```
-GET https://www.wixapis.com/promote/seo/v1/content-plan-flows/{contentPlanFlowId}
+GET https://www.wixapis.com/seo-content-plan-service/v1/content-plan-flows/{contentPlanFlowId}
 ```
 
-Execute this GET once and return its response. This execution contains no
-`for`/`while` loop and no timer. Repeat it as a separate call when another
-status check is needed. Keep the response compact: flow ID and status suffice.
-
-Example response, showing the public flow fields (optional fields may be absent):
+Read nested `contentPlanFlow.status`. Example:
 
 ```json
 {
   "contentPlanFlow": {
     "id": "<flow-uuid>",
-    "createdAt": "2026-09-08T10:00:00.000Z",
-    "updatedAt": "2026-09-08T10:01:00.000Z",
     "status": "KEYWORD_RESEARCH",
-    "origin": "AGENT",
-    "summaryId": "<summary-uuid>",
-    "keywordResearchId": "<keyword-research-uuid>"
+    "keywordResearchId": "<research-uuid>"
   }
 }
 ```
 
-Read `contentPlanFlow.status`, not a top-level `status`. If it is missing,
-inspect the response instead of silently looping. Always use this generation's
-flow ID; if it stays `CREATED`, report the ID and observed status without
-inventing missing business prerequisites.
-See [Get Content Plan Flow](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/get-content-plan-flow).
+Pacing:
+
+1. The first check needs no pause. Set an end time with a supported clock: five
+   minutes by default, or a shorter runtime limit or user-requested window.
+2. Between checks, wait about 15 seconds with the client's supported delay. Use
+   a separate wait or scheduling tool if one exists. Only if you run code
+   yourself and have no such tool, put one awaited sleep of about 15 seconds in
+   that code, before its single GET (for example,
+   `await new Promise(r => setTimeout(r, 15000))` in JavaScript or
+   `time.sleep(15)` in Python). A sleep that is not awaited does not pause. With
+   neither a wait tool nor code execution, go to step 4. Sending checks back to
+   back with no pause is not pacing. This is client pacing, not an API rate
+   limit or a completion-time promise.
+3. **Each execution makes one HTTP request and returns.** Before each later
+   check, confirm the pause fits the window and wait once. Then read the clock
+   again: if the window has ended, go to step 4 without sending. Otherwise send
+   one GET and read its result. Never loop requests, busy-wait, or use API or doc calls as a
+   pause; request counts and frozen `updatedAt` values do not measure time.
+4. If no usable clock or waiting exists, or the window ends, report incomplete
+   with the saved ID, status and release history. Expiry does not prove failure.
+   End the turn for a later requested resume; do not restart automatically.
+
+| Observed status | Action |
+| --- | --- |
+| `CREATED`, `SITE_ANALYSIS`, `SITE_SUMMARY` | Continue paced checks within the window. |
+| `KEYWORD_RESEARCH` | Follow [Check research and release once](#3-check-research-and-release-once), within the same monitoring window. |
+| `CONTENT_PLAN` | Continue paced checks; skip release. |
+| `SUCCESS` | Stop waiting and read candidates. |
+| `PENDING_REQUIREMENTS` | Stop; report the unmet requirement. Never invent site data. |
+| `FAIL`, `CANCELED` | Report the ID and result, then stop. |
+| Missing or unrecognized status | Report uncertainty; do not silently poll. |
 
-`contentPlanFlow.status` is a string enum. Status checks may skip intermediate
-states; decide from the returned value rather than requiring every transition.
-Typical status progression: `CREATED` → `SITE_ANALYSIS` → `KEYWORD_RESEARCH`
-→ **call Create Content Plan** → `CONTENT_PLAN` → `SUCCESS`.
+[Get Content Plan Flow](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/get-content-plan-flow).
 
-| Status | Meaning and next action |
-| --- | --- |
-| `CREATED` | Queued or starting. Check the same flow again; do not change site settings. |
-| `SITE_ANALYSIS` | Analyzing site pages. Continue separate checks. |
-| `SITE_SUMMARY` | Summarizing existing content. Continue separate checks. |
-| `KEYWORD_RESEARCH` | Waiting for Create Content Plan. Release once when generation is requested. |
-| `CONTENT_PLAN` | Generating briefs. Continue separate checks; do not release again. |
-| `SUCCESS` | Ready. Read candidates in step 5. |
-| `PENDING_REQUIREMENTS` | Missing business information. Stop polling and report the actual unmet requirement from evidence. Do not invent or update business data, or repeatedly trigger replacements. |
-| `FAIL` | Generation failed. Report the flow ID and failure; do not silently start a replacement. |
-| `CANCELED` | Canceled and cannot be resumed. Report it and stop. |
-| `UNKNOWN` | No usable status. Inspect the response and report uncertainty instead of guessing progress. |
+## 3. Check research and release once
+
+Create Content Plan is an action on Blog Post Candidate, distinct from the
+flow-status read. It requires matching research `SUCCESS`; elapsed time at this
+stage proves neither readiness nor failure.
 
-Check every few seconds using separate calls. Completion time varies.
+1. No `keywordResearchId` on the flow: report it missing and stop; do not guess it.
+2. Read **that exact research** (below), not the latest research. Not `SUCCESS`
+   yet: pause, then read again.
+3. Research `SUCCESS`: read the same flow again, with no extra delay.
+4. Flow still `KEYWORD_RESEARCH` with the same research ID: [release once](#release-once).
+   `CONTENT_PLAN` or `SUCCESS`: skip release and follow the status. A changed
+   research ID: check the new research; the old success does not authorize it.
 
-### 3. Release the flow
+### Read the matching research
 
 ```
-POST https://www.wixapis.com/promote/seo/v1/create-content-plan
-{ "contentPlanFlowId": "<flow-uuid>" }
+GET https://www.wixapis.com/seo-content-plan-service/v1/site-keyword-research?keywordResearchId={keywordResearchId}
 ```
 
-Successful response:
+Require `siteKeywordResearch.id` and `contentPlanFlowId` to match the flow being
+followed, then read `status`. Never omit the query ID: the ID-less read returns
+the latest successful research, not this job's. Keyword-list items are not a
+research-status check.
+
+Minimal matching response:
 
 ```json
 {
-  "success": true,
-  "contentPlanFlowId": "<flow-uuid>"
+  "siteKeywordResearch": {
+    "id": "<research-uuid>",
+    "status": "SUCCESS",
+    "contentPlanFlowId": "<flow-uuid>"
+  }
 }
 ```
 
-Failure response fields (the diagnostic text comes from the API):
+This check is the published procedure: the [Create Content Plan reference](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/create-content-plan)
+says to poll Get Site Keyword Research with the flow's `keywordResearchId` until
+`SUCCESS`, then re-read the flow before releasing, and the
+[Get Content Plan Flow reference](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/get-content-plan-flow)
+says the same.
 
-```json
-{
-  "success": false,
-  "message": "<reason returned by the API>"
-}
+Get Site Keyword Research itself is a BETA method with no public reference page
+of its own. It requires `wix-seo.read`. The query parameter, response fields and
+statuses above match its API definition and live responses on this base.
+
+**Fallback:** if this call fails, is unavailable, or returns a response without
+the matching `id`, `contentPlanFlowId` and a `status` shown above, do not
+release. Keep paced flow reads only: a flow that reaches `CONTENT_PLAN` or
+`SUCCESS` needs no release; one still at `KEYWORD_RESEARCH` when the window ends
+is reported incomplete with its IDs. This follows the Create Content Plan
+reference, which requires research `SUCCESS` before release.
+
+### Release once
+
+When the user requested generation or continuation, and no release has already
+been attempted for this flow, call Create Content Plan **once**:
+
+```
+POST https://www.wixapis.com/seo-content-plan-service/v1/create-content-plan
+{ "contentPlanFlowId": "<flow-uuid>" }
 ```
 
-The response fields are `success` (boolean), `message` (failure reason, only
-when `success` is false), and `contentPlanFlowId` (flow UUID when returned).
-Check `success` as well as the HTTP status. If false, report `message` and stop;
-a successful HTTP response alone is not a completed plan.
+Minimal response examples:
+
+```json
+{ "success": true, "contentPlanFlowId": "<returned-flow-uuid>" }
+```
 
-On success, retain the returned `contentPlanFlowId` for the next status check
-and candidate read. This response is not the list of briefs: continue to steps
-4 and 5. Do not call release again to retrieve results; on an already successful
-flow it regenerates a plan under a new flow ID.
-See [Create Content Plan](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/create-content-plan).
+```json
+{ "success": false, "message": "<failure-message>" }
+```
 
-### 4. Poll until SUCCESS
+Record the attempt before sending. Concurrent/repeated calls can duplicate plans.
+If release history is uncertain, ask rather than send another POST. Check HTTP
+status and response `success`; `false` requires reporting `message`, not claiming
+completion. On HTTP `428` with application code
+`FLOW_NOT_READY_FOR_CONTENT_PLAN` (listed in the Create Content Plan reference's
+errors), inspect the error and make a paced
+status recheck; do not retry the POST in a loop. Other errors or an
+uncertain response require reporting the attempt, not repeating it.
+
+On success, retain the returned `contentPlanFlowId` and monitor it with the same
+bounded, single-request approach. A different returned ID is a separate flow;
+explain that and never claim the original completed. Completion still requires
+observed `SUCCESS` and returned candidates. Do not release an already successful
+flow to recover it: that action regenerates a separate plan.
+[Create Content Plan](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/create-content-plan).
+
+### Edge cases
+
+| Situation | Action |
+| --- | --- |
+| Research briefly not found | The flow can link the ID before its research record exists. Read again after a pause within the window, then inspect the flow if it persists; do not release or restart. |
+| Research `FAIL`, `CANCELED`, `REVERTED`, missing/unknown status, or mismatched IDs | Stop and report the result; no release or replacement. |
+| Get Site Keyword Research unavailable | Keep the error and IDs. Continue paced flow reads only: `CONTENT_PLAN`/`SUCCESS` needs no release; still `KEYWORD_RESEARCH` when the window ends means report incomplete, because readiness cannot be verified. Never release from flow status or keyword-list items. |
+| Authorization denied or other error | Report the specific error and keep the IDs; no private fallback or readiness guess. |
 
-Same single-GET execution and nested response as step 2, using the release
-response's flow ID and returning after each check. Typical status progression:
-`CONTENT_PLAN` → `SUCCESS`. Read candidates in a subsequent execution after
-observing `SUCCESS`.
+## 4. Read and present briefs
 
-### 5. Read the briefs
+Only after observing `SUCCESS` for the same flow:
 
 ```
-GET https://www.wixapis.com/promote/seo/v1/content-plan-flows/{contentPlanFlowId}/blog-post-candidates
+GET https://www.wixapis.com/seo-content-plan-service/v1/content-plan-flows/{contentPlanFlowId}/blog-post-candidates
 ```
 
-Example response showing the fields needed to display one topic:
+Omit `paging` to return all candidates. Read titles and keywords from `briefData`:
 
 ```json
 {
-  "blogPostCandidates": [
-    {
-      "id": "<candidate-id>",
-      "briefData": {
-        "h1Title": "How to Care for Handmade Ceramic Mugs",
-        "keyword": "ceramic mug care",
-        "mainKeyword": "handmade ceramic mugs",
-        "pageUrl": "https://www.example.com/mugs"
-      }
+  "blogPostCandidates": [{
+    "id": "<candidate-id>",
+    "briefData": {
+      "h1Title": "How to Care for Handmade Ceramic Mugs",
+      "keyword": "ceramic mug care",
+      "mainKeyword": "handmade ceramic mugs",
+      "pageUrl": "https://www.example.com/mugs"
     }
-  ],
-  "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false }
+  }],
+  "pagingMetadata": { "count": 1, "hasNext": false }
 }
 ```
 
-This is illustrative data, not the user's results. Candidates can contain
-additional fields; see the linked reference for the full contract. Omitting
-`paging` returns all candidates in a single response. Each candidate's brief
-fields are nested under `briefData`, not at the candidate's top level. Map them
-directly:
-
-```js
-const topics = response.blogPostCandidates.map(candidate => ({
-  id: candidate.id,
-  title: candidate.briefData?.h1Title,
-  keyword: candidate.briefData?.keyword,
-  mainKeyword: candidate.briefData?.mainKeyword,
-  supportingPageUrl: candidate.briefData?.pageUrl
-}));
-```
+The final reply must give the flow ID, observed completion and count,
+followed by a table with **Title | Keyword | Main keyword | Supporting URL**.
+Populate all four columns from `briefData`, with clickable supporting URLs;
+a titles-only or titles/main-keywords table is incomplete. Label any shortened subset.
+Absent fields are unavailable; do not invent them. `pageUrl` supports an existing
+page, not a newly published post. Explain weak or repetitive results honestly;
+successful generation does not establish editorial quality or promise rankings.
+[List Blog Post Candidates](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/list-blog-post-candidates).
+
+## Editing keywords after completion (optional)
 
-`pageUrl` identifies the existing site page the proposed post supports; it is
-not the URL of a newly published blog post. Generation creates briefs, not
-published posts. Do not read `candidate.title`, `candidate.keyword`, or
-`candidate.pageUrl`, or infer missing data from those nonexistent top-level
-fields. If a nested field is absent, report it as unavailable and inspect the
-raw candidate before making another request. Report the actual returned
-titles and available keywords/supporting page URLs. Do not invent briefs or
-claim completion from the release response.
-See [List Blog Post Candidates](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/list-blog-post-candidates).
-
-### Present the result
-
-Start with the flow ID, observed `SUCCESS` status, and returned candidate count.
-Use a compact table with one row per topic: suggested title, target keyword,
-main keyword, and supporting page URL. Include the actual returned URL as a
-link; do not merely say that each brief contains a URL. Avoid repeating SEO
-titles and descriptions unless requested. If the answer must be shortened,
-label the displayed subset and total explicitly instead of claiming to show all
-topics. These are AI-generated suggestions; do not promise rankings or traffic.
-Assess the returned topics before recommending them: if they are repetitive,
-mostly restate the site name, or lack a clear connection to the site's business,
-say so plainly. Successful generation does not establish editorial quality.
-Still show the actual results; do not silently replace weak titles with invented
-ones or call them optimized without evidence. Explain what business context
-would help assess or refine them, without modifying the site's settings.
-
-## Editing keywords (optional)
-
-After step 2, before or after step 3, read the keywords:
+After observed flow `SUCCESS`, read research once:
 
 ```
-GET https://www.wixapis.com/promote/seo/v1/content-plan-keyword-research-items
+GET https://www.wixapis.com/seo-content-plan-service/v1/content-plan-keyword-research-items
 ```
 
-Edit one keyword (field-masked, only `keyword` and `main_keyword` writable):
+No parameters are required; omit optional `paging` for all items. Match returned
+`keywordResearchId` to the completed flow and use returned `keywordResearchItems`
+item IDs before editing. A mismatch or HTTP `404` is not permission to edit or
+retry immediately. This is a post-completion read, not a pre-completion readiness
+test.
+The list is site-scoped and returns the latest research, not per-research status.
+Its reserved `contentPlanFlowId` query field is ignored; it cannot target an older
+flow or prove that flow's readiness.
+[List Keyword Research Items](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/list-keyword-research-items).
+
+Only `keyword` and `mainKeyword` are writable, using a field mask.
+Set `mainKeyword: true` to promote an existing item. Whether `false` demotes one
+is not verified; do not rely on it, and read the item back after any change.
+[Update Keyword Research Item](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/update-keyword-research-item).
+
+List uses `content-plan-keyword-research-items`, while Update uses
+`keyword-research-items/{itemId}`. Preserve that difference. Use the returned
+`item.id` for `{itemId}` and the same value in the Update body.
 
 ```
-PATCH https://www.wixapis.com/promote/seo/v1/keyword-research-items/{itemId}
+PATCH https://www.wixapis.com/seo-content-plan-service/v1/keyword-research-items/{itemId}
 {
-  "keywordResearchId": "...",
-  "item": { "id": "...", "keyword": "new keyword" },
+  "keywordResearchId": "<research-uuid>",
+  "item": { "id": "<item-id>", "keyword": "new keyword" },
   "fieldMask": "keyword"
 }
 ```
 
-**Copy-on-write:** the response may carry a different `keywordResearchId`.
-Always use the one from the response for the next write. Edits are not
-durable across generations.
-
-## Do not
-
-- Poll forever without calling Create Content Plan (step 3).
-- Read candidates before `SUCCESS`.
-- Retry after `PENDING_REQUIREMENTS`.
-- Ask for a site ID.
-- Retry after a 403 — the caller lacks **Manage SEO Settings**.
+The copy-on-write response can return a new `keywordResearchId`; use it for the
+next write. Edits do not persist across generations.

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -211,7 +211,8 @@ route takes it. The site stays the same, at the same URL, now server-rendered.
 - **From a shell, without attachments:** two calls. `{ siteId, prepare: true, size }`
   with the ZIP's `size` (`wc -c < build.zip`) answers with `curl` commands for
   the build ZIP and, when the site's repository takes it, a source ZIP; run them
-  as given, then make the second call it names, with `uploadKey`. A 404 on the
+  as given, then make the second call it names:
+  `{ siteId, uploadKey, sourceUploadId?, expectedHeadRevisionId?, releaseNotes? }`. A 404 on the
   second call means the upload URL expired: prepare again. A prepared upload is
   finished by that second call and by nothing else: a release made another way
   (the ZIP attached, say) leaves the prepared upload behind and releases without

package/skills/wix-readme/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: wix-readme
+description: "What the Wix plugin holds and how to work with Wix through it: the flow the Wix MCP README returns, an index of the plugin's skills with what each does, and the Wix MCP tools with what each does. Use when the plugin was just installed or when the user asks what the Wix plugin can do or which skill or tool fits a task."
+---
+
+# The Wix plugin
+
+The plugin is two things: skills, folders of instructions and shipped code for building on Wix, each with a `SKILL.md` at its root; and the Wix MCP server at `https://mcp.wix.com/mcp`, whose tools read and change the user's Wix sites and account. The skills say how; the tools do.
+
+## How to work with Wix through the plugin
+
+Every Wix task ends in one of two places: a call made now with the user's account, or code the user keeps that makes the same calls (an app, a headless site, a script). The way there is the same.
+
+1. **Start with `WixREADME`**, once per conversation. It returns this flow in full and the account's sites with their installed apps.
+2. **Pick the site.** The `siteId` comes from the site context; when several fit, ask. A business solution's API works only on a site with that app installed, and an app's version changes its endpoints, so check the site's apps first.
+3. **Find the method.** The first source that gives it: an earlier tool result in the conversation; else the skill that covers the task (the index below says what each is for), whose example is the model when it matches the case; else the docs, `SearchWixRESTDocumentation` or `BrowseWixRESTDocsMenu` for REST, the SDK, CLI, headless and apps searches for code, then `ReadFullDocsArticle` on the method's page.
+4. **Get the exact shape.** A request is modeled on an example that matches the case: a skill's recipe or template, or the method's docs page, when it shows the fields the case needs. That is enough. The schema is for what no example shows: a field, an enum, a filter or sort key (a closed list per method). `SearchWixAPISpec` on the method's docs URL returns the request and response schemas, the REST URL and the JavaScript SDK call; `ReadFullDocsMethodSchema` when it is not available.
+5. **Make the call, or write the code.** To do it now: `ExecuteWixAPI`, one function holding every step of the task, the reads and the writes they feed. For code the user keeps: write the call from the shape found in step 4, REST or SDK. `wix-headless-templates` is that code already written and verified, one folder per business solution, and `wix-headless-kit` builds a site on it.
+
+Throughout: nothing Wix-specific from memory. Every URL, id, setting location, product fact, request shape and field name comes from a skill, the docs tools, an earlier tool result or the user.
+
+## Creating a site
+
+A new Wix site is written in code and uploaded. `StartDeployWebsite` returns the guide for a site the agent writes or files the user brought; `StartHeadlessBuild` returns the guide for a site that needs Wix business features (a store, bookings, a CMS, members, payments and the rest). Each guide creates the site, uploads it and says what comes next; call one and follow it.
+
+What the guides stand on:
+
+- **One site, created once**, by the provision call (`POST .../headless-business-setup/v1/headless-business/provision`, `origin: 'agent'`), which returns `metaSiteId`, the id every later call takes. A site made earlier is found with `ListWixSites` and uploaded to again; the URL never changes.
+- **Static pages are dropped, a Wix Astro build is released.** A drop sends the complete file set each time. A build (`.wix/build-metadata.json` beside `dist/`) is released to Wix hosting, server-rendered, through `UploadHeadlessWebsiteFiles` only: as an attachment, or in two calls (`prepare: true` with the zip's `size`, then `uploadKey`) from a shell that reaches the internet. The project's source is stored with the release, and a later session continues the site from it.
+- **`UploadHeadlessWebsiteFiles`** takes `siteId` and the files, as `attachments` or the `files` text bundle, and returns the live URL and the dashboard. Without the MCP, the same drop is a `curl` multipart call, with or without a login.
+- **Business features** come from `wix-headless-kit`'s run on the same site and `appId`: apps installed and content seeded, the Astro project built from `wix-headless-templates`, the build released.
+
+To read more: the recipe, `wix-manage/references/sites/upload-static-site.md` (https://www.wix.com/skills/wix-manage/references/sites/upload-static-site.md): the calls for every route, drop and release, finding and changing a site, the anonymous route, limits and failures. The cold start (https://www.wix.com/skills/headless-cold-start/headless-kit.md): the headless build from a cold environment to the released site.
+
+## Two ways to Wix
+
+### The plugin with the Wix MCP
+
+The preferred way. The plugin's MCP configuration connects the Wix MCP server at `https://mcp.wix.com/mcp`; the client signs the user in on the first call and the tools below are in the tool list, with nothing to install. The flow above runs on them: `WixREADME` for the context, the documentation tools to find a method and its shape, `ExecuteWixAPI` to call it, `StartDeployWebsite` and `StartHeadlessBuild` with `UploadHeadlessWebsiteFiles` to create a site and put it live. The skills are read from the plugin's folder, and `ReadFullDocsArticle` reads them online when they are not there.
+
+Context first:
+
+| Tool | What it does |
+|---|---|
+| `WixREADME` | The context every other tool assumes. Call it once per conversation before a Wix task; for another site later, call `GetSiteContext` instead. |
+| `ListWixSites` | Lists the user's sites, with an optional name filter. Needs no `WixREADME` first. |
+| `GetSiteContext` | Deep context for one site, by name or id: its apps, settings and data, as markdown. |
+
+Building and deploying a site:
+
+| Tool | What it does |
+|---|---|
+| `StartDeployWebsite` | Returns the guide to create a site on Wix and put files on it: HTML, CSS and JS, a static build, a zip, another builder's export. Updates keep the site and URL. Works with or without a Wix login. |
+| `StartHeadlessBuild` | Returns the headless guide, for a site that needs Wix business features: a store, bookings, events, a restaurant menu, a blog, pricing plans, donations, forms, members, a CMS, payments. |
+| `UploadHeadlessWebsiteFiles` | The upload step of those two guides: puts a static site or a Wix Astro build onto an existing Wix Headless site by its metaSiteId, as files, as attachments, or in two calls with presigned URLs. |
+| `GetSuggestedDomains` | Domain name suggestions for a site. |
+
+Calling Wix APIs:
+
+| Tool | What it does |
+|---|---|
+| `ExecuteWixAPI` | Reads and changes a site's or account's data with one JavaScript function over the Wix REST API: chained calls, pagination, loops, the reads that feed the writes. The preferred way to call Wix APIs. |
+| `SearchWixAPISpec` | Inspects the Wix REST API spec and each method's JavaScript SDK call by running JavaScript against the index: the exact request and response shape, enums, the SDK import and signature. |
+
+Documentation:
+
+| Tool | What it does |
+|---|---|
+| `SearchWixRESTDocumentation` | Searches the Wix REST API docs. The starting point for finding an endpoint. |
+| `BrowseWixRESTDocsMenu` | Browses the REST docs as a menu, category by category. |
+| `SearchWixSDKDocumentation` | Searches the Wix JavaScript SDK docs. |
+| `SearchWixHeadlessDocumentation` | Searches the Wix Headless docs. |
+| `SearchWixCLIDocumentation` | Searches the Wix CLI docs: commands, local development, authentication. |
+| `SearchWixWDSDocumentation` | Searches the Wix Design System docs. |
+| `SearchBuildAppsDocumentation` | Searches the Wix Build Apps docs. |
+| `SearchDevelopmentDocumentation` | Broad Wix developer docs: platform concepts and guides, after the specific searches return nothing. |
+| `SearchWixHelpCenter` | Searches the Wix Help Center: how site owners do things by hand in the dashboard and editors. |
+| `ReadFullDocsArticle` | Reads a page in full by URL: a docs article or method page, a skill's `SKILL.md` or any of its files, a Help Center article. |
+| `ReadFullDocsMethodSchema` | The full request and response schema of one method, by its docs URL. |
+
+Media and feedback:
+
+| Tool | What it does |
+|---|---|
+| `UploadImageToWixSite` | Uploads images to a site's Media Manager and returns their URLs and media ids. |
+| `PickImagesForWixMedia` | Shows the user a file picker to upload images from their device to the Media Manager. |
+| `ReportIssueToWix` | Reports one problem with Wix's tools, APIs or docs to the Wix team, when the user asks for it. |
+
+### The Wix CLI
+
+The other way, from a shell. `@wix/cli` is Wix's command-line tool: it signs in to a Wix account, creates and manages Wix projects on disk, a Wix app or a Wix Headless site, builds them and releases them to Wix, and mints tokens for REST calls. Its session lives on the machine. All as `npx @wix/cli@latest <command>`:
+
+| Command | What it does |
+|---|---|
+| `login` | Signs in with a device code and writes the session to `~/.wix/auth/account.json`. |
+| `whoami` | Shows the signed-in account. |
+| `create` | Creates a Wix project with its site: for a headless site, the site, its OAuth app and hosting, and the project's `wix.config.json` (`siteId`, `appId`). |
+| `env pull` | Writes the project's environment to `.env.local`: the site's client id and the values the build reads. |
+| `build` | Builds the project for Wix: for an Astro site, `dist/` and `.wix/build-metadata.json`. |
+| `release` | Releases the build to Wix; the site keeps its URL. |
+| `token`, `token --site <siteId>` | Mints an admin token, account-scoped or site-scoped, for REST calls from a shell: `Authorization: Bearer <token>` (`wix-docs/references/CALLING.md`). |
+
+`wix-headless-kit` builds a Wix Headless site through the MCP's tools or through the CLI; a CLI session already on the machine makes its run the CLI route, where `install/setup.mjs` runs `create`, and `build` then `release` put the site live.
+
+Without the MCP, each tool is a plain HTTP call to the same backend. `wix-docs` covers these, with the request bodies, as its `curl` lane:
+
+| Tool | Without the MCP |
+|---|---|
+| `SearchWixRESTDocumentation`, `SearchWixSDKDocumentation`, `SearchWixHeadlessDocumentation`, `SearchWixCLIDocumentation`, `SearchWixWDSDocumentation`, `SearchBuildAppsDocumentation`, `SearchDevelopmentDocumentation` | `POST https://www.wixapis.com/mcp-docs-search/v1/docs/search` (or `/search/markdown`) with `search_term` and the `document_type` of that corpus. |
+| `BrowseWixRESTDocsMenu` | `POST https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse`. |
+| `ReadFullDocsArticle` | Append `.md` to any `https://dev.wix.com/docs/...` URL; a skill's file is `https://www.wix.com/skills/<skill>/<path>`. |
+| `SearchWixAPISpec`, `ReadFullDocsMethodSchema` | `POST https://mcp.wix.com/api/code-mode/search` with the same JavaScript. |
+| `ExecuteWixAPI` | The REST call itself, to `https://www.wixapis.com`, with a token: which identity a method takes and how to mint the token are in `wix-docs/references/CALLING.md`. |
+| `StartDeployWebsite`, `StartHeadlessBuild`, `UploadHeadlessWebsiteFiles` | `create`, `build` and `release` from a shell; the `wix-manage` recipe `references/sites/upload-static-site.md` creates a site and drops files over REST. |
+
+## Skills
+
+Each skill is a folder with a `SKILL.md` at its root that says what it does and which of its files to read when. A skill may already be on disk, in the plugin's folder or under `.agents/skills/<skill>/` after `npx skills add wix/skills`, or served by the client's skill tool; read it from there. Otherwise every file is online at `https://www.wix.com/skills/<skill>/<path>`, read with `ReadFullDocsArticle` or `curl`; `https://www.wix.com/skills/<skill>/` with the trailing slash lists the skill's files. Paths below are inside the skill's folder.
+
+### wix-headless-kit
+
+Online: https://www.wix.com/skills/wix-headless-kit/SKILL.md. On disk: the plugin's `skills/wix-headless-kit/`, or `.agents/skills/wix-headless-kit/`.
+
+Builds a Wix Headless site on shipped, verified `@wix/sdk` code: one typed data layer, hooks, components, Astro pages and a seed script per Wix business solution, from `wix-headless-templates`. The agent designs the presentation on those hooks and releases to Wix hosting. Runs as a CLI flow from a shell, or as Wix API calls through the MCP.
+
+**The cold start**, `wix-headless-cold-start/headless-kit.md` (https://www.wix.com/skills/headless-cold-start/headless-kit.md, what `StartHeadlessBuild` returns), takes a cold environment to where wix-headless-kit runs, then hands off to its `SKILL.md`. It measures three facts: the Wix MCP's tools in the tool list; Node 24.18 or later with `npm` reaching the registry; a way to get a build to `UploadHeadlessWebsiteFiles`, as an attachment or by `curl` to its upload URLs. The facts pick the route: all three, the plugin route (site through `ExecuteWixAPI`, Astro build here, release through the upload tool); MCP but no way to release a build, the API-call guide (`guides/api-run.md`, static pages in the upload tool's `files`); a Wix CLI session on the machine, the CLI route. The project folder comes first, with any handed-over files extracted into it. Skills on disk are used where they are; otherwise `CI=1 npx skills@latest add wix/skills --skill wix-headless-kit --skill wix-docs --skill wix-manage --yes`, then `node .agents/skills/wix-headless-kit/install/templates.mjs` for the templates, and `install/bootstrap.mjs` on the CLI route.
+
+- `SKILL.md`: the steps of a build and the table of business solutions.
+- `guides/api-run.md`: the whole run as Wix API calls through the MCP, for an agent with no shell or a shell that cannot reach Wix.
+- `guides/capabilities.md`: which Wix product owns which feature, and what ships for it.
+- `guides/existing-site.md`: a new frontend for a Wix site that already has its content, and continuing a site built in an earlier session.
+- `guides/migration.md`: a site moving to code after "Go Headless" in its dashboard.
+- `guides/reference-mode.md`: a stack that cannot run the shipped React code.
+- `guides/feedback.md`: sending the user's feedback on building with Wix.
+- `install/`: the scripts of a run (`setup.mjs`, `attach.mjs`, `deploy.mjs`, `install.mjs`, `templates.mjs`, `context.mjs`, `bootstrap.mjs`, `check.mjs`) and `pins.json`, the pinned CLI and templates versions.
+
+### wix-headless-templates
+
+Online: https://www.wix.com/skills/wix-headless-templates/SKILL.md. On disk: the plugin's `skills/wix-headless-templates/`, or `.agents/skills/wix-headless-templates/`.
+
+The code wix-headless-kit builds from, one folder per business solution: `storefront`, `bookings`, `rentals`, `blog`, `cms`, `forms`, `members`, `events`, `restaurants`, `donations`, `pricing-plans`, `portfolio`, `faq`, plus `blank` and `shared`. Each folder holds:
+
+- `INSTRUCTIONS.md`: the playbook, with the contracts.
+- `app/`: the typed, framework-agnostic data layer over `@wix/sdk`, React hooks and reference components.
+- `app-astro/`: the Astro pages with owner-editable SEO.
+- `rest/`: the same data layer as plain REST calls, for a site without a bundler.
+- `seed/`: the seed script that fills the site from a plan, `SEED.md` as the plan's contract, and a reader of what the site already holds.
+- `project/`: the solution composed into the CLI's Astro scaffold.
+
+`compose.mjs` at the root composes a solution's layers into a project.
+
+### wix-manage
+
+Online: https://www.wix.com/skills/wix-manage/SKILL.md. On disk: the plugin's `skills/wix-manage/`, or `.agents/skills/wix-manage/`.
+
+REST recipes to configure and manage a site's business solutions, one recipe per task with the exact endpoints, request bodies and order of steps. `SKILL.md` is the index of every recipe by area, each a link. The recipes are under `references/<area>/`: `app-installation`, `stores`, `ecommerce`, `bookings`, `calendar`, `donations`, `get-paid`, `pricing-plans`, `restaurants`, `events`, `blog`, `cms`, `rich-content`, `forms`, `contacts`, `automations`, `marketing`, `google-ads`, `google-business-profile`, `analytics`, `seo`, `media`, `sites`, `domains`, `site-properties`, `collaborators`, `custom-apps`, `dashboard-navigation`, `accessibility`. Each recipe is also a docs article under its API's section.
+
+### wix-docs
+
+Online: https://www.wix.com/skills/wix-docs/SKILL.md. On disk: the plugin's `skills/wix-docs/`, or `.agents/skills/wix-docs/`.
+
+Looks up the Wix API and SDK documentation to confirm an endpoint, method, request and response shape, field, enum or error before writing Wix code. `SKILL.md` has the two lanes, plain `curl` and the MCP's documentation tools, with the search, browse and read requests. `references/API_SPEC_SEARCH.md`: the spec index and its queries. `references/CALLING.md`: the identities a call runs as and how each token is minted. `references/EXTRACTING.md`: reading only the needed part of a big menu or method page with `curl` and `grep`.
+
+### wix-readme
+
+This index.