@wix/agent-skills 1.19.0 → 1.19.2

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
@@ -104,7 +107,7 @@ Full CRUD operations for Wix Bookings services using Services API. Covers servic
 "Answers whether an appointment-based Wix Bookings service currently has bookable availability — the primary question — and diagnoses the cause only when there's no availability or the owner asks why. To diagnose, first rules out service-level blockers the availability endpoint can't see (service hidden, online booking off), then runs DiagnoseAvailability for ordered, machine-readable staff/setup reasons, with a manual fallback for booking-policy and capacity causes. Use when someone asks whether a service has availability, or why a service shows no times / customers can't book it."
 
 ### [End-to-End Booking Flow](references/bookings/end-to-end-booking-flow.md)
-Complete booking flow from service discovery to payment. Query services, check availability with Time Slots V2, create bookings, and process payment via eCommerce checkout.
+Books and settles appointments, classes and courses with the site owner's credentials — an operator managing bookings, or server-side code booking as the owner. Covers service discovery, availability with Time Slots V2, creating the booking, and settling it by direct confirmation or eCommerce checkout. A visitor booking for themselves needs a visitor token instead; this recipe links that path.
 
 ### [External Calendar Integration](references/bookings/external-calendar-integration.md)
 OAuth-based integration with Google Calendar, Microsoft Outlook, and Apple Calendar. Covers authentication flows, sync configuration, and bidirectional event management.
@@ -283,35 +286,35 @@ 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).
+- **Improve an existing campaign / see what to fix next / Campaign Success Guide / mark or reopen a recommendation** → [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md).
 - **Create a multi-channel / lead-gen / Shopping campaign** → [Create a Performance Max Campaign](references/google-ads/create-performance-max-campaign.md).
 - **Pause / resume / launch / update budget / delete / history** → [Manage Campaign Lifecycle](references/google-ads/manage-campaign-lifecycle.md).
 - **Performance, conversions, search terms, per-product / per-asset metrics** → [Query Campaign Performance Analytics](references/google-ads/query-campaign-analytics.md).
 - **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."
+"Campaign Success Guide for existing Wix Google Ads Performance Max Leads campaigns. Use after creating a supported campaign, even while it is learning or has no metrics, and whenever users ask how to improve a campaign, what to fix next, to view the guide, or to mark or reopen a recommendation. Covers campaign and site selection; prioritized actionable recommendations; deduplicated, destination-specific Editor and Google Ads navigation; offers to perform supported work after approval; Merchant Center and Business Profile connection follow-ups; and suggestion-status tracking."
 
 ### [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)
+Publish a user's ready-made website — an index.html, a static build, or a zip exported from an AI builder or any other tool — as a new live Wix site. Covers both ways to get there — handing the user the Wix Headless drop page, and calling the Wix Headless instant-site REST API yourself when you can reach the files and make outbound HTTPS requests. When you also hold the user's identity, covers putting the published site straight into their Wix account and reading back its final live URL. Use whenever the user wants to upload, publish, deploy, or host their own HTML/CSS/JS as a NEW site, including files generated for them earlier in the conversation, or to update a site already published this way (iterate on the same site instead of creating another). 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/create-and-update-booking-services.md

@@ -201,6 +201,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Consultation",
       "type": "APPOINTMENT",
@@ -234,6 +235,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Free Consultation",
       "type": "APPOINTMENT",
@@ -264,6 +266,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "Yoga Class",
       "type": "CLASS",
@@ -283,7 +286,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   }'
 ```
 
-After creation, use the `service.schedule.id` from the response to create class events with `bulkCreateEvents` (see Step 3).
+After creation, use `results[0].item.schedule.id` from the response to create class events with `bulkCreateEvents` (see Step 3). This requires `returnEntity: true` on the request — without it the response carries only `results[0].itemMetadata.id`, which has no `schedule.id`; and the created service is directly under `item` (there is no `item.service`).
 
 **Required Fields:**
 

package/skills/wix-manage/references/bookings/create-appointment-service.md

@@ -109,6 +109,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -142,6 +143,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -171,7 +173,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `schedule.availabilityConstraints.sessionDurations` sets the appointment length
 - Availability is based on the assigned staff member's working hours schedule
 
-Save the `serviceId` from the response: `results[0].item.service.id`
+Save the `serviceId` from the response: `results[0].item.id` (the created service is directly under `item` — there is no `item.service`). This requires `returnEntity: true` on the request; without it the response carries only `results[0].itemMetadata.id`.
 
 ---
 

package/skills/wix-manage/references/bookings/create-class-service.md

@@ -96,6 +96,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -124,6 +125,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -149,7 +151,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - `defaultCapacity` is **required** — sets max participants per session
 - After creation, class sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 
-**Response:** Save the service ID from `results[0].itemMetadata.id`
+**Response:** Save the service ID from `results[0].item.id` and the schedule ID for `bulkCreateEvents` from `results[0].item.schedule.id` (the created service is directly under `item`). This requires `returnEntity: true` on the request — without it the response carries only `results[0].itemMetadata.id`, which has no `schedule.id`.
 
 ---
 

package/skills/wix-manage/references/bookings/create-course-service.md

@@ -101,6 +101,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -129,6 +130,7 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
   -H 'Authorization: <AUTH>' \
   -H 'Content-Type: application/json' \
   -d '{
+    "returnEntity": true,
     "services": [{
       "name": "<SERVICE_NAME>",
       "description": "<GENERATED_DESCRIPTION>",
@@ -157,8 +159,8 @@ curl -X POST 'https://www.wixapis.com/bookings/v2/bulk/services/create' \
 - After creation, course sessions must be scheduled separately via `bulkCreateEvents` using the returned `service.schedule.id` (see [Create and Update Booking Services](./create-and-update-booking-services.md))
 - If the user asked you to create the course and gave the session count/times, the job is not complete after `bulkCreateServices`; continue by creating the Calendar events, then verify the service has future events before telling the user it is ready
 
-Save the `serviceId` from the response: `results[0].item.service.id`
-Save the `service.schedule.id` from the response for the follow-up `bulkCreateEvents` request.
+Save the `serviceId` from the response: `results[0].item.id` (the created service is directly under `item` — there is no `item.service`). This requires `returnEntity: true` on the request; without it the response carries only `results[0].itemMetadata.id`.
+Save the `service.schedule.id` from the response (`results[0].item.schedule.id`) for the follow-up `bulkCreateEvents` request.
 
 ---