@wix/agent-skills 1.31.1 → 1.31.2

package/skills/wix-headless-templates/pricing-plans/rest/plans.ts

@@ -5,10 +5,10 @@
 // A plan without a numeric price is malformed and never returned (plans-core `planAmount`).
 // Porting: keep the path, keep the body, port the core once.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md
-import { wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
-import { plansQuery, toDetail, toSummaries, type FormatOptions, type Raw } from "./plans-core.js";
-import type { PlanDetail, PlanSummary } from "./types.js";
+import { wixRequest } from "../../shared/rest/client.js";
+import { imgSrc } from "../../shared/rest/media.js";
+import { plansQuery, toDetail, toSummaries, type FormatOptions, type Raw } from "../app/wix/pricing-plans/plans-core.js";
+import type { PlanDetail, PlanSummary } from "../app/wix/pricing-plans/types.js";
 
 export type { FormatOptions };
 

package/skills/wix-headless-templates/pricing-plans/rest/purchase.ts

@@ -4,9 +4,9 @@
 // order form, and payment itself, so a visitor token starts it. Never create the order yourself,
 // never hand-build a checkout URL.
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-import { wixRequest } from "./client.js";
-import { purchaseBody, redirectUrl, type PurchaseOptions } from "./purchase-core.js";
-import type { Raw } from "./plans-core.js";
+import { wixRequest } from "../../shared/rest/client.js";
+import { purchaseBody, redirectUrl, type PurchaseOptions } from "../app/wix/pricing-plans/purchase-core.js";
+import type { Raw } from "../app/wix/pricing-plans/plans-core.js";
 
 export type { PurchaseOptions };
 

package/skills/wix-headless-templates/pricing-plans/seed/seed-pricing-plans.mjs

@@ -23,6 +23,7 @@
 import { setSiteCurrency } from "../../shared/seed/site.mjs";
 import { seedSiteId } from "../../shared/seed/site-context.mjs";
 import { wixToken } from "../../shared/seed/wix-cli.mjs";
+import { isMain } from "../../shared/seed/main.mjs";
 import { readFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 
@@ -283,7 +284,7 @@ export async function setupPricingPlans(ctx, { plans = [], currency } = {}) {
 
 // ---- 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-headless-templates/rentals/rest/rentals.ts

@@ -10,8 +10,8 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-import { wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
+import { wixRequest } from "../../shared/rest/client.js";
+import { imgSrc } from "../../shared/rest/media.js";
 import {
   FALLBACK_FIELDS,
   RENTALS_APP_ID,
@@ -42,8 +42,8 @@ import {
   toSummary,
   type Raw,
   type StartWindow,
-} from "./rentals-core.js";
-import type { EndOption, RentalDetail, RentalFormField, RentalQuote, RentalResult, RentalSummary, StartOption } from "./types.js";
+} from "../app/wix/rentals/rentals-core.js";
+import type { EndOption, RentalDetail, RentalFormField, RentalQuote, RentalResult, RentalSummary, StartOption } from "../app/wix/rentals/types.js";
 
 export { RENTALS_APP_ID, RENTALS_FORM_ID, RENTALS_PAGE_SIZE, dailyEndOptions, defaultTimeZone };
 

package/skills/wix-headless-templates/rentals/seed/seed-rentals.mjs

@@ -26,6 +26,7 @@ import { readFileSync } from "node:fs";
 import { resolveItemImages } 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";
 /** The Wix Rentals app: the service's immutable appId, the catalog filter, the cart's appId. */
@@ -301,7 +302,7 @@ export async function setupRentals(ctx, { resourceTypes = [], rentals = [], curr
 
 // ---- 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-headless-templates/restaurants/rest/menu.ts

@@ -7,8 +7,8 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/list-menus.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/list-items.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
-import { wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
+import { wixRequest } from "../../shared/rest/client.js";
+import { imgSrc } from "../../shared/rest/media.js";
 import {
   anyLabels,
   assembleMenus,
@@ -19,8 +19,8 @@ import {
   nextCursor,
   toSiteMoney,
   type Raw,
-} from "./menu-core.js";
-import type { MenuData, SiteMoney } from "./types.js";
+} from "../app/wix/restaurants/menu-core.js";
+import type { MenuData, SiteMoney } from "../app/wix/restaurants/types.js";
 
 const get = (path: string, query?: Record<string, string | readonly string[]>) => wixRequest<Raw>(path, { method: "GET", query });
 

package/skills/wix-headless-templates/restaurants/rest/ordering.ts

@@ -12,10 +12,10 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/fulfillment-methods/list-fulfillment-methods.md
 // 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 { WixApiError, wixRequest } from "../../shared/rest/client.js";
+import { imgSrc } from "../../shared/rest/media.js";
 import { fetchSiteMoney } from "./menu.js";
-import { initialSelection, nextCursor, validateSelection, type Raw } from "./menu-core.js";
+import { initialSelection, nextCursor, validateSelection, type Raw } from "../app/wix/restaurants/menu-core.js";
 import {
   RESTAURANTS_ORDERS_APP_ID,
   assertOrderAdded,
@@ -29,8 +29,8 @@ import {
   toFulfillmentMethods,
   toMenuOrderingMap,
   toOrderCart,
-} from "./ordering-core.js";
-import type { FulfillmentMethodInfo, MenuItem, MenuOrderingInfo, OrderCart, OrderSelection, OrderingStatus } from "./types.js";
+} from "../app/wix/restaurants/ordering-core.js";
+import type { FulfillmentMethodInfo, MenuItem, MenuOrderingInfo, OrderCart, OrderSelection, OrderingStatus } from "../app/wix/restaurants/types.js";
 
 export { RESTAURANTS_ORDERS_APP_ID };
 

package/skills/wix-headless-templates/restaurants/rest/reservations.ts

@@ -9,9 +9,9 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-held-reservation.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/reserve-reservation.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-reservation.md
-import { wixRequest } from "./client.js";
-import { availableSlots, reservationBody, reserveeBody, toConfirmation, toHold, toLocations } from "./reservations-core.js";
-import type { Raw } from "./menu-core.js";
+import { wixRequest } from "../../shared/rest/client.js";
+import { availableSlots, reservationBody, reserveeBody, toConfirmation, toHold, toLocations } from "../app/wix/restaurants/reservations-core.js";
+import type { Raw } from "../app/wix/restaurants/menu-core.js";
 import type {
   ReservationConfirmation,
   ReservationFormConfig,
@@ -19,7 +19,7 @@ import type {
   ReservationLocationInfo,
   ReservationReservee,
   ReservationSlot,
-} from "./types.js";
+} from "../app/wix/restaurants/types.js";
 
 const RESERVATIONS = "/table-reservations/reservations/v1";
 

package/skills/wix-headless-templates/restaurants/seed/seed-restaurants.mjs

@@ -28,6 +28,7 @@ import { readFileSync } from "node:fs";
 import { resolveItemImages } 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 MENUS_APP_ID = "b278a256-2757-4f19-9313-c05c783bec92";
@@ -560,7 +561,7 @@ export async function setupRestaurants(ctx, plan) {
 
 // ---- 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-headless-templates/shared/capabilities/site-search/rest/search.ts

@@ -4,8 +4,8 @@
 // a literal body per function. Every call here answers a visitor token (observed live). Porting:
 // keep the paths, keep the bodies, port the core once.
 // docs: https://dev.wix.com/docs/api-reference/business-management/site-search/wix-site-search/search.md
-import { wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
+import { wixRequest } from "../../../rest/client.js";
+import { imgSrc } from "../../../rest/media.js";
 import { siteSearchPlan } from "./site-search-config.generated.js";
 import {
   GROUP_LIMIT,
@@ -23,8 +23,8 @@ import {
   toSearchAll,
   toSuggestGroups,
   type Raw,
-} from "./search-core.js";
-import type { SearchAllResult, SearchOptions, SearchPage, SiteSearchConfig, SuggestGroup } from "./types.js";
+} from "../app/wix/site-search/search-core.js";
+import type { SearchAllResult, SearchOptions, SearchPage, SiteSearchConfig, SuggestGroup } from "../app/wix/site-search/types.js";
 
 /** The plan's siteSearch entry resolved — types in order, routes, labels. */
 export const config: SiteSearchConfig = resolveConfig(siteSearchPlan);

package/skills/wix-headless-templates/shared/capabilities/site-search/seed/install.mjs

@@ -11,10 +11,10 @@
 // (searchAll("<a seeded title word>")) and expect a non-empty group before wiring the UI. Zero
 // documents after a minute means the app is not installed or the content is not visible to the
 // index (hidden products, drafts), not that the query is wrong.
-import { execFileSync } from "node:child_process";
 import { seedSiteId } from "../../../seed/site-context.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { installSiteSearch } from "../../../seed/site.mjs";
+import { wixToken } from "../../../seed/wix-cli.mjs";
 
 function flag(name) {
   const i = process.argv.indexOf(`--${name}`);
@@ -29,9 +29,11 @@ if (!siteId) {
   console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
   process.exit(1);
 }
-const token = execFileSync("npx", ["-y", "@wix/cli@1.1.258", "token", "--site", siteId], { encoding: "utf8" }).trim();
-if (!token) {
-  console.log(JSON.stringify({ error: "the Wix CLI returned no token — run `npx @wix/cli@1.1.258 login` first" }));
+let token;
+try {
+  token = wixToken(siteId);
+} catch (e) {
+  console.log(JSON.stringify({ error: String(e.message).slice(0, 400) }));
   process.exit(1);
 }
 try {

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

@@ -0,0 +1,15 @@
+// Whether a seed module is the script node was started with (`node seed-<vertical>.mjs plan.json`)
+// rather than imported. Compares real paths, so Windows backslashes, relative invocations and
+// symlinked folders all match (node reports the module's real path in import.meta.url).
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function isMain(moduleUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}

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

@@ -99,7 +99,7 @@ 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.
+  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
@@ -107,16 +107,18 @@ to a file if you want it later). `.seed-exit` and `seed-result.json` are written
   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 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
+- `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
@@ -143,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.
@@ -161,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
 
@@ -169,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

@@ -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";
@@ -854,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

@@ -396,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.
@@ -417,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.
 
 ---
 
@@ -445,7 +445,7 @@ 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."

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.
 
 ---