@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,85 @@
+# Storefront — seeding
+
+Seed the Wix Stores catalog by **running `seed-store.mjs` with a plan file** — don't hand-write
+the REST calls. The script mints its own site token via the Wix CLI (requires a logged-in CLI
+session and a `wix.config.json` in the working directory), installs the Stores app if needed,
+waits for the V3 catalog, and creates everything in the right order.
+
+**Set each product's type by what the buyer receives** — physical (shipped, has `quantity`) or
+digital (a file they keep, `digitalFilePath`/`digitalFileUrl`, no `quantity`); the plan below shows
+both. *Access* — a membership or an online course/program the buyer enrolls in — is Pricing Plans,
+not a store product.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief:
+
+```json
+{
+  "products": [
+    { "name": "The Glam Rocker", "description": "Sequin-studded velvet legend…",
+      "price": 49.99, "quantity": 12, "imageUrl": "https://…" },
+    { "name": "The Understudy", "description": "…", "price": 245, "quantity": 8,
+      "options": [{ "name": "Color", "type": "color",
+                    "choices": [{ "name": "Ink", "colorCode": "#1B1B2F" },
+                                { "name": "Bone", "colorCode": "#EDE6D6" }] }] },
+    { "name": "Encore Jacket", "description": "…", "price": 68, "compareAtPrice": 129,
+      "quantity": 5 },
+    { "name": "Backstage Guide", "description": "…", "price": 12,
+      "digitalFilePath": "/Users/me/guide.pdf" }
+  ],
+  "categories": { "Legends": ["The Glam Rocker"], "Rising Stars": [] }
+}
+```
+
+- `description` — plain text or simple HTML (`<p>`, `<br/>`, `<strong>`, `<em>`); converted to
+  Wix rich text so the storefront renders paragraphs and bold, not tag text.
+- `options` — ONLY things the buyer selects-and-buys (Size, Color); they become variants.
+  `type: "color"` renders as real swatches (give every color choice a `colorCode`); anything
+  else renders as text pills. Variants are expanded automatically (full cross-product, each
+  carrying the product's price/compareAtPrice/quantity) — keep option counts small.
+- `compareAtPrice` (> `price`) — the "was" price: strikethrough on the PDP, sale badge data on
+  the tile.
+- **Give every product an image** (a store without product images looks broken: gray boxes on
+  tiles, PDP, and cart) — the default is an `imagePrompt` (AI-generated, ~1 Wix AI credit
+  per image, account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting —
+  always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use `imagePath` (a file on
+  this machine — uploaded to Wix Media) or `imageUrl` (their own hosted URL; verify it with
+  `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the seed; a failed image leaves
+  that product text-only. Seed text-only only when the user explicitly asks.
+- `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`.
+- `categories` — category name → product NAMES. Omit when the brief names none.
+
+**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
+the shipped UI**: give at least one product a color option and put one product on sale —
+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.
+
+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).
+
+## Escape hatch — individual functions
+
+`setupStore` is built from exported steps; import them only for a partial re-seed or custom
+ordering: `installStoresApp`, `bulkCreateProducts`, `createCategories`,
+`addProductsToCategories`, `attachProductImages` — plus `makeCtx()` for the auth context.
+
+## Reference
+
+If a call returns an unexpected shape or you need an operation this module doesn't cover, read
+the live Wix API reference — never guess. The authoritative source recipe is
+`wix-headless/references/inline-recipes/setup-online-store.md`. Key pages:
+
+- Bulk Create Products With Inventory: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-create-products-with-inventory.md
+- Create Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/create-category.md
+- Bulk Add Items To Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category.md
+- Bulk Update Products (image attach): https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-update-products.md

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

@@ -0,0 +1,415 @@
+// Storefront seed — a BUILD-TIME script, never shipped in the app. Run it from the project
+// root (where wix.config.json lives) with a plan file:
+//
+//   node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
+//
+// It mints its own site token via the Wix CLI (the token never leaves this process), installs
+// the Wix Stores app if needed, waits for the V3 catalog, bulk-creates products (variants
+// expanded, descriptions converted to rich text), creates categories (serially — the shared
+// tree 409s on concurrent creates), assigns products, and attaches images. Prints a JSON
+// result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "products": [{ "name", "description", "price", "compareAtPrice"?, "quantity",
+//                    "options"?: [{ "name", "type"?: "text"|"color",
+//                                   "choices": ["S","M"] | [{ "name", "colorCode" }] }],
+//                    "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"?,
+//                    "digitalFileUrl"? | "digitalFilePath"?, "digitalFileName"? }],
+//     "categories"?: { "<category name>": ["<product name>", ...] } }
+//
+// Seeding is ADDITIVE — this script never deletes or overwrites existing content.
+// If a call fails with an unexpected shape, read the live API reference (the authoritative
+// source recipe is wix-headless/references/inline-recipes/setup-online-store.md) — never guess.
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+
+const API = "https://www.wixapis.com";
+const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+
+// ---- auth: siteId from wix.config.json, token minted by the Wix CLI ----------------------------
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
+  const siteId = config.siteId ?? config.projectId;
+  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
+  // The CLI returns a byte-identical token within a run — mint once, reuse.
+  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
+    encoding: "utf8",
+    cwd,
+  }).trim();
+  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
+  return { token, siteId };
+}
+
+// ---- transport ----------------------------------------------------------------------------------
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  // Retry while the catalog is still provisioning: right after a fresh Stores install the V3
+  // WRITE path becomes usable later than the read path, so the first bulk-create can 428 even
+  // after the read probe clears. Wait it out (~80s budget); other errors throw immediately.
+  // ⚠️ An errored bulk create (seen live with a bare 429 {}) may still have APPLIED
+  // server-side — creation is idempotent by name in setupStore for exactly that reason.
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetch(API + path, {
+      method,
+      headers: {
+        Authorization: `Bearer ${ctx.token}`,
+        "wix-site-id": ctx.siteId,
+        "Content-Type": "application/json",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const json = await res.json().catch(() => ({}));
+    if (res.ok) return json;
+    if (isProvisioning(res.status, json) && attempt < 40) {
+      await sleep(2000);
+      continue;
+    }
+    throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// A freshly installed catalog signals "not writable yet" with a 428 under (at least) two codes.
+const PROVISIONING_CODES = new Set(["CATALOG_V1_SITE_CALLING_CATALOG_V3_API", "CATALOG_V3_SITE_PROVISIONING"]);
+
+function isProvisioning(status, json) {
+  if (PROVISIONING_CODES.has(json?.details?.applicationError?.code)) return true;
+  return status === 428 && /provision/i.test(json?.message || "");
+}
+
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md
+async function waitForCatalogV3(ctx, { attempts = 40, delayMs = 2000 } = {}) {
+  for (let i = 0; i < attempts; i++) {
+    const res = await fetch(`${API}/stores/v3/products/query`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${ctx.token}`, "wix-site-id": ctx.siteId, "Content-Type": "application/json" },
+      body: JSON.stringify({ query: { paging: { limit: 1 } } }),
+    });
+    if (res.ok) return;
+    const json = await res.json().catch(() => ({}));
+    if (!isProvisioning(res.status, json)) return;
+    await sleep(delayMs);
+  }
+}
+
+// ---- description string -> Wix rich-text nodes --------------------------------------------------
+// Descriptions arrive as HTML as often as not. The writable field is `description` (Ricos
+// nodes) — the HTML `plainDescription` the storefront renders is derived from them, so markup
+// dropped into a TEXT node comes back escaped and the PDP shows literal tags. Convert the tags
+// a model actually emits; a tag-free string stays one paragraph.
+
+const HTML_ENTITIES = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'", "&nbsp;": " " };
+
+function decodeEntities(s) {
+  return s.replace(/&(?:amp|lt|gt|quot|#39|nbsp);/g, (m) => HTML_ENTITIES[m] ?? m);
+}
+
+function mkTextNodes(html) {
+  const nodes = [];
+  let bold = 0, italic = 0, last = 0, m;
+  const tag = /<(\/?)(strong|b|em|i)\s*\/?>/gi;
+  const push = (raw) => {
+    const text = decodeEntities(raw.replace(/<[^>]*>/g, ""));
+    if (!text) return;
+    const decorations = [];
+    if (bold > 0) decorations.push({ type: "BOLD" });
+    if (italic > 0) decorations.push({ type: "ITALIC" });
+    nodes.push({ type: "TEXT", textData: { text, decorations } });
+  };
+  while ((m = tag.exec(html)) !== null) {
+    push(html.slice(last, m.index));
+    const step = m[1] ? -1 : 1;
+    if (/^(strong|b)$/i.test(m[2])) bold = Math.max(0, bold + step);
+    else italic = Math.max(0, italic + step);
+    last = tag.lastIndex;
+  }
+  push(html.slice(last));
+  return nodes.length ? nodes : [{ type: "TEXT", textData: { text: "", decorations: [] } }];
+}
+
+function mkDesc(text, i) {
+  const blocks = String(text ?? "").split(/<\/p\s*>|<br\s*\/?>/i).map((b) => b.trim()).filter(Boolean);
+  return {
+    nodes: (blocks.length ? blocks : [""]).map((block, n) => ({
+      type: "PARAGRAPH", id: `desc-${i}-${n}`,
+      nodes: mkTextNodes(block),
+      paragraphData: { textStyle: { textAlignment: "AUTO" } },
+    })),
+    metadata: { version: 1, id: `desc-meta-${i}` },
+  };
+}
+
+// ---- options / variants -------------------------------------------------------------------------
+
+function buildOptions(options = []) {
+  return options.map((o) => {
+    const color = o.type === "color";
+    return {
+      name: o.name,
+      optionRenderType: color ? "SWATCH_CHOICES" : "TEXT_CHOICES",
+      choicesSettings: {
+        choices: o.choices.map((c) =>
+          color
+            ? { choiceType: "ONE_COLOR", name: c.name, colorCode: c.colorCode }
+            : { choiceType: "CHOICE_TEXT", name: typeof c === "string" ? c : c.name }),
+      },
+    };
+  });
+}
+
+// Full Cartesian product, each variant priced/stocked from the product; visible:true baked in.
+function expandVariants(options = [], { price, compareAtPrice, quantity }, digitalFileId) {
+  const base = {
+    price: {
+      actualPrice: { amount: String(price) },
+      ...(compareAtPrice ? { compareAtPrice: { amount: String(compareAtPrice) } } : {}),
+    },
+    visible: true,
+    ...(digitalFileId
+      ? { digitalProperties: { digitalFile: { id: digitalFileId } }, inventoryItem: { inStock: true } }
+      : { physicalProperties: {}, inventoryItem: { quantity: quantity ?? 0, preorderInfo: { enabled: false } } }),
+  };
+  if (!options.length) return [base];
+  let combos = [[]];
+  for (const o of options) {
+    const rt = o.type === "color" ? "SWATCH_CHOICES" : "TEXT_CHOICES";
+    const names = o.choices.map((c) => (typeof c === "string" ? c : c.name));
+    combos = combos.flatMap((combo) =>
+      names.map((choiceName) => [...combo, { optionChoiceNames: { optionName: o.name, choiceName, renderType: rt } }]));
+  }
+  return combos.map((choices) => ({ ...base, choices }));
+}
+
+// ---- operations ---------------------------------------------------------------------------------
+
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installStoresApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: STORES_APP_ID, enabled: true },
+    } });
+  } catch {
+    // already installed is fine — the readiness wait below still confirms the V3 catalog is live
+  }
+  await waitForCatalogV3(ctx);
+}
+
+// Existing products by exact name (for idempotent reruns). `name` is NOT filterable on the
+// V3 query — fetch a page and match client-side (seed catalogs are small). Empty map on any
+// failure — falling back to create-everything is the additive behavior we had before.
+export async function queryProductsByNames(ctx, names) {
+  const out = new Map();
+  if (!names.length) return out;
+  try {
+    const wanted = new Set(names);
+    const r = await req(ctx, "/stores/v3/products/query", { body: { query: { cursorPaging: { limit: 100 } } } });
+    for (const p of r.products ?? []) {
+      if (wanted.has(p.name) && !out.has(p.name)) out.set(p.name, { id: p.id, slug: p.slug, revision: p.revision });
+    }
+  } catch (e) {
+    console.error(`product name pre-check failed (creating everything): ${String(e.message).slice(0, 120)}`);
+  }
+  return out;
+}
+
+// A digital variant is SELLABLE only with BOTH a file and stock: without the file the cart rejects
+// it as ITEM_NOT_FOUND_IN_CATALOG, without stock as "exceeds available inventory" — and either way
+// the product reads back visible and in the catalog, so nothing surfaces until a buyer tries to buy.
+// A digitalFile* field is the only way into DIGITAL here, which makes the file-less product
+// unbuildable. The bytes are PUT, not imported by url: an uploaded file is READY at once, while an
+// imported one stays PENDING and the cart rejects the product until it settles.
+// docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/generate-file-upload-url.md
+const FILE_MIME = { pdf: "application/pdf", zip: "application/zip", epub: "application/epub+zip",
+  mp3: "audio/mpeg", wav: "audio/wav", mp4: "video/mp4", png: "image/png", jpg: "image/jpeg" };
+
+async function uploadDigitalFile(ctx, { digitalFileUrl, digitalFilePath, digitalFileName }) {
+  const src = digitalFilePath ?? digitalFileUrl;
+  const fileName = digitalFileName || decodeURIComponent(basename(new URL(src, "file:").pathname));
+  const mimeType = FILE_MIME[fileName.split(".").pop().toLowerCase()];
+  if (!mimeType) throw new Error(`digitalFileName needs one of these extensions (${Object.keys(FILE_MIME).join(", ")}): ${fileName}`);
+  const bytes = digitalFilePath
+    ? readFileSync(digitalFilePath)
+    : await fetch(digitalFileUrl).then((r) => {
+        if (!r.ok) throw new Error(`digitalFileUrl ${digitalFileUrl} -> ${r.status}`);
+        return r.arrayBuffer();
+      });
+  const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", { body: { mimeType, fileName } });
+  const res = await fetch(uploadUrl, { method: "PUT", headers: { "Content-Type": mimeType }, body: bytes });
+  const json = await res.json().catch(() => ({}));
+  const id = (json.file || json)?.id;
+  if (!res.ok || !id) throw new Error(`digital file upload failed (${res.status}): ${JSON.stringify(json).slice(0, 200)}`);
+  return id;
+}
+
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-create-products-with-inventory.md
+export async function bulkCreateProducts(ctx, products) {
+  const fileIds = await Promise.all(products.map((p) =>
+    p.digitalFileUrl || p.digitalFilePath ? uploadDigitalFile(ctx, p) : null));
+  const body = {
+    returnEntity: true,
+    products: products.map((p, i) => ({
+      name: p.name,
+      // DIGITAL drops physicalProperties and can't be POS-visible (DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS).
+      ...(fileIds[i]
+        ? { productType: "DIGITAL" }
+        : { productType: "PHYSICAL", physicalProperties: {}, visibleInPos: true }),
+      visible: true,
+      description: mkDesc(p.description, i),
+      options: buildOptions(p.options),
+      variantsInfo: { variants: expandVariants(p.options, p, fileIds[i]) },
+    })),
+  };
+  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,
+  }));
+  await stockOptionlessProducts(ctx, created);
+  return created.map((p) => ({ id: p.id, slug: p.slug, revision: p.revision }));
+}
+
+// The bulk create stocks a variant via its choices; an OPTION-LESS product's single default
+// variant is NOT stocked by it and lands OUT_OF_STOCK — stock those explicitly.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/bulk-create-inventory-items.md
+async function stockOptionlessProducts(ctx, created) {
+  const need = created.filter((p) => !p.hasOptions && !p.isDigital && p.id); // digital variants ship inStock from the create
+  if (!need.length) return;
+  const missing = need.filter((p) => !p.variantId).map((p) => p.id);
+  if (missing.length) {
+    const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: missing } }, paging: { limit: missing.length } } } });
+    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); });
+  }
+  const inventoryItems = need
+    .filter((p) => p.variantId)
+    .map((p) => ({ productId: p.id, variantId: p.variantId, quantity: p.quantity }));
+  if (inventoryItems.length) {
+    await req(ctx, "/stores/v3/bulk/inventory-items/create", { body: { inventoryItems } });
+  }
+}
+
+// Categories share the @wix/stores tree revision — concurrent creates 409, so: sequential.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/create-category.md
+export async function createCategories(ctx, names) {
+  const out = [];
+  for (const name of names) {
+    const r = await req(ctx, "/categories/v1/categories", {
+      body: { category: { name, visible: true }, treeReference: { appNamespace: "@wix/stores", treeKey: null } },
+    });
+    out.push({ id: r.category?.id, name });
+  }
+  return out;
+}
+
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category.md
+export async function addProductsToCategories(ctx, mapping) {
+  for (const [categoryId, productIds] of Object.entries(mapping)) {
+    await req(ctx, `/categories/v1/bulk/categories/${categoryId}/add-items`, {
+      body: {
+        items: productIds.map((catalogItemId) => ({ catalogItemId, appId: STORES_APP_ID })),
+        treeReference: { appNamespace: "@wix/stores", treeKey: null },
+      },
+    });
+  }
+}
+
+// Bulk image attach in ONE call. items: [{ id, url, altText }] — no revision to pass: the
+// current revision is read right before the update, so attach any number of times, any pass.
+// Wix re-hosts each url server-side; the media can take a little while to appear on read-back
+// (propagation) — normal, not a failure.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-update-products.md
+export async function attachProductImages(ctx, items) {
+  if (!items?.length) return;
+  const ids = items.map((it) => it.id);
+  const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } } });
+  const revById = new Map((q.products ?? []).map((p) => [p.id, p.revision]));
+  return req(ctx, "/stores/v3/bulk/products/update", {
+    body: {
+      products: items.map((it) => ({
+        product: { id: it.id, revision: revById.get(it.id), media: { itemsInfo: { items: [{ url: it.url, altText: it.altText }] } } },
+      })),
+    },
+  });
+}
+
+/**
+ * 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.
+ */
+export async function setupStore(ctx, { products = [], categories = {} } = {}) {
+  await installStoresApp(ctx);
+
+  // 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 withNames = products.map((p) => {
+    const hit = createdByName.get(p.name) ?? existing.get(p.name);
+    return { ...(hit ?? {}), name: p.name };
+  });
+  const idByName = new Map(withNames.map((p) => [p.name, p.id]));
+
+  const names = Object.keys(categories);
+  const cats = names.length ? await createCategories(ctx, names) : [];
+  if (cats.length) {
+    const mapping = {};
+    for (const c of cats) {
+      const ids = (categories[c.name] || []).map((n) => idByName.get(n)).filter(Boolean);
+      if (ids.length) mapping[c.id] = ids;
+    }
+    if (Object.keys(mapping).length) await addProductsToCategories(ctx, mapping);
+  }
+
+  // Pass 2 — images: resolve (import by url / generate by prompt) in one parallel wave, then
+  // bulk-attach. Failures leave the product text-only; the seed's exit never depends on images.
+  const files = await resolveItemImages(ctx, withNames.map((p, i) => ({
+    url: products[i]?.imageUrl,
+    path: products[i]?.imagePath,
+    prompt: products[i]?.imagePrompt,
+    displayName: `${p.slug || "product"}.png`,
+  })));
+  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);
+  let imagesAttached = 0;
+  try {
+    if (imageItems.length) await attachProductImages(ctx, imageItems);
+    imagesAttached = imageItems.length;
+  } catch {
+    /* never block on image failure — the products stay text-only */
+  }
+
+  return { products: withNames, categories: cats, imagesAttached };
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  if (!planPath) {
+    console.error("usage: node seed-store.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupStore(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}

package/skills/wix-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, analytics, accessibility, dashboard-navigation."
+description: "REST recipes to configure and manage a Wix site's business solutions — stores, bookings, payments, CMS, and more. Open the matching recipe for the exact endpoint, method, and payload before calling — never guess a Wix API. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, google-business-profile, analytics, accessibility, seo, dashboard-navigation."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
@@ -34,6 +34,16 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
+## SEO
+
+### [Manage a Wix Site's SEO Tags](references/seo/manage-seo-tags.md)
+**Technical:** Reads and writes SEO tags (titles, descriptions, social tags, structured data, indexing) at three levels: site-wide, page-type patterns, and individual items. Always read before write — every Set replaces in full.
+
+### [Manage URL Redirects on a Wix Site](references/seo/manage-url-redirects.md)
+**Technical:** Reads, creates, and deletes URL redirects through the public SEO Redirects API. Distinguishes exact from group redirects, handles language-scoped redirects on multilingual sites, reads per-item results from bulk responses, and confirms before writes, because creating a redirect can permanently delete an existing one.
+
+---
+
 ## Accessibility
 
 ### [Scan a Wix Site for Accessibility Issues](references/accessibility/scan-site-accessibility.md)
@@ -268,6 +278,7 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 **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`.
 - **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).
 - **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).
@@ -285,6 +296,9 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 ### [Manage Campaign Lifecycle](references/google-ads/manage-campaign-lifecycle.md)
 **Technical:** Lists/gets campaigns and runs lifecycle actions: launch (first activation) vs resume (reactivate after pause), pause (with optional `scheduledResumeDate`/reminder), partial `UpdateCampaign` (name, budget, targeting), delete (irreversible), and read the change log / status history. Covers the 5-live-campaign cap and budget-boundary validation.
 
+### [Manage a Campaign Success Guide](references/google-ads/manage-campaign-success-guide.md)
+**Technical:** Retrieves or generates the prioritized success guide for an existing Google Ads Performance Max Leads campaign and updates a returned suggestion's `OPEN` or `COMPLETED` tracking status. Use for "How can I improve my campaign?", "what should I fix next?", "show my campaign success guide", "mark this recommendation complete", and "reopen this recommendation". Also offer it directly after campaign creation—even while `LEARNING` or before metrics exist; only that proactive offer requires user approval before retrieval. A direct improvement or guide request is already approval. A clear statement that the user completed a returned recommendation is an actionable request to mark it `COMPLETED`, even when phrased as an update rather than a question; do not merely acknowledge it or ask for redundant confirmation. Pre-campaign assets, keywords, budgets, and targeting remain in Get AI Campaign Suggestions.
+
 ### [Query Campaign Performance Analytics](references/google-ads/query-campaign-analytics.md)
 **Technical:** Reads campaign analytics via six endpoints — daily performance metrics (with previous-period trends), conversion metrics (orders/revenue/ROAS from Wix), search terms, per-product shopping performance, and per-asset PMAX-Leads metrics. Explains `campaignResourceName` vs Wix `campaignId`, the `dateRange` shape, field enums, sorting, and paging.
 
@@ -296,6 +310,18 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
+## Google Business Profile
+
+**Routing — how a business appears on Google Search and Maps.** A Google connection is the prerequisite for all Google-backed location work: check it first, and route "connect / reconnect / disconnect Google" to the connection recipe.
+
+### [Connect a Wix Site to Google Business Profile](references/google-business-profile/connect-google-business-profile.md)
+**Technical:** Establishes, checks, and removes the site's Google Business Profile connection. Reads the connection status (`NEVER_CONNECTED` / `VALID` / `NEEDS_RECONNECT`), requests a single-use 15-minute connect URL for the site owner to authorize in their own browser, confirms completion by re-reading the status, and warns before any reconnect that permanently removes the site's imported locations. Never auto-retries the non-idempotent connect-URL call.
+
+### [Manage Google Business Profile Locations for a Wix Site](references/google-business-profile/manage-google-business-profile-locations.md)
+**Technical:** Imports locations from the connected Google account (accounts → unimported locations → bulk create with per-item results), queries them Wix-only or hydrated with live Google data, routes each update to the correct side (Wix row vs Google listing), creates new Google listings, checks profile liveness via Voice of Merchant, and distinguishes un-importing from Wix from deleting the real Google listing. Reports a missing connection as a setup step and respects Google's shared ~10-edits-per-minute budget.
+
+---
+
 ## Marketing
 
 ### [Create and Publish a Social Media Post (with AI generation)](references/marketing/create-and-publish-social-post.md)
@@ -407,7 +433,7 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 **Technical:** Manages pre-order settings for product variants using V3 Inventory API. Covers enabling/disabling pre-orders, setting messages, configuring limits, and handling trackQuantity requirements.
 
 ### [Update Product with Options](references/stores/update-product-with-options.md)
-**Technical:** Modifies existing products and variants using Catalog V3 Products API. Covers adding/removing option choices, variant-specific pricing, and revision-based updates to prevent conflicts.
+**Technical:** Modifies existing products and variants using Catalog V3 Products API. Covers adding/removing option choices, and the writable choice/variant fields — media & displayImage, SKU/barcode, price incl. compareAtPrice (sale), visibility — plus revision-based updates and which fields are read-only (choice inStock/visible, variant media/inventory).
 
 ### [Stores Dashboard Navigation](references/stores/stores-dashboard-navigation.md)
 **Technical:** Direct links to Wix Stores and eCommerce dashboard pages on manage.wix.com (products list, edit product, categories, inventory, orders list, order details, abandoned checkouts, gift cards, shipping, tax), pairing each main Stores/eCommerce entity with its read API for "view it in your dashboard" links.