@wix/agent-skills 1.11.0 → 1.13.0

package/README.md

@@ -92,6 +92,10 @@ Run the [`release-bump`](.github/workflows/release-bump.yml) workflow from the *
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new skills.
 
+### Eval Token Budgets
+
+Eval scenarios under `yaml/wix-manage-evals/` may define a top-level `maxTokens` value. The GitHub Actions eval gate compares that budget against the PR run's total tokens for the scenario and fails the PR check when the budget is exceeded. This gate-owned field is separate from `llm_judge.maxTokens`, which only configures the judge assertion.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/references/data-collection/WIX_DATA.md

@@ -261,6 +261,16 @@ const bulkResult = await items.bulkInsert("MyCollection", [
 | `get`, `query`, `count`, `distinct` | `SCOPE.DC-DATA.READ` |
 | `insert`, `update`, `save`, `remove`, `bulkInsert`, `bulkUpdate`, `bulkRemove` | `SCOPE.DC-DATA.WRITE` |
 
+### Elevating permissions (backend only)
+
+In backend code (service plugins, events, backend APIs), wrap the `items` method with `auth.elevate` from `@wix/essentials` to run with elevated permissions:
+
+```typescript
+import { auth } from '@wix/essentials';
+const elevatedQuery = auth.elevate(items.query);
+const configResult = await elevatedQuery('MyCollection').find();
+```
+
 ## Date/Time Handling
 
 - **Date (date-only)**: Store as a string in "YYYY-MM-DD" format (as returned by `<input type="date" />`).

package/skills/wix-design-system/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: wix-design-system
-description: Wix Design System component reference. Use when building UI with @wix/design-system, choosing components, checking props and examples, or writing tests with component testkits. Triggers on "what component", "how do I make", "WDS", "show me props", "testkit", "driver", or component names like Button, Card, Box, Text.
+description: Wix Design System component reference. Use when building UI with @wix/design-system, choosing components, checking props and examples, or writing tests with component testkits. Triggers on "what component", "how do I make", "WDS", "show me props", "testkit", "driver", or component names like Button, Card, Modal, Box, Text.
+metadata:
+  verified: true
 ---
 
 # WDS Documentation Navigator

package/skills/wix-manage/SKILL.md

@@ -121,66 +121,44 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ## eCommerce
 
 **Routing — pick the right entry point:**
-- **Any sales/business improvement request** (boost sales, promotions, help my business, holiday deals, improve revenue, discounts, shipping, coupons, clearance) → use [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md). This is the **default entry point** — it analyzes ALL domains (discounts, shipping, future: gift cards, taxes) and generates cross-domain recommendations. Do NOT ask clarifying questions.
-- **Apply previously generated shipping recommendations** → use [Recipe: Apply Shipping Recommendations](references/ecommerce/recipe-apply-shipping-recommendations.md)
-- **Store pickup configuration** → use [Setup Store Pickup Location](references/ecommerce/setup-store-pickup-location.md)
-- **Discount not working at checkout** → use [Troubleshoot: Discount Not Applying](references/ecommerce/troubleshoot-discount-not-applying.md)
-- **Checkout delivery step drop-off** → use [Troubleshoot: Checkout Delivery Drop-off](references/ecommerce/troubleshoot-checkout-delivery-dropoff.md)
+- **Any sales/business improvement request** (boost sales, promotions, help my business, holiday deals, improve revenue, discounts, shipping, coupons, clearance) → use [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md). This is the **default entry point** — it analyzes ALL domains (discounts, shipping) and generates cross-domain recommendations. Do NOT ask clarifying questions.
+- **Pricing & promotions** (coupons, discount rules, ribbons, sales) → use the [Pricing & Promotions](references/ecommerce/ecom-pricing.md) dispatcher.
+- **Shipping setup** (rates, regions, pickup, free shipping, fix coverage) → use the [Shipping](references/ecommerce/ecom-shipping.md) dispatcher.
 
-### [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md)
-**THE entry point for all eCommerce recommendation requests.** Unified skill that analyzes site data across ALL domains (discounts + shipping), generates up to 5 cross-domain recommendations, and persists them to the tracking database. Covers discount strategies (seasonal, upsell, stock mover, bundling) AND shipping optimization (coverage gaps, free shipping, rate strategy, carrier backup). Use this for ANY business improvement request.
-
-### [Recipe: Apply Shipping Recommendations](references/ecommerce/recipe-apply-shipping-recommendations.md)
-**Technical:** Applies AI-generated shipping recommendations. Creates or updates shipping options based on recommendation data.
+### [eCommerce: Load Context](references/ecommerce/ecom-load-context.md)
+**L1 loader** — loads general site data (siteId, country, currency, industry, catalog analytics) needed by every eCommerce category. Each category dispatcher loads this before tag-matching; runs once per session.
 
-### [Setup Store Pickup Location](references/ecommerce/setup-store-pickup-location.md)
-**Technical:** Configures in-store pickup at checkout using Delivery Profiles API.
+### [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md)
+**Entry point for all eCommerce recommendation requests.** Unified skill that analyzes site data across ALL domains (discounts + shipping), generates up to 5 cross-domain recommendations, and persists them to the tracking database. Covers discount strategies (seasonal, upsell, stock mover, bundling) AND shipping optimization (coverage gaps, free shipping, rate strategy, carrier backup). Use this for ANY business improvement request.
 
-### [Troubleshoot: Discount Not Applying](references/ecommerce/troubleshoot-discount-not-applying.md)
-**Technical:** Diagnostic tree for inactive discounts — checks active status, time window, scope targeting, revision mismatch, app installation.
+### [Pricing & Promotions](references/ecommerce/ecom-pricing.md)
+**Dispatcher** — routes coupon/discount/sale/ribbon/bundle requests to the right leaf recipe (create coupon, create discount rule, troubleshoot discount-not-applying), and routes strategic "run a sale / boost sales" requests to `recommend-ecommerce-strategy`.
 
-### [Troubleshoot: Checkout Delivery Drop-off](references/ecommerce/troubleshoot-checkout-delivery-dropoff.md)
-**Technical:** Diagnostic tree for delivery step conversion below 65% benchmark.
+### [Shipping](references/ecommerce/ecom-shipping.md)
+**Dispatcher** — routes shipping-setup requests (rates, regions, pickup, free shipping, fix coverage, optimize rates) to the right leaf recipe. The Shipping Options + Delivery Profiles APIs have no public docs page; `ecom-shipping-api.md` is the authoritative inline reference.
 
 <details>
-<summary>Internal skills (loaded automatically by the entry points above — do NOT use directly)</summary>
-
-#### Goals
-- [Goal: Increase AOV](references/ecommerce/goal-increase-aov.md) — UPSELL_BOOST
-- [Goal: Clear Inventory](references/ecommerce/goal-clear-inventory.md) — STOCK_MOVER
-- [Goal: Seasonal Revenue](references/ecommerce/goal-seasonal-revenue.md) — SEASONAL
-- [Goal: Drive Cross-Sells](references/ecommerce/goal-drive-cross-sells.md) — BUNDLE_AND_SAVE
-- [Goal: Reduce Cart Abandonment](references/ecommerce/goal-reduce-cart-abandonment.md) — Shipping
-
-#### Flows
-- [Flow: Upsell Boost](references/ecommerce/flow-upsell-boost.md)
-- [Flow: Bundle and Save](references/ecommerce/flow-bundle-and-save.md)
-- [Flow: Stock Mover](references/ecommerce/flow-stock-mover.md)
-- [Flow: Seasonal Promotion](references/ecommerce/flow-seasonal-promotion.md)
-- [Flow: Fix Coverage Gaps](references/ecommerce/flow-fix-coverage-gaps.md)
-- [Flow: Add Free Shipping](references/ecommerce/flow-add-free-shipping.md)
-- [Flow: Optimize Shipping Rates](references/ecommerce/flow-optimize-shipping-rates.md)
-
-#### Guardrails
-- [Guardrail: Discount Conflicts](references/ecommerce/guardrail-discount-conflicts.md)
-- [Guardrail: Margin Protection](references/ecommerce/guardrail-margin-protection.md)
-- [Guardrail: Shipping Health](references/ecommerce/guardrail-shipping-health.md)
-- [Guardrail: Rate Pricing Sanity](references/ecommerce/guardrail-rate-pricing-sanity.md)
-
-#### Config & API References
-- [API: Recommendation Tracking](references/ecommerce/api-recommendation-tracking.md)
-- [API: Shipping Delivery](references/ecommerce/api-shipping.md)
-- [Setup: Discount Rules](references/ecommerce/setup-discount-rules.md)
-- [Setup: Coupons](references/ecommerce/setup-coupons.md)
-- [Setup: Shipping Regions](references/ecommerce/setup-shipping-regions.md)
-- [Setup: Shipping Rates](references/ecommerce/setup-shipping-rates.md)
-
-#### Tracking
-- Tracking is built into [Recommend: eCommerce Strategy](references/ecommerce/recommend-ecommerce-strategy.md) (Steps 2 + 8) — no separate skill needed
-- [API: Recommendation Tracking](references/ecommerce/api-recommendation-tracking.md) — CRUD API reference for the tracking service
-
-#### Reference
-- [Skill Graph](references/ecommerce/skill-graph.md)
+<summary>Internal skills (loaded automatically by the dispatchers / orchestrator above — do NOT use directly)</summary>
+
+#### Pricing & promotions leaves (loaded by the Pricing dispatcher or by the strategy orchestrator)
+- [Pricing: Create Coupon](references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md)
+- [Pricing: Create Discount Rule](references/ecommerce/pricing-promotions/ecom-pricing-create-discount-rule.md)
+- [Pricing: Discount Not Applying](references/ecommerce/pricing-promotions/ecom-pricing-troubleshoot-not-applying.md)
+- Goals: [Increase AOV](references/ecommerce/pricing-promotions/ecom-pricing-goal-increase-aov.md), [Clear Inventory](references/ecommerce/pricing-promotions/ecom-pricing-goal-clear-inventory.md), [Seasonal Revenue](references/ecommerce/pricing-promotions/ecom-pricing-goal-seasonal-revenue.md), [Drive Cross-Sells](references/ecommerce/pricing-promotions/ecom-pricing-goal-drive-cross-sells.md)
+- Flows: [Upsell Boost](references/ecommerce/pricing-promotions/ecom-pricing-flow-upsell-boost.md), [Bundle and Save](references/ecommerce/pricing-promotions/ecom-pricing-flow-bundle-and-save.md), [Stock Mover](references/ecommerce/pricing-promotions/ecom-pricing-flow-stock-mover.md), [Seasonal Promotion](references/ecommerce/pricing-promotions/ecom-pricing-flow-seasonal-promotion.md)
+
+#### Shipping leaves (loaded by the Shipping dispatcher)
+- [Set Up Rates](references/ecommerce/shipping/ecom-shipping-setup-rates.md)
+- [Set Up Regions](references/ecommerce/shipping/ecom-shipping-setup-regions.md)
+- [Set Up Pickup / Local Delivery](references/ecommerce/shipping/ecom-shipping-setup-pickup.md)
+- [Add Free Shipping](references/ecommerce/shipping/ecom-shipping-free-shipping.md)
+- [Optimize Rates](references/ecommerce/shipping/ecom-shipping-optimize-rates.md)
+- [Fix Coverage Gaps](references/ecommerce/shipping/ecom-shipping-fix-coverage.md)
+- [API Reference](references/ecommerce/shipping/ecom-shipping-api.md) — inline spec for Shipping Options + Delivery Profiles
+
+#### Cross-cutting tracking
+- [API: Recommendation Tracking](references/ecommerce/api-recommendation-tracking.md) — load BEFORE generating any recommendation; persists PROPOSED state and tracks MarkExecuting → MarkDone/MarkFailed.
+
 
 </details>
 

package/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md

@@ -1,7 +1,6 @@
 ---
 name: "API: Recommendation Tracking"
-description: CRUD API for persisting and managing the lifecycle of AI-generated recommendations. Tracks state transitions from PROPOSED through APPROVED, EXECUTING, to DONE/FAILED/REJECTED. Every recommendation must be persisted here before presenting to the merchant.
-layer: config
+description: Cross-cutting tracking API for AI-generated recommendations across eCommerce categories (checkout, shipping, pricing). ALWAYS LOAD BEFORE generating a "give me N recommendations / concrete actions" response, in addition to the category recipe.
 ---
 # API: Recommendation Tracking Service
 
@@ -11,6 +10,8 @@ This service persists recommendations in a database and tracks their lifecycle s
 
 **Base URL**: `https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations`
 
+> **Internal-but-callable API.** This is a Wix-internal service with NO public `dev.wix.com` docs page. It **IS callable via `CallWixSiteAPI`** in the authenticated editor/dashboard context the MCP runs in (verified: the endpoints return auth/validation errors, not 404). This file is the authoritative spec — do not try to `ReadFullDocsArticle` an external doc for it.
+
 ## How to call these APIs
 
 Use `CallWixSiteAPI` to invoke each endpoint:

package/skills/wix-manage/references/ecommerce/ecom-load-context.md

@@ -0,0 +1,144 @@
+---
+name: "eCommerce: Load Context"
+description: "eCommerce L1 context loader — calls wix-profile-client/v4/profile/metasite (NOT site-properties) to load siteId, country, currency, industry, last-30-day visitors/orders/GPV. Skip if already loaded."
+---
+
+# eCommerce: Load Context
+
+> **L1 loader pattern.** Each L1 domain (eCommerce, Stores, Get-paid, Contacts, …) owns its own context loader. This file is the **eCommerce** L1 loader. Other L1s have their own (e.g. `stores-load-context.md` will detect Catalog V1/V3 for Stores categories). The boilerplate (Step 1 + 2) is small; the **field list and runtime detections differ by L1**.
+
+> **When to run.** Called from the dispatch block of any eCommerce category's `default.md` (Tax, Pricing & promotions, …) before tag-matching. Run **once per session**. If `siteData.country` is already in your conversation context, skip the API calls below and return immediately — every subsequent eCommerce category entry reuses the loaded data.
+
+This is the canonical extract of Steps 1 + 3 from today's `recommend-ecommerce-strategy.md`, scoped to the fields eCommerce categories actually need.
+
+## Step 1 — Resolve siteId
+
+If a `siteId` is not already known, call `ListWixSites`:
+
+```
+ListWixSites()
+```
+
+- If the merchant referenced a site by name, match it.
+- If exactly one site exists, auto-select it.
+- Otherwise, ask the merchant which site to use.
+
+**Do not proceed without a `siteId`.**
+
+## Step 2 — Load business profile (the canonical endpoint)
+
+Same call today's `recommend-ecommerce-strategy.md` Step 3 makes. The field list below is the **eCommerce** subset — orchestrator-needed metrics (visitors / orders / GPV → AOV) plus locale/currency/industry used for dispatch tags and recommendations.
+
+```
+CallWixSiteAPI(
+  url: "https://www.wix.com/wix-profile-client/v4/profile/metasite",
+  method: "POST",
+  body: {
+    "fields": [
+      "language",
+      "merchant_business_country",
+      "suggested_main_industry",
+      "suggested_sub_industry",
+      "last_30_days_distinct_visitors",
+      "last_30_days_orders_count",
+      "online_gpv_last_30_days",
+      "payment_currency"
+    ]
+  }
+)
+```
+
+Extract each field into conversation context as `siteData`:
+
+| Field in response | Maps to | Notes |
+|---|---|---|
+| `fields.language.aSingleValue.aString` | `siteData.language` | Locale code (e.g. `en-US`) |
+| `fields.merchant_business_country.aSingleValue.aString` | `siteData.country` | ISO-3166-1 alpha-2 |
+| `fields.suggested_main_industry.aSingleValue.aString` | `siteData.industry` | Used by Pricing orchestrator's goal classification |
+| `fields.suggested_sub_industry.aSingleValue.aString` | `siteData.subIndustry` | Optional |
+| `fields.last_30_days_distinct_visitors.aSingleValue.aLong` | `siteData.visitors30d` | **Returned as JSON string** — `parseInt` before arithmetic |
+| `fields.last_30_days_orders_count.aSingleValue.aLong` | `siteData.orders30d` | parseInt |
+| `fields.online_gpv_last_30_days.aSingleValue.aLong` | `siteData.gpv30d` | parseInt |
+| `fields.payment_currency.aSingleValue.aString` | `siteData.currency` | ISO-4217 |
+
+Missing fields ⇒ no data for that field (don't fabricate). If `merchant_business_country`, `suggested_main_industry`, or `online_gpv_last_30_days` are missing or null, surface to the merchant: "Cannot resolve required site data: <fields>." and stop.
+
+**Derived value:** `siteData.aov = parseInt(gpv30d) / parseInt(orders30d)` — in `siteData.currency` units.
+
+## Step 2b — Detect catalog presence and load analytics
+
+Call `GetCatalogAnalytics` once here so all downstream pricing/promotions flows can reference `siteData.catalogAnalytics` without re-fetching.
+
+```
+CallWixSiteAPI(
+  url: "https://manage.wix.com/recommendations/v1/recommendations/get-catalog-analytics-tool",
+  method: "POST",
+  body: {
+    "aggregates": [
+      {"op":"count","field":"price"},
+      {"op":"min","field":"price"},
+      {"op":"max","field":"price"},
+      {"op":"avg","field":"profitMargin"},
+      {"op":"quantiles","field":"price","q":[0.5,0.75,0.9]},
+      {"op":"sum","field":"quantity"},
+      {"op":"sum","field":"ordersCount"}
+    ],
+    "minMarginPct": 0.15
+  }
+)
+```
+
+Save the full `categoryGroups` array as `siteData.catalogAnalytics`. From the "All Products" group extract:
+- `siteData.catalogProductCount` = `count()` value (0 if missing or call fails)
+- `siteData.hasCatalog` = `siteData.catalogProductCount > 0`
+
+If the call fails, set `siteData.hasCatalog = true` (assume catalog exists; let downstream fail naturally).
+
+**This data is used by all pricing & promotions discount flows.** Flows that require a product catalog (Bundle & Save, Upsell Boost, Stock Mover, Seasonal) MUST check `siteData.hasCatalog` before proceeding — if `false`, stop with: "This site has no products. Set up your product catalog first before running promotions."
+
+## Step 3 — Derive region (used by dispatch context tags)
+
+From `siteData.country`, set `siteData.region`:
+- `BR | AR | MX | CL | CO | PE` → `LATAM`
+- EU member states (`DE | FR | IT | ES | NL | BE | PL | SE | IE | AT | PT | FI | DK | CZ | HU | GR | RO | BG | HR | SK | SI | LT | LV | EE | CY | MT | LU`) → `EU`
+- `JP | CN | KR | SG | AU | NZ | IN | TH | ID | MY | PH | VN | HK | TW` → `APAC`
+- otherwise → `null`
+
+(UK is **not** in `region:EU`. AU/NZ are in `region:APAC` but Tax inclusive-pricing rules differ — handled inside Tax promotions.)
+
+## Step 4 — Return
+
+Return immediately. Subsequent eCommerce category dispatches read `siteData.*` from conversation context without re-fetching. If the agent crosses into a different L1 (e.g. Stores) within the same session, that L1's loader will see `siteData.country` already loaded, skip its Steps 1-3, and only fire its own general derivations.
+
+## Architectural rule — general site data only
+
+**This file must contain only general / cross-cutting site data** — fields that **every** category in this L1 needs. It must **not** include L3-category-specific runtime detection (e.g. Tax calculator, Catalog V1/V3, payment-provider state, shipping-coverage state).
+
+Reasoning:
+- Per-category detect calls accumulate cost on every session entry, even when the agent never visits that category.
+- L3-specific state can use APIs that aren't TPA-public (e.g. the Wix Tax FQDNs are `exposure: INTERNAL`); if the L1 loader depends on them, the entire L1 fails to load. Keeping the loader general-only contains the blast radius.
+- Per-category state can change independently of the merchant; loading it eagerly invites stale-data bugs.
+
+**Where category-specific runtime data is detected instead:** inside the category's `default.md` (Step before dispatch) or inside the specific promotion that needs it. The L1 loader does **not** prime per-category fields; the category does its own detection lazily, only when its own intent dispatch fires.
+
+Concretely for the categories we know about:
+- **Tax** — calculator detection (Manual vs Avalara) belongs in `ecom-tax.md` (the merged category-doc + dispatcher) or in each Tax promotion when it runs. Not here.
+- **Catalog V1/V3 version detection** — belongs in the Stores category loader when Stores migrates. `getCatalogAnalytics` (product count/margin/price) is already loaded here as a cross-cutting concern; V1/V3 detection is a separate, Stores-specific signal.
+- **Payments & finance** (when Get-paid migrates) — payment-provider state belongs in `finance-and-payments/get-paid-finance-default.md`.
+
+## What this file does NOT do
+
+- **Does not detect per-category runtime state** (see architectural rule above).
+- **Does not load tracking history.** But: if any recipe in this session generates a recommendation to present to the merchant — regardless of which eCommerce category — it MUST load [API: Recommendation Tracking](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/api-recommendation-tracking) and follow the lifecycle: load history before generating (Query), persist as PROPOSED via BatchCreate before presenting, and track execution via MarkExecuting / MarkDone / MarkFailed. This obligation applies to ALL eCommerce domains.
+- **Does not load non-eCommerce L1 fields** (catalog V1/V3 version detection, payment provider, …). Those belong inside the owning L1's category-level files (per the architectural rule). Note: `getCatalogAnalytics` (product count, margin, price distribution) IS loaded here as a cross-cutting concern; Catalog V1/V3 version detection is separate and belongs in the Stores category's own loader.
+- **Does not enforce dispatch.** The category's `default.md` is what scores tags and picks a promotion — this file only fills general site context.
+
+## Pattern for future L1 loaders
+
+When a new L1 domain is migrated to the routing tree, author a `<l1>-load-context.md` at its root:
+
+- `references/stores/stores-load-context.md` — Stores L1 loader. Steps 1-3 same boilerplate, Step 4 runtime-detects Catalog version (V1/V3) and any other Stores-specific fields.
+- `references/get-paid/get-paid-load-context.md` — Get-paid L1 loader. Step 4 inspects payment provider state, enabled methods.
+- `references/contacts/contacts-load-context.md` — Contacts L1 loader. Possibly minimal — most CRM ops don't need runtime detection.
+
+Each lives sibling to its L1's category-docs. Each is referenced from every category's `default.md` within its L1. Skip-if-loaded check across L1s makes cross-L1 sessions cost-free.

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

@@ -0,0 +1,84 @@
+---
+name: "Pricing & Promotions"
+description: Pricing & Promotions boundary owner — discounts, coupons, sales, ribbons, bundles. **Always load this dispatcher first when a question touches both discount work and refunds, payments, product-price edits, or shipping rates** — the rules for which side owns each topic live in this file, not in this README line.
+---
+
+# Pricing & Promotions
+
+Discount rules, coupon codes, sales, ribbons, bundles, tiered pricing, and the strategic side of "run a promotion to grow revenue".
+
+> **Routing rule (READ FIRST).** Any merchant query that mentions BOTH a Pricing-side topic (discount, coupon, sale, ribbon, bundle, promotion strategy) AND a NON-pricing-side topic (refunding a past order, processing a payment, editing the product's base price, shipping rates) MUST be answered by loading this dispatcher first AND the relevant other category (refunds → Get Paid / Dashboard; price → Catalog; shipping rates → Shipping). Do NOT route mixed queries from the WixREADME index alone; the binding decision lives here.
+
+**Pricing & promotions is NOT:**
+- The product price itself or its description/image → see **Catalog** (those are product fields).
+- A standing $0 shipping option/region rate → see **Shipping & fulfillment**.
+- Refunding a previous discounted order → route to verified 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. Ties → highest `priority`. No match → follow the base recipe at the bottom.
+>
+> **Do not fall back to legacy `setup-*` or `flow-*` pricing slugs.** The skills below replaced earlier `…/skills/setup-coupons` and `…/skills/flow-<name>` articles during the routing-tree migration. If a slug below returns a transient 404 (rawdocs ingestion delay), **retry the same URL after a brief pause** — do NOT load any `setup-coupons` or `flow-*` legacy version even if it appears in the WixREADME index; that content is stale pre-migration material that contradicts this dispatcher.
+
+### Actions — concrete operations
+
+> - [Create coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon) — tags: `[intent:create-coupon]` · priority 0
+> - [Create discount rule (auto-apply)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:create-discount-rule]` · priority 0
+> - [Add sale ribbon / new ribbon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:add-ribbon]` · priority 0 · *ribbons are configured via Discount Rules; same recipe*
+> - [Schedule a future sale](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:schedule-sale]` · priority 0 · *uses Discount Rules with `startTime` in the future*
+
+### Business flows — the orchestrator
+
+The single business-flow orchestrator (`recommend-ecommerce-strategy`) handles all strategic discount intents. It classifies internally (SEASONAL / UPSELL_BOOST / STOCK_MOVER / BUNDLE_AND_SAVE / ABANDONED_CART) and loads its `goal-*` / `flow-*` support files from the kept ecommerce-root siblings.
+
+> - [Run a sale / promotion strategy](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recommend-e-commerce-strategy) — tags: `[intent:run-a-sale]` · priority 0
+> - [Boost my business / increase sales](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recommend-e-commerce-strategy) — tags: `[intent:boost-business]` · priority 0
+> - [Seasonal / holiday promotion](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recommend-e-commerce-strategy) — tags: `[intent:seasonal-promo]` · priority 0
+> - [Clearance / move slow stock](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recommend-e-commerce-strategy) — tags: `[intent:clearance]` · priority 0
+> - [Increase AOV (bundle / upsell)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recommend-e-commerce-strategy) — tags: `[intent:increase-aov]` · priority 0
+>
+> **If the orchestrator above returns a 404** — do not stop. Classify the merchant intent directly and load the matching goal skill via `ReadFullDocsArticle`, then follow its routing chain into the flow skill:
+> - Holiday / event / date mentioned (SEASONAL — takes priority over all other signals) → [Goal: Seasonal Revenue](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-seasonal-revenue)
+> - "Boost sales", "increase AOV", "upsell", "spend more" (UPSELL_BOOST) → [Goal: Increase AOV](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-increase-aov)
+> - "Clearance", "slow stock", "overstock", "move inventory" (STOCK_MOVER) → [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" (BUNDLE_AND_SAVE) → [Goal: Drive Cross-Sells](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/goal-drive-cross-sells)
+
+### Info / troubleshoot / recommendation
+
+> - [Discount not applying — diagnose](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-discount-not-applying) — tags: `[intent:troubleshoot]` · priority 0
+> - [View active discounts (Coupons API)](https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/query-coupons) — tags: `[intent:view-active-discounts]` · priority 0 · **API doc, no skill** (per §7.5)
+> - [View active discounts (Discount Rules API)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/discount-rules/query-discount-rules) — tags: `[intent:view-active-rules]` · priority 0 · **API doc, no skill**
+> - [Coupon usage stats](https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/get-coupon-usage) — tags: `[intent:coupon-usage-stats]` · priority 0 · **API doc, no skill**
+> - Competitive pricing check (how do my prices compare?) — tags: `[intent:competitive-pricing]` · *no Wix API for competitor data — advise the merchant to benchmark externally (Google Shopping / market research); Wix only exposes their own catalog prices via Catalog API*
+
+### Cross-category routes (handled in another category)
+
+> - [Change product price](https://dev.wix.com/docs/api-reference/business-solutions/stores/products-v3/update-product) — tags: `[intent:change-price]` · *price is a product field — Catalog API*
+> - [Set compare-at price](https://dev.wix.com/docs/api-reference/business-solutions/stores/products-v3/update-product) — tags: `[intent:set-compare-at]` · *Catalog*
+> - [Free shipping over $X (promo rule)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:free-shipping-promo]` · *belongs here as a promo rule; a $0 shipping rate is Shipping*
+
+## Tag matching
+
+The agent matches the merchant's natural-language query to an `intent:*` tag (cues are in each promotion file's `description`), AND matches MerchantContext to any context tags. A promotion's tags must ALL be satisfied for it to be eligible. Among eligible promotions, the one with the highest tag-count wins; ties broken by `priority`.
+
+### Worked examples
+
+| Merchant query | MerchantContext | Match |
+|---|---|---|
+| "Create a 20% off coupon" | any | `ecom-pricing-create-coupon` via `[intent:create-coupon]` |
+| "Run a Black Friday sale" | any | `recommend-ecommerce-strategy` via `[intent:run-a-sale]` (orchestrator classifies as SEASONAL internally) |
+| "Help me boost my sales" | any | `recommend-ecommerce-strategy` via `[intent:boost-business]` |
+| "My coupon code XMAS isn't working" | any | `ecom-pricing-troubleshoot-not-applying` |
+| "Show me my active discounts" | any | `query-coupons` API doc (no skill — per §7.5) |
+| "Change the price of product Y" | any | Catalog cross-route (re-dispatch to Catalog when that category exists) |
+
+## Base recipe (fallback)
+
+If nothing matches, the merchant query is too vague. Ask **one** clarifying question:
+
+> "Do you want to (a) **create** a specific discount/coupon now, (b) **strategize** a sale or promotion campaign, or (c) **fix** a discount that isn't applying?"
+
+Map the answer → re-dispatch:
+- (a) → `ecom-pricing-create-coupon` (default for "create a discount")
+- (b) → `recommend-ecommerce-strategy`
+- (c) → `ecom-pricing-troubleshoot-not-applying`

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`