@wix/agent-skills 1.12.0 → 1.14.0

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

@@ -0,0 +1,64 @@
+---
+name: "Shipping"
+description: Shipping-setup boundary owner for an eCommerce store. **Always load this dispatcher first whenever a question touches shipping setup** — rates, regions, pickup, free-shipping thresholds, and diagnosing wrong/missing shipping. Order fulfillment (mark shipped, tracking, labels, invoices) is currently handled outside the routing tree.
+---
+
+# Shipping
+
+Set up and tune how a store ships — what rates to charge, which regions are covered, pickup/local-delivery options, free-shipping thresholds, and diagnosing wrong or missing shipping at checkout.
+
+> **Routing rule (READ FIRST).** This dispatcher owns shipping *setup* — rates, regions, pickup, free-shipping thresholds, and diagnosing wrong/missing shipping at checkout. Post-purchase / order-execution work (mark shipped, update tracking, partial/bulk fulfill, shipping labels, packing slips, invoices, "find unshipped orders") is not yet in the routing tree — fall back to the relevant API docs or Dashboard guidance for those.
+
+**Shipping is NOT:**
+- Tax on shipping or destination tax → tax APIs / Dashboard.
+- The checkout/delivery step conversion itself → see **Checkout & cart**.
+- Marking orders fulfilled, updating tracking, bulk fulfillment, invoices, or shipping labels → not covered here; use the Order Fulfillments API directly or the Wix Dashboard.
+- Order lifecycle (approve/cancel/search an order), refunds/payments → existing Get Paid/payment docs or Dashboard guidance.
+
+> **Before dispatching** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded.
+>
+> **Promotion dispatch.** Score each entry below by (a) the merchant's query → `intent:*` tags, (b) MerchantContext → context tags. Load the **highest-scoring** entry with `ReadFullDocsArticle`. Ties → highest `priority`. No match → follow the base recipe at the bottom.
+>
+> **Do not fall back to legacy `flow-*` slugs.** The skills below replaced earlier `…/skills/flow-<name>` articles (e.g. `flow-add-free-shipping`) during the routing-tree migration. If a slug below returns a transient 404 from the docs backend (rawdocs ingestion delay on a freshly-renamed slug), **retry the same URL after a brief pause** — do NOT load the legacy `flow-*` version, which carries stale pre-migration content that contradicts this dispatcher.
+>
+> **API reference.** All shipping endpoints (Shipping Options + Delivery Profiles) are documented inline in [Shipping API Reference](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-api-reference) — there is no public `dev.wix.com` docs page for them, so that file is the authoritative spec. The recipes below link to it where needed.
+>
+> **Routing rule:** After identifying the matching skill above, call `ReadFullDocsArticle` on it BEFORE making any API calls or offering a configuration. The exact endpoint shapes, field names, and guardrails live in the recipe — do not configure shipping from training knowledge alone. If the URL returns a 404, retry once; then try the next-best match from the list above.
+
+### Actions — set up shipping
+
+> - [Set up shipping rates / rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-rates) — tags: `[intent:setup-rates]` · priority 0
+> - [Set up delivery regions / coverage](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-regions) — tags: `[intent:setup-regions]` · priority 0
+> - [Set up store pickup / local delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-pickup-local-delivery) — tags: `[intent:setup-pickup]` · priority 0
+> - [Add free shipping over $X](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-add-free-shipping) — tags: `[intent:free-shipping]` · priority 0
+
+### Optimize & fix
+
+> - [Optimize shipping rates (flat ↔ tiered, gaps)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — tags: `[intent:optimize-rates]` · priority 0
+> - [Fix coverage gaps (regions with no shipping option)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-fix-coverage-gaps) — tags: `[intent:fix-coverage]` · priority 0
+
+### Troubleshoot
+
+> - [Shipping rate incorrect (customer charged wrong shipping)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-optimize-rates) — tags: `[intent:rate-incorrect]` · priority 0 · *audit rates via the Rate Pricing Sanity guardrail, then correct the rate structure*
+
+## Tag matching
+
+The agent matches the merchant's natural-language query to an `intent:*` tag (cues are in each file's `description`), AND matches MerchantContext to any context tags (e.g. `country`, `region`). All of an entry's tags must be satisfied for it to be eligible; highest tag-count wins; ties → `priority`.
+
+### Worked examples
+
+| Merchant query | MerchantContext | Match |
+|---|---|---|
+| "Set up free shipping over $50" | any | `ecom-shipping-free-shipping` via `[intent:free-shipping]` |
+| "How much should I charge for shipping?" | any | `ecom-shipping-setup-rates` via `[intent:setup-rates]` |
+| "I want customers to pick up from my shop" | any | `ecom-shipping-setup-pickup` via `[intent:setup-pickup]` |
+| "Some regions have no shipping option" | any | `ecom-shipping-fix-coverage` via `[intent:fix-coverage]` |
+| "A customer was charged the wrong shipping" | any | `ecom-shipping-optimize-rates` via `[intent:rate-incorrect]` (runs rate-sanity guardrail first) |
+
+## Base recipe (fallback)
+
+If nothing matches, the merchant's intent is unclear. Ask **one** clarifying question:
+
+> "Do you want to **set up** shipping (rates, regions, or pickup), **add free shipping**, **optimize** your existing rates, or **fix** a region with no shipping option?"
+
+Map the answer to one of the `intent:*` tags above and re-dispatch. Order-fulfillment requests fall outside this dispatcher — use the Order Fulfillments API or Wix Dashboard.

package/skills/wix-manage/references/ecommerce/{setup-coupons.md → pricing-promotions/ecom-pricing-create-coupon.md}

@@ -1,9 +1,10 @@
 ---
-name: "Setup: Coupons"
-description: Creates and manages coupon codes using the Coupons V2 API. Covers coupon types (percentage, fixed amount, fixed price, free shipping), scope targeting, usage limits, and the mapping from discount recommendations to coupon API payloads.
-layer: config
+name: "Pricing: Create Coupon"
+description: "PREFERRED recipe for converting a COUPON recommendation (mechanism: COUPON) into a Wix coupon. Use THIS entry — NOT the legacy setup-coupons entry which is superseded. Maps scope/discountType/conditions to Coupons V2 API fields."
 ---
-# Setup Coupons
+# Pricing: Create Coupon
+
+> **This skill is the single source for coupon creation.** Do NOT load `…/skills/setup-coupons` — that legacy slug pre-dates the routing tree migration and its content has been merged into this file. If the WixREADME index surfaces it, ignore it.
 
 ## Prerequisites
 
@@ -22,7 +23,7 @@ layer: config
 
 Before creating a coupon, check for code conflicts and existing promotions on the same scope.
 
-**Endpoint**: `POST https://www.wixapis.com/v2/coupons/query`
+**Endpoint**: `POST https://www.wixapis.com/stores/v2/coupons/query`
 
 **Request**:
 ```json
@@ -66,11 +67,21 @@ Before creating a coupon, check for code conflicts and existing promotions on th
 
 Check for: duplicate codes, overlapping scopes with active coupons, and cross-mechanism stacking with active automatic discount rules.
 
+### Guardrails — run before creating the coupon
+
+- **Duplicate / conflicting code** — reject a code already in use.
+- **Cross-mechanism stacking** — coupons stack with automatic discount rules at checkout. Query active discount rules on overlapping scope; if found, warn with the combined effective discount ("a 20% coupon during a 20% automatic sale = ~36% off"). Only one coupon applies per checkout, but automatic rules are unlimited.
+- **% sanity** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed; > 100% always block.
+- **Margin** — if cost data is available, ensure the discount doesn't push price below cost; otherwise warn for > 40%.
+- **User override** — explicit merchant values override these caps; document the override in your reasoning.
+
+(The automatic-rule side of these checks lives in [Create Discount Rule](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) → "Guardrails".)
+
 ---
 
 ## Step 2: Create a percentage-off coupon
 
-**Endpoint**: `POST https://www.wixapis.com/v2/coupons`
+**Endpoint**: `POST https://www.wixapis.com/stores/v2/coupons`
 
 **Request** — 15% off all store products:
 ```json
@@ -215,6 +226,8 @@ Instead of targeting a scope, you can require a minimum cart subtotal. This is a
 | Free shipping | `freeShipping` | Boolean `true` | `"freeShipping": true` |
 | Buy X Get Y | `buyXGetY` | Object with `x` and `y` fields | `"buyXGetY": {"x": 2, "y": 1}` |
 
+> **Note**: Free shipping as an **automatic discount rule** is NOT supported — use the `freeShipping` coupon type here, or configure a free-shipping rate via the Shipping Options API.
+
 ## Scope values for Wix Stores
 
 | Scope target | `namespace` | `group.name` | `group.entityId` |
@@ -327,6 +340,7 @@ When the recommendation output has `mechanism: "COUPON"`, use this mapping to co
 
 | Error | Cause | Fix |
 |---|---|---|
+| `"When scope or minimumSubtotal is not used - only FreeShipping coupon is allowed"` | Coupon sent without `scope` or `minimumSubtotal` | Add `scope: { "namespace": "stores", "group": { "name": "product" } }` for site-wide, or set `minimumSubtotal` |
 | Duplicate code | Another coupon uses the same code | Generate a different code |
 | Invalid startTime | Value too low (must be epoch ms, not seconds) | Multiply by 1000 if in seconds |
 | Both scope and minimumSubtotal set | These are oneOf — cannot use both | Choose scope OR minimumSubtotal |

package/skills/wix-manage/references/ecommerce/{setup-discount-rules.md → pricing-promotions/ecom-pricing-create-discount-rule.md}

@@ -1,5 +1,5 @@
 ---
-name: "Setup: Discount Rules"
+name: "Pricing: Create Discount Rule"
 description: Configures automatic discount rules using the eCommerce Discount Rules API. Covers percentage and fixed-amount discounts, scope targeting (catalog-wide, specific collections, or individual products), scheduling active periods, and the find-by-name + update pattern.
 layer: config
 ---
@@ -126,6 +126,36 @@ Note existing rules and their scopes to avoid stacking conflicts.
 
 ---
 
+## Guardrails — run before creating or updating any discount
+
+These checks guard every discount creation (rule **or** coupon). Run them before the create/update calls below. **User input overrides all caps** — if the merchant explicitly asks for a value beyond a threshold, honor it and document the override in your reasoning.
+
+**Conflict / stacking** (uses the Step 1 query of active rules; for coupons, also query active coupons):
+- **Same-scope overlap** — a new rule conflicts with an existing active rule when scopes overlap (both `CATALOG`; `CATALOG` vs `COLLECTION`; same `COLLECTION`/`SPECIFIC_PRODUCTS` id). Wix stacks automatic rules → warn and offer to deactivate the existing one.
+- **Time overlap** — overlapping `activeTimeInfo` on the same scope (`existingStart < newEnd AND existingEnd > newStart`) → warn about the overlap window.
+- **Cross-mechanism (automatic + coupon)** — automatic discounts and coupons both apply at checkout. If creating a rule, query active coupons on overlapping scope (and vice-versa); warn with the combined effective discount. (Only one coupon per checkout, but automatic rules are unlimited.)
+
+**Margin / sanity:**
+- **Global cap** — default max discount **25%**; flag anything higher (proceed only on explicit request).
+- **Minimum margin** — default floor **15%**; if cost data is available, `effective_margin = (price − cost − discount_amount) / price × 100` must stay ≥ 15% (block + explain otherwise).
+- **% sanity** — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed ("makes the product free"); > 100% always block.
+- **Stacking margin** — when a new discount overlaps existing active ones, evaluate the *combined* discount against the cap and margin floor, not just the new one in isolation.
+
+| Scenario | Action |
+|---|---|
+| Discount ≤ 25% and margin ≥ 15%, no scope overlap | Proceed |
+| Scope/time/cross-mechanism overlap | Warn; offer to deactivate existing or confirm stacking |
+| Discount 26–50% (no override) | Warn, ask to confirm |
+| Discount > 50% | Warn with $ example, confirm |
+| Discount = 100% | Block unless confirmed |
+| Discount > 100% | Block always |
+| Combined/stacked discount exceeds cap or margin floor | Warn about cumulative effect |
+| Any threshold, explicit user override | Proceed, document the override in reasoning |
+
+When a discount *isn't* applying as expected, see [Troubleshoot: Discount Not Applying](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-discount-not-applying).
+
+---
+
 ## Step 2: Create a percentage discount rule
 
 **Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules`

package/skills/wix-manage/references/ecommerce/{flow-bundle-and-save.md → pricing-promotions/ecom-pricing-flow-bundle-and-save.md}

@@ -1,28 +1,16 @@
 ---
 name: "Flow: Bundle and Save"
-description: Creates a discount campaign promoting product discovery and cross-selling by requiring minimum item quantities. Targets high-margin categories with complementary products.
-layer: flow
-references:
-  - name: "Guardrail: Discount Conflicts"
-    path: ecommerce/guardrail-discount-conflicts.md
-    load: true
-  - name: "Setup: Discount Rules"
-    path: ecommerce/setup-discount-rules.md
-    load: true
+description: BUNDLE_AND_SAVE sub-flow — load [Goal: Drive Cross-Sells] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README.
 ---
 # Flow: Bundle & Save Campaign
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts)
-> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules)
+> **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).
 
 Creates a discount that rewards customers for purchasing multiple items, encouraging product discovery and cross-selling. The discount activates when the cart contains a minimum number of items, and targets categories or products where bundling makes strategic sense.
 
 ## Prerequisites
 
-- Wix Stores installed on the site
-- Products exist in the catalog across multiple categories
-- Access to `getCatalogAnalytics` and `getProductCatalogData` tools
+- Products exist in the catalog across multiple categories (`siteData.hasCatalog === true`, checked at context load)
 - Categories with 2+ products suitable for bundling
 
 ## Required APIs
@@ -32,25 +20,18 @@ Creates a discount that rewards customers for purchasing multiple items, encoura
 
 ---
 
-## Step 1: Gather catalog data
+## Step 1: Use pre-loaded catalog data
 
-Call `getCatalogAnalytics` and `getProductCatalogData` concurrently to assess the catalog's bundle potential.
+Catalog analytics and product data are already in conversation context — do NOT re-fetch:
 
-**getCatalogAnalytics** call:
-```
-aggregates: min(price), max(price), avg(profitMargin), count
-```
-
-**getProductCatalogData** call:
-```
-ordered: price DESC, ordersCount DESC
-```
+- `siteData.catalogAnalytics` — category groups with `min(price)`, `max(price)`, `avg(profitMargin)`, `count()`. Loaded by the eCommerce Load Context.
+- `siteData.productCatalogData` — per-product list sorted `price DESC, ordersCount DESC` for BUNDLE_AND_SAVE goal. Loaded by the run-a-sale orchestrator Step 5.
 
-Save the following values:
-- `min_price`, `max_price` — price range determines viable bundle combinations
+Extract the following from context:
+- `min_price`, `max_price` — from the "All Products" group in `siteData.catalogAnalytics`
 - `avg_profit_margin` — sets the discount ceiling
 - `count` — catalog breadth; more products = more bundling options
-- Top products by price and order count — identifies popular items for bundle anchoring
+- Top products by price and order count — from `siteData.productCatalogData`
 
 ---
 
@@ -118,29 +99,7 @@ If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs.
 
 ## Step 7: Run guardrail checks
 
-**Run the Guardrail: Discount Conflicts checks before creating the rule.**
-
-1. Query existing active discount rules:
-
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
-
-**Request**:
-```json
-{
-  "query": {
-    "filter": {
-      "active": true
-    },
-    "paging": {
-      "limit": 100
-    }
-  }
-}
-```
-
-2. Check for scope overlap with existing rules. Bundle discounts are especially prone to stacking — a customer buying 3 items in a category with both a bundle discount and a catalog-wide sale would get both.
-3. Check for coupon stacking risks.
-4. If conflicts found, present to merchant and get confirmation.
+**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.** Bundle discounts are especially prone to **scope-overlap stacking** (a customer buying 3 items in a category with both a bundle discount and a catalog-wide sale gets both) and **coupon stacking** — present any conflicts to the merchant and confirm.
 
 ---
 

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

@@ -1,30 +1,22 @@
 ---
 name: "Flow: Seasonal Promotion"
-description: Creates event-driven promotional campaigns tied to holidays or seasonal events. Uses country and date context to identify upcoming events, calculates optimal campaign windows, and targets relevant categories.
-layer: flow
-references:
-  - name: "Guardrail: Discount Conflicts"
-    path: ecommerce/guardrail-discount-conflicts.md
-    load: true
-  - name: "Setup: Discount Rules"
-    path: ecommerce/setup-discount-rules.md
-    load: true
+description: SEASONAL sub-flow — load [Goal: Seasonal Revenue] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README.
 ---
 # Flow: Seasonal Promotion
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts)
-> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules)
+> ⛔ **Routing gate — [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue) must be loaded before this flow.**
+>
+> 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).
 
 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.
 
 ## Prerequisites
 
-- Wix Stores installed on the site
-- Products exist in the catalog
-- Access to `getCatalogAnalytics`, `getProductCatalogData`, and `getSiteData` tools
+- Products exist in the catalog (`siteData.hasCatalog === true`, checked at context load)
 - `current_date` available for event scheduling
-- Site `country` known for region-specific event mapping
+- Site `country` known for region-specific event mapping (`siteData.country`, loaded by eCommerce Load Context)
 
 ## Required APIs
 
@@ -82,27 +74,18 @@ For Black Friday + Cyber Monday, use a single extended window: start the precedi
 
 ---
 
-## Step 3: Gather catalog data
+## Step 3: Use pre-loaded catalog data
 
-Call `getCatalogAnalytics` and `getProductCatalogData` concurrently.
+Catalog analytics and product data are already in conversation context — do NOT re-fetch:
 
-**getCatalogAnalytics** call:
-```
-aggregates: sum(ordersCount), quantiles([0.5, 0.9], price), avg(profitMargin)
-```
-
-**getProductCatalogData** call:
-```
-ordered: ordersCount DESC
-```
-
-This sort order surfaces the best-selling products first — seasonal campaigns should lead with proven sellers to maximize revenue.
+- `siteData.catalogAnalytics` — category groups with `sum(ordersCount)`, `quantiles([0.5,0.9], price)`, `avg(profitMargin)`. Loaded by the eCommerce Load Context.
+- `siteData.productCatalogData` — per-product list sorted `ordersCount DESC` for SEASONAL goal. Loaded by the run-a-sale orchestrator Step 5.
 
-Save the following values:
-- `total_orders` — overall sales volume
-- `price_p50`, `price_p90` — price distribution for discount sizing
+Extract from context:
+- `total_orders` — `sum(ordersCount)` from the "All Products" group in `siteData.catalogAnalytics`
+- `price_p50`, `price_p90` — from quantiles in `siteData.catalogAnalytics`
 - `avg_profit_margin` — sets discount ceiling
-- Top products by sales volume
+- Top products by sales volume — from `siteData.productCatalogData`
 
 ---
 
@@ -160,30 +143,7 @@ If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs.
 
 ## Step 8: Run guardrail checks
 
-**Run the Guardrail: Discount Conflicts checks before creating the rule.**
-
-1. Query existing active discount rules:
-
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
-
-**Request**:
-```json
-{
-  "query": {
-    "filter": {
-      "active": true
-    },
-    "paging": {
-      "limit": 100
-    }
-  }
-}
-```
-
-2. Check for time overlap — seasonal promotions have defined windows, so check that no existing rule covers the same period on the same scope.
-3. Check for scope overlap — a seasonal category discount stacking with an existing catalog-wide discount could create unexpectedly deep combined discounts.
-4. Check for coupon stacking — seasonal events often have high coupon usage.
-5. If conflicts found, present to merchant and get confirmation.
+**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.** For seasonal campaigns the most relevant are **time overlap** (defined windows — ensure no existing rule covers the same period/scope), **scope overlap** (a category discount stacking with a catalog-wide one), and **coupon stacking** (seasonal events drive high coupon usage). Present any conflicts to the merchant and get confirmation.
 
 ---
 

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

@@ -1,32 +1,18 @@
 ---
 name: "Flow: Stock Mover"
-description: Creates discount campaigns to clear slow-moving inventory by targeting products with high stock levels and low sales velocity. Uses deeper discounts proportional to inventory urgency.
-layer: flow
-references:
-  - name: "Guardrail: Discount Conflicts"
-    path: ecommerce/guardrail-discount-conflicts.md
-    load: true
-  - name: "Guardrail: Margin Protection"
-    path: ecommerce/guardrail-margin-protection.md
-    load: true
-  - name: "Setup: Discount Rules"
-    path: ecommerce/setup-discount-rules.md
-    load: true
+description: Stock-mover clearance sub-flow — load [Goal: Clear Inventory] FIRST (it owns the routing); this is a sub-step.
 ---
 # Flow: Stock Mover Clearance
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts)
-> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection)
-> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules)
+> **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).
 
 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.
 
 ## Prerequisites
 
-- Wix Stores installed on the site
-- Products exist in the catalog with inventory (quantity) data
-- Access to `getCatalogAnalytics` and `getProductCatalogData` tools
+- Products exist in the catalog with inventory (quantity) data (`siteData.hasCatalog === true`, checked at context load)
 - Inventory tracking enabled for target products
 
 ## Required APIs
@@ -36,27 +22,18 @@ Creates a discount targeting slow-moving inventory — products with high stock
 
 ---
 
-## Step 1: Gather inventory and sales data
+## Step 1: Use pre-loaded catalog data
 
-Call `getCatalogAnalytics` and `getProductCatalogData` concurrently to assess stock levels and sales velocity.
+Catalog analytics and product data are already in conversation context — do NOT re-fetch:
 
-**getCatalogAnalytics** call:
-```
-aggregates: sum(quantity), sum(ordersCount), avg(profitMargin)
-```
+- `siteData.catalogAnalytics` — category groups with `sum(quantity)`, `sum(ordersCount)`, `avg(profitMargin)`. Loaded by the eCommerce Load Context.
+- `siteData.productCatalogData` — per-product list sorted `quantity DESC, ordersCount ASC` for STOCK_MOVER goal. Loaded by the run-a-sale orchestrator Step 5.
 
-**getProductCatalogData** call:
-```
-ordered: quantity DESC, ordersCount ASC
-```
-
-This sort order surfaces products with the most stock and the fewest sales first — the primary candidates for clearance.
-
-Save the following values:
-- `total_quantity` — total stock across catalog
-- `total_orders` — total sales across catalog
-- `avg_profit_margin` — average profit margin (sets discount ceiling)
-- Per-product: `quantity`, `ordersCount`, `price`, `name`, `id`, `categoryId`
+Extract from context:
+- `total_quantity` — `sum(quantity)` from the "All Products" group in `siteData.catalogAnalytics`
+- `total_orders` — `sum(ordersCount)` from the "All Products" group
+- `avg_profit_margin` — sets the discount ceiling
+- Per-product: `quantity`, `ordersCount`, `price`, `name`, `id`, `categoryId` — from `siteData.productCatalogData`
 
 ---
 
@@ -122,38 +99,7 @@ If scope is CATEGORY, call `getCategoryIds` to convert category names to GUIDs.
 
 ## Step 6: Run guardrail checks
 
-**IMPORTANT: Run both guardrail checks before creating the discount rule. Clearance discounts are the most likely to trigger margin warnings.**
-
-### 6a: Discount Conflicts
-
-1. Query existing active discount rules:
-
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
-
-**Request**:
-```json
-{
-  "query": {
-    "filter": {
-      "active": true
-    },
-    "paging": {
-      "limit": 100
-    }
-  }
-}
-```
-
-2. Check for scope overlap. Clearance items that already have an active discount would stack — warn the merchant about combined discount depth.
-3. Check for coupon stacking risks. A customer combining a clearance discount with a coupon code could get an unexpectedly deep total discount.
-
-### 6b: Margin Protection
-
-This check is especially critical for clearance:
-
-- Verify `discount_percentage <= avg_profit_margin - 15%` for each candidate product.
-- If the discount would push effective margin below 15%, warn the merchant: "This clearance discount of {discount}% on {product_name} would reduce the effective margin to {remaining_margin}%. The minimum margin threshold is 15%. Proceed?"
-- If margin data is unavailable, apply extra caution — cap at 15% unless the merchant explicitly overrides.
+**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.
 
 ---
 
@@ -278,7 +224,19 @@ Save the returned `id` and `revision` for later management.
 1. Query discount rules to confirm the new rule exists and is `active: true`
 2. Verify the correct products or category are targeted
 3. Report to the merchant:
-   > "Clearance discount is live: {discount}% off {number_of_products} slow-moving items. These products had a velocity ratio of {avg_velocity}, indicating high stock relative to sales. Monitor inventory levels — once stock clears, consider deactivating the rule."
+   > "Clearance discount is live: {discount}% off {number_of_products} slow-moving items. These products had a velocity ratio of {avg_velocity}, indicating high stock relative to sales. **Margin floor enforced — effective margin stays ≥ 15% on every targeted SKU.** Monitor inventory levels — once stock clears, consider deactivating the rule."
+
+---
+
+## Presentation requirement — margin guardrail line is mandatory
+
+When generating recommendations for the merchant (whether persisted as PROPOSED via the tracking API or returned inline), **every clearance recommendation MUST include explicit margin-floor language in its `reasoning` / `why` field.** Examples:
+
+- "Discount keeps effective margin ≥ 15% (minMarginPct floor)."
+- "Pre-discount margin {X}%, post-discount {Y}% — above 15% breakeven floor."
+- "Margin protected: 20% off does NOT push `{product}` below the 15% floor."
+
+Urgency labels, stock level, capital tied up, and the "Why {N}%" velocity rationale are NOT substitutes — the merchant must see a per-item margin protection statement on every clearance line. If you cannot meet the floor at the velocity-tier discount, either reduce the discount or drop the item; never silently breach the floor.
 
 ---
 

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

@@ -1,33 +1,17 @@
 ---
 name: "Flow: Upsell Boost"
-description: Creates a discount campaign to increase average order value by setting minimum subtotal conditions above current AOV. Uses margin-based discount tiers and targets high-margin categories.
-layer: flow
-references:
-  - name: "Guardrail: Discount Conflicts"
-    path: ecommerce/guardrail-discount-conflicts.md
-    load: true
-  - name: "Guardrail: Margin Protection"
-    path: ecommerce/guardrail-margin-protection.md
-    load: true
-  - name: "Setup: Discount Rules"
-    path: ecommerce/setup-discount-rules.md
-    load: true
+description: UPSELL_BOOST sub-flow — load [Goal: Increase AOV] FIRST (it owns classification and routing); this is a sub-step, NOT a direct entry from README.
 ---
 # Flow: Upsell Boost Campaign
 
-> **Before executing this skill**, read these referenced skills with `ReadFullDocsArticle`:
-> - [Guardrail: Discount Conflicts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-discount-conflicts)
-> - [Guardrail: Margin Protection](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/guardrail-margin-protection)
-> - [Setup: Discount Rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/setup-discount-rules)
+> **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).
 
 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.
 
 ## Prerequisites
 
-- Wix Stores installed on the site
-- Products exist in the catalog with price data
-- Access to `getCatalogAnalytics` and `getProductCatalogData` tools
-- AOV data available from site metrics (revenue / ordersCount)
+- Products exist in the catalog with price data (`siteData.hasCatalog === true`, checked at context load)
+- AOV data available from site metrics (`siteData.aov`, loaded by eCommerce Load Context)
 
 ## Required APIs
 
@@ -36,27 +20,19 @@ Creates a discount that incentivizes customers to spend more per order by settin
 
 ---
 
-## Step 1: Gather catalog data and site metrics
+## Step 1: Use pre-loaded catalog data
 
-Call `getCatalogAnalytics` and `getProductCatalogData` concurrently to collect pricing, margin, and product data.
+Catalog analytics and product data are already in conversation context — do NOT re-fetch:
 
-**getCatalogAnalytics** call:
-```
-aggregates: count, quantiles([0.5, 0.75, 0.9], price), avg(profitMargin)
-```
-
-**getProductCatalogData** call:
-```
-ordered: price DESC, ordersCount DESC
-```
+- `siteData.catalogAnalytics` — category groups with `count()`, `quantiles([0.5,0.75,0.9], price)`, `avg(profitMargin)`. Loaded by the eCommerce Load Context.
+- `siteData.productCatalogData` — per-product list sorted `price DESC, ordersCount DESC` for UPSELL_BOOST goal. Loaded by the run-a-sale orchestrator Step 5.
+- `siteData.aov` — site-level AOV (revenue / ordersCount). Loaded by eCommerce Load Context.
 
-Also retrieve site-level AOV from `getSiteData` (AOV = revenue / ordersCount). Run the AOV sanity check: if AOV < price_p25, override with price_p50 as the effective AOV.
-
-Save the following values:
-- `effective_aov` — the validated average order value
-- `avg_profit_margin` — average profit margin across the catalog
-- `price_p50`, `price_p75`, `price_p90` — pricing quantiles
-- Top products by price and order volume
+Extract from context:
+- `effective_aov` — use `siteData.aov`; run AOV sanity 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`
 
 ---
 
@@ -114,36 +90,7 @@ Max 3 categoryIds per discount rule.
 
 ## Step 6: Run guardrail checks
 
-**IMPORTANT: Run both guardrail checks before creating the discount rule.**
-
-### 6a: Discount Conflicts
-
-1. Query existing active discount rules:
-
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
-
-**Request**:
-```json
-{
-  "query": {
-    "filter": {
-      "active": true
-    },
-    "paging": {
-      "limit": 100
-    }
-  }
-}
-```
-
-2. Check for scope overlap, time overlap, and coupon stacking risks with the planned upsell discount.
-3. If conflicts found, present to merchant and get confirmation before proceeding.
-
-### 6b: Margin Protection
-
-Verify that `discount_percentage <= avg_profit_margin - 15%` (minMarginPct). If the discount would push effective margin below 15%, warn the merchant.
-
-The global discount cap is 25%. Do not exceed this unless the merchant explicitly overrides it.
+**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.
 
 ---