@wix/agent-skills 1.12.0 → 1.14.0

package/skills/wix-manage/references/ecommerce/{goal-clear-inventory.md → pricing-promotions/ecom-pricing-goal-clear-inventory.md}

@@ -1,22 +1,16 @@
 ---
 name: "Goal: Clear Inventory"
-description: Maps the STOCK_MOVER business goal to inventory turnover KPIs and clearance discount flows.
-layer: goal
-references:
-  - name: "Flow: Stock Mover"
-    path: ecommerce/flow-stock-mover.md
-    load: true
-  - name: "Guardrail: Margin Protection"
-    path: ecommerce/guardrail-margin-protection.md
-    load: false
+description: STOCK_MOVER clearance goal — always load BEFORE recommending any clearance / overstock / slow-stock / dead-inventory action.
 ---
 # Goal: Clear Slow-Moving Inventory
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Flow: Stock Mover](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-stock-mover)
+> **Routing rule (READ FIRST).** Any merchant query about clearing slow / overstocked / dead / stagnant inventory MUST load this recipe before any other clearance recipe. Do NOT route directly to [Flow: Stock Mover](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-stock-mover) from the WixREADME index — this goal owns the velocity scoring, discount tiers, **margin-floor guardrail**, and the per-recommendation presentation rules. The flow is a sub-step.
 >
-> **Related skills** (read with `ReadFullDocsArticle` if needed):
-> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection)
+> ⛔ **MANDATORY — call this NOW before any API call or recommendation generation:**
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-stock-mover")
+> ```
+> The guardrail is also enforced in [Pricing: Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails".
 
 Automate clearance discounts for products with high stock levels and low sales velocity, converting stagnant inventory into revenue before it becomes a carrying cost liability.
 
@@ -79,6 +73,21 @@ The sole action for this goal. Identifies slow-moving products using the velocit
 
 ---
 
+## Presentation requirement — surface the margin guardrail
+
+**Every clearance recommendation presented to the merchant MUST explicitly reference the margin-floor guardrail in its `reasoning` / `why` field.** Clearance discounts push closest to cost, so the merchant needs to see — per item — that the discount stays above the floor.
+
+Acceptable phrasings:
+- "Discount keeps effective margin ≥ 15% (minMarginPct floor)."
+- "Stays above breakeven — current margin {X}%, post-discount {Y}%, floor 15%."
+- "Margin protected: this discount does NOT push below the 15% floor on `{product}`."
+
+If a candidate item would violate the floor at the velocity-tier discount, **either** lower the discount to stay above the floor and say so, **or** drop the item and note "skipped — would breach margin floor."
+
+Do NOT present a clearance recommendation that omits margin language. Urgency / stock level / "why this %" are not substitutes — the guardrail line is required.
+
+---
+
 ## Measurement Plan
 
 ### Before campaign launch

package/skills/wix-manage/references/ecommerce/{goal-drive-cross-sells.md → pricing-promotions/ecom-pricing-goal-drive-cross-sells.md}

@@ -1,16 +1,16 @@
 ---
 name: "Goal: Drive Cross-Sells"
-description: Maps the BUNDLE_AND_SAVE business goal to multi-item purchase KPIs and bundling flows.
-layer: goal
-references:
-  - name: "Flow: Bundle and Save"
-    path: ecommerce/flow-bundle-and-save.md
-    load: true
+description: BUNDLE_AND_SAVE goal — always load BEFORE recommending bundling / cross-sell / multi-item / "buy together" actions.
 ---
 # Goal: Drive Cross-Sells and Product Discovery
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save)
+> **Routing rule (READ FIRST).** Any merchant query about cross-sells, bundling, "buy together", multi-item purchases, or items-per-order MUST load this recipe before any flow-* recipe. Do NOT route directly to [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save) from the WixREADME index — this goal owns the catalog-profile→bundle-shape matrix and the **per-recommendation multi-item-structure requirement** (every recommendation MUST use `minItemQuantity` or an equivalent multi-item condition — plain single-item percent-off recommendations FAIL this goal). The flow is a sub-step.
+>
+> ⛔ **MANDATORY — call this NOW before any API call or recommendation generation:**
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save")
+> ```
+> The flow defines the required discount-rule mechanics (minItemQuantity condition, catalog data steps, guardrails). Without it, your recommendations will lack the correct structure.
 
 Promote product discovery and multi-item purchases by creating bundle-based discounts that reward customers for buying across categories or adding complementary items to their cart.
 
@@ -81,6 +81,24 @@ The sole action for this goal. Creates a percentage discount with a `minItemQuan
 
 ---
 
+## Presentation requirement — every recommendation MUST carry a multi-item condition
+
+**Every cross-sell recommendation presented to the merchant MUST use a `minItemQuantity` (or equivalent multi-item) condition** — plain single-item percentage discounts FAIL this goal's intent. The merchant must be able to see, per recommendation, the quantity threshold that triggers the discount and the scope it applies to.
+
+Acceptable shapes:
+- `apply_discount` with `conditions.minItemQuantity: 2` (or 3, 4) scoped to a category or specific products
+- "Buy 2+ accessories, save 15%" — minItemQuantity 2 on the accessories category
+- "Buy any 3 items, save 10%" — minItemQuantity 3 site-wide
+- "Buy these 2 together, save 15%" — minItemQuantity 2 on ITEMS scope with specific productIds
+
+NOT acceptable for this goal:
+- "20% off accessories" — no quantity threshold, defeats the cross-sell mechanic
+- "Site-wide 10% off" — no multi-item incentive
+
+State the quantity threshold and scope per recommendation in the `reasoning` / `why` field (e.g., "Buy 3+ items → 10% off site-wide; targets the multi-category catalog profile"). If you cannot construct a multi-item condition for a candidate, drop it; never present a plain percent-off as a cross-sell recommendation.
+
+---
+
 ## Measurement Plan
 
 ### Before campaign launch

package/skills/wix-manage/references/ecommerce/{goal-increase-aov.md → pricing-promotions/ecom-pricing-goal-increase-aov.md}

@@ -1,36 +1,25 @@
 ---
 name: "Goal: Increase AOV"
-description: Maps the UPSELL_BOOST business goal to measurable KPIs and actionable discount flows. Covers AOV benchmarking, margin-based discount tiers, and minSubTotal strategy.
-layer: goal
-references:
-  - name: "Flow: Upsell Boost"
-    path: ecommerce/flow-upsell-boost.md
-    load: true
-  - name: "Flow: Bundle and Save"
-    path: ecommerce/flow-bundle-and-save.md
-    load: true
-  - name: "Flow: Add Free Shipping"
-    path: ecommerce/flow-add-free-shipping.md
-    load: false
-  - name: "Flow: Optimize Shipping Rates"
-    path: ecommerce/flow-optimize-shipping-rates.md
-    load: false
-  - name: "Guardrail: Margin Protection"
-    path: ecommerce/guardrail-margin-protection.md
-    load: false
+description: UPSELL_BOOST goal — always load BEFORE recommending AOV / upsell / "boost my sales" / shipping-threshold actions. Owns the cross-domain lever map (discount + shipping + bundle) for open-ended sales prompts.
 ---
 # Goal: Increase Average Order Value
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Flow: Upsell Boost](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-upsell-boost)
-> - [Flow: Bundle and Save](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save)
+> **Routing rule (READ FIRST).** Any merchant query about increasing AOV, upselling, "boosting sales", or open-ended "help my business" prompts MUST load this recipe before any flow-* recipe. Do NOT route directly to [Flow: Upsell Boost](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-upsell-boost) from the WixREADME index — this goal owns the cross-domain lever map (discount + shipping + bundle), the catalog→lever-selection rules, and the per-recommendation **multi-lever mix requirement** that an open "boost sales" prompt must satisfy. The flows are sub-steps.
+>
+> ⛔ **MANDATORY — call these NOW before any API call or recommendation generation:**
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-upsell-boost")
+> ```
+> If the request covers bundle/cross-sell intent too:
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-bundle-and-save")
+> ```
 >
 > **Shipping flows that also serve AOV goals** (load if shipping domain is active):
-> - [Flow: Add Free Shipping](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-add-free-shipping) — free shipping threshold pushes carts above AOV
-> - [Flow: Optimize Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-optimize-shipping-rates) — rate optimization improves conversion on higher-value orders
+> - [Flow: Add Free Shipping](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-add-free-shipping) — free shipping threshold pushes carts above AOV
+> - [Flow: Optimize Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — rate optimization improves conversion on higher-value orders
 >
-> **Related skills** (read with `ReadFullDocsArticle` if needed):
-> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection)
+> The margin/cap guardrails are enforced in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails".
 
 Incentivize customers to spend above the store's current average order value (AOV) by creating threshold-based discounts that reward higher cart totals.
 
@@ -96,6 +85,24 @@ A complementary action that increases AOV by encouraging multi-item purchases. I
 
 ---
 
+## Presentation requirement — open prompts demand a multi-lever mix
+
+When the merchant's query is open-ended (e.g., "boost my sales", "help my business", "give me 3 to 5 actions"), the recommendation set **MUST mix at least two of the following lever types** — never propose an all-discount set:
+
+| Lever type | Example action |
+|---|---|
+| Discount rule (auto-apply) | `apply_discount` with `minSubTotal` above AOV |
+| Coupon | code-gated discount for subscribers / influencers |
+| Free-shipping / shipping change | `create_shipping_option` with AOV-calibrated threshold |
+| Bundle / `minItemQuantity` rule | multi-item discount targeting cross-sell categories |
+| `minSubTotal` / AOV-threshold rule | spend-based discount above current AOV |
+
+State the lever type per recommendation in the `reasoning` / `why` field (e.g., "Lever: free-shipping threshold — pushes carts above current AOV $X"). A recommendation set containing only `apply_discount` actions FAILS the UPSELL_BOOST goal's open-prompt intent.
+
+If the merchant's prompt names a specific lever (e.g., "give me a coupon"), this rule does NOT apply — focus all recommendations on that lever. The multi-lever requirement is for OPEN prompts where the lever is the agent's call.
+
+---
+
 ## Measurement Plan
 
 ### Before campaign launch

package/skills/wix-manage/references/ecommerce/{goal-seasonal-revenue.md → pricing-promotions/ecom-pricing-goal-seasonal-revenue.md}

@@ -1,16 +1,16 @@
 ---
 name: "Goal: Seasonal Revenue"
-description: Maps the SEASONAL business goal to event-driven revenue KPIs and promotional flows.
-layer: goal
-references:
-  - name: "Flow: Seasonal Promotion"
-    path: ecommerce/flow-seasonal-promotion.md
-    load: true
+description: SEASONAL goal — always load BEFORE recommending any holiday / event / date-tied promotion. Owns the priority rule (holiday beats UPSELL_BOOST when both signals are present).
 ---
 # Goal: Capitalize on Seasonal Events
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Flow: Seasonal Promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-seasonal-promotion)
+> **Routing rule (READ FIRST).** Any merchant query that mentions a holiday, cultural event, season, or specific date tied to a discount MUST load this recipe before any flow-* recipe. Do NOT route directly to [Flow: Seasonal Promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-seasonal-promotion) from the WixREADME index — this goal owns the **priority rule** ("holiday/event/date beats all other signals — even 'maximize revenue' / 'boost sales' must classify as SEASONAL when a date is named"), the event calendar, and the per-recommendation time-window presentation rules. The flow is a sub-step.
+>
+> ⛔ **MANDATORY — call this NOW before any API call or recommendation generation:**
+> ```
+> ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/flow-seasonal-promotion")
+> ```
+> Do NOT skip this or defer it — the flow defines the event calendar, campaign window calculation, and discount-sizing logic required to produce correct seasonal recommendations.
 
 Capitalize on holidays, cultural events, and seasonal moments to drive revenue spikes through time-limited promotional campaigns.
 
@@ -107,6 +107,19 @@ For quick, high-urgency promotions with short windows (24-72 hours). Creates imm
 
 ---
 
+## Presentation requirement — every recommendation MUST carry a time window
+
+**Every seasonal recommendation presented to the merchant MUST include an explicit campaign window** in its `reasoning` / `why` field — either `startDate` + `endDate` in the rule params, or a duration phrase in the human-readable reasoning. The merchant must be able to see, per recommendation, when it activates and when it expires.
+
+Acceptable phrasings:
+- "Runs Nov 25 – Dec 1 (Black Friday weekend)."
+- "Campaign window: 7 days starting Dec 18; ends Christmas Eve."
+- "Active from event launch through Cyber Monday (Nov 28)."
+
+A seasonal recommendation with no time window is NOT acceptable — even if everything else is correct, the absence of a window means the discount runs indefinitely and defeats the seasonal framing. If you cannot determine a window for an item, drop it; never present a windowless seasonal recommendation.
+
+---
+
 ## Measurement Plan
 
 ### Before campaign launch

package/skills/wix-manage/references/ecommerce/{troubleshoot-discount-not-applying.md → pricing-promotions/ecom-pricing-troubleshoot-not-applying.md}

@@ -1,5 +1,5 @@
 ---
-name: "Troubleshoot: Discount Not Applying"
+name: "Pricing: Discount Not Applying"
 description: Diagnostic tree for when a discount rule exists but isn't applying at checkout. Checks active status, time window, scope targeting, revision, and app installation.
 layer: troubleshoot
 ---

package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md

@@ -18,25 +18,27 @@ references:
   - name: "Goal: Drive Cross-Sells"
     path: ecommerce/goal-drive-cross-sells.md
     load: false
-  - name: "Goal: Reduce Cart Abandonment"
-    path: ecommerce/goal-reduce-cart-abandonment.md
-    load: false
   - name: "Setup: Coupons"
     path: ecommerce/setup-coupons.md
     load: false
 ---
 # Recommend: eCommerce Strategy
 
+> ⛔ **MANDATORY PRE-STEP — do this BEFORE Step 1 (before any API call).**
+>
+> Classify the merchant's request and immediately call `ReadFullDocsArticle` on the matching goal skill. Do NOT gather data first — the goal skill tells you which metrics to pull and what guardrails to apply.
+>
+> | Merchant intent | Goal to load |
+> |---|---|
+> | Holiday / event / date mentioned | `ReadFullDocsArticle` → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) |
+> | "increase AOV", "spend more", "upsell", "boost sales", generic sales improvement | `ReadFullDocsArticle` → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) |
+> | "clear inventory", "overstock", "clearance", "slow-moving" | `ReadFullDocsArticle` → [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory) |
+> | "bundle", "cross-sell", "buy together", "more items per order" | `ReadFullDocsArticle` → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells) |
 >
-> **After classifying domains in Step 4b**, load the matching goal skill with `ReadFullDocsArticle`:
-> - **SEASONAL** → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue)
-> - **UPSELL_BOOST** / **SHIPPING** → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov) (includes both discount and shipping flows)
-> - **STOCK_MOVER** → [Goal: Clear Inventory](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-clear-inventory)
-> - **BUNDLE_AND_SAVE** → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells)
-> - **ABANDONED_CART** → [Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-reduce-cart-abandonment)
+> After loading the goal skill, continue from Step 1 below. The goal skill will instruct you to load the matching flow skill — follow those instructions too.
 >
-> **If COUPON mechanism in Step 4c**, load:
-> - [Setup: Coupons](https://dev.wix.com/docs/api-reference/business-solutions/coupons)
+> **If COUPON mechanism in Step 4c**, also load:
+> - [Pricing: Create Coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon)
 
 ## EXECUTION RULES — READ BEFORE ANYTHING ELSE
 
@@ -179,7 +181,6 @@ Based on the merchant's request AND the site data, determine which domains to an
 |---|---|---|
 | **DISCOUNTS** | Merchant mentions sales, promotions, revenue, AOV, clearance, holidays, coupons. **Also activate if no specific domain is mentioned** (default). | Always — site data contains discount metrics |
 | **SHIPPING** | Merchant mentions shipping, delivery, checkout conversion, cart abandonment. **Also activate proactively** if site data suggests shipping issues. | High visitors + low orders may indicate shipping friction |
-| **ABANDONED_CART** | Activate proactively if site data shows abandoned carts with no active recovery automation. No merchant trigger needed — detect from data. | `currentDiscounts` empty or no cart recovery automation visible |
 
 **Priority rule**: If the merchant mentions a specific holiday/event/date, the DISCOUNTS domain MUST use the **SEASONAL** strategy — even if other signals like "boost sales" or "increase revenue" could match other goals. Holidays are time-sensitive and take priority over general intent.
 
@@ -205,10 +206,6 @@ Based on the merchant's request AND the site data, determine which domains to an
 
 **For SHIPPING domain — load the same goal as discounts.** Shipping flows (free shipping threshold, rate optimization) serve the same business goals as discount flows. Load the matching discount goal above — it now includes shipping flow references.
 
-**For ABANDONED_CART domain — load the cart abandonment goal:**
-
-[Goal: Reduce Cart Abandonment](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-reduce-cart-abandonment)
-
 **The goal skill will instruct you to load flow and guardrail skills** — follow those instructions. This chain provides the detailed execution logic you need for high-quality recommendations.
 
 **Do NOT skip this step.** The goal/flow/guardrail skills contain critical constraints (margin tiers, campaign windows, conflict checks) that prevent bad recommendations.
@@ -418,35 +415,9 @@ Analyze the site's shipping configuration using the rules below. All shipping re
 
 **Priority order:** CRITICAL blockers (no options, no coverage) → Conversion-linked (no free shipping, high rates) → Revenue opportunities (international, tiered pricing) → Configuration improvements (consolidate, add estimates).
 
-### Abandoned cart recommendations (if ABANDONED_CART domain active)
-
-Detect if the merchant has significant cart abandonment without active recovery. All abandoned cart recommendations use `domain: "abandoned_cart_recovery"`.
-
-**Eligibility gate (BOTH conditions required):**
-1. Cart abandonment recovery automation is **NOT active** on the site
-2. Estimated missing sales >= $200 over the last 30 days
-
-**If either condition fails, do NOT generate abandoned cart recommendations.**
-
-**Urgency thresholds based on missing sales (USD, last 30 days):**
-
-| Missing sales | Urgency |
-|---|---|
-| >= $1,000 | HIGH |
-| $200 — $999 | MEDIUM |
-| < $200 | Do not recommend |
-
-**Action type:** `activate_abandoned_cart_recovery`
-
-**Params must include:** `automation_key` ("wix_e_commerce-cart_abandonment"), `missing_sales_usd` (integer, rounded), `abandoned_cart_count` (integer), `window_days` (always 30).
-
-**Title pattern:** "Recover $[missing_sales_usd] in abandoned carts"
-
-**Reasoning MUST cite:** automation is inactive, exact cart count, exact missing sales USD, 30-day window, and why the urgency level was chosen.
-
 ### Cross-domain balance
 
-- If request is generic, aim for recommendations from **multiple domains** (e.g., 2-3 discount + 1-2 shipping + abandoned cart if eligible)
+- If request is generic, aim for recommendations from **multiple domains** (e.g., 2-3 discount + 1-2 shipping)
 - If request targets a specific domain, focus all slots on that domain
 - Rank by business impact: CRITICAL blockers first, then conversion-linked, then revenue opportunities
 
@@ -471,7 +442,13 @@ Detect if the merchant has significant cart abandonment without active recovery.
 
 **MANDATORY — do NOT skip unless the user said `SKIP_TRACKING`.**
 
-Call `BatchCreate` to persist ALL recommendations as PROPOSED:
+Before calling BatchCreate, load the tracking recipe to get the exact request body shape:
+
+```
+ReadFullDocsArticle("https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-recommendation-tracking")
+```
+
+Then call `BatchCreate` to persist ALL recommendations as PROPOSED:
 
 ```
 CallWixSiteAPI(
@@ -483,7 +460,7 @@ CallWixSiteAPI(
       {
         "title": "<recommendation title>",
         "reasoning": "<recommendation reasoning>",
-        "domain": "<discounts|shipping|abandoned_cart_recovery>",
+        "domain": "<discounts|shipping>",
         "urgency": "<CRITICAL|HIGH|MEDIUM|LOW>",
         "advice": {
           "action": "<action type>",
@@ -550,7 +527,7 @@ If BatchCreate fails, report the error and include recommendations without track
 | `id` | GUID from tracking BatchCreate response (omit if tracking skipped/failed) |
 | `title` | Short, actionable. Max 200 chars. Always English. |
 | `reasoning` | **Must reference which API call returned the data.** Always English. |
-| `domain` | `"discounts"`, `"shipping"`, or `"abandoned_cart_recovery"` (future: `"gift_cards"`, `"taxes"`) |
+| `domain` | `"discounts"` or `"shipping"` (future: `"gift_cards"`, `"taxes"`) |
 | `urgency` | `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW` |
 | `mechanism` | `AUTOMATIC` or `COUPON`. From Step 4c. Only for discounts domain. |
 | `name` | Marketing headline, 2-5 words. Translate to site `language` if not English. |
@@ -565,7 +542,6 @@ If BatchCreate fails, report the error and include recommendations without track
 |---|---|
 | discounts | `apply_discount` |
 | shipping | `create_shipping_option`, `update_shipping_option`, `enable_backup_rate`, `activate_region` |
-| abandoned_cart_recovery | `activate_abandoned_cart_recovery` |
 
 ---
 

package/skills/wix-manage/references/ecommerce/{api-shipping.md → shipping/ecom-shipping-api.md}

@@ -1,7 +1,6 @@
 ---
-name: "API: Shipping Delivery"
-description: REST API reference for Shipping Options and Delivery Profiles. Covers CRUD operations, region/carrier management, and query patterns for both services. Internal reference — these APIs are not yet published in public docs.
-layer: config
+name: "Shipping: API Reference"
+description: "Shipping Options API: POST /ecom/v1/shipping-options/query (list all), POST /ecom/v1/shipping-options (create), PATCH /ecom/v1/shipping-options/{id} (update), DELETE /ecom/v1/shipping-options/{id} (delete). Delivery Profiles API: POST /ecom/v1/delivery-profiles/query. Base: https://www.wixapis.com/ecom"
 ---
 # API: Shipping Delivery
 
@@ -73,6 +72,8 @@ Creates a new shipping option and associates it with one or more delivery region
 
 **Required fields**: `shippingOption.deliveryRegionId` (or `deliveryRegionIds`), `shippingOption.title`, `shippingOption.rates[]`
 
+> **Gotcha:** use the **singular** `deliveryRegionId` when linking an option to one region. Passing a single region in the plural `deliveryRegionIds` field returns `deliveryRegionId is not a valid GUID`.
+
 **Request**:
 ```json
 {

package/skills/wix-manage/references/ecommerce/{flow-fix-coverage-gaps.md → shipping/ecom-shipping-fix-coverage.md}

@@ -1,20 +1,26 @@
 ---
-name: "Flow: Fix Coverage Gaps"
-description: Detects active delivery regions with zero shipping options and creates standard shipping for them. Cross-references delivery profiles with shipping options to find regions where customers cannot complete checkout.
-layer: flow
-references:
-  - name: "Guardrail: Shipping Health"
-    path: ecommerce/guardrail-shipping-health.md
-    load: true
-  - name: "Setup: Shipping Regions"
-    path: ecommerce/setup-shipping-regions.md
-    load: true
+name: "Shipping: Fix Coverage Gaps"
+description: "Coverage gap = active delivery region with ZERO Shipping Options (NOT zero carriers or no backup rate). Step 1: POST /ecom/v1/delivery-profiles/query. Step 2: POST /ecom/v1/shipping-options/query — count options per region; gap = active region with count 0. Step 3: POST /ecom/v1/shipping-options to create standard shipping for each gap region."
 ---
 # Flow: Fix Shipping Coverage Gaps
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Shipping Health](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-shipping-health)
-> - [Setup: Shipping Regions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-regions)
+> **Before executing this skill**, read [Setup: Shipping Regions](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-regions) with `ReadFullDocsArticle` for region/carrier mechanics.
+
+## Shipping health score (inline)
+
+Use to gauge urgency before fixing gaps:
+
+| Score | Key indicator | Action |
+|---|---|---|
+| CRITICAL | no profiles/options, or all regions inactive | immediate setup |
+| POOR | minimal config, low CVR, or no backup rates | fix fundamentals |
+| FAIR | basic setup, no free shipping, moderate CVR | add free shipping, expand regions |
+| GOOD | domestic + international, free shipping, good CVR | optimize rates/carriers |
+| EXCELLENT | full coverage, tiered rates, high CVR | maintain |
+
+## Business-context filter for international (MANDATORY)
+
+Before creating or recommending ANY international shipping, check the store's `industry`/`businessType` (case-insensitive) for: food, restaurant, grocery, bakery, catering, perishable, fresh, meat, produce, dairy, drink, beverage. **If matched → do NOT create/recommend international shipping** (cold-chain & regulatory barriers). A region is "international" if its `name` contains "international"/"internacional", its `destinations[]` is empty (Rest of World), or it includes countries outside the store's home country.
 
 Detects delivery regions where customers cannot see any shipping options at checkout and creates standard shipping to fill the gaps. A coverage gap is a HIGH priority blocking issue -- customers in affected destinations literally cannot complete a purchase.
 
@@ -26,9 +32,9 @@ Detects delivery regions where customers cannot see any shipping options at chec
 
 ## Required APIs
 
-- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles)
-- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options)
-- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles)
+- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options)
+- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option)
 
 ---
 
@@ -296,4 +302,4 @@ Use the same request from Step 2 and verify the count now covers all active, non
 
 ## References
 
-- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference)

package/skills/wix-manage/references/ecommerce/{flow-add-free-shipping.md → shipping/ecom-shipping-free-shipping.md}

@@ -1,20 +1,25 @@
 ---
-name: "Flow: Add Free Shipping"
+name: "Shipping: Add Free Shipping"
 description: Creates a free shipping option with an AOV-calibrated threshold to reduce cart abandonment and increase average order value. Validates threshold against catalog price distribution.
-layer: flow
-references:
-  - name: "Guardrail: Rate Pricing Sanity"
-    path: ecommerce/guardrail-rate-pricing-sanity.md
-    load: true
-  - name: "Setup: Shipping Rates"
-    path: ecommerce/setup-shipping-rates.md
-    load: true
 ---
-# Flow: Add Free Shipping
+# Shipping: Add Free Shipping
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Rate Pricing Sanity](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-rate-pricing-sanity)
-> - [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-rates)
+> **This skill is the single source for adding free shipping.** Do NOT load `…/skills/flow-add-free-shipping` — that legacy slug pre-dates the routing tree migration and its content has been merged into this file. If the WixREADME index surfaces it, or this slug returns a transient 404 from the docs backend (rawdocs ingestion delay), retry this same URL — do NOT fall back to the legacy slug.
+
+> **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)
+
+Validate every rate you create or update against the store's AOV; flag any that fail:
+
+| Check | Threshold | Why / fix |
+|---|---|---|
+| Excessive rate | amount > AOV × 0.15 | top cart-abandonment driver |
+| Per-item penalty | `multiplyByQuantity: true` | penalizes larger orders → use flat/tiered |
+| Free threshold too high | threshold > AOV × 2 | unreachable; lower to ~AOV × 1.2 |
+| Free threshold too low | threshold < AOV × 0.8 | no upsell incentive; raise to ~AOV × 1.2 |
+| Backup rate shock | `backupRate.amount` > AOV × 0.15 | set to 5–10% of AOV |
+| Hidden surcharges | total `additionalCharges` > AOV × 0.10 | review necessity |
 
 Adds a free shipping option with an optimal threshold calibrated against the site's average order value and catalog price distribution. Free shipping is the single most effective lever for reducing cart abandonment at the delivery step.
 
@@ -27,10 +32,10 @@ Adds a free shipping option with an optimal threshold calibrated against the sit
 
 ## Required APIs
 
-- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options)
-- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option)
-- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#update-shipping-option)
-- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-delivery-profiles)
+- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options)
+- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option)
+- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#update-shipping-option)
+- [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-delivery-profiles)
 
 ---
 
@@ -263,4 +268,4 @@ Report to the merchant:
 
 ## References
 
-- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference)

package/skills/wix-manage/references/ecommerce/{flow-optimize-shipping-rates.md → shipping/ecom-shipping-optimize-rates.md}

@@ -1,20 +1,23 @@
 ---
-name: "Flow: Optimize Shipping Rates"
+name: "Shipping: Optimize Rates"
 description: Analyzes catalog price distribution and current rate structure to recommend optimal shipping rate strategy. Handles flat-to-tiered conversion, tier gap detection, and per-item penalty removal.
-layer: flow
-references:
-  - name: "Guardrail: Rate Pricing Sanity"
-    path: ecommerce/guardrail-rate-pricing-sanity.md
-    load: true
-  - name: "Setup: Shipping Rates"
-    path: ecommerce/setup-shipping-rates.md
-    load: true
 ---
 # Flow: Optimize Shipping Rates
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Rate Pricing Sanity](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-rate-pricing-sanity)
-> - [Setup: Shipping Rates](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-shipping-rates)
+> **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)
+
+Validate every rate you create or update against the store's AOV; flag any that fail:
+
+| Check | Threshold | Why / fix |
+|---|---|---|
+| Excessive rate | amount > AOV × 0.15 | top cart-abandonment driver |
+| Per-item penalty | `multiplyByQuantity: true` | penalizes larger orders → use flat/tiered |
+| Free threshold too high | threshold > AOV × 2 | unreachable; lower to ~AOV × 1.2 |
+| Free threshold too low | threshold < AOV × 0.8 | no upsell incentive; raise to ~AOV × 1.2 |
+| Backup rate shock | `backupRate.amount` > AOV × 0.15 | set to 5–10% of AOV |
+| Hidden surcharges | total `additionalCharges` > AOV × 0.10 | review necessity |
 
 Analyzes the site's catalog price distribution and current shipping rate structure to determine if the rate strategy is optimal. Recommends and applies changes when flat rates should become tiered, when tier gaps exist, or when per-item penalties are harming conversion.
 
@@ -27,9 +30,9 @@ Analyzes the site's catalog price distribution and current shipping rate structu
 
 ## Required APIs
 
-- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#query-shipping-options)
-- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#update-shipping-option)
-- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping#create-shipping-option)
+- [Query Shipping Options](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#query-shipping-options)
+- [Update Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#update-shipping-option)
+- [Create Shipping Option](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference#create-shipping-option)
 
 ---
 
@@ -360,4 +363,4 @@ Verify:
 
 ## References
 
-- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-shipping)
+- [API: Shipping Delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference)