@wix/agent-skills 1.19.0 → 1.19.1

package/skills/wix-manage/references/google-ads/install-and-create-account.md

@@ -1,12 +1,12 @@
 ---
 name: "Install Google Ads and Create an Account"
-description: "One-time setup for running Google paid ads on a Wix site: install the Wix Google Ads app, then create the Google Ads account that every campaign, suggestion, and analytics call depends on. Covers checking whether an account already exists, choosing a currency, optionally attaching a promotional incentive (credit offer), linking a Google Merchant Center account, and deleting an account. Use when the user wants to 'set up Google Ads', 'connect Google Ads', 'start advertising on Google', 'create a Google Ads account', or hits an ACCOUNT_NOT_FOUND / app-not-installed error before creating a campaign. Google Ads REST API, base https://www.wixapis.com/google-ads/v1."
+description: "One-time setup for running Google paid ads on a Wix site: install the Wix Google Ads app, then create the Google Ads account that every campaign, suggestion, and analytics call depends on. Covers checking whether an account already exists, choosing a currency, optionally attaching a promotional incentive (credit offer), linking a Google Merchant Center account, and deleting an account. Use when the user wants to 'set up Google Ads', 'connect Google Ads', 'start advertising on Google', 'create a Google Ads account', or hits an ACCOUNT_NOT_FOUND / app-not-installed error before creating a campaign. Google Ads REST API, base https://www.wixapis.com/_serverless/pa-google/v1."
 ---
 # RECIPE: Install Google Ads and Create an Account
 
 Setting up Google Ads on a Wix site is a **strict two-step prerequisite** for everything else in this area: (1) install the Wix Google Ads app, then (2) create the Google Ads account. Campaigns, suggestions, analytics, and billing all fail with `ACCOUNT_NOT_FOUND` (or an app-not-installed error) until both are done. This is a one-time setup per site.
 
-Base URL for all endpoints: `https://www.wixapis.com/google-ads/v1`. The `<AUTH>` placeholder is shorthand for the `Authorization` header; body-bearing calls also need `Content-Type: application/json`.
+Base URL for all endpoints: `https://www.wixapis.com/_serverless/pa-google/v1`. The `<AUTH>` placeholder is shorthand for the `Authorization` header; body-bearing calls also need `Content-Type: application/json`.
 
 > **This flow creates a billable advertising account.** Creating the account and launching campaigns spends the site owner's real money. Confirm intent with the user before calling **Create Account**, and surface the chosen currency.
 
@@ -17,7 +17,7 @@ Base URL for all endpoints: `https://www.wixapis.com/google-ads/v1`. The `<AUTH>
 Before installing or creating anything, check for an existing account. **Get Account For Current Site** returns an empty response (not an error) when none exists, so it's the safe probe.
 
 ```bash
-curl -X GET 'https://www.wixapis.com/google-ads/v1/accounts/current-site' -H 'Authorization: <AUTH>'
+curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/accounts/current-site' -H 'Authorization: <AUTH>'
 ```
 
 - **`account` present** → setup is already done. Skip to whatever the user actually wants (create a campaign, view analytics, etc.). Do **not** create a second account — Create Account returns `ACCOUNT_ALREADY_EXISTS`.
@@ -48,7 +48,7 @@ Example response for an existing account:
 Idempotent — safe to call even if already installed (no effect). Required before Create Account.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/install-if-not-installed' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/install-if-not-installed' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' -d '{}'
 ```
 
@@ -61,7 +61,7 @@ Returns `{}`. Always run this before the first Create Account on a site.
 New accounts in supported currencies can attach an **incentive** — a promotional credit granted after the account spends a threshold. Skip this step for unsupported currencies (the call returns no offers).
 
 ```bash
-curl -X GET 'https://www.wixapis.com/google-ads/v1/incentives?currency=USD' -H 'Authorization: <AUTH>'
+curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/incentives?currency=USD' -H 'Authorization: <AUTH>'
 ```
 
 Returns up to three tiers (`lowOffer`, `mediumOffer`, `highOffer`), each with an `incentiveId`, an `awardAmount` (credit granted), and a `requiredAmount` (spend needed to unlock it), plus a `consolidatedTermsAndConditionsUrl`. Present the tiers to the user and let them pick; carry the chosen `incentiveId` into STEP 3 as `selectedIncentiveId`. The incentive is recorded now and applied automatically once the account's budget is assigned — there is no separate apply call in this flow.
@@ -73,7 +73,7 @@ Returns up to three tiers (`lowOffer`, `mediumOffer`, `highOffer`), each with an
 Requires `currency` (ISO-4217, e.g. `USD`). Pass `selectedIncentiveId` if the user picked one in STEP 2. **Confirm with the user before this call** — it provisions a billable account.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/accounts' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/accounts' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "currency": "USD",
@@ -107,7 +107,7 @@ The currency choice is durable and drives budget minimums/maximums and manager-a
 `UpdateAccount` is a partial update — send only the fields you're changing. Merchant Center linking is needed before a retail Performance Max campaign can serve product ads.
 
 ```bash
-curl -X PATCH 'https://www.wixapis.com/google-ads/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
+curl -X PATCH 'https://www.wixapis.com/_serverless/pa-google/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{ "account": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "merchantCenterAccountId": "9876543210" } }'
 ```
@@ -119,7 +119,7 @@ The response's `merchantCenterAccountLinkStatus.status` starts at `PENDING` —
 Conversion actions (Purchase, Page View, etc.) are what campaigns optimize toward. To inspect them:
 
 ```bash
-curl -X GET 'https://www.wixapis.com/google-ads/v1/accounts/current-site/conversion-actions' -H 'Authorization: <AUTH>'
+curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/accounts/current-site/conversion-actions' -H 'Authorization: <AUTH>'
 ```
 
 ### Delete the account
@@ -127,7 +127,7 @@ curl -X GET 'https://www.wixapis.com/google-ads/v1/accounts/current-site/convers
 `DeleteAccount` unlinks and removes the account. This is destructive and cannot be undone — **always confirm with the user first**, and prefer pausing campaigns over deleting the whole account when the user just wants to stop spending.
 
 ```bash
-curl -X DELETE 'https://www.wixapis.com/google-ads/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890' -H 'Authorization: <AUTH>'
+curl -X DELETE 'https://www.wixapis.com/_serverless/pa-google/v1/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890' -H 'Authorization: <AUTH>'
 ```
 
 Returns `{}`. Errors with `ACCOUNT_NOT_FOUND` if no account exists.

package/skills/wix-manage/references/google-ads/query-campaign-analytics.md

@@ -1,12 +1,12 @@
 ---
 name: "Query Campaign Performance Analytics"
-description: "Reads performance analytics for a Google Ads campaign on a Wix site: daily performance metrics (impressions, clicks, CTR, cost, leads, phone calls) with optional previous-period comparison and trends; conversion metrics from Wix Analytics (orders, revenue, leads, CPL, ROAS); the search terms that triggered a campaign's ads; per-product shopping performance for retail campaigns; and per-asset performance (headlines, descriptions, images) for PMAX Leads. Explains when to use campaignResourceName vs the Wix campaignId, the dateRange shape, field enums, sorting, and paging. Use when the user asks 'how is my campaign doing', 'show ad performance', 'what search terms triggered my ads', 'which products/assets perform best', 'campaign ROI/ROAS', or 'conversions from my Google ads'. REST base https://www.wixapis.com/google-ads/v1."
+description: "Reads performance analytics for a Google Ads campaign on a Wix site: daily performance metrics (impressions, clicks, CTR, cost, leads, phone calls) with optional previous-period comparison and trends; conversion metrics from Wix Analytics (orders, revenue, leads, CPL, ROAS); the search terms that triggered a campaign's ads; per-product shopping performance for retail campaigns; and per-asset performance (headlines, descriptions, images) for PMAX Leads. Explains when to use campaignResourceName vs the Wix campaignId, the dateRange shape, field enums, sorting, and paging. Use when the user asks 'how is my campaign doing', 'show ad performance', 'what search terms triggered my ads', 'which products/assets perform best', 'campaign ROI/ROAS', or 'conversions from my Google ads'. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 ---
 # RECIPE: Query Campaign Performance Analytics
 
 Read how a Google Ads campaign is performing. Six query endpoints cover different breakdowns; picking the right one depends on the metric and the campaign type. Performance data is only available once a campaign is `LIVE`, and typically appears within a few hours of activity.
 
-Base URL: `https://www.wixapis.com/google-ads/v1` (search-term V2 is under `/v2`). `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. All endpoints are read-only.
+Base URL: `https://www.wixapis.com/_serverless/pa-google/v1` (search-term V2 is under `/v2`). `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. All endpoints are read-only.
 
 **Two identifiers — get them right:**
 - **`campaignResourceName`** — the Google Ads resource name `customers/{customerId}/campaigns/{campaignId}` (from `campaign.resourceName`). Used by **Performance Metrics** and **Search Term Metrics (v1)**.
@@ -33,7 +33,7 @@ Both come from Get/List Campaign (see [Manage Campaign Lifecycle](manage-campaig
 Clicks, impressions, CTR, cost, leads, phone calls — per day, plus a summary row. `fields` chooses which metrics to return (defaults to clicks, impressions, CTR, cost, phone calls, date). `includePreviousPeriod: true` adds a `previousPeriodSummaryRow` and `trends` (decimal % change vs the equivalent preceding period).
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/performance-metrics' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/performance-metrics' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "campaignResourceName": "customers/3827461950/campaigns/7412836509",
@@ -60,7 +60,7 @@ curl -X POST 'https://www.wixapis.com/google-ads/v1/performance-metrics' \
 Business outcomes from **Wix Analytics** (not Google). Both `campaignId` and `dateRange` are **required**. Complex query — 120s SLA.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/conversion-metrics' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/conversion-metrics' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{ "campaignId": "b3f8e241-7c4a-4d19-a562-9f1e30d87c05", "dateRange": { "custom": { "from": "2026-03-01", "to": "2026-03-31" } } }'
 ```
@@ -74,7 +74,7 @@ curl -X POST 'https://www.wixapis.com/google-ads/v1/conversion-metrics' \
 The actual queries users typed. Use **V2** (`/v2/search-term-metrics`, keyed by `campaignId`) — it supports both Smart and PMAX Leads. Optional `searchTermText` (contains-match) and `searchTermTextsFilter` (`{ type: "MATCH" | "NOT_MATCH", searchTermTexts: [...] }`). Sortable by `COST`/`CLICKS`/`IMPRESSIONS`; paged with `nextPageToken`.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v2/search-term-metrics' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v2/search-term-metrics' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "campaignId": "b3f8e241-7c4a-4d19-a562-9f1e30d87c05",
@@ -100,7 +100,7 @@ curl -X POST 'https://www.wixapis.com/google-ads/v2/search-term-metrics' \
 Product-level rows for a Shopping campaign, plus a summary with total conversions, revenue, and ROAS. `resultSetting` controls the payload: `SUMMARY_ONLY`, `RESULTS_ONLY`, or `SUMMARY_AND_RESULTS`. 120s SLA. Note: per-product `conversions`/`conversionRate` always return 0 (not queried from Google) — use the summary's `totalConversions`/`roas` for outcomes.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/shopping-performance-metrics' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/shopping-performance-metrics' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "campaignId": "b3f8e241-7c4a-4d19-a562-9f1e30d87c05",
@@ -119,7 +119,7 @@ Results carry `productTitle`, `productImageUrl`, and the Wix `productId`; the `s
 Which creative assets perform best. `filter.assetTypes` narrows to specific roles (`HEADLINE`, `DESCRIPTION`, `MARKETING_IMAGE`, …).
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/asset-performance-metrics' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/asset-performance-metrics' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "campaignId": "b3f8e241-7c4a-4d19-a562-9f1e30d87c05",

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

@@ -5,163 +5,225 @@ description: Generate an SEO content plan and read its blog post topics, or trou
 
 # 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).