@wix/agent-skills 1.27.0 → 1.29.0

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md

@@ -8,7 +8,7 @@ description: "SEASONAL sub-flow — load [Goal: Seasonal Revenue] FIRST (it owns
 >
 > This flow is a sub-step, not a direct entry point. If you have not yet called `ReadFullDocsArticle` on [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) in this conversation, **stop and load it now**. The goal skill owns the SEASONAL classification rule, the time-window presentation requirement, and the priority rule that gates access to this flow.
 >
-> **Before executing this flow**, also read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity).
+> **Before executing this flow**, also read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-plausibility).
 
 Creates event-driven promotional discounts tied to holidays, shopping events, or seasonal milestones. The flow identifies upcoming events based on the site's country and current date, calculates optimal campaign start/end windows, and targets event-relevant product categories with appropriately sized discounts.
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-stock-mover.md

@@ -6,7 +6,7 @@ description: "Stock-mover clearance sub-flow — load [Goal: Clear Inventory] FI
 
 > **Routing rule (READ FIRST).** This recipe is a sub-step of [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory). If you arrived here directly from the WixREADME index, load the goal recipe NOW before executing — it owns the velocity scoring, classification cues, and the per-recommendation presentation rules (including the **margin-floor guardrail** surfacing requirement).
 >
-> **Then** read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity).
+> **Then** read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-plausibility).
 
 Creates a discount targeting slow-moving inventory — products with high stock levels and low sales velocity. The discount depth is proportional to how overstocked the product is, with deeper discounts for the most stagnant items. Margin protection guardrails are especially important here since clearance discounts tend to push closer to cost.
 
@@ -99,7 +99,7 @@ If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs.
 
 ## Step 6: Run guardrail checks
 
-**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule** (conflict/stacking, %-sanity, margin floor). Clearance is the **most margin-sensitive** case: discounts push closest to cost, so the margin-floor check (effective margin ≥ 15% unless the merchant overrides) is the one most likely to fire here — verify it per candidate product.
+**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule** (conflict/stacking, %-plausibility, margin floor). Clearance is the **most margin-sensitive** case: discounts push closest to cost, so the margin-floor check (effective margin ≥ 15% unless the merchant overrides) is the one most likely to fire here — verify it per candidate product.
 
 ---
 

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-flow-upsell-boost.md

@@ -4,7 +4,7 @@ description: "UPSELL_BOOST sub-flow — load [Goal: Increase AOV] FIRST (it owns
 ---
 # Flow: Upsell Boost Campaign
 
-> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-sanity).
+> **Before executing this skill**, read [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) with `ReadFullDocsArticle` — it contains the discount-rule mechanics **and** the pre-create guardrails (conflict/stacking, margin floor, %-plausibility).
 
 Creates a discount that incentivizes customers to spend more per order by setting a minimum subtotal threshold above the store's current AOV. The discount percentage is scaled to the store's average profit margin, and the scope targets high-margin categories or products.
 
@@ -29,7 +29,7 @@ Catalog analytics and product data are already in conversation context — do NO
 - `siteData.aov` — site-level AOV (revenue / ordersCount). Loaded by eCommerce Load Context.
 
 Extract from context:
-- `effective_aov` — use `siteData.aov`; run AOV sanity check: if AOV < price_p25, override with price_p50 as effective AOV
+- `effective_aov` — use `siteData.aov`; run AOV plausibility check: if AOV < price_p25, override with price_p50 as effective AOV
 - `avg_profit_margin` — from the "All Products" group in `siteData.catalogAnalytics`
 - `price_p50`, `price_p75`, `price_p90` — from quantiles in `siteData.catalogAnalytics`
 - Top products by price and order volume — from `siteData.productCatalogData`
@@ -90,7 +90,7 @@ Max 3 categoryIds per discount rule.
 
 ## Step 6: Run guardrail checks
 
-**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule** — conflict/stacking (scope, time, coupon cross-stacking), the 25% cap, the 15% margin floor, and %-sanity. Present any warnings to the merchant and get confirmation before proceeding.
+**Run the pre-create guardrails in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails" before creating the rule** — conflict/stacking (scope, time, coupon cross-stacking), the 25% cap, the 15% margin floor, and %-plausibility. Present any warnings to the merchant and get confirmation before proceeding.
 
 ---
 

package/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-free-shipping.md

@@ -8,7 +8,7 @@ description: Creates a free shipping option with an AOV-calibrated threshold to
 
 > **Before executing this skill**, read [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-rates) with `ReadFullDocsArticle` for the rate-object mechanics.
 
-## Rate pricing sanity (inline guardrail)
+## Rate pricing plausibility (inline guardrail)
 
 Validate every rate you create or update against the store's AOV; flag any that fail:
 
@@ -101,7 +101,7 @@ If the threshold needs adjustment, update the shipping option via PATCH (see Ste
 
 ---
 
-## Step 3: Run AOV sanity check
+## Step 3: Run AOV plausibility check
 
 Before calculating a threshold, validate that AOV is reliable by comparing it against catalog price distribution.
 
@@ -263,7 +263,7 @@ Report to the merchant:
 | `deliveryRegionId is not a valid GUID` | Used `deliveryRegionIds` (plural) instead of `deliveryRegionId` (singular) | Use the singular `deliveryRegionId` field |
 | `SHIPPING_OPTION_NOT_FOUND` | Option ID doesn't exist when trying to update | Re-query shipping options to get current IDs |
 | `REVISION_MISMATCH` | Revision doesn't match the current version when updating | Re-fetch the option for the latest revision, then retry |
-| Threshold seems unreasonable | AOV data is unreliable (too few orders, data anomaly) | Run the AOV sanity check (Step 3) and use `effective_aov` instead of raw AOV |
+| Threshold seems unreasonable | AOV data is unreliable (too few orders, data anomaly) | Run the AOV plausibility check (Step 3) and use `effective_aov` instead of raw AOV |
 | Free shipping not visible at checkout | Region linked to the option has `active=false` | Check region active status and activate if intended |
 
 ## References

package/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-optimize-rates.md

@@ -6,7 +6,7 @@ description: Analyzes catalog price distribution and current rate structure to r
 
 > **Routing rule:** BEFORE taking any action, call `ReadFullDocsArticle` on [Shipping API Reference](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference). The Query Shipping Options and Update/Create Shipping Option endpoints used in Steps 2–4 live there. Do NOT query or modify any shipping options without loading it first.
 
-## Rate pricing sanity (inline guardrail)
+## Rate pricing plausibility (inline guardrail)
 
 Validate every rate you create or update against the store's AOV; flag any that fail:
 

package/skills/wix-manage/references/ecommerce/shipping/ecom-shipping-setup-rates.md

@@ -1,10 +1,10 @@
 ---
 name: "Shipping: Set Up Rates"
-description: Configures shipping option rates — rate types (flat, tiered, free), condition types and operators, free shipping threshold calibration, AOV sanity check, per-item penalty avoidance, and tier gap detection.
+description: Configures shipping option rates — rate types (flat, tiered, free), condition types and operators, free shipping threshold calibration, AOV plausibility check, per-item penalty avoidance, and tier gap detection.
 ---
 # Shipping Rates
 
-## AOV Sanity Check
+## AOV Plausibility Check
 
 **MANDATORY before any threshold calculation that references AOV.** Raw AOV can be misleading due to data issues or bulk purchases.
 
@@ -80,6 +80,6 @@ When ALL of the following are true, flat rate is optimal and no change is needed
 
 Sort all conditions by value and look for gaps between ranges. Gaps mean some cart totals have no matching rate, which can cause checkout failures.
 
-## Shipping Cost Sanity Check
+## Shipping Cost Plausibility Check
 
 Any rate `amount > AOV x 0.15` (15% of average order value) should be flagged as a cart abandonment risk.

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -16,7 +16,7 @@ Five ways to get the files live; what you have decides which are open to you.
 | Option | Needs | Carries | The user ends up with |
 | --- | --- | --- | --- |
 | **A.** `curl` + CLI token → [into the account](#publish-into-the-users-account) | A shell; a Wix CLI login | Anything on disk | A site in their account, final URL |
-| **B.** `ExecuteWixAPI` → [into the account](#publish-into-the-users-account) | The Wix MCP | Small text files already in the conversation | A site in their account, final URL |
+| **B.** `ExecuteWixAPI` → [into the account](#publish-into-the-users-account) | The Wix MCP | Files already in the conversation — text as is, small binaries as base64 — and anything downloaded from the site | A site in their account, final URL |
 | **C.** `curl` → [anonymous](#publish-anonymously) | A shell | Anything on disk | A live site for one hour; kept by a [claim](#claim-it-into-the-users-account) (through the Wix MCP or a CLI token) or the save link |
 | **D.** [The drop page](#the-drop-page) | Nothing | Whatever the user uploads | The same, after they upload it themselves |
 | **E.** [The headless skill](#keep-building-add-a-backend-when-you-need-one) | A shell; Node; a Wix CLI login | A project folder, source included (built for you) | A site in their account as a Wix Headless project, released with the Wix CLI, ready for Wix Business Solutions |
@@ -30,8 +30,13 @@ What sets them apart:
   byte is written out inside the call. That costs nothing extra for a page you
   generated or the user pasted (it's already in the conversation); for files on
   disk it means reading them in and writing them back out, and each change
-  resends all of it. A string body is sent as UTF-8, so binary files (PNG, JPG,
-  fonts, zips) arrive corrupted; link images by absolute URL.
+  resends all of it. Files travel in the tool's `files` param — text raw, a
+  binary file (PNG, JPG, fonts) as base64 — and `wix.multipart()` builds the
+  upload body (below). Base64 costs about a third more than the file and every
+  byte is tokens, so it suits small assets (an icon, a logo, a font) and files
+  you downloaded from the site to change; a photo goes in by absolute URL
+  (`<img src="https://…">`) or with `curl` from a shell. The bundle is capped at
+  4M characters.
 - **A CLI login** is one approval by the user in the browser: run
   `npx @wix/cli login` and have them approve; `npx @wix/cli token` then prints a
   token (see [Before the calls](#before-the-calls)). It also unlocks later
@@ -43,8 +48,8 @@ What sets them apart:
   the only one that takes framework source as is and leaves a project ready for a
   backend. A drop site can still move to it [later](#keep-building-add-a-backend-when-you-need-one).
 
-So: a small page already in the conversation, with the Wix MCP connected — B,
-shell or not. Static files on disk — A with a CLI login, else C (claimed through
+So: a site already in the conversation — pages, styles, a logo — with the Wix
+MCP connected — B, shell or not. Static files on disk — A with a CLI login, else C (claimed through
 the Wix MCP when it's connected). A framework project (a `package.json`), or a
 site that needs stores, bookings, a CMS or members from the start — E. Files out
 of your reach, or nothing above fits — D.
@@ -108,8 +113,27 @@ curl -sS -X POST \
   "siteUrl": "https://headless-zjfqzddjtww-northwind-1406.wix-site-host.com" }
 ```
 
-Option B — the same two calls as one `ExecuteWixAPI` script, for small text files
-already in the conversation:
+Option B — the same two calls as one `ExecuteWixAPI` script, for files already
+in the conversation. The files go in the tool's **`files` param**, not in
+`code`: one bundle, each file introduced by a line `=== FILE: <path> ===` and
+followed by its raw text, `<path>` relative to the site root. A binary file is
+introduced by `=== FILE: <path> base64 ===` and followed by its base64. Nothing
+in it is escaped, so quotes, backticks, `${}` and backslashes arrive as written.
+
+```
+=== FILE: index.html ===
+<!doctype html><html><head><title>Northwind Studio</title>
+<link rel="stylesheet" href="assets/styles.css"></head><body><h1>Northwind Studio</h1><img src="assets/logo.png"></body></html>
+=== FILE: assets/styles.css ===
+body { font-family: sans-serif; margin: 0; padding: 4rem; }
+=== FILE: assets/logo.png base64 ===
+iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==
+```
+
+In `code`, the bundle is the `files` global (`[{ path, content, encoding? }]`,
+`encoding: 'base64'` on the binary entries) and `wix.multipart()` turns it into
+the upload body: one part named `files` per file, the path as its filename, a
+content type guessed from the extension, base64 entries decoded to their bytes.
 
 ```javascript
 async function run() {
@@ -117,31 +141,21 @@ async function run() {
     url: 'https://www.wixapis.com/headless-business-setup/v1/headless-business/provision',
     body: { origin: 'drop', newMetasite: { namingStrategy: { metaSiteName: 'Northwind Studio' }, seedOptions: [] },
             synchronousSteps: ['SET_METASITE_NAME', 'CONFIGURE_HEADLESS_APP'] } });
-  // path → text content, as template literals. Escape \ as \\ first, then ` as \` and ${ as \${
-  // (an unescaped \ is dropped or reinterpreted: /\d+/ would arrive as /d+/).
-  const files = {
-    'index.html': `<!doctype html><html><head><title>Northwind Studio</title>
-<link rel="stylesheet" href="assets/styles.css"></head><body><h1>Northwind Studio</h1></body></html>`,
-    'assets/styles.css': `body { font-family: sans-serif; margin: 0; padding: 4rem; }`,
-  };
-  const boundary = '----wixdropboundary';
-  const body = Object.entries(files).flatMap(([path, text]) => [
-    '--' + boundary,
-    `Content-Disposition: form-data; name="files"; filename="${path}"`,
-    '', text,
-  ]).concat('--' + boundary + '--', '').join('\r\n');
+  const mp = wix.multipart();                                   // the `files` param; or pass [{ path, content | base64 | bytes }]
   return await wix.request({ scope: 'account', method: 'POST',
     url: `https://www.wixapis.com/headless-business-setup/v1/headless-business/${created.data.metaSiteId}/drop`,
-    headers: { 'Content-Type': 'multipart/form-data; boundary=' + boundary },
-    body });                                                          // a string body is sent verbatim
+    headers: { 'Content-Type': mp.contentType },
+    body: mp.body });
 }
 ```
 
 `wix.request` returns `{ status, data }`; read a response's fields from `data`
-(`created.data.metaSiteId`). Keep the body's shape exactly. It's a string; an
-object is sent as JSON and rejected. Lines end in `\r\n`, the body ends with
-`--<boundary>--`, and the header names the same boundary the body uses. Break any of these and the drop
-fails with a bare `500`.
+(`created.data.metaSiteId`). Don't build the multipart body by hand — a missing
+`\r\n` or a boundary mismatch is a bare `500` — and don't put file text inside
+`code` as string literals: that second layer of escaping is what corrupts
+backslashes and `${}`. Don't put image bytes in `code` either — they're a
+`base64` entry in `files`. The one thing `files` cannot carry is a file with a
+line that reads exactly `=== FILE: … ===`.
 
 `siteUrl` is the site's final address — it's already in the user's account. Give
 the user two links: `siteUrl`, and its dashboard at
@@ -169,24 +183,28 @@ unzip -o current.zip -d current      # the site's files + wix.config.json
 ```
 
 In an `ExecuteWixAPI` script, request the same URL with `responseType: 'base64'`
-and read the zip in memory. Entries are stored (method 0) or deflated (method 8):
+and unzip it in memory with `wix.unzip()`. Each entry is `{ path, bytes, text() }`:
+`bytes` is the file as stored, `text()` decodes it when it's text. Don't decode
+every entry — an image run through a text decoder is corrupted.
 
 ```javascript
 const r = await wix.request({ scope: 'account', method: 'GET', responseType: 'base64',
   url: `https://www.wix.com/_api/wixstro-deployments/v1/instant-sites/${metaSiteId}/download.zip` });
-const z = Uint8Array.from(atob(r.data), (c) => c.charCodeAt(0));
-const u16 = (o) => z[o] | (z[o + 1] << 8), u32 = (o) => (u16(o) | (u16(o + 2) << 16)) >>> 0;
-let e = z.length - 22; while (u32(e) !== 0x06054b50) e--;            // end of central directory
-const files = {};
-for (let i = 0, p = u32(e + 16); i < u16(e + 10); i++) {            // one central-directory entry each
-  const name = new TextDecoder().decode(z.slice(p + 46, p + 46 + u16(p + 28)));
-  const at = u32(p + 42), start = at + 30 + u16(at + 26) + u16(at + 28);
-  const raw = z.slice(start, start + u32(p + 20));
-  files[name] = u16(p + 10) === 0 ? new TextDecoder().decode(raw)
-    : await new Response(new Blob([raw]).stream().pipeThrough(new DecompressionStream('deflate-raw'))).text();
-  p += 46 + u16(p + 28) + u16(p + 30) + u16(p + 32);
-}
-// files: { 'index.html': '…', 'assets/styles.css': '…', 'wix.config.json': '…' }
+const entries = await wix.unzip(r.data);
+// entries: [{ path: 'index.html', bytes, text() }, { path: 'assets/logo.png', bytes, text() }, { path: 'wix.config.json', … }]
+```
+
+Edit in memory — text through `text()`, binaries left as they are — then drop
+the full set back in the same script, leaving `wix.config.json` out. Entries go
+to `wix.multipart()` as they are; an edited file replaces its entry with
+`{ path, content }`:
+
+```javascript
+const edited = entries.filter((e) => e.path !== 'wix.config.json').map((e) =>
+  e.path === 'index.html' ? { path: e.path, content: e.text().replace('Northwind Studio', 'Northwind Studio — Est. 1998') } : e);
+const mp = wix.multipart(edited);
+await wix.request({ scope: 'account', method: 'POST', headers: { 'Content-Type': mp.contentType }, body: mp.body,
+  url: `https://www.wixapis.com/headless-business-setup/v1/headless-business/${metaSiteId}/drop` });
 ```
 
 The live URL itself (`*.wix-site-host.com`) can't be read from a script; this
@@ -219,7 +237,8 @@ Keep both: `metaSiteId` addresses the site, `projectId` builds the save link.
 ### 2. Upload the files
 
 Same multipart shape as the [drop](#2-drop-the-files--the-site-goes-live), to the
-upload path, with the attribution parameters:
+upload path, with the attribution parameters (in a script: `wix.multipart()` with
+the `files` param, posted to this URL):
 
 ```bash
 curl -sS -X POST \
@@ -323,7 +342,7 @@ Failures come back as HTTP 400 with a code in `details.applicationError.code`:
 - **`403 PERMISSION_DENIED` on a drop** — the token expired or is missing (see
   [Before the calls](#before-the-calls)), or the site isn't the caller's. A site
   that's still anonymous is changed by upload + release, not by a drop.
-- **`500` on a drop or upload** — the multipart body is malformed (see the shape
+- **`500` on a drop or upload** — the multipart body was built by hand and is malformed (see the shape
   above). Rebuild it from the example; sending it again unchanged fails the
   same way.
 - **`404` on the anonymous route after step 1** — the hour passed or the site was

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

@@ -1624,7 +1624,7 @@ function normalizeV5Contact(contact = {}) {
   return normalized;
 }
 // Legacy V4-style `info` payloads (pre-GA generated transforms) convert through this
-// STRICT whitelist: unknown keys throw instead of silently dropping source data.
+// STRICT allowlist: unknown keys throw instead of silently dropping source data.
 // `extendedFields` and `labelKeys` throw because they have no mechanical V5 equivalent —
 // V5 custom fields live under extendedFields.namespaces (Data Extension Schema) and
 // labels became tags (Tags API); both need a setup-time decision, not a converter guess.

package/skills/wix-vibe-headless/references/restaurants/seed/seed-restaurants.cjs

@@ -326,7 +326,7 @@ async function enableOnlineReservations(ctx, reservationLocationId, revision) {
 }
 
 // ══ EXPERIENCES (setup-restaurant-experiences.md) ══════════════════════════════════════════════════
-// An experience is a reservation that IS a curated dining occasion (wine tasting, chef's table). Feature
+// An experience is a reservation that IS a curated dining occasion (chef's table, tasting menu). Feature
 // of the Table Reservations app — no separate install. Created against a reservationLocationId (from
 // listReservationLocations). The full create payload lives in the live docs (fields evolve) — build each
 // `experience` from the Create-Experience doc; this only wires the loop. Set configuration.visible:true.