@wix/agent-skills 1.16.0 → 1.16.2

package/skills/wix-manage/references/sites/read-site-context.md

@@ -0,0 +1,125 @@
+---
+name: "Read Account or Site Context"
+description: Probe a Wix site or account for full context in one call — installed apps by display name, locale, currency, timezone, and status. Account token + siteId targets one site; account token alone returns up to 10; site-scoped token alone returns the site it is scoped to.
+---
+# Read Account or Site Context
+
+Returns a site's name, URL, status, locale/region, and all installed apps with human-readable display names.
+
+---
+
+## Markdown endpoint (recommended)
+
+**Endpoint**: `POST https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown`
+
+Returns `{ "markdown": "..." }`.
+
+### Account token + siteId — one specific site
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{"siteId": "<metaSiteId>"}'
+```
+
+Response:
+
+```
+## 1. Acme Store
+
+**ID**: `<metaSiteId>`
+**URL**: [https://example.wixsite.com/acme](https://example.wixsite.com/acme)
+**Status**: Published
+**Editor Type**: Editorless
+**Created**: Aug 14, 2026, 05:21 · **Updated**: Aug 17, 2026, 20:44
+**Velo**: Enabled
+
+### Properties
+
+**Locale & Region**
+- Language: **en**
+- Country: **US**
+- Timezone: **America/New_York**
+- Currency: **USD**
+
+### Apps
+
+- **Wix Stores** (ID: `215238eb-22a5-4c36-9e7b-e7c08025e04e`) — Catalog app version: **V3**
+- **Wix Bookings** (ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
+- **Wix Blog** (ID: `14bcded7-0066-7c35-14d7-466cb3f09103`)
+```
+
+### Without siteId
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context/markdown' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+- **Account token**: returns up to 10 sites. If the account has more: `_Showing 10 sites (more available)_` — call again with a specific `siteId`.
+- **Site-scoped token** (e.g. the Wix connector in Base44): returns the one site the token is scoped to.
+
+---
+
+## JSON endpoint
+
+**Endpoint**: `POST https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context`
+
+Same request shape. `installedApps` contains raw `appId` UUIDs — extract only what you need:
+
+```javascript
+const res = await fetch(
+  "https://www.wixapis.com/_api/dynamic-context/v1/dynamic-context",
+  {
+    method: "POST",
+    headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ siteId: metaSiteId }),
+  }
+);
+const { sites } = await res.json();
+const site = sites[0];
+
+const KNOWN_APPS = {
+  stores:       "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+  bookings:     "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
+  blog:         "14bcded7-0066-7c35-14d7-466cb3f09103",
+  events:       "140603ad-af8d-84a5-2c80-a0f60cb47351",
+  pricingPlans: "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3",
+  restaurants:  "13e8d036-5516-6f75-e025-2aca3b5d7930",
+};
+
+const appById = Object.fromEntries(
+  (site.installedApps ?? []).map((a) => [a.appId, a])
+);
+
+const context = {
+  id:              site.id,
+  name:            site.displayName,
+  url:             site.url,
+  currency:        site.properties?.paymentCurrency,
+  locale:          `${site.properties?.locale?.languageCode}-${site.properties?.locale?.country}`,
+  timezone:        site.properties?.timeZone,
+  hasStores:       !!appById[KNOWN_APPS.stores],
+  storesCatalogV:  appById[KNOWN_APPS.stores]?.catalogVersion ?? null, // "V3" | "V1" | null
+  hasBookings:     !!appById[KNOWN_APPS.bookings],
+  hasBlog:         !!appById[KNOWN_APPS.blog],
+  hasEvents:       !!appById[KNOWN_APPS.events],
+  hasPricingPlans: !!appById[KNOWN_APPS.pricingPlans],
+  hasRestaurants:  !!appById[KNOWN_APPS.restaurants],
+};
+```
+
+---
+
+## API Reference
+
+- [Get Dynamic Context — markdown](https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context-markdown)
+- [Get Dynamic Context — JSON](https://dev.wix.com/docs/api-reference/tools/dynamic-site-context/get-dynamic-context)
+- [Query Sites](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites) — for paginating or filtering the full site list
+- [Get Installed Apps](https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps) — raw app instances with fields not in the context snapshot
+- [Get Site Properties](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties) — full properties including business description, address, social links

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

@@ -1,6 +1,6 @@
 ---
 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.
+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, or to import from CSV/TSV export files with no source site. 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
@@ -54,7 +54,20 @@ Example — Start:
 
 ```
 POST https://www.wixapis.com/site-import/v1/imports
-Body: { "request": "Import https://example-store.com into a new Wix site" }
+Body: {
+  "request": "Import https://example-store.com into a new Wix site",
+  "source_url": "https://example-store.com"
+}
+```
+
+Example — Start from exported files (no source site, FILE run):
+
+```
+POST https://www.wixapis.com/site-import/v1/imports
+Body: {
+  "request": "Import these product export files into a new Wix site",
+  "fileUrls": ["https://example.com/exports/products.csv"]
+}
 ```
 
 Example — Poll:
@@ -96,7 +109,8 @@ and act only on the user's explicit yes.
 
 This creates real infrastructure and writes to the user's Wix account. Before
 calling **Start**, confirm:
-- The source URL and platform are correct
+- The source URL and platform are correct — or, for a file-only import, the
+  export file URL(s) 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.
@@ -107,7 +121,7 @@ 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.
+  ids, or `sourcePlatform`/`sourceConfidence`/`destinationSiteId` 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)".
@@ -148,12 +162,37 @@ You are the user experience; the API is plumbing. Keep the protocol invisible:
 **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.
+   Body: `{"request": "<natural language; MUST include the source store URL when crawling a live site>", "source_url": "<the source store URL>", "fileUrls": ["<CSV/TSV export URL>", ...]}`
+   `request` is required (1–20000 chars). `source_url` and `fileUrls` are both
+   optional, but send whichever applies — never leave both out with no way to
+   identify what to import:
+   - **`source_url`** — send it whenever the user names a site to crawl. It's
+     the identity the service uses to select which migration the request joins,
+     not just an extra hint.
+   - **`fileUrls`** — send it when the user has CSV/TSV export file(s) to import
+     instead of crawling a live site. Setting it makes this a **FILE run**: no
+     source site is probed and no source credentials are requested, even if
+     `source_url` is also present — `source_url` only changes what the
+     migration is keyed on (see below), it does not add a crawl on top of the
+     file import. Up to 20 URLs, http/https only (ports 80/443), each ≤2048
+     chars. If `source_url` is absent, the file set itself is the migration
+     identity — re-sending the same URLs continues the same migration; a
+     different set starts a new one. If a URL isn't reachable, the whole call
+     is rejected with `INVALID_FILE_URL` (nothing is silently dropped).
+   - A request with neither `source_url` nor a URL/site identifiable in
+     `request`, and no `fileUrls`, is rejected with `SITE_UNIDENTIFIED`.
+   Returns: `importId`, `sourcePlatform`, `sourceConfidence`, `destinationSiteId`.
+   `sourcePlatform` comes back as `CSV` for a FILE run (no site was probed, so
+   `sourceConfidence` is meaningless there). `destinationSiteId` is the id of
+   the Wix site being imported into — returned as soon as Start succeeds,
+   even before a source is confirmed.
+   **One import per store at a time, keyed on `source_url`** (or the file set
+   when there's no `source_url`): re-starting with the same identity continues
+   the SAME migration (server returns the existing `importId`, no new import
+   created). A different identity always starts an independent migration, even
+   for the same user. If a different user on the account already owns an
+   import for that identity, 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
@@ -230,13 +269,26 @@ the user has no way to open a file.
 - 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.
+- **Site Import is in limited rollout, with no self-service enablement path.**
+  If Start returns `404` or `403` with `"code": "NOT_ENABLED"`, tell the user
+  plainly that site import isn't available on their account yet — then stop.
+  **Do not tell them to "contact Wix support"**: this API is unlisted and
+  ALPHA, Wix Support has no visibility into it or way to grant access, and the
+  public "importing a site created outside of Wix" help-center article is an
+  unrelated, long-stalled feature-request page — sending a user to either is a
+  dead end. If a Wix feedback tool is available in your environment, you may
+  offer to send feedback noting their interest; that is the only channel that
+  reaches the team. 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).
+  required field is missing (`request`/`message` must be 1–20000 chars),
+  `source_url` exceeds 2048 chars, or `fileUrls` has more than 20 entries or
+  one over 2048 chars. A request with no identifiable site (no `source_url`
+  and no URL in `request`) and no `fileUrls` is rejected with
+  `SITE_UNIDENTIFIED` — ask the user for the store URL or export file(s) and
+  retry. A `fileUrls` entry that isn't a reachable http/https URL rejects the
+  whole call with `INVALID_FILE_URL` — tell the user which link failed and ask
+  for a working one.
 - 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,

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

@@ -0,0 +1,273 @@
+---
+name: "Create Product (Catalog V3)"
+description: Mandatory first recipe for every Wix Stores Catalog V3 create-product request. Before any mutation, require an explicit name and price for every product; an absent price is never 0. If no product is identified, offer both image-upload and text-description paths and stop. If name or price is missing, ask or offer a suggestion and stop. When both are present, create from the supplied details without requiring optional enrichment. Covers single/bulk creation, inventory, physical/digital products, images, options, variants, SKUs, and validation.
+---
+
+# Create Product (Catalog V3)
+
+Use this recipe for one or multiple Catalog V3 products. Catalog V1 remains supported through [Create Product (Catalog V1)](create-product-catalog-v1.md).
+
+> [!IMPORTANT]
+> **Apply the no-product gate first.** A vague request such as “I’d like to add a new product” does not identify a product. Respond only:
+>
+> **“What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.”**
+>
+> Then end the turn. Do not ask for name, price, product type, options, SEO, inventory, or any other structured field yet. Do not replace the image-or-text choice with a checklist, form, or questionnaire. Reading this recipe must be the final tool call in that turn.
+
+Canonical example:
+
+- User: “For my Wix store, I’d like to add a new product.”
+- Assistant: “What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.”
+- Result: **Stop. Do not request structured product fields yet.**
+
+## Preflight: respond and return before mutation
+
+Name and price are mandatory **workflow inputs for every product**, even when the API schema accepts an omitted price or initializes it to zero. Evaluate the cases below in order. When a case says **RETURN**, end the turn immediately: do not call a create endpoint, do not continue to examples, and do not create first and ask afterward.
+
+1. **No product identified:** Respond only: “What product would you like to create? You can upload up to 3 images and I’ll generate the product information from them, or describe the product in text.” **RETURN.** Do not replace the two paths with a form, checklist, questionnaire, text-only prompt, or requests for name, price, type, options, SEO, or inventory.
+2. **Any product lacks an explicit name or price:** Ask for all missing mandatory values in one question and offer to suggest them. When only price is missing, respond only: “What price should I set for [product name]? I can suggest one if you’d like.” **RETURN.**
+3. **Every name and price is known:** Creation may continue. Options, variations, description, SEO, info sections, type, SKU, inventory, and images are optional. Use them when supplied or requested; do not ask the user to resolve them before creation.
+
+“Create it,” “create it now,” “for my store, create,” or similar mutation language does not satisfy a missing price. A usable price must be either explicitly supplied by the user or a suggestion the user accepted. Treat `0` as supplied only when the user explicitly requests a free or zero-priced product.
+
+Before every create call, assert both conditions:
+
+- Every product has a non-empty name from the user or an accepted suggestion.
+- Every variant has a price from the user or an accepted suggestion; no price came from an API default, placeholder, example, or assumption.
+
+If any product is missing a price, **do not call the API**. Ask for the missing price, using the product's supplied name when available, and offer to suggest one. Never put `"amount": "0"` in the request unless the user explicitly chose a zero price.
+
+## Core flow
+
+1. Apply the preflight. When it says **RETURN**, make no API call in that turn.
+2. Send site-scoped calls with `Authorization`, `wix-site-id`, and `Content-Type: application/json`.
+3. If the catalog version is unknown, run:
+
+   ```bash
+   curl --request GET \
+     --url 'https://www.wixapis.com/stores/v3/provision/version' \
+     --header 'Authorization: <AUTH>' \
+     --header 'wix-site-id: <SITE_ID>' \
+     --header 'Content-Type: application/json'
+   ```
+
+   Continue here only for `V3_CATALOG`; use the V1 recipe for `V1_CATALOG`.
+4. Resolve each product's supplied type, variants, SKUs, inventory intent, and images after its mandatory name and variant price are known. Do not invent optional attributes the user did not supply or request.
+5. Choose the endpoint, build the products, upload any images, create, and validate every result. Continue until all requested products succeed or report the exact failed items.
+
+## Choose the endpoint
+
+| Request | No inventory | Quantity or in-stock state |
+|---|---|---|
+| One product | `POST /stores/v3/products` | `POST /stores/v3/products-with-inventory` |
+| Multiple products | `POST /stores/v3/bulk/products/create` | `POST /stores/v3/bulk/products-with-inventory/create` |
+
+- Bulk endpoints accept 1–100 products, so a compatible bulk endpoint is also valid for one product.
+- For multiple products requested as one batch, send one bulk call. Use the with-inventory endpoint when any product needs inventory; include `inventoryItem` only on tracked variants.
+- Never send `inventoryItem` to a no-inventory endpoint. Do not invent inventory.
+- Digital products normally use a no-inventory endpoint.
+- Per bulk request, allow at most 100 products, 100 total options, 100 modifiers, 100 info sections, and 1000 variants. Split larger input into compliant batches.
+
+## Build each product
+
+| Concern | Rule |
+|---|---|
+| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits physical properties and inventory. |
+| Variants | Include at least one. Price, SKU, barcode, inventory, and digital file are variant-level fields. |
+| Price | Use a string in `price.actualPrice.amount`; add `compareAtPrice` only when supplied. |
+| SKU | Preserve supplied strings exactly, including `#`, punctuation, and leading zeroes. Keep variant SKUs unique unless explicitly requested otherwise. |
+| Options | Define non-empty choices and create every requested Cartesian combination. Each variant references one choice from every option through `optionChoiceNames`. |
+| Text | Prefer `plainDescription` for unformatted copy. Use `description` only for a valid Ricos document. |
+| Media | Up to 3 images are supported per product. Preserve their supplied order in `media.itemsInfo.items`; `media.main` is read-only. |
+
+This inventory-aware physical product is the reusable shape. Remove `inventoryItem` when using a no-inventory endpoint; remove `media` when no image was supplied.
+
+```json
+{
+  "name": "Canvas Tee",
+  "productType": "PHYSICAL",
+  "physicalProperties": {},
+  "media": {"itemsInfo": {"items": [{
+    "url": "https://static.wixstatic.com/media/example.jpg",
+    "altText": "Canvas Tee"
+  }]}},
+  "options": [{
+    "name": "Size",
+    "optionRenderType": "TEXT_CHOICES",
+    "choicesSettings": {"choices": [
+      {"choiceType": "CHOICE_TEXT", "name": "Small"},
+      {"choiceType": "CHOICE_TEXT", "name": "Large"}
+    ]}
+  }],
+  "variantsInfo": {"variants": [
+    {
+      "choices": [{"optionChoiceNames": {
+        "optionName": "Size", "choiceName": "Small", "renderType": "TEXT_CHOICES"
+      }}],
+      "sku": "TEE-001-S",
+      "price": {
+        "actualPrice": {"amount": "18.50"},
+        "compareAtPrice": {"amount": "22.00"}
+      },
+      "inventoryItem": {"quantity": 13},
+      "physicalProperties": {},
+      "visible": true
+    },
+    {
+      "choices": [{"optionChoiceNames": {
+        "optionName": "Size", "choiceName": "Large", "renderType": "TEXT_CHOICES"
+      }}],
+      "sku": "TEE-001-L",
+      "price": {"actualPrice": {"amount": "18.50"}},
+      "inventoryItem": {"inStock": true},
+      "physicalProperties": {},
+      "visible": true
+    }
+  ]}
+}
+```
+
+For a color option, use `SWATCH_CHOICES`; each choice uses `choiceType: ONE_COLOR` and `colorCode`, and the variant reference uses `renderType: SWATCH_CHOICES`.
+
+A digital product uses the smaller shape below. Add the supplied variant-level digital file only when one was provided.
+
+```json
+{
+  "name": "Focus Planner PDF",
+  "productType": "DIGITAL",
+  "variantsInfo": {"variants": [{
+    "sku": "PDF-FOCUS-01",
+    "price": {"actualPrice": {"amount": "9.99"}},
+    "visible": true
+  }]}
+}
+```
+
+### Generated descriptions and SEO
+
+- When copy is generated from an image, every factual claim must be user-supplied or directly visible. Preserve user-supplied facts such as a stated material; do not reject them merely because the image alone cannot prove them. Color, shape, and visible decoration may come from the image. Dimensions, capacity, care instructions, durability, compatibility, performance, and any material the user did not identify must be omitted. For example, never write “dishwasher safe” or “microwave safe” unless the user supplied that fact. Omit uncertain claims instead of turning them into marketing language.
+- Use `plainDescription` unless formatting is required. SEO tags use `seoData.tags`.
+- For formatted bullets, the Ricos node is `BULLETED_LIST`, not `BULLET_LIST`, and its data field is `bulletedListData`:
+
+```json
+{
+  "description": {"nodes": [{
+    "type": "BULLETED_LIST",
+    "nodes": [{"type": "LIST_ITEM", "nodes": [{
+      "type": "PARAGRAPH",
+      "nodes": [{"type": "TEXT", "textData": {"text": "Visible blue glaze"}}],
+      "paragraphData": {}
+    }]}],
+    "bulletedListData": {}
+  }]}
+}
+```
+
+## Add images
+
+Skip this step when no image was supplied. Prefer the available dedicated Wix image-upload capability and upload all attachments and public image URLs together. Do not reconstruct that capability inside a general API-execution call. When no dedicated uploader is available, use `POST /site-media/v1/files/import` with the external URL in the body field named exactly `url`—not `importUrl`:
+
+```json
+{"url":"https://example.com/product.jpg","mimeType":"image/jpeg","displayName":"Product.jpg","mediaType":"IMAGE"}
+```
+
+A successful upload that returns the matching `wixstatic.com` URL may be used in product media while asynchronous processing is `PENDING`; do not treat `PENDING` alone as a failure. Stop if the upload reports `FAILED`. Poll `GET /site-media/v1/files/get-file-by-id?fileId=<FILE_ID>` until `file.operationStatus` is `READY` only when the workflow needs guaranteed processing, image metadata, transformations, or independent proof that the asset is ready. A pending URL proves submission, not completed processing, so do not describe it as ready or fully verified unless a later response proves that. Do not use a thumbnail URL or reuse the original external URL after upload.
+
+Track every upload as its own product-to-file record. A poll or timeout fallback may return only that file's URL—never another product's URL. If an upload fails, retry the same asset through another supported transfer method when possible; never silently replace it with a different image. If the exact asset cannot be preserved, create only products whose requested images uploaded successfully and report every blocked product and failed source exactly; for a single required-image product, make no product-create call.
+
+## Wrap the request
+
+Use the chosen product object directly in either envelope:
+
+```json
+{"product": PRODUCT}
+```
+
+```json
+{"products": [PRODUCT_1, PRODUCT_2], "returnEntity": true}
+```
+
+The first is for single endpoints; the second is for bulk endpoints. If the user supplies only a SKU pattern for variants, generate a stable unique SKU per combination and preserve the mapping in the result.
+
+For one product when the user supplied no quantity, stock state, or inventory-tracking request, the complete direct path is `POST /stores/v3/products` with `{"product": PRODUCT}`. Do not infer `inStock: true`, add `inventoryItem`, or choose `/products-with-inventory`; physical product type does not imply inventory. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to the same no-inventory request.
+
+For one physical product with inventory, the complete direct path is one `POST /stores/v3/products-with-inventory` call with `{"product": PRODUCT}`. Put `inventoryItem` on its priced variant. If it has ready images, add `"fields": ["MEDIA_ITEMS_INFO"]` to that same request. The product shape, envelope, endpoint, and validation paths are complete here: do not search another recipe or schema, probe an alternate endpoint, or make a post-create read unless the projected create response does not prove requested media.
+
+### Request projected media when validating images
+
+`media.itemsInfo.items` is a projected response field. Creating a product with media does not guarantee that the create response—or an ordinary Get Product call—returns the gallery. To receive it, pass `"MEDIA_ITEMS_INFO"` in the request-level `fields` array.
+
+For a single create with images:
+
+```json
+{"product": PRODUCT_WITH_MEDIA, "fields": ["MEDIA_ITEMS_INFO"]}
+```
+
+For a bulk create with images:
+
+```json
+{
+  "products": [PRODUCT_1, PRODUCT_2],
+  "returnEntity": true,
+  "fields": ["MEDIA_ITEMS_INFO"]
+}
+```
+
+If the create result still does not prove the stored gallery, make at most one read-only verification call:
+
+```http
+GET /stores/v3/products/<PRODUCT_ID>?fields=MEDIA_ITEMS_INFO
+```
+
+Inspect `product.media.itemsInfo.items` from that projected response. Do not interpret an omitted `itemsInfo` as lost media, search the Update Product schema, or PATCH the same media merely to retrieve it. A PATCH is appropriate only when a projected response proves the stored media is actually wrong.
+
+## Validate before reporting success
+
+| Endpoint result | Required checks |
+|---|---|
+| Single, no inventory | Require `product.id`; report only response-backed fields as verified. For images, request `MEDIA_ITEMS_INFO` on create or use one projected Get Product verification call. |
+| Single, with inventory | Require `product.id`; inspect `inventoryResults.results`, item metadata, and top-level error. |
+| Bulk, no inventory | Inspect every `results[].itemMetadata`; with `returnEntity: true`, the created entity is `results[].item`, not `results[].product`. Reconcile `bulkActionMetadata.totalSuccesses` and `totalFailures` with the requested count. |
+| Bulk, with inventory | Use the exact two-sibling response paths below. Inspect every product and inventory result, both bulk metadata objects, item metadata, and the inventory error before reporting success. |
+
+`POST /stores/v3/bulk/products-with-inventory/create` does **not** return the same flat envelope as `/stores/v3/bulk/products/create`. Its response has two top-level sibling objects:
+
+```json
+{
+  "productResults": {
+    "results": [{"itemMetadata": {}, "item": {}}],
+    "bulkActionMetadata": {}
+  },
+  "inventoryResults": {
+    "results": [{"itemMetadata": {}, "item": {}}],
+    "bulkActionMetadata": {},
+    "error": null
+  }
+}
+```
+
+Before claiming that an inventory-aware bulk create succeeded:
+
+1. Inspect every `productResults.results[]` entry and require `itemMetadata.success`; with `returnEntity: true`, read the product from `item`.
+2. Reconcile `productResults.bulkActionMetadata.totalSuccesses`, `totalFailures`, and `undetailedFailures` with the requested product count.
+3. Separately inspect every top-level `inventoryResults.results[]` entry and require `itemMetadata.success`; with `returnEntity: true`, read the inventory entity from `item`.
+4. Reconcile `inventoryResults.bulkActionMetadata.totalSuccesses`, `totalFailures`, and `undetailedFailures` with the expected inventory-item count, and inspect `inventoryResults.error`.
+
+The inventory error check is mandatory even when every item and metadata count succeeded. Explicitly read the sibling field—for example, normalize `inventoryResults.error ?? null`—and report success only when it is absent or null. Do not infer that value from HTTP 200, item metadata, or bulk metadata.
+
+For `POST /stores/v3/products-with-inventory`, inspect the returned `product.id`, every `inventoryResults.results[].itemMetadata`, and top-level `inventoryResults.error` directly from the create response. Do not issue inventory queries, product searches, Get Product calls, or PATCH calls merely to reconfirm values already proven by that response. If item success proves the inventory write but the response omits the requested quantity, report the quantity as submitted; if the user needs it independently verified, make one targeted inventory read using the returned product ID without first fetching the product again. The only other allowed extra read is the single projected media verification described above when requested images are not present in the projected create result. GET and HEAD requests must not include a request body.
+
+Never read `productResults.inventoryResults`: that path does not exist. A successful product result or HTTP 200 does not prove inventory creation succeeded.
+
+Retry only failed transient items, not successful products. If a requested field is absent from the response, call it submitted rather than API-verified; never echo the request as proof that it was stored.
+
+`product.visible: true` proves catalog visibility, not that an unpublished site is live. Say “created” or “visible in the catalog”; say “live” only when site publication is independently confirmed.
+
+## Failure guide
+
+- Inventory missing: use the with-inventory endpoint and include `inventoryItem` on each tracked variant.
+- Multiple requested products sent separately: use one compatible bulk call unless they cannot form a compliant batch or specific failed items are being retried.
+- `variantsInfo must not be empty`: include at least one priced variant per product.
+- Option/variant mismatch: create every requested combination and reference every option once per variant.
+- Media not visible: use the uploaded `wixstatic.com` URL in `media.itemsInfo.items`; do not set `media.main`.
+- Digital product rejected: omit physical properties and inventory; keep price, SKU, and any supplied digital file on the variant.

package/skills/wix-replatform/resources/rp-target-wix/lib/wix-writers.js

@@ -324,7 +324,7 @@ function applySafeModeToRequestBody(body, safeModeOptions) {
 // media import, Contacts manage/schema, and Members manage.
 //
 // Auth scheme normalization: Wix API keys (`IST.…`) are sent RAW in the Authorization
-// header; OAuth access tokens (e.g. a Wix CLI token from `npx @wix/cli token --site …`)
+// header; OAuth access tokens (e.g. a Wix CLI token from `npx @wix/cli@latest token --site …`)
 // must be sent as `Bearer <token>`. Detect and prefix so both credential kinds work.
 function authHeaderValue(token) {
   const t = String(token).trim();

package/skills/wix-vibe-headless/SKILL.md

@@ -149,7 +149,8 @@ installed, not what the business is about. Never default to store/bookings on si
    `INSTRUCTIONS.md`.
 3. **Ensure the vertical's files are in place** — copy `references/<vertical>/app/` and
    `references/shared/app/` into the app's `src/`, and set `WIX_CLIENT_ID` in `wix-config.js`. (Where
-   and how they get there is your platform's call — see its instructions.)
+   and how they get there is your platform's call — see its instructions. On base44 the install step
+   writes and verifies `wix-config.js` for you, so there's nothing to set by hand.)
 4. **Wire the shipped client** following the vertical's INSTRUCTIONS: the components are themed by
    base44's design tokens (`src/index.css` — shadcn palette, already set by the design phase), so
    there's no re-skin step; just wire routes + header/footer through the Layout. The UI ships as

package/skills/wix-vibe-headless/install/deploy.cjs

@@ -1,6 +1,8 @@
 // Post-install deploy — run by base44.md STEP 1 with the vertical(s) the app needs:
-//   node deploy.cjs <vertical> [<vertical> …]
+//   node deploy.cjs <vertical> [<vertical> …] --client-id <id> --metasite-id <id>
 //   (storefront | bookings | blog | cms | portfolio | pricing-plans | events | members)
+// Pass the two ids from the prompt and this writes src/rest/wix-config.js for you — see WRITE below.
+// Retyping those ids into the file by hand is how a storefront ships with a dead client id.
 // ONE mechanism: recursively copy `app/` -> /app/src. The shared transport (app/rest/wix-client.js,
 // wix-config.js) is copied always; then each named vertical's app/ (its UI + app/rest/ helpers).
 // Deploy every vertical the app actually uses, in one call or across several — an app that needs both
@@ -13,9 +15,10 @@
 // No vertical arg -> deploys just the shared transport; re-run with the vertical(s) once known.
 // NOTE: .cjs on purpose — the app is an ESM package ("type":"module"); a .js here would load as ESM
 // and require()/module.exports would throw.
-const { existsSync, cpSync, readFileSync } = require('fs');
+const { existsSync, cpSync, readFileSync, writeFileSync } = require('fs');
 
 const REF = '/app/.agents/skills/wix-vibe-headless/references';
+const WIX_CONFIG = '/app/src/rest/wix-config.js';
 const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants'];
 
 // force:false + errorOnExist:false — fill in only files that AREN'T there yet; never overwrite.
@@ -66,11 +69,55 @@ function replaceMembersAuthLeftovers() {
   return result;
 }
 
+// --- WRITE the credentials ----------------------------------------------------------------------
+//
+// The two ids arrive as flags so this script writes them once, character-for-character, instead of a
+// later hand-edit of the placeholder file.
+//
+// An id already in the file wins; the flags only fill what is unset. A host that writes this file
+// at app creation (Base44) has each id as an exact value rather than a copy read out of a prompt.
+// Per id, so a host that resolved one but not the other still gets the gap filled.
+//
+// This briefly worked the other way round for WIX_METASITE_ID, while Base44 could write a different
+// site than the business: it shared one field between the launch and a metasite it provisions per
+// app, and the launch's id lost. Fixed on that side, and the ids it stores now verify against the
+// site each launch came from, so the file is trusted again.
+function readWixConfig() {
+  if (!existsSync(WIX_CONFIG)) return {};
+  const src = readFileSync(WIX_CONFIG, 'utf8');
+  const pick = (name) => {
+    const v = (src.match(new RegExp(`${name}\\s*=\\s*["']([^"']*)["']`)) || [])[1] || '';
+    return v.startsWith('<') ? '' : v;   // the shipped file's `<YOUR-…>` placeholders count as unset
+  };
+  return { clientId: pick('WIX_CLIENT_ID'), metaSiteId: pick('WIX_METASITE_ID') };
+}
+
+function writeWixConfig(clientId, metaSiteId) {
+  const body = [
+    '// Wix credentials — written by the skill\'s deploy step from the ids in your prompt.',
+    '// Safe to commit: WIX_CLIENT_ID is a public, buyer-facing id (it only mints anonymous visitor',
+    '// tokens); WIX_METASITE_ID just identifies the site.',
+    `export const WIX_CLIENT_ID = "${clientId}";`,
+    `export const WIX_METASITE_ID = "${metaSiteId}";`,
+    '',
+  ].join('\n');
+  writeFileSync(WIX_CONFIG, body);
+}
+
 // --- main ---------------------------------------------------------------------------------------
 
 // Accept one or many: `deploy.cjs members cms`. Duplicates collapse; order is preserved so the
 // first vertical listed wins any same-path file (the copy never overwrites).
-const requested = [...new Set(process.argv.slice(2))];
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : null;
+};
+const clientId = flag('client-id');
+const metaSiteId = flag('metasite-id');
+// Verticals are the positional args — drop the flags and their values.
+const flagArgs = new Set(['--client-id', '--metasite-id', clientId, metaSiteId].filter(Boolean));
+const requested = [...new Set(argv.filter((a) => !flagArgs.has(a)))];
 const deployed = { verticals: [] };
 
 // Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/).
@@ -92,4 +139,17 @@ if (!requested.length) {
   deployed.note = 'no vertical given — deployed the shared transport only; re-run: node deploy.cjs <vertical> [<vertical> …]';
 }
 
+const onDisk = readWixConfig();
+const finalClientId = onDisk.clientId || clientId;
+const finalMetaSiteId = onDisk.metaSiteId || metaSiteId;
+
+if (!finalClientId || !finalMetaSiteId) {
+  deployed.wixConfig = 'skipped — no ids provided';
+} else if (finalClientId === onDisk.clientId && finalMetaSiteId === onDisk.metaSiteId) {
+  deployed.wixConfig = 'already_set';
+} else {
+  writeWixConfig(finalClientId, finalMetaSiteId);
+  deployed.wixConfig = 'written';
+}
+
 console.log(JSON.stringify(deployed));