@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-manage/references/events/events-dashboard-navigation.md

@@ -0,0 +1,81 @@
+---
+name: "Events Dashboard Navigation"
+description: "Builds direct links to Wix Events dashboard pages on manage.wix.com — the published and draft event lists, a new event, categories, staff, a recurring series' occurrences, and one event's pages: overview, edit, tickets, guests (RSVP or ticketed), orders, schedule, registration settings and form, and policies. Pairs each Events entity with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+---
+
+# Events Dashboard Navigation
+
+Build direct links into the Wix Events pages of a site's dashboard. For the general URL contract
+(metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+Every Events page is under the `events` namespace of the Wix Events app
+(`140603ad-af8d-84a5-2c80-a0f60cb47351`). Take routes from these tables — don't build one from an
+API path or a page title.
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Events list | `events` | Published events (upcoming, past, cancelled) |
+| Drafts | `events/drafts` | Unpublished events |
+| New event | `events/new` | Create an event; add `?eventType=RSVP` or `?eventType=TICKETS`, and `&recurrenceStatus=RECURRING` for a series. `TICKETS` is the dashboard's value — the API's `registration.initialType` is `TICKETING`; don't swap them |
+| Categories | `events/categories` | Site-wide event categories |
+| Staff | `events/staff` | Staff who check guests in |
+| Occurrences | `events/occurrences/{categoryId}` | All occurrences of a recurring series — `dateAndTimeSettings.recurringEvents.categoryId` |
+
+## One Event's Pages
+
+An event's pages are `events/event/{eventId}/{tab}`. For an event whose `status` is `DRAFT`, insert
+`draft/`: `events/event/draft/{eventId}/{tab}`. An unknown tab redirects to the overview.
+
+| Page | `{tab}` | Notes |
+|---|---|---|
+| Overview | `overview` | |
+| Edit details | `edit` | Title, date, location, description |
+| Tickets | `tickets` | Ticketed events only |
+| One ticket | `tickets/{ticketDefinitionId}` | Edit a ticket type |
+| New ticket | `tickets/new` | |
+| Guests — RSVP event | `rsvp-guests` | `registration.initialType` `RSVP` |
+| One RSVP | `rsvp-guests/{rsvpId}` | |
+| Guests — ticketed event | `ticketed-guests` | `registration.initialType` `TICKETING` |
+| One ticket holder | `ticketed-guests/{ticketNumber}` | e.g. `FM9X-EHKF-ZO1P` |
+| Orders | `orders` | Ticketed events only |
+| One order | `orders/{orderNumber}` | e.g. `FM9X-EHKF-ZO` |
+| Schedule (agenda) | `features/schedule` | |
+| Video conferencing | `features/video-conferencing` | |
+| Promotion | `promotions` | |
+| Settings | `settings` | |
+| Registration settings | `settings/registration-settings` | Open/close registration, guest limit, waitlist |
+| Registration form | `settings/registration-form` | Form questions |
+| Registration messages | `settings/registration-messages` | Confirmation texts; also `settings/registration-closed`, `settings/tickets-unavailable` |
+| Policies | `settings/policies` | One policy: `settings/policies/{policyId}` |
+| Ticket settings | `settings/tickets-settings` | Tickets per order, tax |
+| Guest emails | `settings/rsvp-confirmation-email`, `settings/order-confirmation-email`, `settings/reminder-email`, `settings/cancellation-email`, `settings/waitlist-email` | |
+
+Pick the guests tab from the event's type: `rsvp-guests` for RSVP events, `ticketed-guests` for
+ticketed ones. Read it with `"fields": ["REGISTRATION"]` when you don't already have it.
+
+## Pairing Entities with Their Read APIs
+
+Fetch the entity, then link its page.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Event | `POST https://www.wixapis.com/events/v3/events/query` · `GET https://www.wixapis.com/events/v3/events/{eventId}` | `events/event/{eventId}/overview` (`draft/` inserted for a draft) |
+| Ticket definition | `POST https://www.wixapis.com/events/v3/ticket-definitions/query` | `events/event/{eventId}/tickets/{ticketDefinitionId}` |
+| RSVP | `POST https://www.wixapis.com/events/v2/rsvps/search` | `events/event/{eventId}/rsvp-guests/{rsvpId}` |
+| Order | `GET https://www.wixapis.com/events/v1/events/{eventId}/orders/{orderNumber}` · list: `GET https://www.wixapis.com/events/v1/orders?eventId={eventId}` | `events/event/{eventId}/orders/{orderNumber}` |
+| Ticket | `GET https://www.wixapis.com/events/v1/tickets/{ticketNumber}?eventId={eventId}` · list: `GET https://www.wixapis.com/events/v1/tickets?eventId={eventId}` | `events/event/{eventId}/ticketed-guests/{ticketNumber}` |
+| Policy | `POST https://www.wixapis.com/events/v2/policies/query` | `events/event/{eventId}/settings/policies/{policyId}` |
+| Category | `POST https://www.wixapis.com/events/v1/categories/query` | `events/categories` |
+| Recurring series | the event's `dateAndTimeSettings.recurringEvents.categoryId` | `events/occurrences/{categoryId}` |
+
+See [Manage Wix Events](https://dev.wix.com/docs/api-reference/business-solutions/events/skills/manage-events#find-an-event) for finding an event by title, and
+[Manage Event Guests](https://dev.wix.com/docs/api-reference/business-solutions/events/skills/manage-event-guests) for the guest reads.
+
+Example — after adding a guest to a ticketed event:
+
+```
+Added Sam Lee to Winter Gala.
+Guest list: https://manage.wix.com/dashboard/{metaSiteId}/events/event/{eventId}/ticketed-guests
+```

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/manage-oauth-apps.md

@@ -25,6 +25,7 @@ curl -X POST \
   -d '{
     "oAuthApp": {
       "name": "My Storefront",
+      "origin": "agent",
       "loginUrl": "https://example.com/login",
       "allowedRedirectUris": ["https://example.com/callback"],
       "allowedRedirectDomains": ["example.com"]