@wix/agent-skills 1.18.0 → 1.18.2

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

@@ -1,6 +1,6 @@
 ---
 name: "Forms Dashboard Navigation"
-description: "Builds direct links to Wix Forms dashboard pages on manage.wix.com — the forms list, the submissions table, the form builder for a specific form, standalone forms, templates, and forms settings. Pairs each main Forms entity (form, submission) 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."
+description: "Builds direct links to Wix Forms dashboard pages on manage.wix.com. The paths are not guessable and appear in no API reference, so take them from here: under `https://manage.wix.com/dashboard/{metaSiteId}/`, the forms list is `wix-forms`, a form's builder is `wix-forms/form/{formId}`, and that form's submissions are `wix-forms/form/{formId}/submissions` — there is no site-wide submissions page, and nothing lives under `contacts/forms`, `forms`, `form-builder` or `wix-forms-and-payments` (the legacy app). Also standalone forms, and each Forms entity paired with its read API so you can fetch one and hand back a 'view it in your dashboard' link."
 ---
 
 # Forms Dashboard Navigation
@@ -9,36 +9,39 @@ Build direct links into the Wix Forms pages of a site's dashboard. For the gener
 
 ## Main Pages
 
+**Never goess or answer a Forms dashboard-link request from memory** because the routes below are the only correct ones.
+
 | Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
 |---|---|---|
 | Forms list | `wix-forms` | All forms on the site |
 | Form builder | `wix-forms/form/{formId}` | Edit a specific form (fields, rules, submit settings) |
+| Submissions | `wix-forms/form/{formId}/submissions` | That form's submissions table |
 | Standalone form | `wix-forms/standalone-form` | Create a standalone form (has its own shareable page, not embedded in a site page) |
-| Submissions | `wix-forms-and-payments/submissions` | Submissions table across forms |
-| Templates | `wix-forms-and-payments/templates` | Create a form from a template |
-| Forms settings | `wix-forms-and-payments/settings` | Forms-level settings |
 
-Two URL namespaces appear here because the forms management pages and the form builder are registered by two apps (`14ce1214-b278-a7e4-1373-00cebd1bef7c` and `225dd912-7dea-4738-8688-4b8c6955ffc2`); `wix-forms` also redirects to the forms list, so it's the stable entry point.
+**Every Forms page is under `wix-forms`** — the namespace **Wix Forms (New)** `225dd912-7dea-4738-8688-4b8c6955ffc2` registers, the app that owns the Form Schemas v4 API. A `wix-forms-and-payments/...` path belongs to the legacy **Wix Forms (Old)** app `14ce1214-b278-a7e4-1373-00cebd1bef7c`: don't build one, and never install or target that app (see [Create Form](./create-form.md) § Silent breakers).
+
+**Submissions are per form**, hanging off that form's builder path — there is no site-wide submissions page to link to. With no `{formId}` in hand, link the forms list and let the owner pick.
 
-Entity-specific links (`{formId}`) accept the entity's ID appended as an extra path segment. Query params can follow.
+Entity-specific links (`{formId}`) take the entity's ID as a path segment, and query params can follow. The dashboard appends its own view state to the submissions URL — `folder` (a JSON-encoded breadcrumb), `sort` (e.g. `createdDate+desc`) and `selectedColumns` (a comma-separated list of field **`target`**s) — none of which you need to construct: the bare path opens the table with the owner's defaults.
 
 ## Pairing Entities with Their Read APIs
 
-Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header. Dashboard forms use the `wix.form_app.form` namespace.
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header. Dashboard forms live in the **`wix.form_app.form`** namespace — every Forms call that takes a namespace, as a query parameter or inside a filter, takes that exact value.
 
 | Entity | Read API | Dashboard link |
 |---|---|---|
 | Form | `GET /form-schema-service/v4/forms` · `POST /form-schema-service/v4/forms/query` · `GET /form-schema-service/v4/forms/{formId}` | `wix-forms/form/{formId}` (edit) or `wix-forms` (list) |
-| Submission | `POST /form-submission/v4/submissions/namespace/query` (filter must include the `namespace`) · `GET /form-submission/v4/submissions/{submissionId}` | `wix-forms-and-payments/submissions` |
+| Submission | `POST /form-submission-service/v4/submissions/namespace/query` (the filter must carry `"namespace": "wix.form_app.form"`) · `GET /form-submission-service/v4/submissions/{submissionId}` | `wix-forms/form/{formId}/submissions` — the `formId` comes off the submission |
 
 Example — after creating a form, hand back its links:
 
 ```
 Created "Contact Form".
 Edit it here: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}
-See submissions: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms-and-payments/submissions
+See submissions: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}/submissions
 ```
 
 ## Notes
 
-- Creating forms via the [Create Form](./create-form.md) recipe (Form Schemas API) makes them appear in the forms list above.
+- Creating forms via the [Create Form](./create-form.md) recipe (Form Schemas API) makes them appear in the forms list above — **but only when the form was created under the `wix.form_app.form` namespace with Wix Forms (New) installed.** A form created under any other namespace is reachable over the API and completely absent from these pages.
+- **Before handing back a `wix-forms/form/{formId}` link, confirm the form actually renders**: `GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary` must return a non-empty `formSummary.fields` whose count matches every input field. An empty summary means the owner will open this link to a blank form (Create Form, STEP 3).

package/skills/wix-manage/references/forms/update-form.md

@@ -0,0 +1,122 @@
+---
+name: "Update Form"
+description: "Changes a Wix form that already exists, with Form Schemas v4 `PATCH` — add a field to my form, add a dropdown, make a field required or optional, rename a label, reorder or retire a question. Covers reading the form back for its `revision` (and the required `namespace` query parameter), the whole-form body that a `PATCH` needs, the wholesale `formFields` replace that silently soft-deletes anything you omit, changing a field's component type in place, retiring a field that already has submissions, and the read-back that proves what was stored. Use whenever the form exists and the request changes what it collects; use Create Form when there is no form yet."
+---
+# RECIPE: Update a Wix Form
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`. Send `wix-site-id: <SITE_ID>` when the token is account-scoped.
+
+Change what a form collects — **add a field, relabel one, tighten a rule, reorder, retire one** — on a form that already exists. **Composing the field itself is not here**: [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) owns the `identifier` / `inputType` / `componentType` table and the options/enum shapes, and [Create Form](./create-form.md) § Silent breakers apply to an added field exactly as to a created one.
+
+**A `PATCH`, never a delete-and-recreate.** An update keeps the `formId` everything downstream already holds — a frontend binding, an automation, a saved dashboard view — and spends no slot against the site's form cap.
+
+---
+
+## The call
+
+```bash
+# 1 · read the form back: you need its current revision, and every field you intend to keep
+curl -X GET \
+  'https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}' \
+  -H 'Authorization: <AUTH>'
+
+# 2 · send that form back with your change applied
+curl -X PATCH \
+  'https://www.wixapis.com/form-schema-service/v4/forms/{formId}' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{ "form": {
+      "id": "{formId}",
+      "revision": "<the revision you just read>",
+      "name": "<the form name>",
+      "namespace": "wix.form_app.form",
+      "formFields": [ ...every field, with your change applied... ],
+      "steps": [ ...every step, with the layout item for a new field... ]
+  } }'
+```
+
+- **⚠️ `namespace` is a REQUIRED query parameter on the read, and this is what a revise run trips over.** Without it the read returns `400 namespace has size 0, expected 10 or more, namespace must not be empty` — a violation naming a *field*, so it reads like a body problem. Fix the call, don't reshape the payload. (The filter on `POST .../v4/forms/query` needs it too.)
+- **The read-back is the body.** Apply your change to what the `GET` returned and send that as `form`. `namespace` is **immutable** and travels along; **there is no `fieldMask`**, and no `revision` outside `form` — inventing either is a silent partial write.
+- **⚠️ Append to `formFields`; never rebuild the entries you read.** `[...form.formFields, newField]` works. Mapping the array to "clean up" each field — dropping `fieldType`, re-shaping an options block — fails with `fieldType cannot be provided with any these fields: input_options, display_options` on **every** field at once. The read-back's field objects are already a valid write shape: pass them through untouched and touch only the one field you are changing.
+- **`formFields` is replaced wholesale.** Wix: *"Any field that's missing from the array you send is moved to `deletedFormFields`, so resend every field you want to keep."* Same for `steps[].layout` — miss an item and that field goes unplaced, which renders empty. Drops are recoverable from `deletedFormFields`, but nothing announces them.
+- **A stale `revision` is rejected** — re-`GET` and re-apply; never guess or increment it.
+- **Plan caps apply to an added field.** `Field count reached its limit of N` on a `PATCH` is the site's premium cap: reduce or upgrade, with the choice put to the user ([Create Form](./create-form.md) § Plan caps). Never split the form across schemas to dodge it.
+
+---
+
+## Adding a field
+
+**Start by reading [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) § Field types and § Choice fields** for the field kind you're adding: it gives the `identifier` / `inputType` / `componentType` triple — take all three from one row, and note that a dropdown or radio is `inputType: "STRING"` — plus the options/enum shape and the GUID every option needs. [Create Form](./create-form.md) § Choice fields carries a complete dropdown body to copy. Composing a field from memory is what turns one `PATCH` into eight.
+
+Then four things are yours to generate:
+
+- **`id`** — a fresh lowercase GUID (`uuidgen | tr 'A-Z' 'a-z'`), unique in the form.
+- **`target`** — the immutable submission key, unique across the form: snake_case plus a short random suffix (`job_industry_7f2b`). **A duplicate `target` is accepted and silently stores nothing** for every field but one.
+- **one GUID per choice option** — `options[]` each need their own, exactly like the field's; a readable slug is rejected ([Create Form](./create-form.md) § Choice fields). Generate them with `uuidgen`, never by hand.
+- **the choices, declared twice** — every option needs `id` + `value` + `label`, and `validation.enum` must list every one of those `value`s. **An empty `validation` is a free-text field, not a dropdown**; the general "always include `validation`, even as `{}`" rule does not apply here, and getting it wrong is accepted with a `200`.
+- **the layout item** — append to `steps[<n>].layout.large.items`, mirroring into `medium` / `small` if the form has them:
+
+```json
+{ "fieldId": "<the new field's id>", "row": <next row>, "column": 0, "width": 12, "height": 1 }
+```
+
+A field missing from the layout isn't dropped, but it sorts last and has no defined position in the owner's builder. To place it mid-form, insert at that `row` and bump every item at or after it — `row` restarts at 0 in each step.
+
+**A choice field's `identifier` is its kind** — `DROPDOWN`, `RADIO_GROUP`, `CHECKBOX_GROUP`, `TAGS` — never `TEXT_INPUT`, which is accepted and stored as a plain text input ([Create Form](./create-form.md) § Choice fields).
+
+---
+
+## The other changes
+
+| Change | How |
+|---|---|
+| Label, placeholder, options, validation, order | Patch them and stop — nothing downstream needs updating |
+| A field's component type, in place | Send that field with the **choice `identifier`** and only the new options block; leaving `textInputOptions` beside `dropdownOptions` reads back as the text-input fallback |
+| Retire a field the form has submissions for | Set `hidden: true` — "hidden from submitters": the field stops rendering, and the submissions already collected under it keep their meaning. Dropping it from the array soft-deletes it instead |
+| Remove a field added by mistake this run | Drop it from `formFields`; it lands on `deletedFormFields` |
+| Rename a `target` | **Never.** It is the storage key, so a rename orphans every submission already collected under the old one. Change the *label* instead |
+
+---
+
+## Verify — an update regresses a form exactly as a create can
+
+**A `200` on the `PATCH` proves the body parsed, nothing about what was stored.** Read the form back, every time:
+
+```
+GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&formIds={formId}
+GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}/summary
+```
+
+Assert on that read-back, not on the `PATCH` response:
+
+- the changed field is there, carrying the `identifier` and `componentType` you sent — **a choice field with a non-empty `options[]`**, which is where a dropdown that degraded to a text input shows up;
+- every field you meant to keep is still present, and every `inputOptions.required` still reads back as sent;
+- `formSummary.fields` still holds one entry per input field — that is what the owner's dashboard renders.
+
+Then hand back the dashboard links ([Forms Dashboard Navigation](./forms-dashboard-navigation.md)): the form builder at `wix-forms/form/{formId}`, and that form's submissions at `wix-forms/form/{formId}/submissions`. New submissions carry the new field; past ones don't.
+
+---
+
+## Troubleshooting
+
+| Error / symptom | Cause | Fix |
+|---|---|---|
+| `400 namespace has size 0, expected 10 or more` / `namespace must not be empty` on a read | The `namespace` **query parameter** was omitted — it is required on every listing read, and the violation naming a field makes it look like a body problem | Add `?namespace=wix.form_app.form` to the read; leave the payload alone |
+| `fieldType cannot be provided with any these fields: input_options, display_options` — on every field | The read-back's `formFields` were re-mapped or "cleaned" before sending | Send the fields exactly as read and append the new one: `[...form.formFields, newField]` |
+| `inputType enum must be in [UNKNOWN_INPUT_TYPE, STRING, NUMBER, …]` | An invented `inputType` such as `ENUM` (with an `enumOptions` block) for a choice field | A dropdown or radio is `inputType: "STRING"` with `stringOptions.componentType`; multi choice is `ARRAY` |
+| The `PATCH` is rejected for a `revision` mismatch | Someone (or an earlier call) updated the form since your read | Re-`GET` and re-apply the change; never increment the revision yourself |
+| Fields that were on the form are gone after the update | `formFields` was sent partial — the omitted fields moved to `deletedFormFields` | Re-send them in a further `PATCH`, from `deletedFormFields` in the read-back; always send the whole array |
+| Surviving fields render empty for the owner | `steps[].layout` was sent without their items | Re-send every layout item, including `SUBMIT_BUTTON`'s; re-verify with `/summary` |
+| The added dropdown/radio reads back as a text input with `textInputOptions` | `identifier` was `TEXT_INPUT` rather than the choice kind — `componentType` alone doesn't route the renderer | Set `identifier` to the choice kind and re-send. Deleting and re-adding the field with the same `identifier` reproduces it ([Create Form](./create-form.md) § Choice fields) |
+| The update lands but the field never appears in submissions | The new field shares a `target` with an existing one — the server keeps one and the rest store nothing | Give it a unique `target` and `PATCH` again |
+| `Field count reached its limit of N` | The site's premium field cap, counting `INPUT` fields | Reduce, or put the upgrade choice to the user ([Create Form](./create-form.md) § Plan caps) |
+
+---
+
+## Related Documentation
+
+- [Create Form](./create-form.md) — composing fields, the identifier table, choice fields, the layout rules, plan caps
+- [Forms Dashboard Navigation](./forms-dashboard-navigation.md) — the builder and submissions links to hand back
+- [Update Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form) — the `PATCH` contract and its replace semantics
+- [Form object](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object) — `revision`, `hidden`, `deletedFormFields`, `steps[].layout`
+- [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) — every field-level rule

package/skills/wix-manage/references/media/generate-image-with-ai.md

@@ -0,0 +1,86 @@
+---
+name: "Generate an Image with AI"
+description: Generates an image from a text prompt with the Wix AI APIs (Runware). Returns a short-lived URL that must be imported to be kept — importing is Upload Media to Wix's job, and this recipe hands off to it. Covers choosing a model and its cost/latency/content-filter trade-off, the accepted output sizes, per-model batching limits, the AI credit each call spends, and why a content refusal arrives as a success response with no image.
+---
+# RECIPE: Generate an Image with AI
+
+For an image the user does not have. An image they supplied — an attachment or a public URL — is uploaded instead: [Upload Media to Wix](upload-media-to-wix.md).
+
+**API reference:** [About the Wix AI APIs](https://dev.wix.com/docs/api-reference/articles/ai-tools/ai-apis/about-the-wix-ai-apis), *Generating images* — endpoint, auth, and the full model table. Developer Preview, so confirm the contract there.
+
+---
+
+## AI credits
+
+Each call spends roughly **one AI credit**, billed to the site owner, or to the Wix user who installed the calling app. `numberResults: n` spends n. Importing is free.
+
+Generate one image per entity that needs one, and say how many a run will generate before starting it. Regenerate only when the user asks.
+
+---
+
+## Step 1: Generate
+
+```bash
+curl -X POST 'https://www.wixapis.com/runwareschemaless/v1/request' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: <AUTH>' \
+-H 'wix-site-id: <METASITE_ID>' \
+-d '[{
+    "taskType": "imageInference",
+    "taskUUID": "3f8c1e42-9b7a-4d16-8a5e-2c0f7b9d4e11",
+    "outputType": "URL",
+    "outputFormat": "PNG",
+    "positivePrompt": "a ceramic pour-over coffee dripper on a walnut counter, morning light",
+    "width": 1024,
+    "height": 1024,
+    "model": "runware:400@1",
+    "numberResults": 1
+}]'
+```
+
+| Parameter | Value |
+|---|---|
+| `taskUUID` | A real UUIDv4. Anything else returns `400 invalidTaskUUID` |
+| `width` / `height` | `1024×1024` (square — products, services, menu items), `1376×768` (16:9 hero), `1200×896` (4:3 editorial). Free-form sizes return 400 |
+| `model` | See below |
+| `numberResults` | `1` |
+
+Omit `steps` and `CFGScale`: Runware accepts them, other models return `400 unsupportedParameter`.
+
+### Models
+
+| `model` | Latency | Content filter |
+|---|---|---|
+| `runware:400@1` | ~5s | Loosest — the default |
+| `google:4@2` | ~25s | Medium, best fidelity |
+| `bfl:5@1` | — | Strictest; refuses trademark-ish prompts |
+
+Any Runware-supported model works — the reference's *Suggested models* table has the current AIR IDs.
+
+### Read the response
+
+```json
+{ "data": [ { "imageURL": "https://im.runware.ai/image/ws/2/ii/<id>.png" } ] }
+```
+
+**A refusal is a success response with no `imageURL`** — test for the field, not the status. On a refusal, reword the prompt or switch model, and report the image as not created.
+
+---
+
+## Step 2: Import
+
+`imageURL` expires, so import it as it lands. [Upload Media to Wix](upload-media-to-wix.md) owns that endpoint and its `PENDING` / `READY` rules; pass the `imageURL` as `url` and `image/png` as `mimeType`.
+
+The result is the returned `file.id` / `file.url` — permanent, and what an entity field takes.
+
+---
+
+## Batches
+
+`runware:400@1` and `bfl:5@1` take several tasks in one body. `google:4@2` returns 504 at three or more, so fire parallel single-task requests for it.
+
+Failure is per image: attach the ones that succeeded, create the rest of the entities text-only, and name which entities have no image and why. A failed image stays missing rather than being swapped for another.
+
+---
+
+For JavaScript callers there is an SDK path — `generateImage()` from the Vercel AI SDK with `runware.image(...)` from `@wix/ai`: [Set up the Wix AI SDK](https://dev.wix.com/docs/api-reference/articles/ai-tools/ai-apis/set-up-the-wix-ai-sdk).

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

@@ -0,0 +1,247 @@
+---
+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.
+---
+
+# 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.
+
+## 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
+
+### 1. Trigger
+
+```
+POST /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.
+
+### 2. Poll until KEYWORD_RESEARCH
+
+```
+GET /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).
+
+Typical status progression: `CREATED` → `SITE_ANALYSIS` → `KEYWORD_RESEARCH`. Check every
+few seconds using the bounded approach above. Completion time varies.
+
+**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.
+
+### 3. Release the flow
+
+```
+POST /create-content-plan
+{ "contentPlanFlowId": "..." }
+```
+
+This advances the flow past `KEYWORD_RESEARCH`. Check `success` in the
+response. If `false`, read `message`.
+
+**Without this call the flow waits forever.**
+
+### 4. Poll until SUCCESS
+
+Same single-GET execution as step 2, returning after each check. Status walks
+`CONTENT_PLAN` → `SUCCESS`. Read candidates in a subsequent execution after
+observing `SUCCESS`.
+
+### 5. Read the briefs
+
+```
+GET /content-plan-flows/{contentPlanFlowId}/blog-post-candidates
+```
+
+Returns `{ "blogPostCandidates": [...] }`. 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
+}));
+```
+
+`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:
+
+```
+GET /content-plan-keyword-research-items
+```
+
+Edit one keyword (field-masked, only `keyword` and `main_keyword` writable):
+
+```
+PATCH /keyword-research-items/{itemId}
+{
+  "keywordResearchId": "...",
+  "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.
+
+## 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).
+- Read candidates before `SUCCESS`.
+- Retry after `PENDING_REQUIREMENTS`.
+- Ask for a site ID.
+- Retry after a 403 — the caller lacks **Manage SEO Settings**.

package/skills/wix-manage/references/seo/manage-seo-tags.md

@@ -1,6 +1,6 @@
 ---
 name: "Manage a Wix Site's SEO Tags"
-description: Read and update the SEO tags of a Wix site at the right level — site-wide tags, page-type patterns, or one item's tags. Discover item IDs and pattern variables instead of inventing them, read before every full-replace write, and report resolved tags with the source each one came from.
+description: Read and update SEO titles and tags at the right level. For "change my site's SEO title", clarify homepage, specific page, or page-type pattern before discovery or writes; site-level tags accept meta tags only, never titles. Discover item IDs and pattern variables, read before every full-replace write, and report resolved tags with their sources.
 ---
 
 # Manage a Wix Site's SEO Tags
@@ -38,6 +38,21 @@ Match the user's request to the level that owns the change:
 | "All my product/blog/event pages should be titled like X" — a convention for every item of a page type | Pattern | **SEO Patterns** |
 | "Change the title of this page/product/post" — one specific item | Item | **Item SEO Tags** |
 
+**Site SEO Tags accepts meta tags only** (including site-level social image
+and robots settings). Never send `title`, `link`, or `script` tags to
+`PATCH /site-seo-tags`. Use Item SEO Tags for a specific page's title, or
+SEO Patterns for a page-type title convention. See the
+[Site SEO Tags object](https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/site-seo-tags-object).
+
+If the user says "change my site's SEO title" without identifying a page or
+page type, ask whether they mean the homepage, another specific page, or a
+page-type title convention. Ask immediately after reading this recipe; do not make discovery or schema
+queries until scope is clear. For an explicit
+homepage request, discover its actual ID; never assume an ID such as `home`.
+Use Item SEO Tags with `STATIC_PAGE`, read its current tags, and merge the title
+into the complete set. Follow the static-page publication rules below.
+Do not substitute `og:title` for the requested SEO title.
+
 Work at the level that matches the change. Writing the same title onto many
 items is the same outcome as one pattern and much harder to undo. If the user's
 words fit more than one level, ask one short question before writing. An
@@ -84,7 +99,38 @@ No request body. Returns `itemSeoTags` with `tags`, `resolvedTags`,
 
 ### List Item SEO Tags — `GET /item-seo-tags/{itemType}?paging.limit=100`
 
-No request body. Returns `itemSeoTagsList[]` and `pagingMetadata` with cursors.
+No request body. Returns `itemSeoTags[]` and `pagingMetadata` with cursors.
+`itemSeoTagsList` is not a response field. Each array entry is an Item SEO Tags
+object directly, not a wrapper: read `entry.itemId`, `entry.tags`, and
+`entry.resolvedTags`, not `entry.itemSeoTags`. Use `itemId` as the path ID;
+`id` is a composite identifier and `hostPageId` is not the item identifier.
+
+For static-page discovery, call this with `STATIC_PAGE`. Example response:
+
+```json
+{
+  "itemSeoTags": [
+    {
+      "itemType": "STATIC_PAGE",
+      "itemId": "<page-id>",
+      "tags": [],
+      "resolvedTags": [
+        { "tag": { "type": "title", "children": "Home | Studio Shop" },
+          "source": "TAG_SOURCE_DEFAULT_PATTERN" }
+      ]
+    }
+  ],
+  "pagingMetadata": { "hasNext": false }
+}
+```
+
+Inspect the returned page identities and resolved tags to identify the requested
+page, then Get that exact `itemId` before writing. If the response does not
+unambiguously identify it, ask the user to identify the page. Do not interpret
+a missing response field as an empty page list, assume the first entry is the
+homepage, or create/update a pattern as a fallback for a missing page. A
+single-page request never authorizes changing all pages of its type.
+See [List Item SEO Tags](https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/list-item-seo-tags).
 
 ### Set Site SEO Tags — `PATCH /site-seo-tags`
 
@@ -255,8 +301,9 @@ issue another Get — the write response is the confirmation.
 - **Calling List Item SEO Tags expecting product names.** List returns IDs
   and tags, not names. Use Search Products to find the ID by name first.
 - **Retrying a 400 with a different request shape without checking why.** A 400
-  means the shape was wrong. Compare against the shapes in this recipe, fix the
-  mismatch, send once. Three retries with guessed shapes is three wasted calls.
+  can mean the target level is wrong, not just the shape. Read the validation
+  message and check the level rules first. Compare against the shapes in this
+  recipe, fix the mismatch, send once. Three retries with guessed shapes is three wasted calls.
 
 Tags can currently be written only for the site's primary language: leave
 `language` unset on every write. There is no revision checking — the last write
@@ -298,12 +345,18 @@ success.
 - **`UNSUPPORTED_ITEM_TYPE`:** the error message lists the item types the API
   supports; use it to redirect the request rather than retrying blindly.
 - **`ITEM_NOT_FOUND`:** re-discover the item ID; do not guess a new one.
+- **Unsupported site-level tag / `FIELD_NOT_ALLOWED`:** a rejected `title`,
+  `link`, or `script` is a wrong-level error, not a nesting or field-mask error.
+  Do not retry it at site level or silently drop the requested tag. Clarify the
+  target if needed, then use the appropriate item or pattern API. Get that
+  target's current tags before merging and writing; never reuse the site's
+  tags as the new target's complete set. A rejected write saved no changes.
 - **Invalid tags:** tags are validated before anything is saved, so nothing
   changed; fix the tag and resend the same complete set.
 - **`400` on a request you built from this recipe:** compare the request you
   sent against the shapes in this recipe's "REST request and response shapes"
-  section. Fix the mismatch — a wrong nesting level, a missing wrapper key, or
-  `fieldMask` sent as an array instead of a string — and send again. Never
+  section and the wrong-level recovery rule above. Fix the mismatch — a wrong
+  nesting level, a missing wrapper key, or `fieldMask` sent as an array instead of a string — and send again. Never
   resend the same shape, and never walk through variations hoping one is
   accepted.
 - **Setting tags for `EVENTS_PAGE` items:** not supported yet, although reading

package/skills/wix-manage/references/stores/change-store-currency.md

@@ -0,0 +1,10 @@
+---
+name: "Change Store Currency"
+description: "Changes the store's payment currency through Site Properties and explains delayed currency updates in catalog responses."
+---
+
+# Change Store Currency
+
+Use the [Site Properties currency recipe](https://dev.wix.com/docs/api-reference/business-management/site-properties/skills/change-payment-currency-site-properties.md) to set the requested payment currency and read it back. Confirm the change with the user before updating it.
+
+Catalog product responses may temporarily show the previous currency after carts and checkout use the new one. Allow time for propagation, then recheck.