@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-manage/references/google-business-profile/manage-google-business-profile-locations.md

@@ -0,0 +1,182 @@
+---
+name: "Manage Google Business Profile Locations for a Wix Site"
+description: Import Google Business Profile locations into the authenticated Wix site, list and query them with or without live Google data, update Wix-side and Google-side details through the correct method for each, create a new Google listing, check whether a profile is actually live on Google, and remove a location from Wix or delete its Google listing. Checks the site's Google connection first and reports a missing one as a setup step, warns before destructive or Google-visible writes, and respects Google's shared rate budget.
+---
+
+# Manage Google Business Profile Locations for a Wix Site
+
+Use the public **Google Business Profile Locations API** to manage the
+authenticated Wix site's Business Profile locations — the entries that decide
+how the business appears on Google Search and Maps. The REST requests do not
+contain a site ID — the site comes from the caller's authorization context.
+Use the site the environment already supplies; if no site is selected, list
+the user's sites once and auto-select the only one, or ask the user to choose
+by site name when several are available. Never invent a site ID or ask the
+user to type one.
+
+> **Unconnected-site fast path — read first.** Read the connection once. Treat
+> `NEVER_CONNECTED`, `NEEDS_RECONNECT`, or a single
+> `CONNECTION_NOT_FOUND`/not-found response from that connection check as the
+> same setup state. Query Wix-only GBP locations once to answer what the site
+> already has, report the result, explain the connect → account selection →
+> unimported-location selection → bulk-create flow, and stop — after that one
+> query the **next action is the final response**, with no other tool call. Do
+> not call a Google-backed location method, probe for Business Profile
+> accounts, guess an endpoint, or make further API probes or documentation
+> searches until the connection is `VALID`. A `403` or `PERMISSION_DENIED` is
+> terminal: the **next action is the final response** explaining it. Stop
+> without the Wix-only query, documentation search, or any other tool call.
+
+The API is a live view onto Google, not a copy: most calls make a real Google
+request, with Google's latency and rate limits. A location's ID is Google's
+opaque location ID and is what identifies it everywhere.
+
+## Direct calls for the unconnected-site path
+
+Use these request shapes directly; do not search the API reference before
+calling them.
+
+| Method | Call |
+|---|---|
+| **Get Connection** | `GET https://www.wixapis.com/gbp/v1/connection` — no body or parameters |
+| **Query GBP Locations** | `POST https://www.wixapis.com/gbp/v1/locations/query` with body below |
+
+```json
+{ "query": { "paging": { "limit": 100 } } }
+```
+
+Make **Get Connection** first, then branch before making any other call:
+
+- `403` or `PERMISSION_DENIED` — stop. The next action is the final response;
+  explain that the current Wix identity cannot inspect the site's GBP state.
+  Do not query locations, inspect installed apps, search documentation, or try
+  another endpoint.
+- `NEVER_CONNECTED`, `NEEDS_RECONNECT`, or `CONNECTION_NOT_FOUND` — make one
+  **Query GBP Locations** call, report the Wix-stored result, explain the future
+  import steps, and stop. The next action is the final response.
+- `VALID` — proceed with the requested Google-backed flow.
+
+Do not call **List GBP Accounts** or another Google-backed method until the
+connection is `VALID` — account discovery requires the connection, and its
+request shape is not the locations query. Never guess an endpoint that is not
+in the table above or in the loaded reference.
+
+## Check the connection first
+
+Google-backed methods require a Google connection, established through the
+**Google Business Profile Connection API** (see the connect recipe). Before
+Google-backed work, call **Get Connection**:
+
+- `VALID` — proceed.
+- `NEVER_CONNECTED` or `NEEDS_RECONNECT` — report a setup step, not an error,
+  and offer to run the connect flow. Do not retry location calls until the
+  connection is `VALID`.
+
+Wix-only reads and deletes still work without active Google credentials:
+**Get GBP Location**, **Query GBP Locations**, **Update Location**,
+**Delete Location**, and **Bulk Delete Locations**.
+
+## Import locations
+
+Importing registers listings that already exist at Google; it never creates
+one. Each step narrows the next:
+
+1. Call **List GBP Accounts**. One Google login can hold several Business
+   Profile accounts, so present the list and let the owner pick — never assume
+   the first one.
+2. Call **List Unimported Locations** with the chosen `accountId`. It returns
+   only what the site hasn't imported yet, so re-running never offers
+   duplicates.
+3. Let the owner select which locations to import, and confirm before writing.
+4. Call **Bulk Create Locations** with the selected locations, supplying `id`
+   and `accountId` on each.
+5. Inspect every `results[].itemMetadata.error`. The call reports per-item
+   failures instead of aborting, so a `200` does not mean every location
+   imported. Report failures explicitly.
+
+Repeat steps 2–5 per account if the owner wants locations from more than one.
+
+## List and query locations
+
+Choose by whether live Google data is needed:
+
+- **Just the site's locations:** call **Query GBP Locations**. Wix-stored rows
+  only — fast, no Google round-trip, no Google rate limit. Use it for counts,
+  ID lookups, and anything driven by `id`, `googleLocationId`, or `accountId`.
+- **Locations with live business details:** call **Query Google Locations**
+  (or **Get Google Location** for one). Each row is hydrated with a live
+  Google fetch. Check each row for `googleError` — one location failing at
+  Google does not fail the request or break paging, so render it as a
+  per-location problem, not an empty result.
+
+## Update the correct side
+
+Wix stores almost nothing; the method name tells you which side a write
+reaches. Check before calling anything destructive:
+
+| Method | Wix row | Google listing |
+|---|---|---|
+| **Create Location**, **Bulk Create Locations** | created | untouched (imports an existing listing) |
+| **Create Google Location** | created | **created** |
+| **Update Location** | updated | untouched (writes Wix-stored fields only) |
+| **Update Google Location** | untouched | **updated** |
+| **Delete Location**, **Bulk Delete Locations** | deleted | untouched |
+| **Delete Google Location** | deleted | **deleted** |
+
+- **Update Location** is not the way to edit a Business Profile — it writes
+  only Wix-stored fields. To change Google-owned data (title, address, hours,
+  categories), call **Update Google Location**, and confirm with the owner
+  first: the change is publicly visible on Google.
+- To create a brand-new Google listing, call **Create Google Location** after
+  explicit confirmation. Use the API's reference-data methods (address schema,
+  category and region suggestions) rather than inventing values.
+- Google allows roughly 10 profile edits per minute per Business Profile, and
+  the budget is shared across every write method. Pace the profile as a whole
+  and treat a `429` as worth retrying after a delay, not as a rejection.
+
+## Remove a location
+
+Decide first whether the owner is removing it from Wix or deleting the real
+Google listing — these are different operations and one is irreversible.
+Confirm which they mean before calling anything:
+
+- **Un-import from Wix, leave Google alone:** call **Delete Location**, or
+  **Bulk Delete Locations** for several. Inspect every
+  `results[].itemMetadata` entry — the bulk call can partially succeed.
+- **Delete the Google listing as well:** call **Delete Google Location** once
+  per location; there is no bulk Google delete. Require explicit confirmation
+  naming the location — the listing disappears from Google Search and Maps.
+- If **Delete Google Location** returns `LOCATION_DB_PERSIST_FAILED`, Google
+  deleted the listing but Wix didn't record it. The error payload carries the
+  location ID; call **Delete Location** with it to reconcile.
+
+## Check whether a profile is actually live
+
+A location existing in Wix does not mean it appears on Google — verification
+can be pending, the profile suspended, or ownership contested. Call
+**Get Voice of Merchant** for the location and act on what Google reports:
+wait, verify, comply, or resolve the conflict.
+
+## Recovery rules
+
+- **`FAILED_PRECONDITION` with `CONNECTION_NOT_FOUND`:** the site has no
+  usable Google connection. Report the setup step and offer the connect flow;
+  do not retry the same call.
+- **`GOOGLE_API_CALL_FAILED`:** read the carried Google code and description.
+  Some failures are permanent (profile suspended, field not editable) —
+  retrying will not help; explain instead.
+- **Per-row `googleError` on hydrating reads:** report it per location and
+  continue with the rest of the page.
+- **Rate limited (`429`):** wait, then retry; interleaved writes share one
+  budget per profile.
+- **Permission denied:** stop after the first `403` or `PERMISSION_DENIED`.
+  Do not retry with other locations, request shapes, or sites, and do not
+  search for an alternate API or method. Deleting locations requires the
+  site's `GBP_ADMIN` role.
+
+The same API also covers reviews and replies, photos and bulk media uploads,
+attributes, verification, performance insights, and location admins — load the
+specific public method reference needed before constructing a request so field
+names, filters, permissions, and errors come from the live contract. Once a
+connection state or typed error selects a branch above, do not search or browse
+for an alternate API, method, or request shape.

package/skills/wix-manage/references/marketing/create-and-publish-social-post.md

@@ -359,6 +359,8 @@ Build the request from `item.channel` (`name` + the `accountId` from STEP 4b), `
 - Otherwise, build it from the STEP 3 table row for your channel + `type`: the text field (`caption` for Instagram/Facebook/LinkedIn/X, `description` for YouTube/Pinterest/GBP/TikTok), the media (`mediaWrapper`, or `imageUrl`/`videoUrl` for a single item), and any channel-specific IDs from the STEP 4b account object, plus `title` where the channel uses one.
 - Instagram and story types require media.
 
+**Attribution (always set this).** Set `item.consumerInfo` to `{ "name": "wix-skills-social" }` on **every** create-draft call, for every channel. `consumerInfo.name` identifies what created the post — the Social Media Marketing dashboard sets `social-marketing`, and this recipe sets `wix-skills-social`. Set it on the draft: `name` is applied on creation only, and Update Item ignores it.
+
 **Idempotency (retry safety).** Set a stable, caller-defined `item.referenceId` on the draft. The Publisher enforces its uniqueness — a second item created/published with the same `referenceId` is rejected with `REFERENCE_ID_ALREADY_EXIST` instead of posting a duplicate. So if a create or publish call times out, retry with the **same** `referenceId` rather than risk double-posting.
 
 **Example — Instagram image post:**
@@ -368,6 +370,7 @@ Build the request from `item.channel` (`name` + the `accountId` from STEP 4b), `
   "item": {
     "channel": { "name": "INSTAGRAM", "accountId": "17841405822304914" },
     "type": "POST",
+    "consumerInfo": { "name": "wix-skills-social" },
     "instagramPost": {
       "imageUrl": "https://static.wixstatic.com/media/cf2434_4b3a2d8eb7f54bc89c0d4524430a2af3~mv2.jpg",
       "caption": "Summer collection just dropped! Shop the look now. #summerstyle #newarrivals"

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/stores/create-product-catalog-v3.md

@@ -20,6 +20,19 @@ Canonical example:
 - 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.**
 
+## Sections
+
+- [Preflight](#preflight-respond-and-return-before-mutation) — whether this turn may mutate at all, and what to answer when it may not
+- [Core flow](#core-flow) — the order the rest of this recipe runs in
+- [Choose the endpoint](#choose-the-endpoint) — single vs bulk, with or without inventory
+- [Build each product](#build-each-product) — the product object: type, media, options, variants, prices, SKUs
+- [Generated descriptions and SEO](#generated-descriptions-and-seo) — what copy written from an image may claim
+- [Add images](#add-images) — uploading a supplied image, or generating one
+- [Wrap the request](#wrap-the-request) — the envelope the chosen endpoint expects
+- [Request projected media](#request-projected-media-when-validating-images) — which fields to project so images are proven on create
+- [Validate before reporting success](#validate-before-reporting-success) — what counts as proof, and what may be claimed
+- [Failure guide](#failure-guide) — reading a rejection
+
 ## 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.
@@ -65,14 +78,14 @@ If any product is missing a price, **do not call the API**. Ask for the missing
 - 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.
+- Digital products use a with-inventory endpoint: an unstocked digital variant is unsellable.
 - 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. |
+| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits them and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
 | 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. |
@@ -127,9 +140,20 @@ This inventory-aware physical product is the reusable shape. Remove `inventoryIt
 }
 ```
 
-For a color option, use `SWATCH_CHOICES`; each choice uses `choiceType: ONE_COLOR` and `colorCode`, and the variant reference uses `renderType: SWATCH_CHOICES`.
+For a color option, use `SWATCH_CHOICES`; each choice uses `choiceType: ONE_COLOR` and `colorCode`, and the variant reference uses `renderType: SWATCH_CHOICES`. For a different **image** per colour (not just the swatch), each choice also carries its own `media`:
+
+```json
+"choicesSettings": {"choices": [
+  {"choiceType": "ONE_COLOR", "name": "Black", "colorCode": "#000000",
+   "media": {"items": [{"url": "https://static.wixstatic.com/media/<black>.jpg"}]}},
+  {"choiceType": "ONE_COLOR", "name": "White", "colorCode": "#FFFFFF",
+   "media": {"items": [{"url": "https://static.wixstatic.com/media/<white>.jpg"}]}}
+]}
+```
 
-A digital product uses the smaller shape below. Add the supplied variant-level digital file only when one was provided.
+The image must be in the product gallery first, and the id/ordering has a trap — assign per-choice media via **[Update Product with Options](update-product-with-options.md) → Choice & variant fields** (also the full choice-vs-variant field split: choice `media`/`colorCode`; variant `price`/`sku`/`barcode`/stock).
+
+A digital variant is **sellable** only when it carries both a digital file and stock; miss either and the product reads back healthy and is rejected at add-to-cart. Upload the file first ([Upload Media to Wix](../media/upload-media-to-wix.md) → Generate Upload URL, then `PUT` the bytes) and send the returned `file.id` to `POST /stores/v3/products-with-inventory`:
 
 ```json
 {
@@ -138,11 +162,15 @@ A digital product uses the smaller shape below. Add the supplied variant-level d
   "variantsInfo": {"variants": [{
     "sku": "PDF-FOCUS-01",
     "price": {"actualPrice": {"amount": "9.99"}},
-    "visible": true
+    "visible": true,
+    "inventoryItem": {"inStock": true},
+    "digitalProperties": {"digitalFile": {"id": "<FILE_ID>"}}
   }]}
 }
 ```
 
+With no file supplied, create the product and report it as not sellable until one is attached — [Update Product with Options](update-product-with-options.md) → Attach a digital file.
+
 ### 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.
@@ -165,7 +193,9 @@ A digital product uses the smaller shape below. Add the supplied variant-level d
 
 ## 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`:
+Skip this step when no image was supplied — unless the user asked for one to be generated, in which case create it first with [Generate an Image with AI](../media/generate-image-with-ai.md) and continue below with the Media Manager file it returns. Do not offer generation unprompted, and never generate a substitute for a supplied image that failed to upload.
+
+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"}
@@ -270,4 +300,4 @@ Retry only failed transient items, not successful products. If a requested field
 - `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.
+- Digital product rejected at add-to-cart: `ITEM_NOT_FOUND_IN_CATALOG` means the variant has no `digitalProperties.digitalFile`; `exceeds available inventory` means it has no `inventoryItem.inStock`. Both read back as a healthy product.

package/skills/wix-manage/references/stores/update-product-with-options.md

@@ -275,6 +275,8 @@ curl -X POST "https://www.wixapis.com/stores/v3/bulk/inventory-items/create" \
 
 ### Update Media Only
 
+Sets the product-level gallery (`media.itemsInfo.items`). For an image shown per option choice (a swatch's photo), see **Per-choice media** below.
+
 ```bash
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   -H "Content-Type: application/json" \
@@ -297,6 +299,56 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
+### Choice & variant fields (what you can set)
+
+Send these inside the `options` / `variantsInfo.variants` arrays — **both arrays complete, in the
+same PATCH**, with the current `revision`, and **identity-preserving** (see *Update Options and
+Variants*): keep the option's `id` and every `choiceId`, or the ids are re-minted and the existing
+variants no longer resolve (`400 "Variant choice not found in product options"`). Each variant needs
+its `id`, its `choices` (by `optionChoiceIds` — or `optionChoiceNames`, see *Gotchas*) **and** a
+`price` — omitting price is `400 "price must not be empty"`.
+
+**Option choice** (`options[].choicesSettings.choices[]`):
+- `name`, `choiceType`, `colorCode` — the choice's identity and swatch colour.
+- `media` = `{ "items": [ { "mediaId" } | { "url" } ] }` — the product photos shown when this choice is picked. `url` is write-only; on read you get `mediaId` (request the `PRODUCT_CHOICES_MEDIA_REFERENCES` mask). Use `media`, **not** `linkedMedia` (a separate display-filter, returned empty when you read `media`).
+  - **Gallery-first; the id you link is the gallery item's, not the upload's.** Add the `url` to the gallery, then read the product back and link the id you see there:
+
+    ```
+    GET /stores/v3/products/{id}?fields=MEDIA_ITEMS_INFO
+    #  → media.itemsInfo.items[].id = "abc~mv2.jpg"   ← link THIS as choice media.items[].mediaId
+    # the id from POST /site-media/v1/files/import or /files/get-file-by-id 400s as a choice mediaId
+    ```
+    `{ "url" }` works in place of `{ "mediaId" }` too, but only once the image is already in the gallery.
+- `displayImage` — the image shown on the swatch itself (distinct from `media`).
+- Read-only, don't send: `inStock`, `visible`, `key`.
+
+**Variant** (`variantsInfo.variants[]`, by its `id` from Get Product; always send `choices` + `price` with it):
+- `price` = `{ "actualPrice": { "amount" }, "compareAtPrice": { "amount" } }` — set `compareAtPrice` above `actualPrice` for a strikethrough sale; omit it for full price.
+- `sku`, `barcode` — per combination.
+- `visible` — hide a single variant.
+- `revenueDetails` — cost / profit tracking.
+- Read-only, don't send: `media` (derived from the choices' media), `inventoryStatus` (stock — use the Inventory API, see *Set Stock for New Variants*), `subscriptionPricesInfo`.
+
+```bash
+# A choice image + a variant's sale price, one PATCH. Both arrays are complete and keep their ids —
+# this exact shape is the one that succeeds; the two shortcuts (choices by name only, or a variant
+# without its choices/price) each 400.
+curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
+  -H "Content-Type: application/json" -H "Authorization: <AUTH>" \
+  -d '{ "product": { "id": "{productId}", "revision": "{currentRevision}",
+        "options": [ { "id": "{optionId}", "name": "Color", "optionRenderType": "COLOR_CHOICES",
+          "choicesSettings": { "choices": [
+            { "choiceId": "{choiceId1}", "name": "Red", "choiceType": "ONE_COLOR", "colorCode": "#C0392B",
+              "media": { "items": [ { "mediaId": "abc~mv2.jpg" } ] } },
+            { "choiceId": "{choiceId2}", "name": "Blue", "choiceType": "ONE_COLOR", "colorCode": "#2C3E50" } ] } } ],
+        "variantsInfo": { "variants": [
+          { "id": "{variantId1}", "sku": "TEE-RED-L",
+            "price": { "actualPrice": { "amount": "20" }, "compareAtPrice": { "amount": "30" } },
+            "choices": [ { "optionChoiceIds": { "optionId": "{optionId}", "choiceId": "{choiceId1}" } } ] },
+          { "id": "{variantId2}", "price": { "actualPrice": { "amount": "20" } },
+            "choices": [ { "optionChoiceIds": { "optionId": "{optionId}", "choiceId": "{choiceId2}" } } ] } ] } } }'
+```
+
 ### Update Variant Price Only
 
 Read `{existingVariantId}` off the Get Product response; a Search or Query Products result does not carry it.
@@ -325,6 +377,35 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
+### Attach a Digital File
+
+A `DIGITAL` product is **sellable** only when its variant carries both a digital file and stock. Upload the file first ([Upload Media to Wix](../media/upload-media-to-wix.md) → Generate Upload URL, then `PUT` the bytes), then send its `file.id` on the variant — `digitalProperties` is a variant field, never a product field.
+
+```bash
+curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: <AUTH>" \
+  -d '{
+    "product": {
+      "id": "{productId}",
+      "revision": "{currentRevision}",
+      "variantsInfo": {
+        "variants": [
+          {
+            "id": "{existingVariantId}",
+            "price": { "actualPrice": { "amount": "9.99" } },
+            "visible": true,
+            "inventoryItem": { "inStock": true },
+            "digitalProperties": { "digitalFile": { "id": "{fileId}" } }
+          }
+        ]
+      }
+    }
+  }'
+```
+
+Confirm from `product.variantsInfo.variants[].digitalProperties.digitalFile` in the response.
+
 ## Important Notes
 
 - A request to hide a product is a `visible: false` update on the product, never a Delete Product call and never a variant-only change.
@@ -348,3 +429,5 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 | `variantsInfo is invalid: variants has size 0, expected 1 or more` | Variants were read from a Search or Query Products response, which does not return them | Re-read the product with Get Product and send its `variantsInfo.variants` |
 | `Missing option choices` or `INVALID_DEFAULT_VARIANT` | Product has options but at least one variant has no matching choices | Rebuild `variantsInfo.variants` so every variant includes choices for all product options |
 | `DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS` | Sent `visibleInPos: true` on a digital product | Digital products can't be visible in POS; leave `visibleInPos` out of the body |
+| `ITEM_NOT_FOUND_IN_CATALOG` at add-to-cart, product exists | A `DIGITAL` variant has no `digitalProperties.digitalFile` | Attach a file — see [Attach a Digital File](#attach-a-digital-file) |
+| `exceeds available inventory` at add-to-cart, product exists | The variant has no stock (`DIGITAL` products included) | Set `inventoryItem.inStock: true` on the variant |

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

@@ -1,6 +1,6 @@
 ---
 name: wix-vibe-headless
-description: "Client-only, dependency-free REST scaffolds for connecting an already-built front end (a vibe-coded app, an HTML/JSX/Vite project, a design-tool export) to a live Wix site over the site's public WIX_CLIENT_ID — the browser talks to Wix directly, no SDK, no backend, no build step. One skill covering every Wix business solution: Stores/eCommerce storefront (products, cart, checkout), Bookings (services, slots, appointments), Blog (posts, categories, tags), Events & Tickets (browse, RSVP, ticketing), Portfolio (collections, projects, galleries), Restaurants (menu, online ordering, reservations), CMS / Wix Data (list, detail, filter, forms, CRUD), Pricing Plans (memberships, subscriptions, checkout), and Members (custom login — email+password, Google/Facebook, and custom SSO — plus account areas and member-gated content). Each vertical ships a copy-as-is REST layer plus wiring instructions. Read-only over the owner's content — never provisions, never mocks data. Triggers: connect my Wix store/shop, build a storefront over Wix, add a cart and checkout, connect Wix Bookings, take appointments/reservations, show my Wix blog, list my Wix events, sell tickets, take RSVPs, build a portfolio from Wix Portfolio, show my restaurant menu / order online / book a table, display my Wix CMS collection, wire a contact form to Wix, sell membership/subscription plans, add member login / sign up, let members log in with Google or Facebook, custom login page, account / profile page, gate content behind login, sign in with SSO/Okta, 'here is my WIX_CLIENT_ID', connect this app to my Wix site over REST. Use this for CLIENT-ONLY REST integration over an existing site; use `wix-headless` instead for SDK + Wix CLI builds, hosting, and one-prompt new-site creation."
+description: "Client-only, dependency-free REST scaffolds for connecting an already-built front end (a vibe-coded app, an HTML/JSX/Vite project, a design-tool export) to a live Wix site over the site's public WIX_CLIENT_ID — the browser talks to Wix directly, no SDK, no backend, no build step. One skill covering every Wix business solution: Stores/eCommerce storefront (products, cart, checkout), Bookings (services, slots, appointments), Blog (posts, categories, tags), Events & Tickets (browse, RSVP, ticketing), Portfolio (collections, projects, galleries), Restaurants (menu, online ordering, reservations), Forms (any visitor-fillable form — contact/enquiry, signup, waitlist, application, survey, quote request; schema-driven render + submit), CMS / Wix Data (list, detail, filter, CRUD), Pricing Plans (memberships, subscriptions, checkout), and Members (custom login — email+password, Google/Facebook, and custom SSO — plus account areas and member-gated content). Each vertical ships a copy-as-is REST layer plus wiring instructions. Read-only over the owner's content — never provisions, never mocks data. Triggers: connect my Wix store/shop, build a storefront over Wix, add a cart and checkout, connect Wix Bookings, take appointments/reservations, show my Wix blog, list my Wix events, sell tickets, take RSVPs, build a portfolio from Wix Portfolio, show my restaurant menu / order online / book a table, display my Wix CMS collection, wire a contact form to Wix, add a contact/enquiry form, build a signup or application form, take survey responses, sell membership/subscription plans, add member login / sign up, let members log in with Google or Facebook, custom login page, account / profile page, gate content behind login, sign in with SSO/Okta, 'here is my WIX_CLIENT_ID', connect this app to my Wix site over REST. Use this for CLIENT-ONLY REST integration over an existing site; use `wix-headless` instead for SDK + Wix CLI builds, hosting, and one-prompt new-site creation."
 ---
 
 # Wix Vibe Headless — client-only REST connectors
@@ -119,15 +119,29 @@ Each vertical's UI + helpers ship in `references/<vertical>/app/`; copy that dir
 | The user wants… | Vertical | Read |
 |---|---|---|
 | Online store: products, categories, cart, checkout | **storefront** | `references/storefront/INSTRUCTIONS.md` |
-| Appointments: services, time slots, booking, checkout | **bookings** | `references/bookings/INSTRUCTIONS.md` |
+| Appointments: services, time slots, booking, checkout — **and the form attached to a bookable service** | **bookings** | `references/bookings/INSTRUCTIONS.md` |
+| Rentals: an item hired for a length **the customer picks** (by the hour or by the day) — Wix Rentals runs on the Bookings APIs, so it is the same vertical | **bookings** | `references/bookings/INSTRUCTIONS.md` ("Rentals") |
 | Blog/news: post feed, post pages, categories, tags | **blog** | `references/blog/INSTRUCTIONS.md` |
-| Events: browse, event page, RSVP, ticketing | **events** | `references/events/INSTRUCTIONS.md` |
+| Events: browse, event page, RSVP, ticketing — **an RSVP is here, not `forms`**, even for one occasion with no tickets | **events** | `references/events/INSTRUCTIONS.md` |
 | Portfolio/showcase: collections, projects, media galleries | **portfolio** | `references/portfolio/INSTRUCTIONS.md` |
 | Restaurant: menu, online ordering, table reservations | **restaurants** | `references/restaurants/INSTRUCTIONS.md` |
-| CMS content: list/detail, filter/search, forms, data CRUD | **cms** | `references/cms/INSTRUCTIONS.md` |
+| Any visitor-fillable form: contact/enquiry, lead, signup, waitlist, application, feedback/survey, quote request, intake or registration. **Not** an event RSVP (`events`) or a per-service booking form (`bookings`) | **forms** | `references/forms/INSTRUCTIONS.md` |
+| CMS content: list/detail, filter/search, data CRUD. **A visitor-fillable form is `forms`** — cms only when the app must read the entries back | **cms** | `references/cms/INSTRUCTIONS.md` |
 | Plans & pricing: memberships/subscriptions, subscribe, my plans | **pricing-plans** | `references/pricing-plans/INSTRUCTIONS.md` |
 | Member accounts: custom login/sign-up (email+password, Google/Facebook, SSO), account area, gated content | **members** | `references/members/INSTRUCTIONS.md` |
 
+**⚠️ Anything a visitor fills in and submits is `forms` — with three exceptions:**
+
+1. **The app must read the entries back → `cms`.** A public gallery, a listing, a member's "my
+   submissions". A visitor cannot read Forms submissions, so those need a collection. Submit-only is
+   always `forms`: a form wired to `insertDataItem` works, but gives up the dashboard form builder,
+   spam protection, submission notifications and CRM contact mapping, and needs the owner to set
+   collection permissions by hand before anyone can submit at all.
+2. **Confirming attendance to an event or occasion → `events`.** A wedding, party or gathering —
+   events ships a built-in RSVP registration form. Route there even for a single occasion with no
+   tickets.
+3. **A form attached to a bookable service → `bookings`.**
+
 ### When the request doesn't name a Wix Business Solution — ask, or check the site
 
 Don't infer which Wix Business Solution to build (stores, bookings, blog, events, portfolio,

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

@@ -1,6 +1,6 @@
 // Post-install deploy — run by base44.md STEP 1 with the vertical(s) the app needs:
 //   node deploy.cjs <vertical> [<vertical> …] --client-id <id> --metasite-id <id>
-//   (storefront | bookings | blog | cms | portfolio | pricing-plans | events | members)
+//   (storefront | bookings | blog | cms | forms | portfolio | pricing-plans | events | members | restaurants)
 // 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,
@@ -9,7 +9,7 @@
 // members and cms names both, and its CMS helpers then come from the skill instead of being
 // hand-written. Order matters only where two verticals ship a file at the SAME path (both have
 // components/…, pages/…): the first one listed wins, since the copy never overwrites. Verticals whose
-// file sets don't overlap (cms ships utils only, no UI) combine freely.
+// file sets don't overlap (cms and forms ship utils only, no UI) combine freely.
 // paths are the Base44 sandbox's /app. Re-running is non-destructive: it fills in only missing files,
 // never overwriting the agent's edits (see COPY), so a later call can add a vertical safely.
 // No vertical arg -> deploys just the shared transport; re-run with the vertical(s) once known.
@@ -19,7 +19,7 @@ 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'];
+const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'forms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants'];
 
 // force:false + errorOnExist:false — fill in only files that AREN'T there yet; never overwrite.
 // A re-run (e.g. the "files missing? re-run" fallback) then restores what's missing without
@@ -117,8 +117,16 @@ 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)))];
+// `rentals` is an alias of the Bookings vertical — Wix Rentals runs on the Bookings APIs. A rental
+// business picks `rentals` and gets the bookings scaffolds; it resolves to bookings everywhere.
+const ALIASES = { rentals: 'bookings' };
+const positional = argv.filter((a) => !flagArgs.has(a));
+const requested = [...new Set(positional.map((a) => ALIASES[a] || a))];
 const deployed = { verticals: [] };
+// Report any alias resolution so the caller sees an intended mapping (rentals -> bookings), not a
+// silent `bookings` result it might read as "rentals unsupported" and wastefully re-deploy.
+const aliased = [...new Set(positional.filter((a) => ALIASES[a]))].map((a) => `${a} -> ${ALIASES[a]}`);
+if (aliased.length) deployed.aliased = aliased;
 
 // Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/).
 if (existsSync(`${REF}/shared/app`)) cpSync(`${REF}/shared/app`, '/app/src', COPY);

package/skills/wix-vibe-headless/install/pin-agents-md.cjs

@@ -18,7 +18,8 @@ The Wix skills live under \`.agents/skills/\` — on ANY turn, read them from th
   - **storefront** — sell physical or digital products online.
   - **bookings** — let customers book appointments or services with your business.
   - **blog** — publish articles for visitors to read.
-  - **cms** — model and serve your own custom, structured content — for anything the other verticals don't cover.
+  - **forms** — any visitor-fillable form: contact/enquiry, lead, signup, waitlist, application, feedback/survey, quote request, intake or registration. **Not forms** — an event or occasion RSVP is **events** (built-in RSVP registration form), and a per-service booking form is **bookings**.
+  - **cms** — model and serve your own custom, structured content — for anything the other verticals don't cover. **Not cms** — a visitor-fillable form is **forms**; reach for cms only when the app must read the entries back.
   - **portfolio** — showcase creative work in collections and project pages.
   - **pricing-plans** — sell memberships or subscriptions to your service.
   - **events** — publish events and handle RSVPs or ticket sales.

package/skills/wix-vibe-headless/platforms/base44-ecom-light-seed.md

@@ -87,7 +87,9 @@ urls are ready by the time you seed.
 
 ## STEP 4 — Wrap up
 
-**Do NOT add the `<WixManageBanner/>` component** and do not send the user Wix dashboard links — this flow does not include the manage banner or back-office handoff.
+**Do NOT add the `<WixManageBanner/>` component** and never paste a Wix dashboard link or path.
+
+**Hand off with one call, before you write anything** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. It comes back telling you what to say; add only that the catalog you seeded is mock data they can edit, replace or delete.
 
 **Preview briefly, don't chase images.** Broken images are expected — `generate_image` returns a `/__generating__/…` placeholder that the platform swaps for the final url automatically at turn end (failures get a stock fallback). **Do NOT edit or debug image urls.** Leave them and finish.
 

package/skills/wix-vibe-headless/platforms/base44-ecom-light.md

@@ -56,7 +56,9 @@ rejects the write. Wire routes/imports in with `find_replace`, leave the rest as
 
 **No seeding in this flow** — the client is the only deliverable. Do not seed, populate, or write data to Wix.
 
-**Do NOT add the `<WixManageBanner/>` component** and do not send the user Wix dashboard links — this flow does not include the manage banner or back-office handoff.
+**Do NOT add the `<WixManageBanner/>` component** and never paste a Wix dashboard link or path.
+
+**Hand off with one call, before you write anything** — `search_base44_docs(query="how do I manage my store's products, orders and inventory?", prefer_dashboard=true)`. It comes back telling you what to say.
 
 **Preview briefly, don't chase images.** Broken images are expected — `generate_image` returns a `/__generating__/…` placeholder that the platform swaps for the final url automatically at turn end (failures get a stock fallback). **Do NOT edit or debug image urls.** Leave them and finish.