@wix/agent-skills 1.18.2 → 1.19.1

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/catalog.ts

@@ -133,33 +133,108 @@ function toDetail(raw: RawProduct): ProductDetail {
   };
 }
 
-/** List visible products (newest catalog order), mapped to grid-ready DTOs. */
-export async function fetchProducts({ limit = 100 } = {}): Promise<ProductSummary[]> {
-  const res = await products
-    .queryProducts({ fields: LIST_FIELDS as any })
-    .limit(limit)
-    .find();
-  return (res.items ?? []).map((p) => toSummary(p as RawProduct));
+// Search Products applies sort/filter/search server-side, across the WHOLE catalog, before
+// cursor paging — the only correct place for them. Sorting or filtering an already-fetched
+// page only rearranges the slice you happen to hold.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
+export const CATALOG_SORTS = {
+  featured: { label: "Default order" }, // the catalog's own order; no merchant-curated promise
+  priceAsc: { label: "Price: low to high" },
+  priceHigh: { label: "Price: high to low" },
+  name: { label: "Name: A\u2013Z" },
+  newest: { label: "Newest" },
+} as const;
+export type CatalogSort = keyof typeof CATALOG_SORTS;
+
+const SORT_FIELDS: Partial<Record<CatalogSort, { fieldName: string; order: "ASC" | "DESC" }[]>> = {
+  priceAsc: [{ fieldName: "actualPriceRange.minValue.amount", order: "ASC" }, { fieldName: "name", order: "ASC" }],
+  priceHigh: [{ fieldName: "actualPriceRange.minValue.amount", order: "DESC" }, { fieldName: "name", order: "ASC" }],
+  name: [{ fieldName: "name", order: "ASC" }],
+  newest: [{ fieldName: "createdDate", order: "DESC" }, { fieldName: "name", order: "ASC" }],
+};
+
+function priceBound(value: number | string | undefined, name: string): number | undefined {
+  if (value == null || value === "") return undefined;
+  const parsed = Number(value);
+  if (!String(value).trim() || !Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${name} must be a non-negative number.`);
+  }
+  return parsed;
+}
+
+export interface CatalogSearchOptions {
+  limit?: number;
+  /** Continues the ORIGINAL query — pass alone; new sort/filter values start without one. */
+  cursor?: string;
+  categoryId?: string | null;
+  sort?: CatalogSort;
+  /** Bounds compare the product's minimum actual variant price, in site currency. */
+  minPrice?: number | string;
+  maxPrice?: number | string;
+  inStockOnly?: boolean;
+  /** Name search, max 100 chars. */
+  search?: string;
 }
 
 /**
- * List visible products in a category, server-side-filtered by the live category id.
- * Category filtering MUST go through searchProducts (the field is not filterable in
- * queryProducts) with the $matchItems operator — this is encoded here so callers never
- * reconstruct it.
+ * Search visible catalog products — sorted, filtered, and searched by Wix across the whole
+ * catalog, then cursor-paged. `nextCursor` continues the same query; start over (no cursor)
+ * whenever any selection changes.
  */
+export async function searchCatalog({
+  limit = 24,
+  cursor,
+  categoryId,
+  sort = "featured",
+  minPrice,
+  maxPrice,
+  inStockOnly = false,
+  search = "",
+}: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null }> {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+    throw new Error("limit must be between 1 and 100.");
+  let query: RawProduct = { cursorPaging: { limit, ...(cursor ? { cursor } : {}) } };
+  if (!cursor) {
+    if (!(sort in CATALOG_SORTS)) throw new Error("Unsupported catalog sort.");
+    const min = priceBound(minPrice, "minPrice");
+    const max = priceBound(maxPrice, "maxPrice");
+    if (min !== undefined && max !== undefined && min > max)
+      throw new Error("minPrice must not exceed maxPrice.");
+    if (search.trim().length > 100) throw new Error("Search must be at most 100 characters.");
+    const conditions: RawProduct[] = [{ visible: true }];
+    if (categoryId)
+      conditions.push({ "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } });
+    // Search rejects two operators in one field object — separate bounds, joined by $and.
+    if (min !== undefined)
+      conditions.push({ "actualPriceRange.minValue.amount": { $gte: String(min) } });
+    if (max !== undefined)
+      conditions.push({ "actualPriceRange.minValue.amount": { $lte: String(max) } });
+    if (inStockOnly) conditions.push({ "inventory.availabilityStatus": { $eq: "IN_STOCK" } });
+    query = {
+      ...query,
+      filter: { $and: conditions },
+      ...(SORT_FIELDS[sort] ? { sort: SORT_FIELDS[sort] } : {}),
+      ...(search.trim() ? { search: { expression: search.trim(), fields: ["name"] } } : {}),
+    };
+  }
+  const res: RawProduct = await products.searchProducts(query, { fields: LIST_FIELDS as any });
+  return {
+    products: (res.products ?? []).map((p: RawProduct) => toSummary(p)),
+    nextCursor: res.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/** First page of visible products in the default order — a thin wrap of searchCatalog. */
+export async function fetchProducts({ limit = 24 } = {}): Promise<ProductSummary[]> {
+  return (await searchCatalog({ limit })).products;
+}
+
+/** First page of a category — same wrap; category filtering only works through search. */
 export async function fetchProductsByCategory(
   categoryId: string,
-  { limit = 100 } = {},
+  { limit = 24 } = {},
 ): Promise<ProductSummary[]> {
-  const res: RawProduct = await products.searchProducts(
-    {
-      filter: { "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } },
-      cursorPaging: { limit },
-    },
-    { fields: LIST_FIELDS as any },
-  );
-  return (res.products ?? []).map((p: RawProduct) => toSummary(p));
+  return (await searchCatalog({ limit, categoryId })).products;
 }
 
 /** Fetch one product by its URL slug, with options/modifiers/variants. Null when not found. */

package/skills/wix-headless-fast/references/storefront/seed/SEED.md

@@ -31,7 +31,8 @@ node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
     { "name": "Backstage Guide", "description": "…", "price": 12,
       "digitalFilePath": "/Users/me/guide.pdf" }
   ],
-  "categories": { "Legends": ["The Glam Rocker"], "Rising Stars": [] }
+  "categories": { "Legends": ["The Glam Rocker"], "Rising Stars": [] },
+  "currency": "EUR"
 }
 ```
 
@@ -53,8 +54,20 @@ node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
 - `digitalFilePath` (a file on this machine) or `digitalFileUrl` — makes the product a digital
   download, uploaded and created with both the file and stock (`quantity` is ignored). It's also the
   only way in: a file-less digital product is created successfully, reads back healthy, and is then
-  rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`.
+  rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`. **No real file in hand?** Don't invent a
+  URL and don't ship the product as digital — seed it physical with stock (drop
+  `digitalFilePath`/`digitalFileUrl`, add `inStock` or a `quantity`) and tell the user the
+  download needs a real file before it can be sold.
 - `categories` — category name → product NAMES. Omit when the brief names none.
+- `quantity` — tracked stock, a non-negative integer. For stock that isn't counted (made to
+  order, print on demand, unlimited) use `"inStock": true` **instead** of `quantity`; sending
+  both is rejected.
+- `currency` — 3-letter ISO code. Set it **only when the brief names one** ("prices in euros",
+  "a German store charging EUR"). Do **not** infer it from a language, a country, or an address
+  — an unrequested switch silently reprices the whole catalog. The seed applies it before
+  creating anything, because a product's price is stored in the site currency at create time.
+  For a few seconds afterwards product reads can still report the old currency; that lag is
+  expected and self-resolves, so don't re-verify it or retry.
 
 **Default to 3 products** unless the brief asks for a specific catalog — the seed shows the
 shape, not a full inventory; the owner adds the rest in the dashboard. **Make those 3 exercise
@@ -64,6 +77,12 @@ truthfully to the business (a ceramics studio has glaze colors; a bakery doesn't
 **Seeding is additive — never delete or overwrite existing content.** No cleanup, no removing
 "sample" data, no resets. If a cleanup genuinely seems needed, ask the user first.
 
+**A bulk create can partially succeed.** The result carries `failures: [{ name, error }]` next
+to `products` — read it. A non-empty `failures` means those products are genuinely absent, not
+mis-mapped, so the rest of the catalog is fine to build on. To retry, re-run the **same** plan:
+creation is idempotent by name, so products that already exist are skipped rather than
+duplicated. Never hand-patch ids to "fill the gap".
+
 Two things this module does not seed (dashboard-only — tell the merchant):
 **ribbons** ("New", "Best Seller") and **per-choice linked media** (color choice → gallery photo).
 

package/skills/wix-headless-fast/references/storefront/seed/seed-store.mjs

@@ -162,7 +162,7 @@ function buildOptions(options = []) {
 }
 
 // Full Cartesian product, each variant priced/stocked from the product; visible:true baked in.
-function expandVariants(options = [], { price, compareAtPrice, quantity }, digitalFileId) {
+function expandVariants(options = [], { price, compareAtPrice, quantity, inStock }, digitalFileId) {
   const base = {
     price: {
       actualPrice: { amount: String(price) },
@@ -171,7 +171,10 @@ function expandVariants(options = [], { price, compareAtPrice, quantity }, digit
     visible: true,
     ...(digitalFileId
       ? { digitalProperties: { digitalFile: { id: digitalFileId } }, inventoryItem: { inStock: true } }
-      : { physicalProperties: {}, inventoryItem: { quantity: quantity ?? 0, preorderInfo: { enabled: false } } }),
+      // inStock:true == untracked stock — always buyable, no count. Otherwise track a quantity.
+      : { physicalProperties: {}, inventoryItem: inStock === true
+          ? { inStock: true }
+          : { quantity: quantity ?? 0, preorderInfo: { enabled: false } } }),
   };
   if (!options.length) return [base];
   let combos = [[]];
@@ -235,7 +238,10 @@ async function uploadDigitalFile(ctx, { digitalFileUrl, digitalFilePath, digital
   const bytes = digitalFilePath
     ? readFileSync(digitalFilePath)
     : await fetch(digitalFileUrl).then((r) => {
-        if (!r.ok) throw new Error(`digitalFileUrl ${digitalFileUrl} -> ${r.status}`);
+        // Don't invent a file and don't ship an unbuyable DIGITAL product: seed it PHYSICAL
+        // with stock (drop digitalFileUrl/digitalFilePath, set inStock or a quantity) and
+        // tell the user the download still needs a real file.
+        if (!r.ok) throw new Error(`digitalFileUrl ${digitalFileUrl} -> ${r.status}. No fetchable file: re-seed this product as PHYSICAL with stock and tell the user it needs a real file before it can be sold as a download.`);
         return r.arrayBuffer();
       });
   const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", { body: { mimeType, fileName } });
@@ -266,15 +272,36 @@ export async function bulkCreateProducts(ctx, products) {
   };
   const r = await req(ctx, "/stores/v3/bulk/products-with-inventory/create", { body });
   // NB: results nest under productResults.results[].item — NOT a top-level `results`.
-  const created = (r.productResults?.results ?? []).map((x, i) => ({
-    id: x.item?.id, slug: x.item?.slug, revision: x.item?.revision,
-    variantId: x.item?.variantsInfo?.variants?.[0]?.id,
-    hasOptions: (products[i]?.options?.length ?? 0) > 0,
-    isDigital: !!fileIds[i],
-    quantity: products[i]?.quantity ?? 0,
-  }));
+  // The bulk returns 200 even on PARTIAL failure, so never map results by array position:
+  // pair each result to its input via itemMetadata.originalIndex and drop the ones that
+  // didn't persist. Positional mapping shifts every id after a failure onto the wrong
+  // product — which then mislabels categories and attaches images to the wrong items.
+  const created = [];
+  const failures = [];
+  for (const x of r.productResults?.results ?? []) {
+    const i = x.itemMetadata?.originalIndex;
+    const src = typeof i === "number" ? products[i] : undefined;
+    if (!x.itemMetadata?.success || !x.item?.id) {
+      failures.push({
+        name: src?.name,
+        error: x.itemMetadata?.error?.description ?? x.itemMetadata?.error?.code ?? "unknown",
+      });
+      continue;
+    }
+    created.push({
+      id: x.item.id, slug: x.item.slug, revision: x.item.revision, name: src?.name,
+      variantId: x.item.variantsInfo?.variants?.[0]?.id,
+      hasOptions: (src?.options?.length ?? 0) > 0,
+      isDigital: !!fileIds[i],
+      quantity: src?.quantity ?? 0,
+      inStock: src?.inStock,
+    });
+  }
   await stockOptionlessProducts(ctx, created);
-  return created.map((p) => ({ id: p.id, slug: p.slug, revision: p.revision }));
+  return {
+    created: created.map((p) => ({ id: p.id, slug: p.slug, revision: p.revision, name: p.name })),
+    failures,
+  };
 }
 
 // The bulk create stocks a variant via its choices; an OPTION-LESS product's single default
@@ -290,9 +317,15 @@ async function stockOptionlessProducts(ctx, created) {
     const vById = new Map((q.products ?? []).map((p) => [p.id, p.variantsInfo?.variants?.[0]?.id]));
     need.forEach((p) => { if (!p.variantId) p.variantId = vById.get(p.id); });
   }
+  // inStock:true == untracked stock (always buyable, no count). Only send a quantity when the
+  // product actually tracks one, or Wix rejects the pair.
   const inventoryItems = need
     .filter((p) => p.variantId)
-    .map((p) => ({ productId: p.id, variantId: p.variantId, quantity: p.quantity }));
+    .map((p) => ({
+      productId: p.id,
+      variantId: p.variantId,
+      ...(p.inStock === true ? { inStock: true } : { quantity: p.quantity }),
+    }));
   if (inventoryItems.length) {
     await req(ctx, "/stores/v3/bulk/inventory-items/create", { body: { inventoryItems } });
   }
@@ -342,20 +375,68 @@ export async function attachProductImages(ctx, items) {
   });
 }
 
+// Reject plans the API would reject halfway through, while nothing has been created yet —
+// a mid-batch 400 leaves a half-seeded store that the agent then has to reason about.
+export function validateProducts(products) {
+  const problems = [];
+  const colorByName = new Map();
+  products.forEach((p, i) => {
+    const where = p.name ? `"${p.name}"` : `product #${i + 1}`;
+    if (!p.name) problems.push(`${where}: name is required`);
+    if (p.quantity != null && (!Number.isInteger(p.quantity) || p.quantity < 0)) {
+      problems.push(`${where}: quantity must be a non-negative integer (got ${p.quantity}) — omit it and set inStock:true for untracked stock`);
+    }
+    for (const opt of p.options ?? []) {
+      const seen = new Set();
+      for (const c of opt.choices ?? []) {
+        const key = typeof c === "string" ? c : c?.name;
+        if (seen.has(key)) problems.push(`${where}: option "${opt.name}" repeats the choice "${key}"`);
+        seen.add(key);
+        // Wix keys a color choice by name, so the same name with two codes collides.
+        const code = typeof c === "object" ? c?.colorCode : undefined;
+        if (code) {
+          const prev = colorByName.get(key);
+          if (prev && prev !== code) problems.push(`color "${key}" is ${prev} on one product and ${code} on another — pick one`);
+          colorByName.set(key, code);
+        }
+      }
+    }
+  });
+  if (problems.length) throw new Error(`invalid seed plan:\n  - ${problems.join("\n  - ")}`);
+}
+
+// Site currency, set BEFORE any product exists (see setupStore). Existing product reads can
+// keep reporting the old currency for a short while after this returns — that lag is expected
+// and self-resolves, so don't re-verify or retry on it.
+// docs: https://dev.wix.com/docs/rest/business-management/site-properties/properties/update-site-properties
+async function setSiteCurrency(ctx, currency) {
+  await req(ctx, "/site-properties/v4/properties", {
+    method: "PATCH",
+    body: { properties: { paymentCurrency: currency }, fields: ["paymentCurrency"] },
+  });
+}
+
 /**
- * ONE-CALL seed: install → create products → categories → attach images, ids threaded in
- * memory. This is the default path — call it once instead of the individual functions.
+ * ONE-CALL seed: install → currency → create products → categories → attach images, ids
+ * threaded in memory. This is the default path — call it once instead of the individual
+ * functions.
  */
-export async function setupStore(ctx, { products = [], categories = {} } = {}) {
+export async function setupStore(ctx, { products = [], categories = {}, currency } = {}) {
+  validateProducts(products);
   await installStoresApp(ctx);
+  // Before any product exists: a product's price is stored in the site currency at create time,
+  // so switching afterwards leaves the catalog priced in the old one.
+  if (currency) await setSiteCurrency(ctx, currency);
 
   // Idempotent by name: an errored bulk create (429/5xx) may still have applied server-side,
   // and SKILL.md tells the agent to re-run a failed seed — creating only the names that don't
   // exist yet makes that rerun safe instead of a duplicator.
   const existing = await queryProductsByNames(ctx, products.map((p) => p.name));
   const toCreate = products.filter((p) => !existing.has(p.name));
-  const created = toCreate.length ? await bulkCreateProducts(ctx, toCreate) : [];
-  const createdByName = new Map(created.map((p, i) => [toCreate[i]?.name, p]));
+  const { created, failures } = toCreate.length
+    ? await bulkCreateProducts(ctx, toCreate)
+    : { created: [], failures: [] };
+  const createdByName = new Map(created.map((p) => [p.name, p]));
   const withNames = products.map((p) => {
     const hit = createdByName.get(p.name) ?? existing.get(p.name);
     return { ...(hit ?? {}), name: p.name };
@@ -381,6 +462,8 @@ export async function setupStore(ctx, { products = [], categories = {} } = {}) {
     prompt: products[i]?.imagePrompt,
     displayName: `${p.slug || "product"}.png`,
   })));
+  // `p.id` guards this: a product that failed to create has no id, and bulk-updating an
+  // undefined id would 400 the whole batch and cost every other product its image.
   const imageItems = withNames
     .map((p, i) => (files[i] && p.id ? { id: p.id, url: files[i].url, altText: products[i]?.altText ?? p.slug } : null))
     .filter(Boolean);
@@ -392,7 +475,10 @@ export async function setupStore(ctx, { products = [], categories = {} } = {}) {
     /* never block on image failure — the products stay text-only */
   }
 
-  return { products: withNames, categories: cats, imagesAttached };
+  // failures is part of the result, not an exception: a partial seed still leaves a usable
+  // store, and the agent needs the names to report rather than silently shipping a short
+  // catalog. Re-run the seed to retry them — existing names are skipped, not duplicated.
+  return { products: withNames, categories: cats, imagesAttached, failures };
 }
 
 // ---- CLI entry ----------------------------------------------------------------------------------

package/skills/wix-manage/SKILL.md

@@ -45,6 +45,9 @@ Read and update SEO titles and tags at the right level. For "change my site's SE
 ### [Generate and Read a Wix Site's Content Plan](references/seo/manage-content-plan.md)
 Generate an SEO content plan and read its blog post topics, or troubleshoot an existing content plan flow stuck at KEYWORD_RESEARCH while polling GetContentPlanFlow. Use this recipe for both generation and stalled-flow questions: it explains the intentional pause, the Create Content Plan release request, missing flow IDs, and the exact public API paths and response fields.
 
+### [Manage Google Search Console for a Wix Site](references/seo/manage-google-search-console.md)
+"Connect a Wix site to Google Search Console and drive its setup through the public GSC Connection and Site Readiness APIs: check connection and readiness, start the Google authorization, verify ownership, add the property, submit the sitemap, request indexing, read search performance, run URL inspection, recover a stale connection, or disconnect. The site owner authorizes in their own browser via a single-use connect URL."
+
 ---
 
 ## Accessibility
@@ -77,7 +80,7 @@ Creates and publishes blog posts using Blog Posts API. Covers resolving the requ
 ## Bookings
 
 ### [Booking Service Policy Setup](references/bookings/booking-service-policy-setup.md)
-Sets up booking policies, cancellation rules, and waitlist configuration using the Services API policy fields. Covers bookingPolicy, cancellationPolicy, and waitlist settings.
+Sets up booking policies, cancellation rules, and waitlist configuration using the Booking Policies API — query for the (default) bookingPolicy entity, then PATCH it with its revision. Covers cancellationPolicy, reschedulePolicy, booking-notice limits, waitlistPolicy, and participants limits — e.g. "customers can cancel up to 24 hours before".
 
 ### [Booking System Integration Gaps](references/bookings/booking-system-integration-gaps.md)
 Documents undocumented API patterns for booking payments. Covers Bookings→Ecommerce integration, booking ID transformation to catalog items, and async payment confirmation flows.
@@ -283,7 +286,7 @@ Creates payment links for unpaid bookings using Payment Links API. Links booking
 
 ## Google Ads
 
-**Routing — Google paid-advertising campaigns for a site (Smart & Performance Max).** All flows require a Google Ads account, created once via the setup recipe. Budgets are in micros (1,000,000 = 1 currency unit). REST base: `https://www.wixapis.com/google-ads/v1`.
+**Routing — Google paid-advertising campaigns for a site (Smart & Performance Max).** All flows require a Google Ads account, created once via the setup recipe. Budgets are in micros (1,000,000 = 1 currency unit). REST base: `https://www.wixapis.com/_serverless/pa-google/v1`.
 - **First-time setup / "connect Google Ads" / `ACCOUNT_NOT_FOUND`** → [Install and Create an Account](references/google-ads/install-and-create-account.md) (do this before anything else).
 - **Suggested keywords / geo / budget / ad copy / images** → [Get AI Campaign Suggestions](references/google-ads/get-campaign-suggestions.md).
 - **Offer a Success Guide after creating a PMAX Leads campaign (a proactive offer requires approval) / improve it / success guide / says they completed or fixed a guide recommendation / mark or reopen a recommendation** → [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md) (a direct improvement/guide request is already approval; works while `LEARNING` and before metrics exist).
@@ -293,25 +296,25 @@ Creates payment links for unpaid bookings using Payment Links API. Links booking
 - **Ad spend, fees, upcoming charges, credit balance** → [Retrieve Billing and Payment Details](references/google-ads/billing-and-payment.md).
 
 ### [Install Google Ads and Create an Account](references/google-ads/install-and-create-account.md)
-"One-time setup for running Google paid ads on a Wix site: install the Wix Google Ads app, then create the Google Ads account that every campaign, suggestion, and analytics call depends on. Covers checking whether an account already exists, choosing a currency, optionally attaching a promotional incentive (credit offer), linking a Google Merchant Center account, and deleting an account. Use when the user wants to 'set up Google Ads', 'connect Google Ads', 'start advertising on Google', 'create a Google Ads account', or hits an ACCOUNT_NOT_FOUND / app-not-installed error before creating a campaign. Google Ads REST API, base https://www.wixapis.com/google-ads/v1."
+"One-time setup for running Google paid ads on a Wix site: install the Wix Google Ads app, then create the Google Ads account that every campaign, suggestion, and analytics call depends on. Covers checking whether an account already exists, choosing a currency, optionally attaching a promotional incentive (credit offer), linking a Google Merchant Center account, and deleting an account. Use when the user wants to 'set up Google Ads', 'connect Google Ads', 'start advertising on Google', 'create a Google Ads account', or hits an ACCOUNT_NOT_FOUND / app-not-installed error before creating a campaign. Google Ads REST API, base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Get AI Campaign Suggestions for Google Ads](references/google-ads/get-campaign-suggestions.md)
-"Reference for the Google Ads Suggestions API on a Wix site: AI/Google-generated inputs that help build effective campaigns — keyword themes (from a URL or autocomplete), geo-target options, low/recommended/high daily-budget tiers with estimated clicks, PMAX budget recommendations, text assets (headlines/descriptions), AI image assets (auto-uploaded to Wix Media), search themes, promotional incentive offers, and complete AI-generated campaign configurations from a campaign brief. Use when the user asks 'suggest keywords for my ads', 'what budget should I use', 'where should I target', 'generate ad copy/headlines', 'generate ad images', 'suggest a whole campaign', or when a create-campaign flow needs suggested values. REST base https://www.wixapis.com/google-ads/v1."
+"Reference for the Google Ads Suggestions API on a Wix site: AI/Google-generated inputs that help build effective campaigns — keyword themes (from a URL or autocomplete), geo-target options, low/recommended/high daily-budget tiers with estimated clicks, PMAX budget recommendations, text assets (headlines/descriptions), AI image assets (auto-uploaded to Wix Media), search themes, promotional incentive offers, and complete AI-generated campaign configurations from a campaign brief. Use when the user asks 'suggest keywords for my ads', 'what budget should I use', 'where should I target', 'generate ad copy/headlines', 'generate ad images', 'suggest a whole campaign', or when a create-campaign flow needs suggested values. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Create and Launch a Performance Max Campaign](references/google-ads/create-performance-max-campaign.md)
-"Creates and launches a Google Ads Performance Max (PMAX) campaign for a Wix site — a goal-based campaign that runs across all Google channels (Search, Display, YouTube, Gmail, Discover, Maps) from an asset group of headlines, descriptions, images, and (for PMAX Leads) search-theme signals. Covers generating AI text and image assets, generating search themes, getting a Google budget recommendation, assembling the asset group with the required minimum assets, choosing PERFORMANCE_MAX vs PERFORMANCE_MAX_LEADS (leads: phone/form goals, negative keywords, 28-day learning) vs retail/Shopping (Merchant Center feed), creating in PAUSED, and launching. Use for 'create a Performance Max campaign', 'PMAX', 'run ads across all of Google', 'lead-gen Google campaign', or 'Google Shopping ads'. Requires an existing Google Ads account. REST base https://www.wixapis.com/google-ads/v1."
+"Creates and launches a Google Ads Performance Max (PMAX) campaign for a Wix site — a goal-based campaign that runs across all Google channels (Search, Display, YouTube, Gmail, Discover, Maps) from an asset group of headlines, descriptions, images, and (for PMAX Leads) search-theme signals. Covers generating AI text and image assets, generating search themes, getting a Google budget recommendation, assembling the asset group with the required minimum assets, choosing PERFORMANCE_MAX vs PERFORMANCE_MAX_LEADS (leads: phone/form goals, negative keywords, 28-day learning) vs retail/Shopping (Merchant Center feed), creating in PAUSED, and launching. Use for 'create a Performance Max campaign', 'PMAX', 'run ads across all of Google', 'lead-gen Google campaign', or 'Google Shopping ads'. Requires an existing Google Ads account. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Manage Campaign Lifecycle](references/google-ads/manage-campaign-lifecycle.md)
-"Manages existing Google Ads campaigns on a Wix site: list/get, launch (first activation) vs resume (reactivate after a pause), pause a running campaign — optionally with a scheduled auto-resume date — update name/budget/targeting, change the daily budget, delete permanently, and read status history / change log. Use when the user wants to 'pause my Google ad', 'resume my campaign', 'stop the campaign', 'change my daily budget', 'rename the campaign', 'delete this campaign', 'list my Google Ads campaigns', or 'why did my campaign status change'. Requires an existing Google Ads account and campaign. REST base https://www.wixapis.com/google-ads/v1."
+"Manages existing Google Ads campaigns on a Wix site: list/get, launch (first activation) vs resume (reactivate after a pause), pause a running campaign — optionally with a scheduled auto-resume date — update name/budget/targeting, change the daily budget, delete permanently, and read status history / change log. Use when the user wants to 'pause my Google ad', 'resume my campaign', 'stop the campaign', 'change my daily budget', 'rename the campaign', 'delete this campaign', 'list my Google Ads campaigns', or 'why did my campaign status change'. Requires an existing Google Ads account and campaign. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md)
 "Retrieves and manages the campaign success guide for an existing Wix Google Ads Performance Max Leads campaign. Offer it after creating a supported campaign, even while it is learning or has no metrics; that proactive offer requires approval before retrieval. A direct request to improve a campaign, see what to fix next, or show the guide is already approval to retrieve it. Also use when a user reports completing or wants to reopen a guide item. Treat a clear completion report as an actionable update request even when phrased as a statement. Covers campaign selection, prioritized guide retrieval, and suggestion status updates without redundant confirmation. REST base https://www.wixapis.com/pa-platform/suggestions/v1."
 
 ### [Query Campaign Performance Analytics](references/google-ads/query-campaign-analytics.md)
-"Reads performance analytics for a Google Ads campaign on a Wix site: daily performance metrics (impressions, clicks, CTR, cost, leads, phone calls) with optional previous-period comparison and trends; conversion metrics from Wix Analytics (orders, revenue, leads, CPL, ROAS); the search terms that triggered a campaign's ads; per-product shopping performance for retail campaigns; and per-asset performance (headlines, descriptions, images) for PMAX Leads. Explains when to use campaignResourceName vs the Wix campaignId, the dateRange shape, field enums, sorting, and paging. Use when the user asks 'how is my campaign doing', 'show ad performance', 'what search terms triggered my ads', 'which products/assets perform best', 'campaign ROI/ROAS', or 'conversions from my Google ads'. REST base https://www.wixapis.com/google-ads/v1."
+"Reads performance analytics for a Google Ads campaign on a Wix site: daily performance metrics (impressions, clicks, CTR, cost, leads, phone calls) with optional previous-period comparison and trends; conversion metrics from Wix Analytics (orders, revenue, leads, CPL, ROAS); the search terms that triggered a campaign's ads; per-product shopping performance for retail campaigns; and per-asset performance (headlines, descriptions, images) for PMAX Leads. Explains when to use campaignResourceName vs the Wix campaignId, the dateRange shape, field enums, sorting, and paging. Use when the user asks 'how is my campaign doing', 'show ad performance', 'what search terms triggered my ads', 'which products/assets perform best', 'campaign ROI/ROAS', or 'conversions from my Google ads'. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Retrieve Google Ads Billing and Payment Details](references/google-ads/billing-and-payment.md)
-"Retrieves billing and payment details for a Wix site's Google Ads account: the current billing period's ad spend (usage), the Wix service fee, the total charge, any promotional coupon adjustment, the billing period dates, and the account's credit balance (positive = available credits, negative = outstanding debt not yet charged). Also explains reading current vs remaining budget from the account object. Use when the user asks 'how much have I spent on Google Ads', 'what's my next Google Ads charge', 'show my ad billing', 'do I have ad credits left', 'why was I charged', or 'upcoming Google Ads payment'. Requires an existing Google Ads account. REST base https://www.wixapis.com/google-ads/v1."
+"Retrieves billing and payment details for a Wix site's Google Ads account: the current billing period's ad spend (usage), the Wix service fee, the total charge, any promotional coupon adjustment, the billing period dates, and the account's credit balance (positive = available credits, negative = outstanding debt not yet charged). Also explains reading current vs remaining budget from the account object. Use when the user asks 'how much have I spent on Google Ads', 'what's my next Google Ads charge', 'show my ad billing', 'do I have ad credits left', 'why was I charged', or 'upcoming Google Ads payment'. Requires an existing Google Ads account. REST base https://www.wixapis.com/_serverless/pa-google/v1."
 
 ### [Google Ads Dashboard Navigation](references/google-ads/google-ads-dashboard-navigation.md)
 "Builds a direct link to the Wix Google Ads dashboard page on manage.wix.com, where campaigns created via the Google Ads API recipes are managed. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
@@ -421,6 +424,9 @@ Drive the Wix Site Import agent to migrate an existing store or site from anothe
 ### [Sites Dashboard Navigation](references/sites/sites-dashboard-navigation.md)
 "Builds direct links to the account-level sites pages on manage.wix.com — the My Sites list (all sites in the account) and each site's own dashboard. Pairs the site list with the Query Sites read API. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
 
+### [Upload a Website or HTML Files](references/sites/upload-static-site.md)
+Get a user's ready-made website live on Wix when they already have the site files — an index.html, a zip, or a static build exported from an AI builder or any other tool — by sending them to the Wix Headless drop page, where they upload the files and instantly get a live hosted site they can claim into their account. Use whenever the user wants to upload, publish, or host their own HTML/CSS/JS files as a NEW site. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+
 ---
 
 ## Stores

package/skills/wix-manage/references/bookings/booking-service-policy-setup.md

@@ -1,6 +1,6 @@
 ---
 name: "Booking Service Policy Setup"
-description: Sets up booking policies, cancellation rules, and waitlist configuration using the Services API policy fields. Covers bookingPolicy, cancellationPolicy, and waitlist settings.
+description: Sets up booking policies, cancellation rules, and waitlist configuration using the Booking Policies API (query, then PATCH the bookingPolicy entity with its revision). Covers cancellationPolicy, reschedulePolicy, booking-notice limits, waitlistPolicy, and participants limits — e.g. "customers can cancel up to 24 hours before".
 ---
 
 # Technical Step-by-Step Instructions: Configuring Wix Bookings Service Policies (Real-World, API-First)
@@ -20,72 +20,98 @@ Wix Bookings policy configuration allows businesses to set rules for:
 - **Waitlist policies**: When waitlists are enabled, capacity handling
 - **Group booking policies**: Maximum participants per booking
 
-Policies can be configured at two levels:
+Policies are **standalone entities** managed by the Booking Policies API (`/bookings/v1/booking-policies`), not fields nested on the service:
 
-- **Site-wide (business) policies**: Default rules that apply to all services
-- **Service-specific policies**: Override rules for individual services
+- Installing Wix Bookings creates a **"Default policy"** (`default: true`) that every new service references.
+- Each service points at exactly one policy via its `bookingPolicy` field; many services can share a policy.
+- To change rules site-wide, update the default policy. To give one service different rules, create a separate policy and reference it from that service.
 
 ### IMPORTANT NOTES
 
-- Services inherit from site-wide booking policies by default
-- Service policies only override fields you explicitly specify - unspecified fields keep site defaults
-- Policy options available may vary based on service type (APPOINTMENT, CLASS, COURSE)
-- All policy configurations support the same core features across service types
+- A default policy exists on any site with Wix Bookings installed — **even before any service exists**. "Set a cancellation window" is always actionable by updating the default policy.
+- Policy updates are PATCH-style: send only the sub-policies you want to change, plus the current `revision` (fetched via query/get) inside the `bookingPolicy` object.
+- Policy options are the same across service types (APPOINTMENT, CLASS, COURSE).
 
 ---
 
 ## Steps
 
-### 1. Configure Site-Wide Business Policy (Optional)
+### 1. Find the Policy to Change
 
-Set default policies that will apply to all services unless overridden. Use the Business Policy API to configure booking deadlines, cancellation rules, waitlist settings, and group booking limits.
+Query existing policies (`POST https://www.wixapis.com/bookings/v1/booking-policies/query`):
 
-### 2. Create or Update Service with Policy Overrides
+```json
+{ "query": { "cursorPaging": { "limit": 100 } } }
+```
 
-When creating or updating a service, specify policy fields that should differ from business defaults. Only include the policy fields you want to override - unspecified fields will inherit from business defaults.
+For a site-wide change, pick the policy with `"default": true`. For a specific service, read the service first — its embedded `bookingPolicy.id` names the policy it uses. Save the policy's `id` and `revision`.
 
-### 3. Configure Course-Specific Policies
+### 2. Update the Policy
 
-Courses may have additional policy options such as `bookUntilXMinutesAfterStart` which allows customers to join courses even after they've started.
+`PATCH https://www.wixapis.com/bookings/v1/booking-policies/<POLICY_ID>` with the current `revision` inside the `bookingPolicy` object and only the sub-policies you're changing. Example — cancellations allowed up to 24 hours before the session:
+
+```json
+{
+  "bookingPolicy": {
+    "id": "<POLICY_ID>",
+    "revision": "<CURRENT_REVISION>",
+    "cancellationPolicy": {
+      "enabled": true,
+      "limitLatestCancellation": true,
+      "latestCancellationInMinutes": 1440
+    }
+  }
+}
+```
+
+**Field map (business rule → policy field):**
+
+| Business rule | Sub-policy fields |
+|---|---|
+| Cancellation deadline | `cancellationPolicy.{enabled, limitLatestCancellation, latestCancellationInMinutes}` |
+| Reschedule deadline | `reschedulePolicy.{enabled, limitLatestReschedule, latestRescheduleInMinutes}` |
+| How far ahead customers can book | `limitEarlyBookingPolicy.{enabled, earliestBookingInMinutes}` |
+| Booking notice / last-minute cutoff | `limitLateBookingPolicy.{enabled, latestBookingInMinutes}` |
+| Booking after session start (courses/classes) | `bookAfterStartPolicy.enabled` |
+| Waitlist | `waitlistPolicy.{enabled, capacity, reservationTimeInMinutes}` |
+| Participants per booking | `participantsPolicy.{enabled, maxParticipantsPerBooking}` |
+
+### 3. Per-Service Policies (Optional)
+
+To give one service different rules, create a new policy (`POST https://www.wixapis.com/bookings/v1/booking-policies`) and point the service at it by updating the service's `bookingPolicy` reference (see [Update Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/update-service)).
 
 ### 4. Verify Policy Application
 
-Query the service to confirm policies are applied correctly. The service should show explicitly set policy fields with your specified values and unspecified fields inheriting from business defaults.
+Read the service (`GET /bookings/v2/services/<SERVICE_ID>`) — the response embeds the full resolved `bookingPolicy`, so you can confirm the effective rules exactly as customers will experience them.
 
 ### IMPORTANT NOTES
 
-- **Policy inheritance**: Only specify fields you want to override - leave others undefined to inherit business defaults
-- **Partial updates**: When updating service policies, only include fields you want to change
-- **Capacity requirements**: Waitlist policies require service capacity settings to be configured
-- **Group booking considerations**: `maxParticipantsPerBooking` works with all service types
-- **Time calculations**: Policy deadlines are calculated from booking start time in business timezone
-- **Course flexibility**: Course services support additional policy options like `bookUntilXMinutesAfterStart`
+- **Revision required**: Every policy update needs the current `revision` inside `bookingPolicy`; fetch it first, or the PATCH fails.
+- **Partial updates**: Send only the sub-policies you're changing; the rest keep their values.
+- **Enabled flags matter**: Each sub-policy has an `enabled` (and often a `limit*`) boolean — setting only the minutes value without enabling the limit has no effect.
+- **Time calculations**: Policy deadlines are calculated from the booking's start time, in minutes (24 hours = 1440).
 
 ### Troubleshooting Common Issues
 
 **Policies not applying:**
 
-- Verify you're setting policies on the service object, not as separate policy entities
-- Check that policy fields are properly nested under `service.policy`
-- Ensure you're updating the correct service ID
+- Policies are separate entities — verify you PATCHed `/bookings/v1/booking-policies/<id>`, not fields on the service object (there is no `service.policy` field)
+- Confirm the service actually references the policy you changed (`service.bookingPolicy.id`)
+- Check the `revision` was current — a stale revision fails the update
 
 **Waitlist not working:**
 
-- Confirm service has `maxParticipants` capacity set
-- Verify `waitingListPolicy.enabled` is `true`
-- Check that `waitingListPolicy.capacity` is set if you want limited waitlist size
+- Verify `waitlistPolicy.enabled` is `true` and `waitlistPolicy.capacity` is set
+- Confirm the service has capacity configured (`defaultCapacity` for CLASS/COURSE)
 
 **Cancellation policies not enforced:**
 
-- Ensure `cancelRescheduleUpToInMinutes` is set to appropriate value
-- Verify `cancelationAllowed` is `true` if cancellations should be permitted
-- Check that payment and booking flow supports the configured policy
+- Set all three fields together: `cancellationPolicy.enabled: true`, `limitLatestCancellation: true`, and `latestCancellationInMinutes` — the minutes value alone has no effect without the booleans
 
 **Group booking limits not working:**
 
-- Confirm `maxParticipantsPerBooking` is set to desired limit
-- Verify service type supports group bookings (all types do)
-- Check that booking UI respects the participant limit
+- Confirm `participantsPolicy.enabled` is `true` and `participantsPolicy.maxParticipantsPerBooking` is set
+- Check that the booking UI respects the participant limit
 
 ## API Documentation References