@wix/agent-skills 1.19.0 → 1.19.2

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

@@ -1,167 +1,229 @@
 ---
 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 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 and Read a Wix Site's Content Plan
 
-## Choose the request path before calling an API
-
-For a request to **generate a new plan**, follow the generation sequence below.
-For a request about an **existing flow**, use this branch instead; do not start
-the generation sequence or make a discovery call to look for the flow.
-
-`KEYWORD_RESEARCH` is an intentional pause, even after ten minutes. Explain
-that Create Content Plan (step 3) releases the existing flow; do not cancel it
-or trigger a replacement just because it is parked.
-First check whether the conversation or a prior response contains the actual
-`contentPlanFlowId`:
-
-- **Missing ID:** Explain the intentional pause and ask for the existing flow
-  ID. End the turn without making a status or release call. You can name the
-  release endpoint, `POST https://www.wixapis.com/promote/seo/v1/create-content-plan`,
-  but do not execute an example request. Placeholder text such as
-  `<YOUR_FLOW_ID>` is never an API argument.
-- **Known ID:** Use that actual flow UUID in the step 3 request's
-  `contentPlanFlowId` field to release the existing flow when requested.
-
-For example, when the user reports a flow parked at `KEYWORD_RESEARCH` but
-provides only a site ID, the next action is a reply, not an API call:
-
-> That status is an intentional pause. Create Content Plan releases the
-> existing flow. Please send the content plan flow ID from your trigger or
-> status response so I can use it in the release request.
-
-The user's reported status is enough to explain the pause; checking it first
-requires the very flow ID that is missing. A site ID is not a flow ID, even
-though both have UUID format.
-Do not guess a collection endpoint to discover the active flow.
-
-The complete status URL is
-`https://www.wixapis.com/promote/seo/v1/content-plan-flows/{contentPlanFlowId}`.
-Use this exact public base path and substitute the known ID. Do not call
-`GET /content-plan-flows` without an ID or construct a URL from a service name.
-
-Trigger, poll, release, poll, read. That is the full loop. The API is
-asynchronous — generation takes minutes — and the flow **parks at
-`KEYWORD_RESEARCH` until you explicitly release it**.
-
-All paths are relative to `https://www.wixapis.com/promote/seo/v1`.
-The API selects the site from the caller's authorization context.
-Writing requires the **Manage SEO Settings** permission.
-
-For a generation request, the only writes in this workflow are Trigger and
-Create Content Plan. Do not update the site's business profile, name,
-description, categories, or publication state to try to accelerate generation.
-Those are separate tasks requiring the user's actual data and authorization.
-`CREATED` can persist while work is queued; it does not justify setup changes
-or extra discovery calls. Continue checking the same flow without modifying
-the site.
-
-Keep every call scoped to the site the user selected. If site context cannot
-be resolved, report the lookup failure and request clarification; do not
-substitute another available site or change its business information. Missing
-context is not proof that the selected site does not exist or belongs to a
-different account. Say that its context could not be retrieved; do not claim
-that the user's site ID is invalid or offer replacement sites. Likewise, unmet
-prerequisites do not authorize switching sites or inventing business data.
+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
 
-Treat each numbered step below as a separate API execution, not sections of
-one script. Even a loop capped at 60 polls can outlive the execution timeout
-and lose the returned flow ID. A polling script must issue one GET and return
-`{ contentPlanFlowId, status }` immediately; decide the next action after that
-response. Never embed the trigger, polling loops, release, and candidate read
-in a single execution. Trigger and release are mutations: if the client asks
-whether an execution changes data, identify them as writes, not read-only.
-
-Generation waits on an external process. Do not put the entire generation in
-one long-running function, an unbounded `while` loop, or a busy-wait. Trigger
-once and return the flow ID immediately. Use separate, bounded status checks
-for the same ID so each response is visible and you can act on its status.
-A status check is one GET, not a loop that waits for a terminal state.
-Use the client's supported waiting mechanism between checks; do not assume
-that timers or sleep functions exist inside an API execution sandbox.
-
-Continue across status checks while the flow is progressing. At
-`KEYWORD_RESEARCH`, release it immediately once, then keep checking that same
-flow until `SUCCESS` and read its candidates. Do not keep polling the parked
-state instead of releasing it, or stop with only a promise to finish later.
-If the client cannot continue waiting, report the flow ID and last observed
-status honestly; that is an incomplete generation, not success.
-
-## The exact call sequence
+**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
 
 ```
-POST /content-plan-flows/trigger
+POST https://www.wixapis.com/promote/seo/v1/content-plan-flows/trigger
 {}
 ```
 
-Returns `{ "contentPlanFlowId": "..." }`. Return this response and end this
-execution here. Save the ID in the conversation before making any status
-request. Do not append step 2 to the trigger script.
+Response:
+
+```json
+{ "contentPlanFlowId": "<flow-uuid>" }
+```
+
+`<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
 
 ```
-GET /content-plan-flows/{contentPlanFlowId}
+GET https://www.wixapis.com/promote/seo/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.
 
-The response is `{ "contentPlanFlow": { "id": "...", "status": "..." } }`.
-Read `contentPlanFlow.status`, not a top-level `status`. A missing status is a
-response-shape problem: inspect the response instead of silently looping.
-`CREATED` alone does not identify a missing prerequisite. If the flow remains
-there without progressing, report the stalled flow ID and observed status; do
-not invent a missing business category or description.
-Always send the trigger's ID when following this generation. The documented
-omitted-ID behavior selects a previous successful flow, not the active flow;
-it is not a way to discover the ID of a parked flow.
-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).
+Example response, showing the public flow fields (optional fields may be absent):
+
+```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>"
+  }
+}
+```
 
-Typical status progression: `CREATED` → `SITE_ANALYSIS` → `KEYWORD_RESEARCH`. Check every
-few seconds using the bounded approach above. Completion time varies.
+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).
 
-**Stop polling and act on these terminal states:**
-- `PENDING_REQUIREMENTS` — the site has unmet prerequisites, such as missing
-  business location information. Identify the actual missing prerequisite from
-  available evidence; do not assume category or description is the cause.
-  Report what needs completing and do not repeatedly trigger new flows.
-- `FAIL` — the pipeline failed. Trigger a new flow to retry.
-- `CANCELED` — someone canceled the flow.
+`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`.
+
+| 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. |
+
+Check every few seconds using separate calls. Completion time varies.
 
 ### 3. Release the flow
 
 ```
-POST /create-content-plan
-{ "contentPlanFlowId": "..." }
+POST https://www.wixapis.com/promote/seo/v1/create-content-plan
+{ "contentPlanFlowId": "<flow-uuid>" }
+```
+
+Successful response:
+
+```json
+{
+  "success": true,
+  "contentPlanFlowId": "<flow-uuid>"
+}
+```
+
+Failure response fields (the diagnostic text comes from the API):
+
+```json
+{
+  "success": false,
+  "message": "<reason returned by the API>"
+}
 ```
 
-This advances the flow past `KEYWORD_RESEARCH`. Check `success` in the
-response. If `false`, read `message`.
+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.
 
-**Without this call the flow waits forever.**
+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).
 
 ### 4. Poll until SUCCESS
 
-Same single-GET execution as step 2, returning after each check. Status walks
+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`.
 
 ### 5. Read the briefs
 
 ```
-GET /content-plan-flows/{contentPlanFlowId}/blog-post-candidates
+GET https://www.wixapis.com/promote/seo/v1/content-plan-flows/{contentPlanFlowId}/blog-post-candidates
+```
+
+Example response showing the fields needed to display one topic:
+
+```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"
+      }
+    }
+  ],
+  "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false }
+}
 ```
 
-Returns `{ "blogPostCandidates": [...] }`. Each candidate's brief fields are
-nested under `briefData`, not at the candidate's top level. Map them directly:
+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 => ({
@@ -204,13 +266,13 @@ would help assess or refine them, without modifying the site's settings.
 After step 2, before or after step 3, read the keywords:
 
 ```
-GET /content-plan-keyword-research-items
+GET https://www.wixapis.com/promote/seo/v1/content-plan-keyword-research-items
 ```
 
 Edit one keyword (field-masked, only `keyword` and `main_keyword` writable):
 
 ```
-PATCH /keyword-research-items/{itemId}
+PATCH https://www.wixapis.com/promote/seo/v1/keyword-research-items/{itemId}
 {
   "keywordResearchId": "...",
   "item": { "id": "...", "keyword": "new keyword" },
@@ -222,22 +284,6 @@ PATCH /keyword-research-items/{itemId}
 Always use the one from the response for the next write. Edits are not
 durable across generations.
 
-## What this recipe adds over the docs
-
-The published reference documents each method. This recipe adds:
-
-1. **The parking gate.** The docs say `KEYWORD_RESEARCH` is a status. This
-   recipe says: the flow stops there until you call Create Content Plan.
-   Without that call, polling runs forever.
-
-2. **PENDING_REQUIREMENTS handling.** This explicit status signals unmet
-   prerequisites. Report it and identify the missing requirement only from
-   evidence; do not infer it from a queued `CREATED` status or fill in business
-   information on the user's behalf.
-
-3. **Copy-on-write on keyword edits.** The `keywordResearchId` can change
-   on the first write. Use the one from the response.
-
 ## Do not
 
 - Poll forever without calling Create Content Plan (step 3).