@wix/agent-skills 1.0.0

package/skills/wix-headless/templates/stores/products/[slug].astro

@@ -0,0 +1,128 @@
+---
+// SSR only — productsV3 SDK needs request-context auth (tenant resolution,
+// site headers). `export const prerender = true` / `getStaticPaths()` builds
+// at compile time with no request, and `.queryProducts().limit()` short-
+// circuits to "is not a function". Keep this page server-rendered; do NOT
+// add prerender=true or getStaticPaths.
+import Layout from "../../layouts/Layout.astro";
+import ProductPurchase from "../../components/ProductPurchase.tsx";
+import SeoTags from "../../components/SeoTags.astro";
+import { productsV3, inventoryItemsV3 } from "@wix/stores";
+import { resolveWixImageUrl } from "../../utils/wix-image";
+import { getBackInStockEnabled } from "../../utils/back-in-stock";
+
+// Tell Wix platform this route is the Stores "product" sub-page.
+// Drives sitemap, dashboard SEO editor, deep links.
+export const wixMetadata = {
+  appDefId: "1380b703-ce81-ff05-f115-39571d94dfcd",
+  pageIdentifier: "wix.stores.sub_pages.product",
+  identifiers: {
+    slug: "STORES.PRODUCT.SLUG",
+  },
+};
+
+const { slug } = Astro.params;
+
+// Wrap the SSR await; a throw here aborts the response stream.
+let product: any = null;
+try {
+  const result = await productsV3.getProductBySlug(slug!, {
+    fields: ["CURRENCY", "PLAIN_DESCRIPTION"],
+  });
+  product = result.product;
+} catch (err) {
+  console.error("[product-detail] getProductBySlug failed:", err);
+}
+
+if (!product) return Astro.redirect("/404");
+
+// Live per-variant stock from inventoryItemsV3 — the authoritative source of
+// truth for OOS gating. productsV3's variantsInfo[].inventoryStatus.inStock is
+// a stale cached flag that does NOT reflect real-time stock changes; don't
+// trust it for the add-to-cart gate. See SHARED_WIRING.md § "Variant OOS gate".
+interface VariantStock { quantity: number; trackQuantity: boolean; preorderEnabled: boolean }
+const inventoryByVariant: Record<string, VariantStock> = {};
+try {
+  const inv: any = await inventoryItemsV3.queryInventoryItems({
+    filter: { productId: product._id },
+  });
+  for (const item of (inv?.items ?? inv?.inventoryItems ?? []) as any[]) {
+    if (!item.variantId) continue;
+    inventoryByVariant[item.variantId] = {
+      quantity: Number(item.quantity ?? 0),
+      trackQuantity: item.trackQuantity === true,
+      preorderEnabled: item.preorderInfo?.enabled === true,
+    };
+  }
+} catch (err) {
+  console.error("[product-detail] inventory query failed:", err);
+}
+
+const imageUrl = resolveWixImageUrl(product.media?.main?.image, 800, 1066);
+const price = product.actualPriceRange?.minValue?.formattedAmount;
+const priceAmount = Number(product.actualPriceRange?.minValue?.amount ?? 0);
+const currency = product.actualPriceRange?.minValue?.currency;
+const description = product.plainDescription?.replace(/<[^>]*>/g, "").trim();
+
+// SSR probe — true only if the dashboard's "Start Collecting Requests" toggle
+// is on for Wix Stores. Returns false on any error so the OOS subscribe form
+// silently hides if the probe / auth fails. See references/BACK_IN_STOCK.md.
+const backInStockEnabled = await getBackInStockEnabled();
+
+// Merchant-edited SEO from dashboard (product settings → SEO).
+// product.seoData.tags returned by default — no fields flag needed.
+const seoTags = product.seoData?.tags ?? [];
+const hasSeoTags = seoTags.some((t: any) => !t.disabled);
+
+const viewContentPayload = {
+  id: product._id,
+  name: product.name,
+  price: priceAmount,
+  currency,
+  origin: "Product Page",
+};
+---
+
+<Layout
+  title={product.name ?? "Product"}
+  description={description?.slice(0, 160)}
+  hasSeoTags={hasSeoTags}
+>
+  {hasSeoTags && <SeoTags slot="head" tags={seoTags} />}
+  <main class="py-3xl">
+    <div class="max-w-wide mx-auto px-xl">
+      <a href="/products" class="text-mute text-sm tracking-wide uppercase">&larr; Back to products</a>
+      <div class="grid grid-cols-1 md:grid-cols-[7fr_5fr] gap-2xl md:gap-4xl mt-xl items-start">
+        <div class="aspect-[4/5] bg-cream rounded-sm overflow-hidden">
+          {imageUrl && <img src={imageUrl} alt={product.name ?? "Product"} class="w-full h-full object-cover" />}
+        </div>
+        <div class="flex flex-col gap-lg md:sticky md:top-2xl">
+          <h1 class="font-display text-4xl leading-tight">{product.name}</h1>
+          {price && <p class="text-xl text-ink-soft">{price}</p>}
+          {description && <p class="text-ink-soft leading-relaxed">{description}</p>}
+          <ProductPurchase
+            client:load
+            product={product}
+            inventoryByVariant={inventoryByVariant}
+            backInStockEnabled={backInStockEnabled}
+            priceAmount={priceAmount}
+          />
+        </div>
+      </div>
+    </div>
+  </main>
+</Layout>
+
+<script
+  type="application/json"
+  id="analytics-view-content"
+  is:inline
+  set:html={JSON.stringify(viewContentPayload)}
+/>
+<script>
+  import { trackEvent } from "../../utils/analytics";
+  const el = document.getElementById("analytics-view-content");
+  if (el?.textContent) {
+    trackEvent("ViewContent", JSON.parse(el.textContent));
+  }
+</script>

package/skills/wix-headless/templates/stores/products/index.astro

@@ -0,0 +1,101 @@
+---
+import Layout from "../../layouts/Layout.astro";
+import ProductCard from "../../components/ProductCard.astro";
+import CategoryRail from "../../components/CategoryRail.astro";
+import { productsV3 } from "@wix/stores";
+import { listStoreCategories } from "../../utils/categories";
+
+const PAGE_SIZE = 24;
+const cursor = Astro.url.searchParams.get("cursor") ?? undefined;
+
+let productList: any[] = [];
+let nextCursor: string | null = null;
+let prevCursor: string | null = null;
+try {
+  let builder = productsV3
+    .queryProducts({ fields: ["CURRENCY"] })
+    .limit(PAGE_SIZE);
+  if (cursor) builder = builder.skipTo(cursor);
+  const result = await builder.find();
+  productList = result.items ?? [];
+  nextCursor = result.cursors?.next ?? null;
+  prevCursor = result.cursors?.prev ?? null;
+} catch (err) {
+  console.error("[products] listing query failed:", err);
+}
+
+// Drop the Wix Gift Card app's auto-mirror products. When the app is enabled,
+// it provisions 5 DIGITAL Stores products (one per denomination) tagged with
+// the "Gift Card" ribbon. Buying them yields a dud line item that does not
+// trigger gift-card issuance — the customer-facing surface for gift cards
+// is /gift-cards (gift-cards pack), not /products.
+productList = productList.filter((p) => p.ribbon?.name !== "Gift Card");
+
+const allCategories = await listStoreCategories();
+
+// Payload for the client-side AddProductImpression event.
+const impressionContents = productList.map((p, index) => ({
+  id: p._id,
+  name: p.name,
+  price: Number(p.actualPriceRange?.minValue?.amount ?? 0),
+  currency: p.actualPriceRange?.minValue?.currency ?? undefined,
+  position: index + 1,
+}));
+
+function pageHref(c: string | null): string | null {
+  if (!c) return null;
+  const params = new URLSearchParams();
+  params.set("cursor", c);
+  return `/products?${params.toString()}`;
+}
+---
+
+<Layout title="Products">
+  <section class="page-header">
+    <div class="container-page">
+      <h1 class="page-header-title">Our Products</h1>
+    </div>
+  </section>
+
+  <CategoryRail
+    categories={allCategories}
+    activeSlug={null}
+    prevHref={pageHref(prevCursor)}
+    nextHref={pageHref(nextCursor)}
+  />
+
+  <section class="section-pad">
+    <div class="container-page">
+      {productList.length === 0 ? (
+        <p class="products-empty">
+          No products yet &mdash; please check back shortly.
+        </p>
+      ) : (
+        <div class="product-grid">
+          {productList.map((product, idx) => (
+            <ProductCard product={product} index={idx} />
+          ))}
+        </div>
+      )}
+    </div>
+  </section>
+</Layout>
+
+<script
+  type="application/json"
+  id="analytics-impressions"
+  is:inline
+  set:html={JSON.stringify(impressionContents)}
+/>
+<script>
+  import { trackEvent } from "../../utils/analytics";
+  function fireImpressions() {
+    const el = document.getElementById("analytics-impressions");
+    if (!el?.textContent) return;
+    trackEvent("AddProductImpression", {
+      contents: JSON.parse(el.textContent),
+      origin: "Product Listing",
+    });
+  }
+  document.addEventListener("astro:page-load", fireImpressions);
+</script>

package/skills/wix-manage/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: wix-manage
+description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, events, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce."
+compatibility: Requires Wix REST API access (API key or OAuth).
+---
+
+# Management Recipes Index
+
+## What Are Management Recipes?
+
+**Management recipes are for REST API operations** that configure, set up, and manage Wix business entities on your site. These recipes use REST API calls and are designed for:
+
+- **Site setup and configuration** — Initial setup of stores, bookings, payments, and other business apps
+- **Entity management** — Creating, updating, and deleting products, services, staff members, pricing plans
+- **Administrative operations** — Bulk updates, contact labeling, data migrations
+- **Backend integrations** — Server-to-server automations, webhooks, data synchronization
+
+These recipes do NOT cover frontend development or SDK usage for displaying data to users.
+
+---
+
+## App Installation
+
+### [Install Wix Apps](references/app-installation/install-wix-apps.md)
+**Technical:** Installs Wix apps on a site using Apps Installer API. Covers enabling Velo (Wix Code), app installation, and common app definition IDs.
+
+### [List Installed Apps](references/app-installation/list-installed-apps.md)
+**Technical:** Lists all apps installed on a site using Apps Installer API. Useful for verifying app installations before making API calls and diagnosing authorization errors.
+
+---
+
+## Blog
+
+### [How to Create Blog Posts](references/blog/how-to-create-blog-posts.md)
+**Technical:** Creates and publishes blog posts using Blog Posts API. Covers Ricos rich content format, image upload via Media Manager, category/tag assignment, and bulk post creation.
+
+---
+
+## Bookings
+
+### [Booking Service Policy Setup](references/bookings/booking-service-policy-setup.md)
+**Technical:** Sets up booking policies, cancellation rules, and waitlist configuration using the Services API policy fields. Covers bookingPolicy, cancellationPolicy, and waitlist settings.
+
+### [Booking System Integration Gaps](references/bookings/booking-system-integration-gaps.md)
+**Technical:** Documents undocumented API patterns for booking payments. Covers Bookings→Ecommerce integration, booking ID transformation to catalog items, and async payment confirmation flows.
+
+### [Bookings Staff Setup](references/bookings/bookings-staff-setup.md)
+**Technical:** Creates staff members and configures custom working hours using Staff API + Calendar Events API. Critical two-step process: create staff → assign schedule → create working hours events.
+
+### [Create and Update Booking Services](references/bookings/create-and-update-booking-services.md)
+**Technical:** Full CRUD operations for Wix Bookings services using Services API. Covers service types (APPOINTMENT, CLASS, COURSE), pricing configuration, location setup, and schedule management.
+
+### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
+**Technical:** Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
+
+### [External Calendar Integration](references/bookings/external-calendar-integration.md)
+**Technical:** OAuth-based integration with Google Calendar, Microsoft Outlook, and Apple Calendar. Covers authentication flows, sync configuration, and bidirectional event management.
+
+### [Multi-Resource Service Creation](references/bookings/multi-resource-service-creation.md)
+**Technical:** Creates resource types and individual resources using Resources API. Enables services that require multiple resources (rooms + equipment + staff) with automatic allocation.
+
+---
+
+## Calendar
+
+### [Configure Default Business Hours](references/calendar/configure-default-business-hours.md)
+**Technical:** Uses Calendar Events API to create WORKING_HOURS events on the business schedule. Covers the critical distinction between Calendar Events API (correct) vs Site Properties API (incorrect) for setting base availability.
+
+---
+
+## CMS
+
+### [CMS Data Items CRUD](references/cms/cms-data-items-crud.md)
+**Technical:** Add, query, update, and delete items in CMS collections. Use this to insert content, bulk insert/update/patch/delete items, query with filters, and manage collection data. Key endpoints: /wix-data/v2/items, /wix-data/v2/bulk/items/*.
+
+### [CMS Data Operations Extended](references/cms/cms-data-operations-extended.md)
+**Technical:** Additional CMS data operations including count, upsert (bulk save), and update by filter patterns.
+
+### [CMS eCommerce Catalog Integration](references/cms/cms-ecommerce-catalog-integration.md)
+**Technical:** The recommended way to sell existing CMS collection items (tickets, bookings, memberships) through Wix checkout. Add the CATALOG plugin to convert any CMS collection into purchasable products with cart and payment integration.
+
+### [CMS References & Relationships](references/cms/cms-references-and-relationships.md)
+**Technical:** Add, replace, or remove items from MULTI_REFERENCE fields. Use insert-references, replace-references, remove-references endpoints. Required for managing multi-reference relationships - these CANNOT be set via regular insert/update/patch operations. Also covers single references and querying with expanded references.
+
+### [CMS Schema Management](references/cms/cms-schema-management.md)
+**Technical:** Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields, and updating collection settings.
+
+---
+
+## Contacts
+
+### [Bulk Delete Contacts](references/contacts/bulk-delete-contacts.md)
+**Technical:** Deletes multiple contacts using filter-based bulk delete. Covers safe deletion patterns, GDPR compliance, soft delete alternatives, and batch processing strategies.
+
+### [Bulk Label and Unlabel Contacts](references/contacts/bulk-label-and-unlabel-contacts.md)
+**Technical:** Adds/removes labels from multiple contacts using Contacts API bulk operations. Covers label creation, contact filtering, batch processing, and rate limit handling.
+
+---
+
+## Domains
+
+### [Domain Search and Purchase](references/domains/domain-search-and-purchase.md)
+**Technical:** Search for available domains, get domain suggestions, and generate purchase links using Domain Search V2 API. Covers availability checks, TLD filtering, and connecting domains to Wix sites.
+
+---
+
+## 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)
+
+### [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.
+
+### [Setup Store Pickup Location](references/ecommerce/setup-store-pickup-location.md)
+**Technical:** Configures in-store pickup at checkout using Delivery Profiles API.
+
+### [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.
+
+### [Troubleshoot: Checkout Delivery Drop-off](references/ecommerce/troubleshoot-checkout-delivery-dropoff.md)
+**Technical:** Diagnostic tree for delivery step conversion below 65% benchmark.
+
+<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)
+- [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)
+
+</details>
+
+---
+
+## Events
+
+### [List Events](references/events/list-events.md)
+**Technical:** Queries events from Wix Events using Events API. Covers field sets (DETAILS, URLS, REGISTRATION), filtering by status/date, and pagination.
+
+---
+
+## Forms
+
+### [Create Form](references/forms/create-form.md)
+**Technical:** Creates a form with fields (name, email, etc.) using the Form Schemas API. Covers field configuration, layout, and post-submission triggers.
+
+---
+
+## Get Paid
+
+### [Create Payment Links](references/get-paid/create-payment-links.md)
+**Technical:** Creates payment links for collecting payments without a checkout flow. Covers store products (catalog items), custom line items, variants, due dates, and sending links via email.
+
+### [How to Setup Wix Payments](references/get-paid/how-to-setup-wix-payments.md)
+**Technical:** Configures Wix Payments as the payment provider. Covers eligibility checking, business verification, bank account setup, and payment method configuration (cards, PayPal, Apple Pay).
+
+### [Payment Links for Bookings](references/get-paid/payment-links-for-bookings.md)
+**Technical:** Creates payment links for unpaid bookings using Payment Links API. Links booking IDs to payment requests with proper redirect handling.
+
+---
+
+## Media
+
+### [Upload Media to Wix](references/media/upload-media-to-wix.md)
+**Technical:** Uploads images and files to the Wix Media Manager using the Import File API. Covers importing from external URLs, checking file status, and using the returned wixstatic.com URL in other APIs.
+
+---
+
+## Pricing Plans
+
+### [Create and Update Pricing Plans](references/pricing-plans/create-and-update-pricing-plans.md)
+**Technical:** Creates subscription and one-time payment plans using Plans API. Covers pricing models (recurring, one-time, free), trial periods, perks configuration, and plan visibility.
+
+### [Pricing Plans Bookings Integration](references/pricing-plans/pricing-plans-bookings-integration.md)
+**Technical:** Links Pricing Plans to Bookings services using the Benefit Programs API. Enables package deals and memberships that grant booking access.
+
+---
+
+## Restaurants
+
+### [Wix Restaurants Setup](references/restaurants/wix-restaurants-setup.md)
+**Technical:** Configures restaurant menus, sections, and items using Menus API. Covers menu structure (Menu → Section → Item), modifiers, pricing, availability schedules, and ordering settings.
+
+---
+
+## Rich Content
+
+### [Ricos Converter Service](references/rich-content/ricos-converter-service.md)
+**Technical:** Validates and converts content between Ricos documents and HTML/Markdown/plain text using the Ricos Documents API. Covers plugin configuration, format conversion in both directions, and document validation.
+
+---
+
+## Site Properties
+
+### [Change Payment Currency](references/site-properties/change-payment-currency-site-properties.md)
+**Technical:** Updates the site-level payment currency (store billing currency) using Site Properties API, including the required request body shape and field mask.
+
+---
+
+## Sites
+
+### [Create Site from Template](references/sites/create-site-from-template.md)
+**Technical:** Creates new Wix sites from templates using account-level APIs. Covers template search, site creation, headless site setup, OAuth app creation, and publishing.
+
+### [Query Sites](references/sites/query-sites.md)
+**Technical:** Lists and queries all sites associated with a Wix account using Sites API. Covers pagination with cursor-based navigation.
+
+---
+
+## Stores
+
+### [Add Store Pages to Site](references/stores/add-store-pages-to-site.md)
+**Technical:** Adds missing checkout and cart pages to a site when Stores app is installed. Used when store pages are missing after migration or setup issues.
+
+### [Bulk Create Products with Options](references/stores/bulk-create-products-with-options.md)
+**Technical:** Uses bulk products endpoint to create multiple products with inventory in a single request. Handles variant generation from options, media format requirements, and error handling for partial failures.
+
+### [Create Product from Image](references/stores/create-product-from-image.md)
+**Technical:** **MANDATORY entry point** for any "create product from image" or "create product from photo" request. STEP 1 auto-detects the site's catalog version (V1/V3) via the provision endpoint, then runs the matching flow inline — V3 supports up to 3 images, info sections, SEO, options/variants, and atomic creation; V1 supports a single image, simple product, and a separate media-attach call. Combines Media Upload + LLM analysis + Product Creation + (V1 only) Add Product Media in one self-contained recipe.
+
+
+### [Create Product (Catalog V1)](references/stores/create-product-catalog-v1.md)
+**Technical:** Create products using the Catalog V1 Products API. Use this recipe when the site's catalog version is CATALOG_V1. Covers simple product creation, product with options, and key V1 request structure differences from V3.
+
+### [Create Product with Options (Catalog V3)](references/stores/create-product-with-options-catalog-v3.md)
+**Technical:** Single product creation with options using Catalog V3 Products API. Covers option types (TEXT_CHOICES, SWATCH_CHOICES), choice configuration, and automatic variant generation.
+
+### [Find Products (Query and Search, Catalog V3)](references/stores/find-products-query-and-search-catalog-v3.md)
+**Technical:** Find, search, query, and list products from a Wix Store using Catalog V3 Search Products and Query Products endpoints. Explains when to use each endpoint, correct fields enum values, filtering, sorting, and paging.
+
+### [Query Products (Catalog V1)](references/stores/query-products-catalog-v1.md)
+**Technical:** Query and list products from a Wix Store using the Catalog V1 Query Products endpoint. Use this recipe when the site's catalog version is CATALOG_V1. Covers basic queries, filtering, sorting, and paging.
+
+### [Setup Online Store (Catalog V3)](references/stores/setup-online-store-catalog-v3.md)
+**Technical:** Initializes a Stores catalog with Catalog V3 Products API, bulk products endpoint, and Categories API. Covers product creation, option configuration, variant management, and category assignment.
+
+### [Update Product Pre-Order](references/stores/update-product-pre-order.md)
+**Technical:** Manages pre-order settings for product variants using V3 Inventory API. Covers enabling/disabling pre-orders, setting messages, configuring limits, and handling trackQuantity requirements.
+
+### [Update Product with Options](references/stores/update-product-with-options.md)
+**Technical:** Modifies existing products and variants using Catalog V3 Products API. Covers adding/removing option choices, variant-specific pricing, and revision-based updates to prevent conflicts.

package/skills/wix-manage/references/app-installation/install-wix-apps.md

@@ -0,0 +1,155 @@
+---
+name: "Install Wix Apps"
+description: Installs Wix apps on a site using Apps Installer API. Covers enabling Velo (Wix Code), app installation, and common app definition IDs.
+---
+# Install Wix Apps on a Site
+
+This recipe guides you through installing Wix apps on a site using the Apps Installer REST API, including enabling Velo (Wix Code) when needed.
+
+## Prerequisites
+
+- Site ID where apps will be installed
+- Knowledge of which app to install (see [Apps Created by Wix](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix))
+
+## Required APIs
+
+- **Apps Installer API**: [REST](https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app)
+
+---
+## Step 0: Find the App ID (skip if you already have it)
+
+If you already know the `appDefId` (e.g. from the table of Wix-built apps below), skip to Step 1.
+
+For any third-party app, or any app you only know by name, resolve the ID first using the Search Market Listings API.
+
+**Endpoint**: `POST https://www.wixapis.com/devcenter/app-market-listing/v1/market-listings/search`
+
+**Request**:
+```bash
+curl -X POST \
+  'https://www.wixapis.com/devcenter/app-market-listing/v1/market-listings/search' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{ "searchTerm": "Usercentrics" }'
+```
+
+**Response** (truncated):
+```json
+{
+  "marketListings": [
+    {
+      "appId": "b8cfbda5-91e8-45ad-8c8d-4d4700534ab5",
+      "basicInfo": { "name": "Usercentrics for Wix", ... }
+    }
+  ]
+}
+```
+
+Use the returned `appId` as the `appDefId` in Step 2.
+
+### IMPORTANT NOTES
+- The `appDefId` field in the install request and the `appId` field returned here are the same value
+- If multiple results come back, match on `basicInfo.name` to confirm you have the right app before installing
+- Only listings with `status: "PUBLISHED"` can be installed
+## Step 1: Enable Velo (Wix Code) if Needed
+
+If you receive the error `WDE0110: Wix Code not enabled`, you must first enable Velo on the site.
+
+**Endpoint**: `POST https://www.wixapis.com/mcp-serverless/v1/velo/provision`
+
+**Request**:
+```bash
+curl -X POST \
+  'https://www.wixapis.com/mcp-serverless/v1/velo/provision/' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+**Response**: Empty body on success.
+
+### IMPORTANT NOTES:
+- Only call this endpoint if you receive the `WDE0110` error
+- This is a one-time operation per site
+
+---
+
+## Step 2: Install the Wix App
+
+Use the Apps Installer API to install any Wix app on a site.
+
+**Endpoint**: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install`
+
+**Request Body**:
+```json
+{
+  "tenant": {
+    "tenantType": "SITE",
+    "id": "<SITE_ID>"
+  },
+  "appInstance": {
+    "appDefId": "<APP_DEF_ID>"
+  }
+}
+```
+
+**Request**:
+```bash
+curl -X POST \
+  'https://www.wixapis.com/apps-installer-service/v1/app-instance/install' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tenant": {
+      "tenantType": "SITE",
+      "id": "<SITE_ID>"
+    },
+    "appInstance": {
+      "appDefId": "<APP_DEF_ID>"
+    }
+  }'
+```
+
+### Common App Definition IDs
+
+Before installing, refer to the [Apps Created by Wix](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix) documentation to find the correct `appDefId` for the app you want to install.
+
+Some common apps:
+| App | appDefId |
+|-----|----------|
+| Wix Stores | `215238eb-22a5-4c36-9e7b-e7c08025e04e` |
+| Wix Bookings | `13d21c63-b5ec-5912-8397-c3a5ddb27a97` |
+| Wix Blog | `14bcded7-0066-7c35-14d7-466cb3f09103` |
+| Wix Events | `140603ad-af8d-84a5-2c80-a0f60cb47351` |
+| Wix Pricing Plans | `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3` |
+
+### IMPORTANT NOTES:
+- NEVER guess the `appDefId`. For Wix-built apps, use the table above. For any other app, resolve the ID using Step 0 (Search Market Listings).
+- The `tenantType` MUST be `SITE`
+- The `id` in tenant is the site's metaSiteId
+
+---
+
+## Error Handling
+
+### App Not Installed Error
+If you receive an error indicating a required app is not installed, use this recipe to install it before proceeding.
+
+### WDE0110: Wix Code not enabled
+Call the Velo provision endpoint (Step 1) first, then retry the original operation.
+
+---
+
+## Next Steps
+
+After installing an app:
+- Configure the app's settings using its specific APIs
+- Set up any required app-specific data (products for Stores, services for Bookings, etc.)
+
+---
+
+## Common Pitfalls
+
+- **"I don't have the appDefId"** → Run Step 0. The table in Step 2 only covers Wix-built apps; the App Market has thousands of others.
+- **Don't try to scrape the App Market website to find IDs** — pages are client-rendered and the appId is not in the HTML. Use Search Market Listings instead.
+- **Don't try `InstallAppFromShareUrl` as a workaround for unknown IDs** — `shareUrlId` is an internal identifier you generally don't have either.