@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-manage/references/site-properties/change-payment-currency-site-properties.md

@@ -1,21 +1,23 @@
 ---
-name: "RECIPE: Change a Site's Payment (Store) Currency via Site Properties API"
-description: "Updates the site-level payment currency (store billing currency) using Site Properties API, including the required request body shape and field mask."
+name: "RECIPE: Change a Site's Regional Properties (Currency, Time Zone, Language) via Site Properties API"
+description: "Updates the site-level payment currency (store billing currency) using Site Properties API, including the required request body shape and field mask. Covers the site time zone and primary language through the same call, whose field mask names top-level properties."
 ---
 
-# RECIPE: Change a Site's Payment (Store) Currency via Site Properties API
+# RECIPE: Change a Site's Regional Properties via Site Properties API
 
 ## Goal
-Update a Wix site's **payment currency** (the ISO-4217 currency code used to bill customers) programmatically.
+Update a Wix site's **regional properties** — payment currency, time zone, or primary language — programmatically.
 
 ## When to use
 - You need to switch a site's store/payment currency (for example, from `USD` to `EUR`).
+- You need to change a site's time zone or primary language.
 - You want to automate regional/business setup for sites.
 
 ## Important notes before you start
-- The `paymentCurrency` field is part of **Site Properties** (often shown in the dashboard under regional/business info).
+- These fields are part of **Site Properties** (often shown in the dashboard under regional/business info).
 - A successful update increments the Site Properties `version`.
 - Use a **field mask** (`fields.paths`) to indicate which fields you're updating.
+- **Field mask paths are top-level property names.** The read response also contains a `locale` object, but it is not the write surface — see Gotchas.
 
 ## Step 1 — (Optional) Read current site properties version
 This is useful to understand the current snapshot version and other regional fields.
@@ -25,8 +27,14 @@ curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
   -H 'Authorization: <AUTH>'
 ```
 
-## Step 2 — Update the payment currency
-Use the `PATCH /site-properties/v4/properties` endpoint: put the new currency under `properties.paymentCurrency` and include a `fields.paths` mask.
+## Step 2 — Update the properties you need
+Use the `PATCH /site-properties/v4/properties` endpoint: put the new values under `properties` and name each one in a `fields.paths` mask.
+
+| Property | Field name | Value format |
+|---|---|---|
+| Payment currency | `paymentCurrency` | 3-letter ISO-4217 code — `USD`, `EUR`, `GBP` |
+| Time zone | `timeZone` | IANA time zone name — `America/New_York`, `Europe/Rome` |
+| Primary language | `language` | 2-letter ISO 639-1 code — `en`, `es`, `it` |
 
 ```bash
 curl -X PATCH 'https://www.wixapis.com/site-properties/v4/properties' \
@@ -42,18 +50,49 @@ curl -X PATCH 'https://www.wixapis.com/site-properties/v4/properties' \
   }'
 ```
 
+Time zone, same shape:
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/site-properties/v4/properties' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  --data-binary '{
+    "properties": {
+      "timeZone": "America/New_York"
+    },
+    "fields": {
+      "paths": ["timeZone"]
+    }
+  }'
+```
+
+To update several properties at once, include each one in `properties` and name each in `paths`:
+
+```bash
+--data-binary '{
+    "properties": { "timeZone": "Europe/Rome", "language": "en" },
+    "fields": { "paths": ["timeZone", "language"] }
+  }'
+```
+
 ### Expected response
-A successful call returns an updated Site Properties snapshot version, for example:
+A successful call returns only the updated Site Properties snapshot version — it does **not** echo the properties back:
 
 ```json
 { "version": "123" }
 ```
 
+To confirm the new value, re-read with the Step 1 `GET`.
+
 ## Gotchas & troubleshooting
-- **Always send a field mask**: omitting `fields.paths` will fail with `400` and `"Illegal request - No updates on request body"`.
+- **Always send a field mask**: omitting `fields.paths` fails with `400` and `"Illegal request - No updates on request body"`.
+- **Do not nest the mask path under `locale`.** The `GET` response contains a `locale` object (`languageCode`, `country`), which makes a path like `locale.timezone` look plausible — it is rejected with `400` and `"Illegal request - Unknown field in field mask - locale.timezone"`. Time zone and language are the top-level `timeZone` and `language` fields.
+- **`locale.languageCode` is a read-only projection** and can differ from the top-level `language` value. Set `language`; read `language` back to verify.
 - Currency must be a **3-letter ISO-4217** code (for example, `USD`, `CAD`, `EUR`, `GBP`).
+- There is no separate per-field endpoint for currency, time zone, or language — all three go through this one call.
 
 ## Related APIs
 - **Site Properties API**: [REST](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/introduction)
+- **Get Site Properties** (full read shape): [REST](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties)
 - Stores Currency Converter (conversion utilities, not for setting the site currency):
   - `POST https://www.wixapis.com/currency_converter/v1/currencies/amounts/{from}/convert/{to}`

package/skills/wix-manage/references/site-properties/site-properties-dashboard-navigation.md

@@ -0,0 +1,31 @@
+---
+name: "Site Settings Dashboard Navigation"
+description: "Builds direct links to the site-settings dashboard pages on manage.wix.com — the settings hub, website settings, and language & region. Pairs site properties with the Site Properties read API. 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."
+---
+
+# Site Settings Dashboard Navigation
+
+Build direct links into the settings pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Settings hub | `settings` | All site settings sections (business info, payments, etc.) |
+| Website settings | `settings/website-settings` | Site name, favicon, social sharing |
+| Language & region | `settings/language-and-region` | Language, currency, time zone |
+
+Older `manage-website...` links redirect to the current routes.
+
+## Pairing Entities with Their Read APIs
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Site properties (business info, locale, currency) | `GET /site-properties/v4/properties` | `settings` (hub) or `settings/language-and-region` |
+
+Example — after changing the payment currency:
+
+```
+Payment currency set to EUR.
+Review your regional settings: https://manage.wix.com/dashboard/{metaSiteId}/settings/language-and-region
+```

package/skills/wix-manage/references/sites/create-headless-site.md

@@ -0,0 +1,52 @@
+---
+name: "Create Headless Site"
+description: Creates a Wix Headless site (headless business) with one account-level API call — site, Wix Business Solution apps, and a configured OAuth client.
+---
+# Create Headless Site
+
+Headless sites are not created from templates. One account-level call creates the site, installs the requested Wix Business Solution apps, and creates and configures the site's OAuth client.
+
+> Do NOT use the [Create Site from Template](create-site-from-template.md) API for headless sites — it only tags the site's namespace and skips the headless setup entirely.
+
+## Prerequisites
+
+- Wix account with site creation permissions
+- Account-level API access
+
+## Provision a Headless Business
+
+**Endpoint**: `POST https://www.wixapis.com/headless-business-setup/v1/headless-business/provision`
+
+**Request Body**:
+```json
+{
+  "newMetasite": {
+    "namingStrategy": { "metaSiteName": "My Headless Business" },
+    "seedOptions": [
+      { "businessSolution": "STORES", "clearTemplateContent": true, "seedDemoContent": false }
+    ]
+  },
+  "synchronousSteps": ["SET_METASITE_NAME", "CONFIGURE_HEADLESS_APP"]
+}
+```
+
+- `namingStrategy` — exactly one of: `metaSiteName` (exact display name), `llmPromptBasedName: {}` (name derived from the top-level `prompt` field), or `defaultName: {}`
+- `seedOptions` — Wix Business Solution apps to install at creation: `STORES`, `BLOG`, `BOOKINGS`, `EVENTS`, `PORTFOLIO`, `PRICING_PLANS`. Each entry takes `clearTemplateContent` (remove sample content) and `seedDemoContent` (seed demo content). Empty installs none
+- `synchronousSteps` — steps to complete before the call returns: `SET_METASITE_NAME`, `CONFIGURE_HEADLESS_APP`, `SEED_CONTENT`. Omitted steps run asynchronously. Include `CONFIGURE_HEADLESS_APP` when the OAuth client must be usable immediately
+
+**Response**:
+```json
+{ "metaSiteId": "<SITE_ID>", "appId": "<OAUTH_CLIENT_ID>" }
+```
+
+`appId` is the site's OAuth client ID — do NOT create a separate OAuth app.
+
+## Existing Sites
+
+To provision headless onto an existing site, pass `"existingMetasite": {}` instead of `newMetasite`. This is a site-level call in the context of that site.
+
+## Next Steps
+
+After creating the site:
+- Install additional apps using [Install Wix Apps](../app-installation/install-wix-apps.md)
+- Add content (products, services, blog posts, etc.)

package/skills/wix-manage/references/sites/create-site-from-template.md

@@ -1,6 +1,6 @@
 ---
 name: "Create Site from Template"
-description: Creates new Wix sites from templates using account-level APIs. Covers template search, site creation, headless site setup, OAuth app creation, and publishing.
+description: Creates new Wix sites from templates using account-level APIs. Covers template search, site creation, and publishing. Not for headless sites.
 ---
 # Create Site from Template
 
@@ -108,23 +108,10 @@ The `siteName` must follow these rules:
 
 If `siteName` is not provided, one is generated automatically.
 
-### For Headless Sites
-
-Add `"namespace": "HEADLESS"` to the request body:
-
-```json
-{
-  "originTemplateId": "<TEMPLATE_ID>",
-  "siteName": "my-headless-site",
-  "namespace": "HEADLESS"
-}
-```
-
 **Response** includes the new site's `metaSiteId`.
 
 ### IMPORTANT NOTES:
-- Only mention headless if user specifically requests it
-- If user doesn't ask for headless, do NOT include the `namespace` field
+- This API creates regular Wix sites. Do NOT use it for headless sites (even with a `namespace` field) — use [Create Headless Site](create-headless-site.md) instead
 
 ---
 
@@ -151,16 +138,6 @@ curl -X POST \
 
 ---
 
-## Step 5: For Headless Sites - Create OAuth App
-
-If the site was created as headless, you MUST create an OAuth app for authentication.
-
-See [Create OAuth App](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-oauth-app) documentation.
-
-This is a site-level call in the context of the newly created site.
-
----
-
 ## Common Template IDs
 
 For quick access without searching:

package/skills/wix-manage/references/sites/site-import.md

@@ -0,0 +1,243 @@
+---
+name: "Site Import"
+description: Drive the Wix Site Import agent to migrate an existing store or site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix. Use this skill whenever the user wants to import, migrate, or clone a store/site into Wix, mentions moving off Shopify/WooCommerce/Magento, or gives a source store URL and asks to bring it into Wix. Covers starting the import, polling progress, answering the agent's mid-import questions, handling deploy/failure/auth-expiry states, and sending post-deploy follow-up changes.
+---
+
+# Site Import
+
+Drives an autonomous Wix-hosted import agent over REST to migrate a store/site
+from another platform into Wix. You act as the relay between the user and the
+agent: start the job, poll it, surface its questions and progress like a chat,
+and report the final result.
+
+## Golden rules — apply to every single message
+
+1. **Only `DEPLOYED` means the site is live.** Any other status — including
+   `AUTH_EXPIRED` — means there is NO finished site yet. Never declare
+   success, completion, or "your site is live" otherwise, and never present a
+   URL from any other source as the result.
+2. **Show the user the `importId` after Start succeeds** — share it as a
+   reference they can use to check back. Never show raw JSON or HTTP codes.
+3. **Never offer menus of monitoring or technical options** — pick the right
+   behavior yourself and do it quietly.
+4. **Plain language only** — write for a shopkeeper, not an engineer.
+5. **This API is the only site-creation tool for this task** — never
+   substitute other Wix site-builder tools (see Scope).
+
+Base URL: `https://www.wixapis.com/site-import`. All calls use account-level
+scope on the signed-in Wix user's account. A full import typically takes
+15–60 minutes.
+
+## Calling the API
+
+This API is **deliberately not listed in the public Wix REST documentation**,
+so do NOT search the Wix docs / API spec for it — the search will come up
+empty every time. That is expected and is NOT a reason to stop, ask the user
+for "special permissions", or switch to a different import product. This
+skill is the documentation; the endpoints below are real and live.
+
+**Make the first API call immediately — no preamble.** Never announce "let me
+check the tools" or "checking auth" before the first call. If Start returns
+an error, handle it per the Rules section — **never probe other endpoints**
+(e.g. site-properties, site-list) to "verify auth"; those calls reveal
+nothing useful.
+
+**All calls are server-side.** Never call this API from an artifact, a web
+page, or any client-side code — those fail with CORS. The entire experience
+is plain chat — API calls plus short messages.
+
+Use the Wix account-level REST API tool available in your environment with
+the **full URL**. Start, Send-a-message, and Cancel are mutating (POST);
+Poll is read-only (GET).
+
+Example — Start:
+
+```
+POST https://www.wixapis.com/site-import/v1/imports
+Body: { "request": "Import https://example-store.com into a new Wix site" }
+```
+
+Example — Poll:
+
+```
+GET https://www.wixapis.com/site-import/v1/imports/<importId>?includeRecentActivity=true
+```
+
+Example — Poll fetching a review document:
+
+```
+GET https://www.wixapis.com/site-import/v1/imports/<importId>?includeRecentActivity=true&artifactIds=mapping-summary,mapping-plan
+```
+
+Example — Send a message:
+
+```
+POST https://www.wixapis.com/site-import/v1/imports/<importId>/messages
+Body: { "message": "Use the blue logo from the About page instead" }
+```
+
+## Scope — this skill drives the import service, nothing else
+
+While an import is the task at hand, ALL site-creation work goes through this
+API. Never fall back to other site-building tools (site-builder/template/AI
+site-generation tools) to "compensate" — not when the import is slow, and
+especially not when it FAILS.
+
+**Status comes ONLY from this API's Poll endpoint.** Never call
+`WixSiteBuilder`, `CreateSiteFromTemplate`, `pullSiteCreationJob`, or any
+other connector tool to "check on the build" — `WixSiteBuilder` in particular
+STARTS a new site build on every call, even when the prompt asks for status.
+A failed import ends with a clear failure report and a full stop; the user
+must never discover a different site in their account that they didn't ask
+for. If an alternative makes sense, propose it AFTER reporting the failure
+and act only on the user's explicit yes.
+
+## Before starting an import
+
+This creates real infrastructure and writes to the user's Wix account. Before
+calling **Start**, confirm:
+- The source URL and platform are correct
+- The user understands it runs for up to ~60 minutes and may ask questions mid-way
+
+Also confirm before calling **Cancel** — it's irreversible.
+
+## What the user sees (presentation rules)
+
+You are the user experience; the API is plumbing. Keep the protocol invisible:
+
+- **Show the `importId` once, right after Start succeeds** — e.g. "Your import
+  ID is `abc123` — keep it handy." Never show raw JSON, HTTP codes, artifact
+  ids, or `sourcePlatform`/`sourceConfidence` values.
+- **Write for a non-technical audience.** No jargon: no "endpoint", "API",
+  "poll", "HTTP", "rate limit", "JSON". Translate events into plain outcomes —
+  "the source store limits how fast it can be read" not "hit rate limit (429)".
+- **Monitor autonomously — never ask the user whether to keep monitoring.**
+  Poll every ~30 seconds until a terminal status arrives. If the user sends a
+  message about something else, handle it then resume polling. Match your
+  environment:
+  - **Background polling**: speak up only on meaningful milestones — platform
+    identified, plan step completes, agent asks a question, site deploys, or
+    something fails. Never narrate each poll or transient errors.
+  - **Turn-based**: end each turn with one concrete progress update. On every
+    later user message, poll first. **Do not end a turn asking whether to keep
+    checking** — just keep checking.
+- **Status answers must be substantive.** Never answer "still in progress".
+  Relay `message` (lightly rephrased) and anything fresh from `recentActivity`
+  / `todos`. If `message` is empty, say the import is still setting up.
+- **Never announce or describe the monitoring itself.** After the one-sentence
+  start message, stay silent until the first milestone.
+- **Keep routine updates to 1–3 short sentences.** No headers, emoji walls, or
+  bullet lists for ordinary progress.
+- On start, two short sentences: (1) import underway, mention detected platform
+  when it helps; (2) share the `importId`. Never say "confidence", "sandbox",
+  "execution", or "session".
+- Progress updates: rephrase `recentActivity` `TEXT` entries and `todos` in
+  plain language; never echo verbatim.
+- Ask `NEEDS_INPUT` questions conversationally, as if they were your own.
+- On `DEPLOYED`, lead with the live URL, then a plain-language summary of what
+  the user got, honest limitations, and 2–3 short follow-up offers. Leave out
+  frameworks, SDKs, and anything from the jargon list.
+- On `FAILED` / `AUTH_EXPIRED` / `SESSION_EXPIRED`, explain what happened in
+  plain words — no codes, no id dumps.
+- **A failure is the headline, never a footnote.** The moment a poll returns
+  `FAILED`, your very next message leads with that fact and the reason — never
+  bury it or paper over it with other tools.
+
+## Endpoints
+
+**Single `importId` for the whole import — assigned at Start, never changes.**
+
+1. **Start** — `POST /v1/imports`
+   Body: `{"request": "<natural language; MUST include the source store URL>"}`
+   Returns: `importId`, `sourcePlatform`, `sourceConfidence`.
+   One import per store at a time: if the same user re-starts for the same store,
+   the server returns the existing `importId` (no new import is created). If a
+   different user on the account already owns an import for that store, Start
+   returns `409 { "code": "IMPORT_IN_PROGRESS" }` — tell the user and stop.
+
+2. **Poll** — `GET /v1/imports/{importId}?includeRecentActivity=true`
+   Returns: `status`, `deployUrl`, `message`, `options[]` (only when
+   `NEEDS_INPUT`), `recentActivity[]`, `recentActivityCount`, `todos[]`,
+   `artifacts[]`.
+   **Always pass `includeRecentActivity=true`** — the activity feed is withheld
+   unless requested. To read a review document, add
+   `&artifactIds=mapping-plan,mapping-gaps` (see "Review documents").
+
+3. **Send a message** — `POST /v1/imports/{importId}/messages`
+   Body: `{"message": "<whatever the user said>"}`
+   **This is the ONE way anything the user says reaches the agent** — an answer
+   to a question, a comment, a correction, or a new instruction. Valid at any
+   point: while `IMPORTING`, at a `NEEDS_INPUT` stop, and after the import
+   finishes. Returns the **same `importId`** — keep polling it.
+
+4. **Cancel** — `POST /v1/imports/{importId}/cancel`
+   Body: `{}`. Only meaningful while status is `IMPORTING`.
+
+## How to run the flow
+
+- After Start, poll every ~30 seconds while `status` is `IMPORTING`. Never
+  pause to ask the user whether to keep monitoring — just keep going. Stop
+  only on a terminal status (`DEPLOYED`, `FAILED`, `CANCELLED`) or explicit
+  cancel.
+- Track progress from:
+  - `recentActivity`: up to 20 `{kind, text}` entries, oldest first. `TEXT`
+    entries are the agent's messages; `TOOL_USE` are action labels. Rolling
+    window — track which entries you've covered to avoid repeating them.
+  - `todos`: `{content, status, activeForm}` — `PENDING | IN_PROGRESS |
+    COMPLETED`. Full snapshot each poll; replace, don't append.
+  - Empty `recentActivity`/`todos`/`artifacts` in early polls is normal — these
+    are best-effort and the agent may not have produced them yet.
+- Act on `status`:
+  - `IMPORTING` — keep polling.
+  - `NEEDS_INPUT` — agent is blocked. Show `message` (and `options` if present)
+    to the user, collect their answer, send it with Send-a-message, then keep
+    polling the same `importId`. The user may answer in free text even when
+    `options` lists suggested answers. If `message` mentions review documents,
+    read them FIRST (see "Review documents") — the decision usually depends on them.
+  - `DEPLOYED` — terminal success. Deliver `deployUrl` and `message` per
+    presentation rules.
+  - `FAILED` — terminal. Relay `message` in plain words.
+  - `AUTH_EXPIRED` — recoverable, NOT success, nothing is live (golden rule 1).
+    Tell the user the connection to their account expired and you're restarting,
+    then call Start again with the same request — work so far is preserved.
+  - `CANCELLED` — terminal.
+- **Anything the user says mid-import goes straight to Send-a-message** — no
+  need to wait for `NEEDS_INPUT`.
+- Follow-up changes after a deploy use the same Send-a-message call. The import
+  stays resumable for 7 days; if idle for ~60 minutes the next message revives
+  it — do not warn the user about a time limit.
+- If Send-a-message returns `409 { "code": "SESSION_EXPIRED" }`, the import
+  can no longer be resumed — tell the user and offer a fresh start.
+
+### Review documents
+
+The agent writes review documents at approval gates (mapping plan, gaps list,
+execution plan, completion summary). **They exist only in the API response** —
+the user has no way to open a file.
+
+- Every poll returns `artifacts[]` as a manifest: `{id, title, format,
+  contentBytes}` with `content` **empty**. This is deliberate — documents are
+  large and most polls don't need them.
+- To read one, poll again with `&artifactIds=<id>[,<id>]`. Those come back with
+  `content` filled in (Markdown or JSON).
+- **When `message` announces review documents, fetch them and summarize for the
+  user in plain language before asking for approval.** Never say "the plan is
+  in a file I can't read" or relay a filename as something the user should open.
+
+## Rules
+
+- Single `importId` — assigned at Start, returned unchanged by Send-a-message.
+- Never invent a `deployUrl` — only report the one returned with `DEPLOYED`.
+- Treat `NEEDS_INPUT` and `AUTH_EXPIRED` as normal conversation turns, not
+  errors.
+- **Site Import is in limited rollout.** If Start returns `404` or `403` with
+  `"code": "NOT_ENABLED"`, tell the user plainly that site import isn't
+  supported on their account yet and they can contact Wix support — then stop.
+  Do not retry or fall back to another site-creation tool.
+- Any other `403` on Start means the caller is not authorized — tell the user
+  and stop. Do not probe other endpoints to diagnose this. A `400` means a
+  required field is missing (`request`/`message` must be 1–20000 chars).
+- Requesting an unknown id in `artifactIds` is silently ignored — not an error.
+  A document simply may not exist yet on an earlier turn.
+- **The user cannot open files.** If a message mentions a document by filename,
+  fetch it with `artifactIds` and read it to them.

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

@@ -0,0 +1,29 @@
+---
+name: "Sites Dashboard Navigation"
+description: "Builds direct links to the account-level sites pages on manage.wix.com — the My Sites list (all sites in the account) and each site's own dashboard. Pairs the site list with the Query Sites read API. 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."
+---
+
+# Sites Dashboard Navigation
+
+For the general URL contract, see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md). Sites pages are **account-level** — they live under `https://manage.wix.com/account/...` and take no metaSiteId.
+
+## Main Pages
+
+| Page | URL | What it manages |
+|---|---|---|
+| My Sites (site list) | `https://manage.wix.com/account/websites` | All sites in the account |
+| A site's dashboard | `https://manage.wix.com/dashboard/{metaSiteId}/home` | One site's dashboard home |
+
+## Pairing Entities with Their Read APIs
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Site | `POST /site-list/v2/sites/query` (returns each site's `id` = metaSiteId + name) | `https://manage.wix.com/dashboard/{id}/home` |
+
+Example — after creating a site from a template:
+
+```
+Created "Sunset Spa" from the template.
+Open its dashboard: https://manage.wix.com/dashboard/{metaSiteId}/home
+All your sites: https://manage.wix.com/account/websites
+```

package/skills/wix-manage/references/stores/add-store-pages-to-site.md

@@ -30,12 +30,28 @@ curl -X POST \
   -d '{}'
 ```
 
-**Response**: Empty body on success.
+**Response**: `200` with `{"pagesAdded": ["<widgetId>", ...]}` when the call completes within the gateway timeout. On sites with many installed apps the call usually does **not** complete in time — see the notes below.
+
+### If the User Already Got a 504
+
+Answer as troubleshooting, not as a failed install:
+
+| What happened | What to do | Why |
+| --- | --- | --- |
+| `504 Gateway Timeout` after ~30 seconds | Wait 1–2 minutes, then verify that the cart/checkout pages exist and checkout works | The gateway timed out while the server-side install may still be running |
+| Pages now exist | Do not call the endpoint again | The repair completed despite the timeout |
+| Pages are still missing after waiting | Call the endpoint once more, then verify again | A second call is only warranted after the first run had time to finish |
+
+Do not describe an immediate retry as harmless or normally idempotent. The endpoint only adds missing pages, but each call still starts a full scan/add/republish pass, so retrying before the first pass finishes can create overlapping work and another publish.
 
 ### IMPORTANT NOTES:
 - This endpoint adds missing store pages (cart, checkout) if they don't exist
 - The request body is empty - no parameters needed
 - Only required Authorization header
+- **Long-running — a 504 does not mean failure.** The endpoint synchronously scans every app installed on the site, adds any missing essential pages, and republishes the site. On real sites this often exceeds the ~30-second gateway timeout, so the call returns `504 Gateway Timeout` (sometimes wrapped as `Internal Server Error` with `errorCode: -100`) while the installation keeps running server-side and usually completes.
+- **On 504, do not retry immediately.** An immediate retry starts a second full install-and-republish pass. Wait 1–2 minutes, then verify the missing pages now exist (check the site's store pages, or have the user refresh and re-test checkout). Call the endpoint again only if the pages are still missing.
+- **Call it from an HTTP tool that is allowed to reach `www.wix.com`** (for example, the Wix MCP `CallWixSiteAPI` tool). Sandboxed code-execution tools (such as `ExecuteWixAPI`) block this host and fail with `403 Forbidden: requests to www.wix.com not allowed`.
+- **The operation republishes the site.** Confirm with the user before running it on a live site.
 
 ---
 

package/skills/wix-manage/references/stores/create-product-from-image.md

@@ -211,7 +211,7 @@ Store the result internally as `subscription_eligible: true/false`. If `true`, a
 
 ## V3 STEP 4: Present Review Card to User (INTERACTIVE)
 
-**You MUST present ALL generated fields to the user and ask for confirmation before proceeding.**
+**Present ALL generated fields to the user so they can review and refine them.** This is a content preview for editing — NOT the create approval. The single confirmation before creating happens later, in V3 STEP 6. Do not ask the user to approve creation at this step.
 
 Present a structured review card using the markdown format below. This provides a visual product-card-style layout:
 
@@ -242,15 +242,15 @@ Present a structured review card using the markdown format below. This provides
 ---
 ```
 
-After the card, present the action options:
+After the card, offer the ways they can adjust the content:
 
 > 1. **Refine** — tell me what to change (e.g., "make the description shorter", "the price should be lower")
 > 2. **Regenerate** — I'll start the analysis over, optionally with additional context from you
-> 3. **Approve** — lock in these details and continue to the next steps
+> 3. **Looks good** — continue to the next steps (options / subscription)
 
 If the user provided a text note that **contradicts** what's visible in the image (e.g., image shows blue but note says "available in red"), ask the user to clarify before proceeding.
 
-**Wait for user confirmation.** Apply any corrections they request. Do NOT proceed until approved.
+Apply any corrections the user requests. When they're happy (or have no changes), continue to the next step. **Do NOT treat this as the final create approval** — that single confirmation comes once, at V3 STEP 6.
 
 ---
 
@@ -342,13 +342,15 @@ If no options were detected:
 
 ## V3 STEP 6: Create the Product
 
-Before making the API call, ask the user one final time:
+> **CRITICAL — THIS IS THE ONLY CREATE CONFIRMATION. ASK EXACTLY ONCE.** The review card in V3 STEP 4 was a content preview for editing, not an approval. Here you ask for the single go-ahead before creating. Do NOT summarize-and-ask more than once — one clear confirmation is enough.
+
+Ask the user once:
 
 > Everything is ready. Shall I create the product now?
 > - **Yes, create it** — I'll submit the product to your store now.
 > - **No, go back** — return to a previous step to make changes.
 
-**Wait for confirmation.** Only proceed with the API call if the user says Yes.
+**Wait for confirmation.** Only proceed with the API call if the user says Yes. If the user already said something like "just create it", treat that as the confirmation and proceed without asking again.
 
 ---
 

package/skills/wix-manage/references/stores/create-product-with-options-catalog-v3.md

@@ -18,20 +18,18 @@ The goal of this step is not just to create *a* product, but to help the user cr
 
 ### 0a. Opening the conversation
 
-**If the user hasn't named a product yet, open the conversation with this question up front:**
+**As soon as this skill is triggered — and the user hasn't already described a product — YOU open the conversation.** Proactively send a single opening message that invites *either or both* input paths and makes clear you'll generate the full product info from whatever they provide:
 
-> **What product would you like to create?**
+> **What would you like to sell? Just describe your product in a few words and/or upload a photo of it — I'll generate the full product info (name, description, price, and any options) for you from there.**
 
-If the user already gave you product details, skip the opening question and go straight to the gap check in 0b.
+The user can reply with a text prompt, an image, or both:
 
-**Offer a starting path.** When opening the conversation (and the user hasn't already committed to a method), let them choose how to provide the product details:
+- **An image is provided (with or without text)** → follow the **[Create Product from Image](https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-from-image)** recipe to generate the product info from the image(s), then continue from the gap check in 0b for anything still missing.
+- **Text only** → continue with the gap check in 0b.
 
-> "You can either **upload a product image** and I'll create the product info from it, or just **describe the product in text** and I'll take it from there. Which would you prefer?"
+If the user *already* described a product when triggering the skill, skip this opening message and go straight to 0b.
 
-- If the user wants to start from an image → follow the **[Create Product from Image](https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-from-image)** recipe to extract the product name, description, price, and any visible options from the image(s), then continue the conversation from 0b with whatever that recipe couldn't fill in.
-- If the user prefers text / a prompt → continue with the gap check in 0b as usual.
-
-> **Count this toward the 1–2 question budget.** If you ask the image-vs-text question, keep the remaining follow-ups to one so the total conversation stays short.
+> **This opening message is the entry point, not a follow-up — it does NOT count against the 1–2 follow-up-question budget in 0b.**
 
 ### 0b. Gap check — decide what (if anything) to ask
 
@@ -59,7 +57,15 @@ You may ask **one** enrichment question to make the product more complete. Ask a
 
 > **CRITICAL — ONCE A PRODUCT-CREATION CONVERSATION HAS STARTED, STAY ON IT.** Do not switch to other topics, suggest unrelated tasks, or start new workflows until the product has actually been created (saved) via STEP 1 — **unless the user explicitly asks to do something else**. If the user goes off-topic, briefly answer if needed, then steer back to finishing and saving the product.
 
-After the product is saved, you're free to suggest next steps (e.g. adding more products, setting up the store).
+### 0d. Confirm once — then create
+
+> **CRITICAL — VALIDATE EXACTLY ONCE BEFORE CREATING.** Right before calling the Create Product API (STEP 1), show a brief summary of what you're about to create and ask for a single go-ahead. Ask **only once**. Do NOT approve-and-then-ask-again (e.g. present a summary, get a "yes", and then ask "shall I create it now?" a second time) — that double confirmation is exactly what we want to avoid. Once the user approves, go straight to STEP 1 with no further approval prompts.
+
+For example:
+
+> "Here's what I'll add to your store: **[name]** — **[price]**[, options: …]. Ready to create it?"
+
+If the user already signaled approval (e.g. "just create it", "go ahead"), treat that as the single confirmation and proceed straight to STEP 1 — do not ask again.
 
 ## STEP 1: create the product with options and variants