@wix/agent-skills 1.12.0 → 1.14.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.12.0",
+  "version": "1.14.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-headless/references/BUILD-astro.md

@@ -51,13 +51,22 @@ The whole Setup window is a single message of sibling `Bash` calls — **emit th
      "navLinks": [ { "href": "/", "label": "Home" }, ... ],
      "loadedPacks": ["stores", "cms", ...],
      "packsWithComponents": ["stores", "ecom", ...],
-     "disabledPacks": ["gift-cards", ...]
+     "disabledPacks": ["gift-cards", ...],
+     "navPath": ".wix/nav.astro",
+     "footerPath": ".wix/footer.astro",
+     "homePath": ".wix/home.astro"
    }
    COMPOSE
    ```
 
    The compose-input shape is documented in `scripts/compose.mjs`'s header.
 
+   **The entire visible page is LLM-generated.** `compose.mjs` still writes the plumbing — `global.css`, `astro.config.mjs`, and `Layout.astro` (the `<html>`/`<head>` shell that imports the fonts, `global.css`, ClientRouter, and the `<Navigation/>`+`<Footer/>` components) — but the **header, footer, and home page are authored by an LLM**, not from templates (there are no `Navigation.astro` / `Footer.astro` / `index.astro` templates anymore). Between `emit-design-tokens.mjs` and `compose.mjs`, dispatch a **Default-tier** generator that reads the token vocabulary at `.wix/design-tokens.css` and authors three files, then pass their paths:
+   - `.wix/nav.astro` → `Navigation.astro` (site header). Contract: one `<header class="site-nav" transition:persist="site-nav">` with brand mark + real nav links (`/`, `/about`, `/faq`), a `<!-- nav:links -->` + `<!-- nav:actions -->` marker and an empty `<div class="nav-actions">` for later vertical patches, and a no-JS mobile toggle.
+   - `.wix/footer.astro` → `Footer.astro`. Contract: one `<footer class="site-footer">` with brand, a short tagline, and the nav links.
+   - `.wix/home.astro` → `index.astro` (full home page). Contract: frontmatter importing `Layout` + a `<Layout>…</Layout>` wrapper; one `<!-- home:<pack> -->` marker per loaded home-contributing pack; and **two decorative-image slots** — `hero` + one section (e.g. `about`). **Each slot is a DEDICATED, EMPTY placeholder element that holds no copy** — e.g. `<div class="hero-image" data-decorative-slot="hero" style="aspect-ratio:4/5"></div>` sitting *beside* the hero text, NOT the `data-decorative-slot` attribute slapped on the content-bearing `<section>`. The image patcher injects an `<img>` only into an empty slot element; if the slot wraps real copy it is skipped (the image never lands). Any element type works (`<div>`/`<figure>`/…) as long as it is its own empty element.
+   - **All three:** compose tokens as utility classes so they match the theme; write real copy (no `{{…}}`); keep `transition:persist` + the `site-nav`/`site-footer` classes (the View-Transitions + `global.css` styling target them). `compose.mjs` writes each verbatim and **errors if any path is missing** (`NO_NAV`/`NO_FOOTER`/`NO_HOME`). Manifest records `nav`/`footer`/`home` = `"llm-generated"`.
+
 **In the SAME message — the business Setup Step 4 batch** (frontend-blind; `SETUP.md` owns recipes/package set). These overlap the bridge's `compose.mjs` (~20 s) so it adds no serial wall:
 
 3. `Bash` × N — app installs, one curl per `pack.apps[*]` → `SETUP.md` § Step 4a. Packs with no `apps[*]` (`cms`, `ecom`, `gift-cards`) install nothing — skip them.

package/skills/wix-headless/references/shared/STYLING.md

@@ -46,7 +46,6 @@ These are layout/spacing/typography concerns that should always be utilities, ne
 > **Never reintroduce a named `--spacing-*` scale.** In Tailwind v4 the `--spacing-*` namespace also generates the width/sizing families (`max-w-*`, `w-*`, `min-w-*`, …), so any `--spacing-<key>` token shadows the matching `max-w-<key>`. The current fix works because the skill's spacing steps happen to equal Tailwind's numeric defaults — but if a brand ever needs genuinely *custom* spacing **values**, put them under a different namespace (e.g. `--rhythm-*`) or use arbitrary values (`py-[5.5rem]`); do not revive `--spacing-*`.
 
 **Width / reading columns:** `max-w-md`, `max-w-3xl`, `max-w-6xl`, `max-w-prose` now resolve correctly to the `--container-*` keys (no spacing collision), so use them freely; `container-reading` (the designer `@utility`) or an arbitrary `max-w-[48rem]` also work.
-
 If a designer's `global.css` contains rules like `.featured-section { padding-block: 6rem; }` or `.product-card-body { display: flex; flex-direction: column; gap: 0.5rem; }`, those are misplaced — they belong in markup as utilities (`py-24`, `flex flex-col gap-2`). Inventing such classes ships broken layouts: every consumer needs the designer to have pre-declared the class, and Tailwind v4 silently drops the references when the rule is missing.
 
 ## Required tokens — the component-CSS template contract

package/skills/wix-headless/scripts/compose.mjs

@@ -212,6 +212,14 @@ const loadedPacks = Array.isArray(input.loadedPacks) ? input.loadedPacks : [];
 const packsWithComponents = Array.isArray(input.packsWithComponents) ? input.packsWithComponents : [];
 const disabledPacks = Array.isArray(input.disabledPacks) ? input.disabledPacks : [];
 
+// Full-page LLM generation (this branch): the LLM authors the entire visible
+// page — header (Navigation.astro), footer (Footer.astro), and home page
+// (index.astro). compose writes each verbatim; there are no templates for them.
+const resolveIn = (p) => { const s = typeof p === "string" ? p.trim() : ""; return s ? (isAbsolute(s) ? s : join(projectDir, s)) : null; };
+const navPath = resolveIn(input.navPath);
+const footerPath = resolveIn(input.footerPath);
+const homePath = resolveIn(input.homePath);
+
 const brandName = brand.name ?? "Brand";
 
 // ── small color helper (derivation fail-safe only) ────────────────────────────
@@ -454,27 +462,16 @@ const navItems = navLinks
   .filter((l) => l && l.href != null && l.label != null)
   .map((l) => ({ href: String(l.href), label: String(l.label) }));
 
-// ── 4. Navigation.astro ──────────────────────────────────────────────────────────
+// ── 4. Navigation.astro (LLM-generated, verbatim) ─────────────────────────────
 {
-  let out = stripAstroHeader(readTemplate("Navigation.astro"));
-  out = out.replaceAll("{{shell.navBrandMark}}", shell.navBrandMark ?? brandName);
-  const links = navItems
-    .map((l) => `        <li class="site-nav-item"><a href="${escAttr(l.href)}">${l.label}</a></li>`)
-    .join("\n");
-  out = out.replace(/^\s*\{\{nav\.links\}\}\s*$/m, links);
-  writeProject("src/components/Navigation.astro", out);
+  if (!navPath || !existsSync(navPath)) die("NO_NAV", `LLM-generated header required via navPath (none at ${navPath ?? "<unset>"})`);
+  writeProject("src/components/Navigation.astro", readFileSync(navPath, "utf8"));
 }
 
-// ── 5. Footer.astro ──────────────────────────────────────────────────────────────
+// ── 5. Footer.astro (LLM-generated, verbatim) ─────────────────────────────────
 {
-  let out = stripAstroHeader(readTemplate("Footer.astro"));
-  out = out.replaceAll("{{brand.name}}", brandName);
-  out = out.replaceAll("{{shell.footerTagline}}", shell.footerTagline ?? "");
-  const links = navItems
-    .map((l) => `        <li><a href="${escAttr(l.href)}">${l.label}</a></li>`)
-    .join("\n");
-  out = out.replace(/^\s*\{\{nav\.links\}\}\s*$/m, links);
-  writeProject("src/components/Footer.astro", out);
+  if (!footerPath || !existsSync(footerPath)) die("NO_FOOTER", `LLM-generated footer required via footerPath (none at ${footerPath ?? "<unset>"})`);
+  writeProject("src/components/Footer.astro", readFileSync(footerPath, "utf8"));
 }
 
 // ── 6. index.astro ────────────────────────────────────────────────────────────────
@@ -485,13 +482,8 @@ const HOME_CONTRIBUTING = ["stores", "bookings", "gift-cards"]; // canonical ord
 const homePool = new Set([...loadedPacks, ...disabledPacks]);
 const homeMarkerPacks = HOME_CONTRIBUTING.filter((p) => homePool.has(p));
 {
-  let out = stripAstroHeader(readTemplate("index.astro"));
-  out = out.replaceAll("{{shell.heroHeadline}}", shell.heroHeadline ?? brandName);
-  out = out.replaceAll("{{shell.heroSub}}", shell.heroSub ?? "");
-  out = out.replaceAll("{{brand.name}}", brandName);
-  const markers = homeMarkerPacks.map((p) => `  <!-- home:${p} -->`).join("\n");
-  out = out.replace(/^\s*\{\{home-markers\}\}\s*$/m, markers);
-  writeProject("src/pages/index.astro", out);
+  if (!homePath || !existsSync(homePath)) die("NO_HOME", `LLM-generated home page required via homePath (none at ${homePath ?? "<unset>"})`);
+  writeProject("src/pages/index.astro", readFileSync(homePath, "utf8"));
 }
 
 // ── manifest (the orchestrator parses this off stdout) ────────────────────────
@@ -508,6 +500,9 @@ const manifest = {
   phase: "compose",
   data: {
     filesWritten,
+    nav: "llm-generated",
+    footer: "llm-generated",
+    home: "llm-generated",
     componentCssImports: packsWithComponents,
     homeMarkers: homeMarkerPacks.map((p) => `home:${p}`),
     tokensApplied: {

package/skills/wix-headless/scripts/patch-decorative-slots.mjs

@@ -2,10 +2,11 @@
 // Inject Image-Phase-1 decorative URLs into the page shells.
 //
 // The design-system Composer (index.astro) and the Phase 4 page designers write
-// `<div data-decorative-slot="<key>">…</div>` placeholders in src/pages/*.astro. Image Phase 1 returns a slot→URL map
-// in its JSON return; the orchestrator pipes that map (as JSON) into this
+// `<el data-decorative-slot="<key>">…</el>` placeholders in src/pages/*.astro
+// (any element — <div>, <section>, <figure>…). Image Phase 1 returns a slot→URL
+// map in its JSON return; the orchestrator pipes that map (as JSON) into this
 // script's stdin. This script reads the map + walks src/pages/*.astro,
-// then injects an <img> as the first child of each matching slot div —
+// then injects an <img> as the first child of each matching empty slot element —
 // pure string substitution, no LLM, no file rewrites.
 //
 // Usage:
@@ -23,9 +24,9 @@
 //     blocks mode or Image Phase 1 had no URLs to publish).
 //   - src/pages missing at <scaffold-dir> and in any single subdir one
 //     level down → exit 2 status="error".
-//   - For each `data-decorative-slot="<key>"` in src/pages/*.astro:
-//       * Key has no URL in the input map → leave the div alone.
-//       * Div already has a non-comment child → skip with a warning.
+//   - For each `data-decorative-slot="<key>"` element in src/pages/*.astro:
+//       * Key has no URL in the input map → leave the element alone.
+//       * Element already has a non-comment child → skip with a warning.
 //       * Otherwise inject <img …> as the first child.
 //   - Output JSON summary of patches/skips/warnings to stdout.
 
@@ -99,14 +100,19 @@ const patched = [];
 const skipped = [];
 const warnings = [];
 
-const SLOT_DIV_REGEX = /(<div[^>]*\bdata-decorative-slot="([^"]+)"[^>]*>)([\s\S]*?)(<\/div>)/g;
+// Match ANY element carrying data-decorative-slot, not just <div>. Full-page
+// LLM generation routinely puts the slot on a <section>/<figure>/<picture>;
+// the closing tag is matched by backreference (\2) to the opening tag name.
+// Slots are empty placeholders by contract, so the non-greedy body cannot
+// straddle a sibling element of the same tag.
+const SLOT_REGEX = /(<([a-zA-Z][\w-]*)[^>]*\bdata-decorative-slot="([^"]+)"[^>]*>)([\s\S]*?)(<\/\2>)/g;
 
 for (const file of candidates) {
   const original = readFileSync(file, "utf8");
   let modified = original;
   let fileChanged = false;
 
-  modified = modified.replace(SLOT_DIV_REGEX, (match, openTag, slotKey, inner, closeTag) => {
+  modified = modified.replace(SLOT_REGEX, (match, openTag, _tagName, slotKey, inner, closeTag) => {
     const url = urlMap[slotKey];
     if (!url) {
       skipped.push({ file, slot: slotKey, reason: "no URL for this slot in input map" });
@@ -121,7 +127,7 @@ for (const file of candidates) {
     }
 
     if (stripped.length > 0) {
-      warnings.push({ file, slot: slotKey, reason: "div has existing non-image child content; not patching to avoid clobber" });
+      warnings.push({ file, slot: slotKey, reason: "slot element has existing non-image child content; not patching to avoid clobber" });
       return match;
     }
 

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`