@wix/agent-skills 1.31.0 → 1.31.2

package/skills/wix-headless-templates/shared/seed/wix-cli.mjs

@@ -1,28 +1,60 @@
 // The Wix CLI the seeds call for a site token and for `wix env pull`.
 //
-// Order: the project's own copy (node_modules/.bin/wix, installed with the template's lock), then
+// Order: the project's own copy (node_modules/@wix/cli, installed with the template's lock), then
 // a `wix` on PATH, then `npx -y @wix/cli@<pinned>` — which installs the CLI before running it, 20 to
 // 60 s and a wall of npm output on a fresh machine. The first two take under two seconds.
-import { existsSync } from "node:fs";
-import { delimiter, join } from "node:path";
+//
+// On Windows `wix` and `npx` are .cmd shims, which Node starts only through a shell (ENOENT
+// without one, EINVAL for an explicit .cmd since Node 20.12). There the CLI's own JS entry, and
+// npm's npx entry beside node.exe, run through node directly.
+import { existsSync, readFileSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
 
 // The CLI version the fallback installs; equal to `@wix/cli` in wix-headless-kit/install/pins.json.
 const WIX_CLI_VERSION = "1.1.258";
+const isWin = process.platform === "win32";
+
+// The JS file a @wix/cli install runs (package.json `bin`), or null.
+function cliEntry(pkgDir) {
+  try {
+    const { bin } = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+    const rel = typeof bin === "string" ? bin : bin?.wix;
+    return rel && existsSync(join(pkgDir, rel)) ? join(pkgDir, rel) : null;
+  } catch {
+    return null;
+  }
+}
+
+function viaNpx() {
+  const pkg = `@wix/cli@${WIX_CLI_VERSION}`;
+  if (!isWin) return { file: "npx", prefix: ["-y", pkg] };
+  const js = join(dirname(process.execPath), "node_modules", "npm", "bin", "npx-cli.js");
+  if (existsSync(js)) return { file: process.execPath, prefix: [js, "-y", pkg] };
+  return { file: "npx.cmd", prefix: ["-y", pkg], shell: true };
+}
 
 export function resolveWixCli(cwd = process.cwd()) {
-  const bin = process.platform === "win32" ? "wix.cmd" : "wix";
-  const local = join(cwd, "node_modules", ".bin", bin);
   // The project's copy counts only once its install has finished: the seed runs beside a detached
   // npm install, and mid-install the .bin shim can exist before the package it points at does
   // (seen live: "Cannot find module node_modules/.bin/wix"). npm writes node_modules/.package-lock.json
   // last, the same marker the kit's install step syncs on.
-  const installed = existsSync(join(cwd, "node_modules", ".package-lock.json")) && existsSync(join(cwd, "node_modules", "@wix", "cli", "package.json"));
-  if (installed && existsSync(local)) return { file: local, prefix: [] };
+  const pkgDir = join(cwd, "node_modules", "@wix", "cli");
+  const installed = existsSync(join(cwd, "node_modules", ".package-lock.json")) && existsSync(join(pkgDir, "package.json"));
+  if (installed) {
+    const local = join(cwd, "node_modules", ".bin", "wix");
+    if (!isWin && existsSync(local)) return { file: local, prefix: [] };
+    const entry = isWin && cliEntry(pkgDir);
+    if (entry) return { file: process.execPath, prefix: [entry] };
+  }
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-    if (dir && existsSync(join(dir, bin))) return { file: join(dir, bin), prefix: [] };
+    if (!dir) continue;
+    if (!isWin && existsSync(join(dir, "wix"))) return { file: join(dir, "wix"), prefix: [] };
+    // A global npm install on Windows: wix.cmd in the prefix, the package beside it.
+    const entry = isWin && existsSync(join(dir, "wix.cmd")) && cliEntry(join(dir, "node_modules", "@wix", "cli"));
+    if (entry) return { file: process.execPath, prefix: [entry] };
   }
-  return { file: "npx", prefix: ["-y", `@wix/cli@${WIX_CLI_VERSION}`] };
+  return viaNpx();
 }
 
 /**
@@ -32,7 +64,7 @@ export function resolveWixCli(cwd = process.cwd()) {
  */
 export function wixToken(siteId, cwd = process.cwd()) {
   const cli = resolveWixCli(cwd);
-  const out = execFileSync(cli.file, [...cli.prefix, "token", "--site", siteId], { encoding: "utf8", cwd });
+  const out = execFileSync(cli.file, [...cli.prefix, "token", "--site", siteId], { encoding: "utf8", cwd, shell: cli.shell, windowsHide: true });
   // An older CLI starts its "update available" box on the token's own line, so a line split is
   // not enough: the token is the first long run of token characters.
   const token = out.match(/[A-Za-z0-9._-]{40,}/)?.[0];
@@ -43,5 +75,5 @@ export function wixToken(siteId, cwd = process.cwd()) {
 /** Runs a Wix CLI command synchronously; same return shape as spawnSync. */
 export function runWix(args, { cwd = process.cwd(), ...opts } = {}) {
   const cli = resolveWixCli(cwd);
-  return spawnSync(cli.file, [...cli.prefix, ...args], { cwd, ...opts });
+  return spawnSync(cli.file, [...cli.prefix, ...args], { cwd, shell: cli.shell, windowsHide: true, ...opts });
 }

package/skills/wix-headless-templates/storefront/INSTRUCTIONS.md

@@ -264,7 +264,7 @@ import { seoTags } from "@wix/seo";
 export const wixMetadata = {
   appDefId: WIX_APPS.checkoutAndOrders.id,
   pageIdentifier: WIX_APPS.checkoutAndOrders.categoryPageMetadata.pageIdentifier,
-  identifiers: { slug: WIX_APPS.checkoutAndOrders.categoryPageMetadata.identifiers.handle },
+  identifiers: { slug: WIX_APPS.checkoutAndOrders.categoryPageMetadata.identifiers.collection },
 };
 
 const slug = Astro.params.slug!;

package/skills/wix-headless-templates/storefront/rest/cart.ts

@@ -6,11 +6,11 @@
 // All calls run with the visitor token: the cart is the token's (see ../shared/client).
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-import { WixApiError, wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
-import { EMPTY_TOTALS, WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, cartErrorMessage, rawId, summaryTotals, toCart } from "./cart-core.js";
-import type { Raw } from "./catalog-core.js";
-import type { Cart } from "./types.js";
+import { WixApiError, wixRequest } from "../../shared/rest/client.js";
+import { imgSrc } from "../../shared/rest/media.js";
+import { EMPTY_TOTALS, WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, cartErrorMessage, rawId, summaryTotals, toCart } from "../app/wix/storefront/cart-core.js";
+import type { Raw } from "../app/wix/storefront/catalog-core.js";
+import type { Cart } from "../app/wix/storefront/types.js";
 
 const CART = "/ecom/v2/carts/current";
 

package/skills/wix-headless-templates/storefront/rest/catalog.ts

@@ -5,8 +5,8 @@
 // Porting: keep the paths, keep the bodies, port the core once.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/get-category-by-slug.md
-import { WixApiError, wixRequest } from "./client.js";
-import { imgSrc, mediaKey } from "./media.js";
+import { WixApiError, wixRequest } from "../../shared/rest/client.js";
+import { imgSrc, mediaKey } from "../../shared/rest/media.js";
 import {
   CATALOG_SORTS,
   DETAIL_FIELDS,
@@ -29,9 +29,9 @@ import {
   type CatalogSort,
   type FacetSelection,
   type Raw,
-} from "./catalog-core.js";
-import { WIX_STORES_APP_ID } from "./cart-core.js";
-import type { Category, Facet, FacetData, ProductDetail, ProductSummary, VariantInventory } from "./types.js";
+} from "../app/wix/storefront/catalog-core.js";
+import { WIX_STORES_APP_ID } from "../app/wix/storefront/cart-core.js";
+import type { Category, Facet, FacetData, ProductDetail, ProductSummary, VariantInventory } from "../app/wix/storefront/types.js";
 
 export { CATALOG_SORTS, choiceAvailability, resolveVariant, sellingPrice, type CatalogSearchOptions, type CatalogSort, type FacetSelection };
 

package/skills/wix-headless-templates/storefront/seed/SEED.md

@@ -54,8 +54,8 @@ to a file if you want it later). `.seed-exit` and `seed-result.json` are written
   `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.
-  A choice may carry its own photo — `imageUrl` | `imagePath` | `imagePrompt` (+ `altText`), the
-  same three forms as a product image: it joins the product's gallery and the product page shows
+  A choice may carry its own photo — `imageMediaId` | `imageUrl` | `imagePath` | `imagePrompt`
+  (+ `altText`), the same forms as a product image: it joins the product's gallery and the product page shows
   it when that choice is picked (a colour's photo). Give it when the source has one per colour.
 - `variantPrices` — `{ "<choice name>": price }` when one option's choices are priced differently
   ("L": 74): every variant carrying that choice takes that price (the first priced choice wins);
@@ -76,9 +76,14 @@ to a file if you want it later). `.seed-exit` and `seed-result.json` are written
 - **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
+  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 `imageMediaId` (a file
+  already in the site's Media Manager, such as one the user uploaded there: the product uses that
+  file as it is, no copy), `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. A `static.wixstatic.com/media/<file id>` URL of a file on this site counts as its
+  `imageMediaId`. List the site's files to find an id: the
+  [Media Manager](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/list-files.md)
+  names each by the name it was uploaded under. 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
@@ -94,17 +99,26 @@ to a file if you want it later). `.seed-exit` and `seed-result.json` are written
   create only; an existing category keeps what it has.
 - `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**: a sentence about
-  currency ("prices in euros") or a price written with its unit ("9 dollars", "$9", "€20"). 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
+  both is rejected. A product with no stock given, drafted or the user's own, is `"inStock": true`.
+  Right after the bulk create, a product's own stock summary can still read `OUT_OF_STOCK`
+  while its inventory items are already stocked; the items are what a buyer's add is checked
+  against. A product **without options** can still end up with no item (a create that ran while
+  the catalog was provisioning): the script stocks those afterwards with one Bulk Create
+  Inventory Items call (`productId`, its single `variantId`, and `inStock: true` or the
+  `quantity`), where `ALREADY_EXISTS` means the item is already there. A seed made call by call
+  reads the items (Query Inventory Items) and creates only the missing ones.
+- `currency` — 3-letter ISO code. Set it **only when the user names one**, in the brief or on their
+  own pages: a sentence about currency ("prices in euros") or a price written with its unit ("9
+  dollars", "$9", "€20"). On a site this run created it is set without asking; a store the user
+  already runs is asked first. 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** when you draft the catalog yourself — 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
+full inventory; the owner adds the rest in the dashboard. The closing names drafted products as
+placeholders. **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). When the brief mentions gift
 wrap, engraving, a message card, pre-orders, or "coming soon" stock, seed ONE product with that
 modifier and ONE pre-order item so the surfaces exist to design against; never add them to a
@@ -131,7 +145,8 @@ a new site (a dozen products: "Baseball Cap", "Ceramic Flower Vase", "Crew T-Shi
 live shop lists them next to the owner's, so they are never silent: the result's `preexisting[]` names
 every product the plan did not name (`{ id, name, slug }`), and the closing message says so with the
 Manage products link (`dashboardProductsUrl` in the result) so the owner removes them there if they
-want to. Categories are idempotent by name — a re-run reuses "Donuts" instead of creating a second one.
+want to. After a currency change their prices keep the same numbers in the new currency, and the
+closing says so. Categories are idempotent by name — a re-run reuses "Donuts" instead of creating a second one.
 
 **Images are confirmed, not assumed.** `imagesAttached` counts the attaches the API reported as
 successful; `imageFailures: [{ name, error }]` names the products left without an image and why.
@@ -149,6 +164,8 @@ duplicated. Never hand-patch ids to "fill the gap".
 
 Two things this module does not seed (dashboard-only — tell the merchant): **SKUs** and
 **subscription plans** (the storefront renders them when the merchant adds them).
+Shipping isn't seeded either; when the brief asks for it, `wix-manage`'s
+`references/ecommerce/ecom-shipping.md` sets it up.
 
 ## Escape hatch — individual functions
 
@@ -157,6 +174,19 @@ ordering: `installStoresApp`, `readAllProducts`, `bulkCreateProducts`,
 `createCategories(ctx, names, details?)`, `addProductsToCategories`, `attachProductImages` — plus
 `makeCtx()` for the auth context.
 
+A seed made call by call sends the body `bulkCreateProducts` builds
+(`POST /stores/v3/bulk/products-with-inventory/create`); the description is rich-text nodes, as
+`mkDesc` turns them out:
+
+```json
+{ "returnEntity": true, "products": [{
+    "name": "Hearth Candle", "productType": "PHYSICAL", "physicalProperties": {},
+    "description": { "nodes": [{ "type": "PARAGRAPH", "id": "d0", "paragraphData": {},
+      "nodes": [{ "type": "TEXT", "id": "", "textData": { "text": "Hand-poured soy wax.", "decorations": [] } }] }] },
+    "variantsInfo": { "variants": [{ "price": { "actualPrice": { "amount": "28" } },
+      "physicalProperties": {}, "inventoryItem": { "inStock": true } }] } }] }
+```
+
 ## Reference
 
 If a call returns an unexpected shape or you need an operation this module doesn't cover, read

package/skills/wix-headless-templates/storefront/seed/seed-store.mjs

@@ -12,13 +12,13 @@
 // 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"? }] }],
+//                                   "choices": ["S","M"] | [{ "name", "colorCode"?, "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"? }] }],
 //                    "variantPrices"?: { "<choice name>": price },
 //                    "ribbon"?, "modifiers"?: [{ "name", "type"?: "choices"|"text", "mandatory"?,
 //                                              "choices"?: ["Gift wrap"], "maxChars"?, "minChars"? }],
 //                    "infoSections"?: [{ "title", "description" }],
 //                    "preorder"?: { "message"?, "limit"? },
-//                    "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"?,
+//                    "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"?, "altText"?,
 //                    "digitalFileUrl"? | "digitalFilePath"?, "digitalFileName"? }],
 //     "categories"?: { "<category name>": ["<product name>", ...] },
 //     "categoryDetails"?: { "<category name>": { "description"?, "imageUrl"? | "imagePath"? | "imagePrompt"? } } }
@@ -32,6 +32,7 @@ import { readFileSync } from "node:fs";
 import { resolveItemImages, resolveItemImagesDetailed } from "../../shared/seed/images.mjs";
 import { seedSiteId } from "../../shared/seed/site-context.mjs";
 import { wixToken } from "../../shared/seed/wix-cli.mjs";
+import { isMain } from "../../shared/seed/main.mjs";
 
 const API = "https://www.wixapis.com";
 const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
@@ -472,9 +473,11 @@ export async function addProductsToCategories(ctx, mapping) {
   }
 }
 
-// Bulk image attach in ONE call. items: [{ id, url, altText }] — no revision to pass: the
+// Bulk image attach in ONE call. items: [{ id, url, mediaId?, 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
+// An item with a mediaId (a file already in this site's Media Manager) is attached by that id and
+// reused as it is; a bare url is re-hosted by Wix server-side, a new file each time. The media can
+// take a little while to appear on read-back
 // (propagation) — normal, not a failure.
 // The bulk update returns 200 on PARTIAL failure, like the bulk create: each item's outcome is
 // in results[].itemMetadata (success, error, originalIndex). Seen live (runs 85 and 86,
@@ -491,7 +494,8 @@ export async function addProductsToCategories(ctx, mapping) {
 // whose choices were linked (by this seed or by the owner in the dashboard) gets those links put
 // back right after.
 const sameFile = (a, b) => a && b && basename(a) === basename(b);
-const galleryHas = (items, url) => items.some((it) => sameFile(it.image?.filename, url) || sameFile(it.image?.url, url));
+// A file attached by id keeps its own display name as the item's filename, so it is found by id.
+const galleryHas = (items, url, mediaId) => items.some((it) => (mediaId && it.id === mediaId) || sameFile(it.image?.filename, url) || sameFile(it.image?.url, url));
 
 export async function attachProductImages(ctx, items) {
   if (!items?.length) return { attached: [], failures: [] };
@@ -508,9 +512,10 @@ export async function attachProductImages(ctx, items) {
       const p = byId.get(it.id);
       const current = p?.media?.itemsInfo?.items ?? [];
       const wanted = it.images ?? [{ url: it.url, altText: it.altText }];
-      const fresh = wanted.filter(({ url }) => !galleryHas(current, url));
+      const fresh = wanted.filter(({ url, mediaId }) => !galleryHas(current, url, mediaId));
       if (!fresh.length) { ok.add(it.id); continue; } // every image is already there
-      toSend.push({ it, p, items: [...current.map(({ id }) => ({ id })), ...fresh.map(({ url, altText }) => ({ url, altText }))] });
+      // A file already in the Media Manager goes in by its id: set by url, Stores imports a copy.
+      toSend.push({ it, p, items: [...current.map(({ id }) => ({ id })), ...fresh.map(({ url, mediaId, altText }) => (mediaId ? { id: mediaId, altText } : { url, altText }))] });
     }
     if (toSend.length) {
       const r = await req(ctx, "/stores/v3/bulk/products/update", {
@@ -558,7 +563,8 @@ function choiceLinksOf(p) {
 
 // Per-choice images (the dashboard's "image per colour"): a choice points at an item of the
 // product's OWN gallery, so the image is attached to the gallery first (pass 2) and linked here by
-// the gallery item's id — the id of the uploaded file is a different id and 400s. Links are a
+// the gallery item's id — for a file imported by url that is a different id from the uploaded
+// file's and the file's 400s; a file attached by its Media Manager id is the item of that id. Links are a
 // product update, which the API only accepts with the variants re-sent beside the options, so the
 // current variants (id, choices, price) ride along unchanged. Wix derives a variant's own media
 // from its choice at creation only; the storefront reads the choice's image, so a link made here
@@ -735,18 +741,19 @@ export async function setupStore(ctx, { products = [], categories = {}, category
   const choiceSpecs = products.map((pl, i) =>
     (pl.options ?? []).flatMap((o) =>
       (o.choices ?? [])
-        .filter((c) => typeof c === "object" && c && (c.imageUrl || c.imagePath || c.imagePrompt))
+        .filter((c) => typeof c === "object" && c && (c.imageMediaId || c.imageUrl || c.imagePath || c.imagePrompt))
         .map((c) => ({
           optionName: o.name,
           choiceName: c.name,
           productName: pl.name,
           altText: c.altText ?? `${pl.name} — ${c.name}`,
-          spec: { url: c.imageUrl, path: c.imagePath, prompt: c.imagePrompt, displayName: `${withNames[i].slug || "product"}-${String(c.name).toLowerCase().replace(/[^a-z0-9]+/g, "-")}.png` },
+          spec: { mediaId: c.imageMediaId, url: c.imageUrl, path: c.imagePath, prompt: c.imagePrompt, displayName: `${withNames[i].slug || "product"}-${String(c.name).toLowerCase().replace(/[^a-z0-9]+/g, "-")}.png` },
         })),
     ));
   const flatChoiceSpecs = choiceSpecs.flat();
   const resolved = await resolveItemImagesDetailed(ctx, [
     ...withNames.map((p, i) => ({
+      mediaId: products[i]?.imageMediaId,
       url: products[i]?.imageUrl,
       path: products[i]?.imagePath,
       prompt: products[i]?.imagePrompt,
@@ -766,8 +773,8 @@ export async function setupStore(ctx, { products = [], categories = {}, category
     .map((p, i) => {
       if (!p.id) return null;
       const images = [
-        ...(files[i] ? [{ url: files[i].url, altText: products[i]?.altText ?? p.slug }] : []),
-        ...choiceLinks[i].map((c) => ({ url: c.file.url, altText: c.altText })),
+        ...(files[i] ? [{ url: files[i].url, mediaId: files[i].existing ? files[i].id : undefined, altText: products[i]?.altText ?? p.slug }] : []),
+        ...choiceLinks[i].map((c) => ({ url: c.file.url, mediaId: c.file.existing ? c.file.id : undefined, altText: c.altText })),
       ];
       return images.length ? { id: p.id, images } : null;
     })
@@ -782,7 +789,7 @@ export async function setupStore(ctx, { products = [], categories = {}, category
   // it is reported here with the resolver's reason, or it ships text-only in silence.
   withNames.forEach((p, i) => {
     const src = products[i] ?? {};
-    if ((src.imageUrl || src.imagePath || src.imagePrompt) && !files[i]) {
+    if ((src.imageMediaId || src.imageUrl || src.imagePath || src.imagePrompt) && !files[i]) {
       imageFailures.push({ name: p.name, error: resolved[i]?.error ?? "image did not resolve" });
     }
   });
@@ -807,7 +814,8 @@ export async function setupStore(ctx, { products = [], categories = {}, category
     const links = choiceLinks[i];
     if (!links.length || !p.id || !imagesAttached) continue;
     try {
-      const r = await linkChoiceImages(ctx, p.id, links.map((c) => ({ optionName: c.optionName, choiceName: c.choiceName, url: c.file.url })));
+      // a file attached by its Media Manager id is the gallery item of that id; an imported one is found by name
+      const r = await linkChoiceImages(ctx, p.id, links.map((c) => ({ optionName: c.optionName, choiceName: c.choiceName, ...(c.file.existing ? { mediaId: c.file.id } : { url: c.file.url }) })));
       choiceImagesLinked += r.linked;
       for (const m of r.missing) choiceImageFailures.push({ name: p.name, choice: m, error: "image not in the product gallery" });
     } catch (e) {
@@ -847,7 +855,7 @@ export async function setupStore(ctx, { products = [], categories = {}, category
 
 // ---- CLI entry ----------------------------------------------------------------------------------
 
-const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+const invokedDirectly = isMain(import.meta.url);
 if (invokedDirectly) {
   const planPath = process.argv[2];
   if (!planPath) {

package/skills/wix-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-manage
-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, never write Wix dashboard URL from memory. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, custom-apps, 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."
+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, never write Wix dashboard URL from memory. Routes to: automations, stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, custom-apps, 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).
 ---
 
@@ -37,7 +37,7 @@ Lists all apps installed on a site using Apps Installer API. Useful for verifyin
 ## Custom Apps
 
 ### [Use App Skills and App Tools](references/custom-apps/use-app-skills-and-app-tools.md)
-"Discovers and runs what the apps installed on a Wix site add for AI agents: app skills, which are an app's instructions for a task (for example pricing a product for customers in another country, or checking a property listing before it is published), and app tools, which are actions and lookups an app exposes. Use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app, skill or tool. Covers reading a chosen skill's instructions and running the app tools it allows, or running a single app tool directly."
+"Discovers and runs what the apps installed on a Wix site add for AI agents: app skills, which are an app's instructions for a task (for example pricing a product for customers in another country, or checking a property listing before it is published), and app tools, which are actions and lookups an app exposes. Use every time a site has custom apps installed, before acting on the user's request: knowing which apps are installed doesn't tell what they can do, so only this skill's discovery calls show whether one of them handles the request. Also use when the user asks for something an installed app provides rather than a built-in Wix feature, asks what their apps can do, or names an app, skill or tool. Covers reading a chosen skill's instructions and running the app tools it allows, or running a single app tool directly."
 
 ---
 
@@ -96,19 +96,7 @@ Sets up booking policies, cancellation rules, and waitlist configuration using t
 "Creates staff members and configures custom working hours using Staff API + Calendar Events API. Critical two-step process: create staff → assign schedule → create working hours events."
 
 ### [Create and Update Booking Services](references/bookings/create-and-update-booking-services.md)
-Full CRUD operations for Wix Bookings services using Services API. Covers service types (APPOINTMENT, CLASS, COURSE), pricing configuration, location setup, and schedule management.
-
-### [Create Booking Service from Prompt](references/bookings/create-booking-service-from-prompt.md)
-"Create a booking service from a user prompt — e.g. 'create a yoga class for $50', 'set up consultations for $75', 'add a personal training appointment', 'create a 6-week photography workshop', 'create a hidden free test course with 8 online sessions'. Determines the service type (APPOINTMENT, CLASS, or COURSE) and delegates to the type-specific recipe. For COURSE services with session dates/counts, follow the course recipe's separate Calendar bulkCreateEvents step; Services V2 alone does not create bookable course sessions."
-
-### [Create Appointment Service](references/bookings/create-appointment-service.md)
-"Create an appointment booking service — e.g. 'set up consultations', 'create a 1-on-1 session', 'add a personal training appointment', 'create a meeting service for $25'. Handles staff assignment (required), session duration, pricing, and 1-on-1 capacity defaults via bulkCreateServices API."
-
-### [Create Class Service](references/bookings/create-class-service.md)
-"Create a class booking service — e.g. 'create a yoga class for $50', 'set up a pilates class', 'add a group fitness session', 'create a weekly meditation class'. Handles group capacity, recurring session defaults, and pricing via bulkCreateServices API. Staff assignment is not used for classes."
-
-### [Create Course Service](references/bookings/create-course-service.md)
-"Create a course booking service — e.g. 'create a 6-week photography workshop', 'set up a training program', 'add a bootcamp course for $300', 'create a hidden free test course with 8 sessions'. Handles group capacity, full-course pricing, bulkCreateServices, and separate course session events via bulkCreateEvents. Staff assignment is not used for courses."
+"Creates and updates Wix Bookings services of every type — appointments, classes and courses — from a plain request such as 'a 60-minute consultation for $75', 'a yoga class for 12 people every Tuesday' or 'a 6-week photography course'. Covers choosing the service type, defaults for what the request leaves out, pricing (free, fixed, free-to-paid), staff, capacity, duration, categories, visibility, images, scheduling class and course sessions on the calendar, and changing existing services."
 
 ### [Check Bookings Availability (and Diagnose Issues)](references/bookings/diagnose-availability-issues.md)
 "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."
@@ -408,7 +396,7 @@ Authoritative recipe for hand-authoring valid Ricos rich-content JSON (the richC
 Creates new Wix sites from templates using account-level APIs. Covers template search, site creation, and publishing. Not for headless sites.
 
 ### [Create Headless Site](references/sites/create-headless-site.md)
-Creates a Wix Headless site (headless business) with one account-level API call — site, Wix Business Solution apps, and a configured OAuth client.
+Creates a Wix Headless website: a site in the user's Wix account whose frontend is files uploaded to Wix hosting, with the Wix business backend behind it through APIs. Creating, uploading, updating and connecting a backend are one flow, in Upload a Website or HTML Files.
 
 ### [Manage OAuth Apps](references/sites/manage-oauth-apps.md)
 Create, read, update, and query OAuth apps for a Wix headless site. Each OAuth app's id is the client_id a frontend uses to mint anonymous visitor tokens and call Wix APIs.
@@ -419,6 +407,9 @@ List, count, and find the sites in a Wix account. Covers the namespace filter fo
 ### [Read Account or Site Context](references/sites/read-site-context.md)
 Probe a Wix site or account for full context in one call — installed apps by display name, locale, currency, timezone, and status. Account token + siteId targets one site; account token alone returns up to 10; site-scoped token alone returns the site it is scoped to.
 
+### [Send Feedback to Wix](references/sites/send-feedback-to-wix.md)
+Relay the user's feedback about building with Wix — the APIs, docs, recipes, Wix MCP and tooling — to Wix, attributed to the authenticated user. Covers when to offer it, how to compose a message Wix can act on, and the call that sends it. Use when the user asks to report something to Wix, is frustrated with a Wix API or flow, or a recipe's flow fell short. Not a support channel, and not for the user's own site content.
+
 ### [Site Import](references/sites/site-import.md)
 Drive the Wix Site Import agent to migrate an existing store or site from another platform (Shopify, WooCommerce, Magento, or any URL) into Wix — as a brand-new site or into the user's existing one — or to import from CSV/TSV export files with no source site. Use this skill whenever the user wants to import, migrate, or clone a store/site into Wix, mentions moving off Shopify/WooCommerce/Magento, or gives a source store URL and asks to bring it into Wix. Covers starting the import, polling progress, answering the agent's mid-import questions, handling deploy/failure/auth-expiry states, and sending post-deploy follow-up changes.
 
@@ -426,7 +417,7 @@ Drive the Wix Site Import agent to migrate an existing store or site from anothe
 "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 live Wix site. Covers every way to get there — publishing straight into the user's Wix account when you hold their identity, publishing anonymously with a save link when you don't, and handing the user the Wix Headless drop page, or releasing it as a Wix Headless project — and how to get the user's identity through the Wix CLI. 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 published this way (replace its files on the same site and URL). 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.
+Create and update a Wix Headless website by uploading its files — an index.html, a static build, a zip exported from an AI builder or any other tool, or pages you write for the user — as a live site in the user's Wix account. Covers every route: uploading with the user's identity (curl with a Wix CLI token, or the Wix MCP), publishing anonymously with a save link when you don't hold it, and the Wix Headless drop page; then updating the same site and URL, and connecting a Wix backend (stores, bookings, forms) through the headless skill. Use when the user wants to upload, publish, deploy or host HTML/CSS/JS as a new Wix site, their own or written for them, or to change a site published this way. 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.
 
 ---
 
@@ -454,7 +445,26 @@ Query and list products from a Wix Store using the Catalog V1 Query Products end
 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 (Catalog V3)](references/stores/update-product-with-options.md)
-Modifies existing products and variants using Catalog V3 Products API. Covers adding/removing option choices, variant-specific pricing, product visibility (hide, unhide, or show a product in the storefront — a product-level `visible` update, never a delete), and revision-based updates to prevent conflicts.
+Start here for existing Catalog V3 product updates, including digital products that fail at add-to-cart with ITEM_NOT_FOUND_IN_CATALOG. Includes name lookup, Get Product, and PATCH in one flow, plus importing a supplied PDF and attaching it to the existing variant. Covers options, variant prices and SKUs, product visibility (hide/unhide through `visible`, never delete), description edits that preserve Rich Content, and revision-based updates. Read another recipe only for a field or operation this flow does not cover.
 
 ### [Stores Dashboard Navigation](references/stores/stores-dashboard-navigation.md)
 "Builds direct links to Wix Stores and eCommerce dashboard pages on manage.wix.com — products list, edit a specific product, categories, inventory, orders list, a specific order, abandoned checkouts, gift cards, shipping and tax settings. Pairs each main Stores/eCommerce entity with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. 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."
+
+<!-- automations-builder-sync:begin -->
+## Automations
+
+### [Build and Manage Wix Automations](references/automations/build-and-manage-automations.md)
+Discover installed automation triggers and actions and inspect an automation’s current active status without changing site data.
+
+<details>
+<summary>Internal skills (loaded on demand by Build and Manage Wix Automations — do NOT use directly)</summary>
+
+- [Automations API Catalog](references/automations/api-catalog.md)
+  Discover installed automation triggers and actions and inspect their schemas through site-scoped public catalog APIs.
+
+- [Automations Activation Status](references/automations/activation-status.md)
+  Read an automation’s current ACTIVE or INACTIVE status and distinguish it from historical run outcomes.
+
+</details>
+
+<!-- automations-builder-sync:end -->

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

@@ -92,7 +92,7 @@ curl -X POST \
 
 Before installing, refer to the [Apps Created by Wix](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix) documentation to find the correct `appDefId` for the app you want to install.
 
-Some common apps:
+Some common apps (`appDefId`; [List Installed Apps](list-installed-apps.md) shows which of them a site already has):
 | App | appDefId |
 |-----|----------|
 | Wix Stores | `215238eb-22a5-4c36-9e7b-e7c08025e04e` |
@@ -102,6 +102,10 @@ Some common apps:
 | Wix Multilingual | `14d84998-ae09-1abf-c6fc-3f3cace5bf19` |
 | Wix Pricing Plans | `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3` |
 | Wix CMS | `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
+| Wix Forms | `225dd912-7dea-4738-8688-4b8c6955ffc2` |
+| Wix Restaurants Menus | `b278a256-2757-4f19-9313-c05c783bec92` |
+| Wix Restaurants Orders (online ordering) | `9a5d83fd-8570-482e-81ab-cfa88942ee60` |
+| Wix Table Reservations | `f9c07de2-5341-40c6-b096-8eb39de391fb` |
 
 ### IMPORTANT NOTES:
 - NEVER guess the `appDefId`. For Wix-built apps, use the table above. For any other app, resolve the ID using Step 0 (Search Market Listings).

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

@@ -8,7 +8,10 @@ This recipe guides you through listing all installed apps on a Wix site using th
 
 ## Prerequisites
 
-- Site ID for the site you want to check
+- A token scoped to the site: the call takes no site parameter and answers for the site the token is
+  for. With the Wix CLI, `npx @wix/cli@latest token --site <siteId>`; through the Wix MCP, `ExecuteWixAPI`
+  with `scope: 'site'` and the `siteId`. An account token, with or without a `wix-site-id` header, answers
+  an empty list, which looks like a site with no apps.
 
 ## Required APIs
 
@@ -18,7 +21,10 @@ This recipe guides you through listing all installed apps on a Wix site using th
 
 ## Step 1: Query Installed Apps
 
-Use the Get Installed Apps endpoint to retrieve all apps installed on a site.
+Use the Get Installed Apps endpoint to retrieve all apps installed on a site. It returns every app
+instance, including the dozens of platform apps every site carries, as ids only: the response has no
+names; match them against the table in Step 2. [Read Account or Site Context](../sites/read-site-context.md)
+has the names, but its list can lag an install by many minutes; this call is immediate.
 
 **Endpoint**: `GET https://www.wixapis.com/apps-installer-service/v1/app-instances`
 
@@ -26,7 +32,7 @@ Use the Get Installed Apps endpoint to retrieve all apps installed on a site.
 ```bash
 curl -X GET \
   'https://www.wixapis.com/apps-installer-service/v1/app-instances' \
-  -H 'Authorization: <AUTH>' \
+  -H "Authorization: $(npx @wix/cli@latest token --site <SITE_ID>)" \
   -H 'Content-Type: application/json'
 ```
 
@@ -36,8 +42,7 @@ curl -X GET \
   "appInstances": [
     {
       "id": "instance-id-1",
-      "appDefId": "1380b703-ce81-ff05-f115-39571d94dfcd",
-      "version": "^0.0.0",
+      "appDefId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
       "enabled": true,
       "status": "UNKNOWN"
     },
@@ -61,12 +66,17 @@ Match the `appDefId` values from the response against known Wix app IDs.
 
 | App | appDefId |
 |-----|----------|
-| Wix Stores | `1380b703-ce81-ff05-f115-39571d94dfcd` |
+| Wix Stores | `215238eb-22a5-4c36-9e7b-e7c08025e04e` |
+| Wix Checkout & Orders (installed with Stores) | `1380b703-ce81-ff05-f115-39571d94dfcd` |
 | Wix Bookings | `13d21c63-b5ec-5912-8397-c3a5ddb27a97` |
 | Wix Blog | `14bcded7-0066-7c35-14d7-466cb3f09103` |
 | Wix Events | `140603ad-af8d-84a5-2c80-a0f60cb47351` |
 | Wix Pricing Plans | `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3` |
-| Wix Restaurants | `13e8d036-5516-6f75-e025-2aca3b5d7930` |
+| Wix CMS (Wix Data) | `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
+| Wix Forms | `225dd912-7dea-4738-8688-4b8c6955ffc2` |
+| Wix Restaurants Menus | `b278a256-2757-4f19-9313-c05c783bec92` |
+| Wix Restaurants Orders (online ordering) | `9a5d83fd-8570-482e-81ab-cfa88942ee60` |
+| Wix Table Reservations | `f9c07de2-5341-40c6-b096-8eb39de391fb` |
 
 For a complete list, see [Apps Created by Wix](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix).
 
@@ -111,8 +121,8 @@ If you receive `401 Unauthorized` or `403 Forbidden` errors from Wix APIs:
 - Check that the token has `APP-MARKET.VIEW-INSTALLED-APP` permission
 
 ### Empty Response
-- The site may have no additional apps installed beyond core Wix functionality
-- This is normal for new or minimal sites
+- Every site carries dozens of platform app instances, so an empty list means the token was not scoped to
+  the site (an account token answers empty), not a site with no apps. Mint a site token and call again.
 
 ---