@wix/agent-skills 1.19.0 → 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
@@ -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/google-ads/billing-and-payment.md

@@ -1,12 +1,12 @@
 ---
 name: "Retrieve Google Ads Billing and Payment Details"
-description: "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."
+description: "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."
 ---
 # RECIPE: Retrieve Google Ads Billing and Payment Details
 
 Report what a site owner will be charged for Google Ads: ad spend, the Wix service fee, coupon adjustments, the total, the billing period, and the account's credit balance.
 
-Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorization` header. This endpoint is read-only.
+Base URL: `https://www.wixapis.com/_serverless/pa-google/v1`. `<AUTH>` is the `Authorization` header. This endpoint is read-only.
 
 **Prerequisite:** a Google Ads account must exist (`ACCOUNT_NOT_FOUND` → run [install-and-create-account](install-and-create-account.md)).
 
@@ -17,7 +17,7 @@ Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorizatio
 Billing is calculated from cached subscription data (not fetched live from Google), and the charge calculation is heavy — this endpoint has a **30-second SLA**, so allow time and don't retry prematurely.
 
 ```bash
-curl -X GET 'https://www.wixapis.com/google-ads/v1/payment-details' -H 'Authorization: <AUTH>'
+curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/payment-details' -H 'Authorization: <AUTH>'
 ```
 
 ```json

package/skills/wix-manage/references/google-ads/create-performance-max-campaign.md

@@ -1,6 +1,6 @@
 ---
 name: "Create and Launch a Performance Max Campaign"
-description: "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."
+description: "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."
 ---
 # RECIPE: Create and Launch a Performance Max Campaign
 
@@ -10,7 +10,7 @@ A **Performance Max (PMAX)** campaign runs across every Google channel from a si
 - **`PERFORMANCE_MAX_LEADS`** — lead-gen variant (phone/form conversions, search-theme signals, negative keywords, a ~28-day learning phase). **Requires** at least one asset group with headlines, descriptions, and images; assets are validated synchronously, so bad assets fail the create call immediately.
 - **Retail / Shopping** — a `PERFORMANCE_MAX` campaign linked to a Google Merchant Center feed (set `merchantCenterAccountId` on the account first — see [install-and-create-account](install-and-create-account.md) — and use `feedLabel`). Retail campaigns don't require a hand-built asset group.
 
-Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. The bidding strategy is server-enforced to `MAXIMIZE_CONVERSIONS` — never set it yourself.
+Base URL: `https://www.wixapis.com/_serverless/pa-google/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. The bidding strategy is server-enforced to `MAXIMIZE_CONVERSIONS` — never set it yourself.
 
 > **Launching spends real money.** Present the assembled asset group and budget and get explicit approval before the Launch call (STEP 5). Create in `PAUSED` first — nothing serves until Launch.
 
@@ -25,7 +25,7 @@ Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorizatio
 `suggestionInfo.landingPageUrl` and `textSuggestionInfo.languageCode` are both required. Response may take up to 60s.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/text-asset-suggestions' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/text-asset-suggestions' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "suggestionInfo": { "landingPageUrl": "https://www.example.com", "assetTypes": ["HEADLINE", "DESCRIPTION"] },
@@ -46,7 +46,7 @@ curl -X POST 'https://www.wixapis.com/google-ads/v1/text-asset-suggestions' \
 Images are generated with AI and **automatically uploaded to the site's Wix Media Manager** — the returned `url` is a `static.wixstatic.com` link you can use directly in the asset group. `suggestionInfo.landingPageUrl` is required.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/image-asset-suggestions' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/image-asset-suggestions' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{ "suggestionInfo": { "landingPageUrl": "https://www.example.com", "assetTypes": ["MARKETING_IMAGE", "SQUARE_MARKETING_IMAGE"] } }'
 ```
@@ -63,7 +63,7 @@ curl -X POST 'https://www.wixapis.com/google-ads/v1/image-asset-suggestions' \
 Search themes are the targeting signals for a leads campaign's asset group. `textSuggestionInfo.languageCode` is required.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/search-theme-suggestions' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/search-theme-suggestions' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{ "landingPageUrl": "https://www.example.com", "textSuggestionInfo": { "languageCode": "en" } }'
 ```
@@ -79,7 +79,7 @@ Each string becomes a `{ "searchTheme": { "text": "…" } }` signal in the asset
 PMAX uses **Generate Budget Recommendation** (not the Smart-campaign budget-suggestions endpoint). `campaignType`, `assetGroupInfo` (with a `finalUrl`), and `currency` are required.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/budget-recommendation' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/budget-recommendation' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "campaignType": "PERFORMANCE_MAX",
@@ -129,7 +129,7 @@ Image `url` must be a Wix Media Manager URL (`static.wixstatic.com`) — the STE
 **Create a PMAX Leads campaign** (status required; create `PAUSED`):
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/campaigns' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/campaigns' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{
     "campaign": {
@@ -178,7 +178,7 @@ Save the returned `campaign.id` and `resourceName`. `status` is read-only and sy
 ## STEP 5: Launch the campaign
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/campaigns/{campaignId}/launch' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/campaigns/{campaignId}/launch' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' -d '{}'
 ```
 

package/skills/wix-manage/references/google-ads/get-campaign-suggestions.md

@@ -1,12 +1,12 @@
 ---
 name: "Get AI Campaign Suggestions for Google Ads"
-description: "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."
+description: "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."
 ---
 # RECIPE: Get AI Campaign Suggestions for Google Ads
 
 The Suggestions API produces the values that make a campaign effective — keywords, locations, budgets, and creative assets — either from Google directly or from Wix's AI. It's the input layer for the create-campaign recipes; this file is the standalone reference for each endpoint and for the two that don't appear there (full campaign suggestions from a brief, and incentive offers).
 
-Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. All suggestion endpoints are **read-only** — none create or spend anything, so run them freely.
+Base URL: `https://www.wixapis.com/_serverless/pa-google/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`. All suggestion endpoints are **read-only** — none create or spend anything, so run them freely.
 
 > **Two conventions to carry into every answer (this is where they trip people up):**
 > - **Budgets come back in micros.** Every `dailyBudget` / `budgetAmountMicros` / `recommendedBudgetAmountMicros` is in micros, where `1,000,000` micros = 1 unit of the account's currency (so `15000000` = $15.00/day). Always convert to currency units when presenting to a user, and pass micros back when creating a campaign.
@@ -39,7 +39,7 @@ Generates one or more complete, ready-to-use campaign configurations — assets,
 - `campaignType` — `SMART` (default) or `PERFORMANCE_MAX_LEADS`.
 
 ```bash
-curl -X POST 'https://www.wixapis.com/google-ads/v1/campaign-suggestions' \
+curl -X POST 'https://www.wixapis.com/_serverless/pa-google/v1/campaign-suggestions' \
   -H 'Authorization: <AUTH>' -H 'Content-Type: application/json' \
   -d '{ "campaignBriefId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "amount": 1, "campaignType": "SMART" }'
 ```
@@ -73,7 +73,7 @@ Present `campaignMessaging` and the config to the user, then use the `campaign`
 Credit offers for **new** accounts, granted after a spend threshold. Only supported currencies return offers. This drives the optional incentive step of [account setup](install-and-create-account.md).
 
 ```bash
-curl -X GET 'https://www.wixapis.com/google-ads/v1/incentives?currency=USD' -H 'Authorization: <AUTH>'
+curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/incentives?currency=USD' -H 'Authorization: <AUTH>'
 ```
 
 Returns `lowOffer` / `mediumOffer` / `highOffer`, each with `incentiveId`, `awardAmount`, and `requiredAmount`, plus a `consolidatedTermsAndConditionsUrl`. Pass the chosen `incentiveId` as `selectedIncentiveId` when creating the account.

package/skills/wix-manage/references/google-ads/google-ads-dashboard-navigation.md

@@ -15,7 +15,7 @@ Build direct links into the Google Ads page of a site's dashboard. For the gener
 
 ## Pairing Entities with Their Read APIs
 
-Fetch state via the Google Ads recipes in this area (`GET /google-ads/v1/accounts/current-site`, `GET /google-ads/v1/accounts/current-site/conversion-actions`), then link the page.
+Fetch state via the Google Ads recipes in this area (`GET /_serverless/pa-google/v1/accounts/current-site`, `GET /_serverless/pa-google/v1/accounts/current-site/conversion-actions`), then link the page.
 
 Example — after creating a campaign: