@wix/agent-skills 1.22.0 → 1.23.0

package/skills/wix-headless-fast/install/deploy.mjs

@@ -45,6 +45,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { templatesDir } from "./templates.mjs";
 import { syncLockRoot } from "./lock.mjs";
+import { siteContext } from "./context.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // The shipped code: the repository's templates/ (a checkout, the cache, or fetched now).
@@ -80,7 +81,11 @@ const CAPABILITY_DEPS = {
     "@wix/media": "^1.0.271",
     "@wix/essentials": "^1.0.10",
   },
+  "site-search": {
+    "@wix/search": "^1.0.90",
+  },
 };
+const SITE_SEARCH = join("shared", "capabilities", "site-search");
 const VERTICAL_DEPS = {
   storefront: {
     core: {
@@ -160,6 +165,19 @@ const VERTICAL_DEPS = {
       "@wix/redirects": "^1.0.125",
     },
   },
+  faq: {
+    core: {
+      "@wix/faq": "^1.0.76",
+    },
+    // no astro block: the FAQ page is a plain page (no wixMetadata item routing); its JSON-LD is inline
+  },
+  donations: {
+    core: {
+      "@wix/donations": "^1.0.64",
+      "@wix/ecom": "^1.0.2454",
+      "@wix/redirects": "^1.0.125",
+    },
+  },
 };
 
 const COPY = { recursive: true, force: false, errorOnExist: false };
@@ -211,6 +229,27 @@ if (!Array.isArray(uploadPolicies)) {
   console.log(JSON.stringify({ error: "plan.capabilities.mediaUpload.policies must be an array" }));
   process.exit(1);
 }
+// Site search is on when the plan carries the entry (`{}` is enough; `true` too). Its fields are
+// data for the generated config; the shipped core drops unknown type names, so only shapes are checked.
+const siteSearchEntry = plan.capabilities?.siteSearch;
+const siteSearch = siteSearchEntry === true ? {} : siteSearchEntry && typeof siteSearchEntry === "object" ? siteSearchEntry : null;
+if (siteSearchEntry != null && siteSearchEntry !== false && !siteSearch) {
+  console.log(JSON.stringify({ error: "plan.capabilities.siteSearch must be an object (or true)" }));
+  process.exit(1);
+}
+if (siteSearch) {
+  const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+  const map = (v) => v === undefined || (v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string"));
+  if ((siteSearch.types !== undefined && !strings(siteSearch.types)) || !map(siteSearch.routes) || !map(siteSearch.labels)) {
+    console.log(JSON.stringify({ error: "plan.capabilities.siteSearch: types must be string[]; routes and labels must be objects of strings" }));
+    process.exit(1);
+  }
+}
+// The generated file is data only; the shipped core resolves defaults (types, routes, labels) from it.
+const siteSearchConfigSource = () =>
+  `// Generated by wix-headless-fast install/deploy.mjs from plan.capabilities.siteSearch.\n` +
+  `// Edit the plan and redeploy. Defaults for anything omitted are in search-core.ts (resolveConfig).\n` +
+  `export const siteSearchPlan = ${JSON.stringify(siteSearch, null, 2)};\n`;
 // ---- static stack: the REST layer, composed flat and stripped ------------------------------------
 if (stack === "static") {
   const { spawnSync } = await import("node:child_process");
@@ -218,10 +257,9 @@ if (stack === "static") {
   const OUT = outDir ? resolve(PROJECT, outDir) : PROJECT;
   const JS = join(OUT, "js", "wix");
   result.out = outDir ?? ".";
-  let clientId = clientIdFlag;
-  if (!clientId && existsSync(join(PROJECT, "wix.config.json"))) {
-    clientId = JSON.parse(readFileSync(join(PROJECT, "wix.config.json"), "utf8")).appId ?? null;
-  }
+  // The client id the browser mints visitor tokens with: --client-id, else the CONTENT app from
+  // .env.local (`wix env pull`; on a migration preview the parent site's app), else the config's appId.
+  let clientId = clientIdFlag ?? (existsSync(join(PROJECT, "wix.config.json")) ? siteContext({ cwd: PROJECT }).content.clientId : null);
   if (!clientId) {
     console.log(JSON.stringify({ error: "static stack needs the public OAuth client id — run `npm create @wix/new@latest init` here first, or pass --client-id" }));
     process.exit(1);
@@ -233,19 +271,23 @@ if (stack === "static") {
   }
   // Only files that aren't there yet — a re-run restores, never clobbers (same as the copy below).
   cpSync(join(REF, "shared", "rest"), JS, COPY);
-  for (const vertical of requested) {
-    cpSync(join(REF, vertical, "rest"), JS, COPY);
+  // Every layer with a rest/ twin: the requested verticals, plus the site-search capability when the
+  // plan turns it on (same shape — rest/ beside app/wix/<name>/ — at templates/shared/capabilities).
+  const layers = requested.map((vertical) => [vertical, join(REF, vertical)]);
+  if (siteSearch) layers.push(["site-search", join(REF, SITE_SEARCH)]);
+  for (const [vertical, root] of layers) {
+    cpSync(join(root, "rest"), JS, COPY);
     // The vertical's transport-agnostic core: types, every *-core.ts, and every *-store.ts under its
     // app/wix/<vertical>/ — the stores are the hooks' logic without React, over the same function
     // names the REST twin exports, so they run against it unchanged.
-    const appWix = join(REF, vertical, "app", "wix", vertical);
+    const appWix = join(root, "app", "wix", vertical);
     for (const f of readdirSync(appWix)) {
       // Every vertical has a types.ts; flat in one folder they would collide, so each lands as
       // <vertical>-types.ts and the vertical's own files are pointed at it below.
       if (f === "types.ts") cpSync(join(appWix, f), join(JS, `${vertical}-types.ts`), COPY);
       else if (f.endsWith("-core.ts") || f.endsWith("-store.ts")) cpSync(join(appWix, f), join(JS, f), COPY);
     }
-    const own = new Set([...readdirSync(join(REF, vertical, "rest")), ...readdirSync(appWix)].filter((f) => f.endsWith(".ts") && f !== "types.ts"));
+    const own = new Set([...readdirSync(join(root, "rest")), ...readdirSync(appWix)].filter((f) => f.endsWith(".ts") && f !== "types.ts"));
     for (const f of own) {
       const fp = join(JS, f);
       if (!existsSync(fp)) continue;
@@ -253,7 +295,12 @@ if (stack === "static") {
       const fixed = src.replace(/from\s+"\.\/types(?:\.js)?"/g, `from "./${vertical}-types.js"`);
       if (fixed !== src) writeFileSync(fp, fixed);
     }
-    result.verticals.push(vertical);
+    if (VERTICALS.includes(vertical)) result.verticals.push(vertical);
+  }
+  if (siteSearch) {
+    // The REST twin imports the plan as data from beside it (shared/rest already owns config.ts).
+    writeFileSync(join(JS, "site-search-config.generated.ts"), siteSearchConfigSource());
+    result.capabilities = { ...result.capabilities, siteSearch: true };
   }
   // Browser ESM resolves nothing: every relative import needs its .js. The rest/ files are written
   // that way; the files borrowed from app/wix/ are bundler-style and get the suffix here.
@@ -286,7 +333,7 @@ if (stack === "static") {
   result.js = `${outDir ? outDir.replace(/\/$/, "") + "/" : ""}js/wix/*.js`;
   // The note lists what actually landed, so it holds for every vertical (and several at once).
   const stores = readdirSync(JS).filter((f) => f.endsWith("-store.js")).map((f) => `./js/wix/${f}`);
-  const dataFiles = readdirSync(JS).filter((f) => f.endsWith(".js") && !f.endsWith("-store.js") && !f.endsWith("-core.js") && !f.endsWith("-types.js") && !["client.js", "config.js", "media.js"].includes(f)).map((f) => `./js/wix/${f}`);
+  const dataFiles = readdirSync(JS).filter((f) => f.endsWith(".js") && !f.endsWith("-store.js") && !f.endsWith("-core.js") && !f.endsWith("-types.js") && !f.endsWith(".generated.js") && !["client.js", "config.js", "media.js"].includes(f)).map((f) => `./js/wix/${f}`);
   result.note = `import the data layer (${dataFiles.join(", ")})${stores.length ? ` and the stores (${stores.join(", ")})` : ""} relative to ${outDir ?? "the project root"} in a <script type="module">; the .ts beside them are the same files with types, for reading; point wix.config.json site.outputDirectory at "./${outDir ?? "."}"`;
   console.log(JSON.stringify(result));
   process.exit(0);
@@ -319,11 +366,20 @@ if (uploadPolicies.length) {
   cpSync(join(REF, "shared", "capabilities", "media-upload", "app"), SRC, COPY);
   cpSync(join(REF, "shared", "capabilities", "media-upload", "app-astro"), SRC, COPY);
 }
+// Site search ships like a vertical (data layer, stores, hooks, components, a search page) at a
+// disjoint path (src/wix/site-search/, src/components/site-search/, …), so the same per-stack rule
+// applies: lib takes only app/wix/, astro adds app-astro/.
+if (siteSearch) {
+  if (stack === "lib") cpSync(join(REF, SITE_SEARCH, "app", "wix"), join(SRC, "wix"), COPY);
+  else cpSync(join(REF, SITE_SEARCH, "app"), SRC, COPY);
+  if (stack === "astro") cpSync(join(REF, SITE_SEARCH, "app-astro"), SRC, COPY);
+}
 
 const unknown = requested.filter((v) => !VERTICALS.includes(v));
 // lib: only @wix/sdk from the shared deps — the Tailwind pair serves the components, which don't ship there.
 const wantedDeps = stack === "lib" ? { "@wix/sdk": SHARED_DEPS["@wix/sdk"] } : { ...SHARED_DEPS };
 if (uploadPolicies.length) Object.assign(wantedDeps, CAPABILITY_DEPS["media-upload"]);
+if (siteSearch) Object.assign(wantedDeps, CAPABILITY_DEPS["site-search"]);
 for (const vertical of requested.filter((v) => VERTICALS.includes(v))) {
   if (stack === "lib") cpSync(join(REF, vertical, "app", "wix"), join(SRC, "wix"), COPY);
   else cpSync(join(REF, vertical, "app"), SRC, COPY);
@@ -351,6 +407,15 @@ if (uploadPolicies.length) {
   );
   result.capabilities = { mediaUpload: uploadPolicies.map((policy) => policy.id) };
 }
+if (siteSearch) {
+  // The SDK transport imports the plan as data from beside it; defaults resolve in the shipped core.
+  writeFileSync(join(SRC, "wix", "site-search", "config.generated.ts"), siteSearchConfigSource());
+  result.capabilities = { ...result.capabilities, siteSearch: true };
+  if (siteSearch.install) {
+    // Indexing needs the Wix Site Search app on the site — a site mutation the deploy never makes.
+    result.note = [result.note, "siteSearch.install: run `node <SKILL_ROOT>/templates/shared/capabilities/site-search/seed/install.mjs` from the project root after the seed (results appear about half a minute later)"].filter(Boolean).join("; ");
+  }
+}
 
 // ---- dependency patch (fill-only) ----------------------------------------------------------------
 if (result.verticals.length && existsSync(PKG_JSON)) {
@@ -416,12 +481,15 @@ if (stack === "astro" && result.verticals.length && existsSync(ASTRO_CONFIG)) {
 
 // ---- ready-made links -----------------------------------------------------------------------------
 // Emit the siteId and the dashboard deep links so nothing downstream re-derives or retypes them.
+// The site the links point at is the CONTENT site — the parent on a migration preview, where the
+// config's site only hosts the deployment (install/context.mjs).
 const WIX_CONFIG = join(PROJECT, "wix.config.json");
-if (existsSync(WIX_CONFIG)) {
-  const config = JSON.parse(readFileSync(WIX_CONFIG, "utf8"));
-  const siteId = config.siteId ?? config.projectId;
+const ctx = existsSync(WIX_CONFIG) ? siteContext({ cwd: PROJECT }) : null;
+if (ctx) {
+  const siteId = ctx.content.siteId;
   if (siteId) {
     result.siteId = siteId;
+    if (ctx.migration.active) result.migration = { parentSiteId: ctx.migration.parentSiteId, deploySiteId: ctx.deploy.siteId };
     result.dashboardUrl = `https://manage.wix.com/dashboard/${siteId}`;
     if (result.verticals.includes("storefront")) {
       result.productsUrl = `https://manage.wix.com/dashboard/${siteId}/wix-stores/products`;
@@ -440,13 +508,10 @@ if (!requested.length) {
 // ---- client ids ---------------------------------------------------------------------------------
 // The shared data client is ambient on managed Astro. Members are different: their shipped
 // custom credential flow always needs an explicit public OAuth client, including on Astro.
-let clientId = clientIdFlag;
-if (!clientId && existsSync(join(PROJECT, "wix.config.json"))) {
-  // On a Wix-managed project the public OAuth client id IS the appId.
-  clientId =
-    JSON.parse(readFileSync(join(PROJECT, "wix.config.json"), "utf8")).appId ??
-    null;
-}
+// --client-id, else the CONTENT app: .env.local's WIX_CLIENT_ID (what `wix env pull` writes — on a
+// migration preview the parent site's app, the one the Astro integration itself runs as), else the
+// config's appId. Never the config first: on a preview that is the deploy-only child app.
+const clientId = clientIdFlag ?? ctx?.content.clientId ?? null;
 if (stack === "react" || stack === "lib") {
   if (clientId) {
     const current = readFileSync(CONFIG_TS, "utf8");

package/skills/wix-headless-fast/install/setup.mjs

@@ -7,6 +7,11 @@
 //
 //   - `wix.config.json` present → refuses. The folder is already a Wix project; deploy.mjs adds
 //     this skill's code or a solution to it, then one install, then the seed if there is content.
+//     One exception: a config and NO project whose `.env.local` (`wix env pull`, run here) declares a
+//     MIGRATION PREVIEW — the config names a site created only to host the deployment, the env names
+//     the site being migrated. Then → MIGRATE: the composed template is copied in around the config,
+//     the code deploys with the parent's app as its client, the install starts, and NO seed runs: the
+//     parent owns its content. Release still goes where the config says (install/context.mjs).
 //   - a project but no `wix.config.json` (a package.json, or an index.html at the root) → CONNECT:
 //     `npm create @wix/new@latest init` in place creates the site and the config, then deploy.
 //   - otherwise (empty, or loose files such as a CSV or a brief) → CREATE: `wix create` with the
@@ -23,11 +28,12 @@
 // steps — the dependency install and the seed — running detached in the background (logs and
 // completion markers in the final event), so the caller can build the brand layer while they finish.
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AGENT_CONFIG_FILES, writeAgentsMd } from "./agents-md.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
+import { siteContext } from "./context.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -67,17 +73,23 @@ if (planPath && !existsSync(planPath)) fail("args", `plan file not found: ${plan
 // ---- 0 · read the folder --------------------------------------------------------------------------
 const cwd = process.cwd();
 const has = (p) => existsSync(join(cwd, p));
-if (has("wix.config.json")) {
-  fail("place", "this folder is already a Wix project (wix.config.json): nothing to set up. deploy.mjs <vertical> adds this skill's code or a solution to it; then ONE npm install; then the vertical's seed module if there is content to create");
-}
 const pkg = has("package.json") ? JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) : null;
 const hasProject = !!pkg || has("index.html");
-const mode = hasProject ? "connect" : "create";
+// A config here: refuse, unless it is a migration preview with no project yet (the site context
+// pulls .env.local when missing — that is where the migration is declared).
+let ctx = null;
+if (has("wix.config.json")) {
+  ctx = siteContext({ cwd });
+  if (hasProject || !ctx.migration.active) {
+    fail("place", "this folder is already a Wix project (wix.config.json): nothing to set up. deploy.mjs <vertical> adds this skill's code or a solution to it; then ONE npm install; then the vertical's seed module if there is content to create. A config with no project is attach.mjs's case (SKILL.md step 3)" + (ctx.pullError ? ` — note: env pull failed here (${ctx.pullError.slice(0, 120)})` : ""));
+  }
+}
+const mode = ctx ? "migrate" : hasProject ? "connect" : "create";
 if (mode === "connect" && !stackFlag) {
   fail("args", "connecting a project on disk needs --stack astro|react|lib|static — the stack you resolved in SKILL.md step 1 for this project");
 }
 const stack = stackFlag ?? "astro";
-emit("folder", { mode, stack, project: hasProject ? (pkg?.name ?? basename(cwd)) : null });
+emit("folder", { mode, stack, project: hasProject ? (pkg?.name ?? basename(cwd)) : null, ...(ctx ? { migration: ctx.migration, deploySiteId: ctx.deploy.siteId, warnings: ctx.warnings } : {}) });
 
 let projectDir = cwd;
 let folderName = null;
@@ -119,6 +131,25 @@ if (mode === "create") {
       fail("scaffold", (scaffold.stderr || scaffold.stdout || "scaffold produced no wix.config.json — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-600));
     }
   }
+} else if (mode === "migrate") {
+  // ---- 1 · a migration preview: the config and credentials came with the folder -------------------
+  // No site is created and nothing is provisioned: `wix.config.json` already names the deploy site
+  // and its app, `.env.local` the parent's. Managed Astro gets the vertical's composed template copied
+  // in around them (what `wix create` would have copied; the config and env are never overwritten);
+  // any other stack is code-only and deploy below adds it.
+  if (planPath) emit("seed_skipped", { reason: `migration preview of site ${ctx.migration.parentSiteId}: the site owns its content and nothing is seeded — the plan is ignored` });
+  if (stack === "astro") {
+    const template = join(templatesDir({ need: `${vertical}/project` }), vertical, "project");
+    emit("scaffolding", { folder: cwd, template, from: "migration preview" });
+    cpSync(template, cwd, { recursive: true, force: false, errorOnExist: false });
+    const pkgPath = join(cwd, "package.json");
+    const scaffolded = JSON.parse(readFileSync(pkgPath, "utf8"));
+    scaffolded.name = basename(cwd).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "site";
+    writeFileSync(pkgPath, JSON.stringify(scaffolded, null, 2) + "\n");
+  }
+  const gi = join(cwd, ".gitignore");
+  const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (!/\.env/.test(cur)) writeFileSync(gi, cur + "\n# local env (pulled from Wix)\n.env.local\n.env\n");
 } else {
   // ---- 1 · init in place --------------------------------------------------------------------------
   // The CLI's `init` links the folder to a NEW site: creates the site and its OAuth app, writes
@@ -141,7 +172,10 @@ if (stack === "static") {
   wixConfig.site = { ...(wixConfig.site ?? {}), outputDirectory: `./${STATIC_OUT}` };
   writeFileSync(join(projectDir, "wix.config.json"), JSON.stringify(wixConfig, null, 2) + "\n");
 }
-emit(mode === "create" ? "scaffolded" : "connected", { folder: folderName ?? cwd, siteId, stack });
+emit(mode === "create" ? "scaffolded" : mode === "migrate" ? "migration_preview" : "connected", {
+  folder: folderName ?? cwd, stack,
+  ...(ctx ? { deploySiteId: ctx.deploy.siteId, contentSiteId: ctx.content.siteId } : { siteId }),
+});
 
 // ---- 2 · deploy shipped code + deps ---------------------------------------------------------------
 // A CREATE from the composed template already holds the code and the lock: deploy adds nothing and
@@ -189,7 +223,7 @@ if (mode === "create" && !subfolder && projectDir !== cwd) {
 // ---- 2d · the agent config files `wix create` would have written --------------------------------
 // Skipped by the CLI because of --skip-install. Fill-only: a project that has its own AGENTS.md
 // keeps it (the event says `kept`).
-emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack }));
+emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack, ...(ctx ? { migration: { parentSiteId: ctx.migration.parentSiteId, deploySiteId: ctx.deploy.siteId } } : {}) }));
 
 // ---- 3 · start the dependency install, detached --------------------------------------------------
 // ONE install, here, for any project with a package.json (deploy patched it). The static stack has
@@ -215,7 +249,7 @@ if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
 // result JSON + exit-code marker land as files the caller syncs on before release. Seeding is
 // additive: it never deletes or overwrites what the site holds.
 let seed = null;
-if (planPath) {
+if (planPath && mode !== "migrate") {
   const seedDir = join(TEMPLATES, vertical, "seed");
   const seedName = existsSync(seedDir)
     ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
@@ -240,20 +274,26 @@ const release = {
   lib: "the project's own build, then npx @wix/cli@latest release of the build folder named in wix.config.json (SKILL.md step 1)",
   static: `npx @wix/cli@latest release — no build; it uploads ${STATIC_OUT}/ whole (wix.config.json site.outputDirectory), so the pages, styles and assets move into ${STATIC_OUT}/ first and import the modules from ./js/wix/ there; the root keeps the config, the plan, the seed output and the skills`,
 }[stack];
+// On a migration preview the links and `siteId` are the PARENT's — the site whose content the pages
+// show and whose dashboard manages it; `deploySiteId` is where `wix release` goes.
 emit("ready_for_brand_layer", {
   mode,
   stack,
   projectDir,
-  siteId,
+  siteId: ctx ? ctx.content.siteId : siteId,
+  ...(ctx ? { deploySiteId: ctx.deploy.siteId, migration: { parentSiteId: ctx.migration.parentSiteId } } : {}),
   dashboardUrl: deployResult.dashboardUrl,
   productsUrl: deployResult.productsUrl,
   categoriesUrl: deployResult.categoriesUrl,
   install,
   seed,
   next:
-    (planPath
+    (mode === "migrate"
+      ? "a migration preview: the site being migrated owns its content (read it with the vertical's read-site.mjs when the brief allows probing; never seed it); theme + write the home page; "
+      : planPath
       ? "theme + write the home page; "
       : "the site is new and empty — seed it (a plan per step 2, the vertical's seed module) or say so; theme + write the home page; ") +
     (install || seed ? "then wait for the done markers" + (seed ? ", verify .seed-exit is 0 (else read seed.log and re-run the seed module)" : "") + "; " : "") +
-    `then ${release}`,
+    `then ${release}` +
+    (mode === "migrate" ? "; the release is the PREVIEW on the deploy site — close with its URL and the parent's dashboard, say the original site is unchanged and that completing the migration is the user's next step in the Wix CLI once they approve" : ""),
 });

package/skills/wix-manage/SKILL.md

@@ -163,7 +163,7 @@ Create and modify CMS collection structures. Covers listing collections, creatin
 Deletes multiple contacts using filter-based bulk delete. Covers safe deletion patterns, GDPR compliance, soft delete alternatives, and batch processing strategies.
 
 ### [Bulk Label and Unlabel Contacts](references/contacts/bulk-label-and-unlabel-contacts.md)
-Adds/removes labels from multiple contacts using Contacts API bulk operations. Covers label creation, contact filtering, batch processing, and rate limit handling.
+Creates contact label definitions or adds/removes labels from matching contacts. Use Find or Create Label for label creation alone; use bulk labeling only when the user requests contact assignments.
 
 ### [Create a Contact](references/contacts/create-a-contact.md)
 Creates a contact with the Contacts API. Covers the minimum identifying fields, the single-object shape of `email` and `phone`, and adding a physical address with the ISO 3166-2 subdivision format required for state, region, and province codes.
@@ -211,7 +211,7 @@ Buy a domain through Wix or connect one the user already owns — intent, availa
 **Entry point for all eCommerce recommendation requests.** Unified skill that analyzes site data across ALL domains (discounts + shipping + gift cards), generates up to 5 cross-domain recommendations, and persists them to the tracking database. Covers discount strategies (seasonal, upsell, stock mover, bundling), shipping optimization (coverage gaps, free shipping, rate strategy, carrier backup), AND selling gift cards (denominations sized from the site's own AOV and catalog prices). Use this for business improvement requests about earning more from existing visitors. **Traffic acquisition (SEO, ads, social, content) is out of scope** — route "grow my traffic" to marketing.
 
 ### [Pricing & Promotions](references/ecommerce/ecom-pricing.md)
-**Dispatcher** — routes coupon/discount/sale/ribbon/bundle requests to the right leaf recipe (create coupon, create discount rule, troubleshoot discount-not-applying), and routes strategic "run a sale / boost sales" requests to `recommend-ecommerce-strategy`.
+Routes discounts, coupons, sales and bundles to promotion recipes, and visual product ribbons to the Catalog Ribbons API. Load this dispatcher for mixed pricing/refund/payment/product-price/shipping requests to choose the appropriate APIs.
 
 ### [Shipping](references/ecommerce/ecom-shipping.md)
 **Dispatcher** — routes shipping-setup requests (rates, regions, pickup, free shipping, fix coverage, optimize rates) to the right leaf recipe. The Shipping Options + Delivery Profiles APIs have no public docs page; `ecom-shipping-api.md` is the authoritative inline reference.
@@ -422,7 +422,7 @@ List, count, and find the sites in a Wix account. Covers the namespace filter fo
 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.
 
 ### [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, 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.
+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.
 
 ### [Sites Dashboard Navigation](references/sites/sites-dashboard-navigation.md)
 "Builds direct links to the account-level sites pages on manage.wix.com — the My Sites list (all sites in the account) and each site's own dashboard. Pairs the site list with the Query Sites read API. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."

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

@@ -107,15 +107,81 @@ Some common apps:
 - 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).
 - The `tenantType` MUST be `SITE`
 - The `id` in tenant is the site's metaSiteId
+- The endpoint, request body, and appDefId table above are complete and canonical for a listed Wix-built app — don't re-verify them with a separate REST/API doc search first; that's a redundant round-trip.
+- Don't spend a call checking whether the app is already installed before installing it. If the task or the error you're handling already tells you it isn't installed (e.g. a fresh site, or a `*_NOT_INSTALLED` error), just call install directly.
 
 ---
 
 ## Error Handling
 
 ### App Not Installed Error
-If you receive an error indicating a required app is not installed, use this recipe to install it before proceeding.
+If you receive an error indicating a required app is not installed (e.g. a `428` or a `*_NOT_INSTALLED` error code), install the app it names using its appDefId, then retry the call that failed. If the user's own request already implies this app is needed — i.e. doing what they asked requires a feature only that app provides — just install it as part of doing that task; don't stop to ask permission or name the app first. Confirm first only when the app isn't implied by anything the user asked for.
+
+**Example** (install the missing app, then retry the call that surfaced the error — all in one script):
+```javascript
+async function() {
+  const siteId = "<SITE_ID>";
+
+  await wix.request({
+    method: "POST",
+    url: "https://www.wixapis.com/apps-installer-service/v1/app-instance/install",
+    body: {
+      tenant: { tenantType: "SITE", id: siteId },
+      appInstance: { appDefId: "<APP_DEF_ID>" }
+    }
+  });
+
+  return await wix.request({
+    method: "<METHOD>",
+    url: "<ORIGINAL_URL_THAT_FAILED>",
+    body: { /* original request body */ }
+  });
+}
+```
+
+### App-Dependent Call Fails Right After Install (Propagation Delay)
+Installing an app and then immediately calling one of its own APIs — e.g. calling Set Multilingual Mode right after installing Wix Multilingual — can race the platform's install propagation, surfacing as a not-found error on the dependent call even though the install itself already succeeded.
+
+**Example** (retry with backoff past the propagation delay instead of surfacing the error, all in one script):
+```javascript
+async function() {
+  const siteId = "<SITE_ID>";
+
+  async function requestWithRetry(requestOptions, delaysMs = [1000, 2000, 4000]) {
+    let lastError;
+    try {
+      return await wix.request(requestOptions);
+    } catch (err) {
+      lastError = err;
+    }
+    for (const delayMs of delaysMs) {
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+      try {
+        return await wix.request(requestOptions);
+      } catch (err) {
+        lastError = err;
+      }
+    }
+    throw lastError;
+  }
 
-If Locale Settings or Locales APIs return `428 MULTILINGUAL_NOT_INSTALLED`, install **Wix Multilingual** using appDefId `14d84998-ae09-1abf-c6fc-3f3cace5bf19`, then retry enabling multilingual mode or creating locales. Confirm with the user before installing unless they already explicitly asked you to install Wix Multilingual.
+  await wix.request({
+    method: "POST",
+    url: "https://www.wixapis.com/apps-installer-service/v1/app-instance/install",
+    body: {
+      tenant: { tenantType: "SITE", id: siteId },
+      appInstance: { appDefId: "14d84998-ae09-1abf-c6fc-3f3cace5bf19" }
+    }
+  });
+
+  return await requestWithRetry({
+    method: "POST",
+    url: "https://www.wixapis.com/locale-settings/v2/settings/mode",
+    body: { multilingualModeEnabled: true }
+  });
+}
+```
+Chain any further calls inside this same function through the same `requestWithRetry` helper, after the first one succeeds.
 
 ---
 

package/skills/wix-manage/references/contacts/bulk-label-and-unlabel-contacts.md

@@ -1,12 +1,29 @@
 ---
 name: "Bulk Label and Unlabel Contacts"
-description: Adds/removes labels from multiple contacts using Contacts API bulk operations. Covers label creation, contact filtering, batch processing, and rate limit handling.
+description: Creates contact label definitions or adds/removes labels from matching contacts. Use Find or Create Label for label creation alone; use bulk labeling only when the user requests contact assignments.
 ---
 # Bulk Label And Unlabel Contacts
 
 ## Description
 Adds and removes labels from multiple contacts using the Wix Contacts REST API.
 
+## Create labels or assign labels?
+
+If the user asks to **create a label** (for example, "Create VIP, Wholesale, and Newsletter labels"), use [Find or Create Label](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/labels/find-or-create-label) directly. Creating a label definition does not require finding contacts or starting a bulk labeling job.
+
+```http
+POST https://www.wixapis.com/contacts/v4/labels
+Content-Type: application/json
+
+{"displayName":"VIP"}
+```
+
+Use the returned `label` and its `key`; `newLabel` distinguishes a newly created label from an existing one. For several names, make one call per name and check each result. Stop here when the request is only to create labels: do not assign them to contacts.
+
+If the user asks to **label or unlabel contacts**, resolve the requested label keys first, then follow the bulk assignment flow below. Create a missing label only when that is part of the authorized request. An explicit request to create labels or apply them to a specified set of contacts authorizes that operation; otherwise confirm the target and intended change before mutating.
+
+## Bulk assignment flow
+
 Labels are added to and removed from all contacts that meet the specified `filter` and `search` criteria.
 The request should specify a `filter` value, a `search` value, or both.
 To perform a dry run, call [Query Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/query-contacts) with the intended filter options.
@@ -17,6 +34,22 @@ The job's status can be retrieved with [Get Bulk Job](https://dev.wix.com/docs/a
 
 **IMPORTANT NOTE:** When specific contacts are to be labeled, they should be filtered by id.
 
+### Steps
+
+1. **Resolve label keys.** When adding, Find or Create Label (above) returns the `key`. To remove a label, or to
+   use only a label that already exists, look it up by name instead of creating it:
+   `POST https://www.wixapis.com/contacts/v4/labels/query` with
+   `{"query":{"filter":{"displayName":{"$eq":"Newsletter"}}}}`, and take each returned label's `key`.
+2. **Resolve named contacts to IDs** with Search Contacts, as in
+   [Update a Contact](update-a-contact.md) — Query Contacts cannot filter on a name:
+   `POST https://www.wixapis.com/contacts/v5/contacts/search` with `{"search":{"search":{"expression":"Leo Marsh"}}}`.
+   Each result in `contacts` has an `id` and `name.first` / `name.last`; keep only exact name matches. If none or
+   more than one contact matches, stop and ask the user.
+3. **Start the job** with the endpoint below, filtering by the resolved IDs:
+   `{"filter":{"id":{"$in":["<CONTACT_ID>"]}},"labelKeysToAdd":["<LABEL_KEY>"]}` (or `labelKeysToRemove`).
+4. **Confirm the job finished** with `GET https://www.wixapis.com/contacts/v4/bulk/jobs/{jobId}`; repeat until
+   `job.status` is `COMPLETED`, then report `job.successTotal` and `job.failedTotal`.
+
 ## API Endpoint
 `POST https://www.wixapis.com/contacts/v4/bulk/contacts/add-remove-labels`
 
@@ -29,10 +62,10 @@ curl -X POST \
   -H 'Content-Type: application/json' \
   -d '{
     "filter": {
-      "info.name.first": "John"
+      "id": { "$in": ["<CONTACT_ID_1>", "<CONTACT_ID_2>"] }
     },
-    "labelKeysToAdd": ["custom.name-john", "custom.name-starts-with-J"],
-    "labelKeysToRemove": ["custom.last-name-smith"]
+    "labelKeysToAdd": ["custom.newsletter"],
+    "labelKeysToRemove": ["custom.prospect"]
   }'
 ```
 

package/skills/wix-manage/references/ecommerce/ecom-pricing.md

@@ -1,6 +1,6 @@
 ---
 name: "Pricing & Promotions"
-description: Pricing & Promotions boundary owner — discounts, coupons, sales, ribbons, bundles. **Always load this dispatcher first when a question touches both discount work and refunds, payments, product-price edits, or shipping rates** — the rules for which side owns each topic live in this file, not in this README line.
+description: Routes discounts, coupons, sales and bundles to promotion recipes, and visual product ribbons to the Catalog Ribbons API. Load this dispatcher for mixed pricing/refund/payment/product-price/shipping requests to choose the appropriate APIs.
 ---
 
 # Pricing & Promotions
@@ -14,7 +14,9 @@ Discount rules, coupon codes, sales, ribbons, bundles, tiered pricing, and the s
 - A standing $0 shipping option/region rate → see **Shipping & fulfillment**.
 - Refunding a previous discounted order → route to verified Get Paid/payment docs or Dashboard guidance.
 
-> **Before dispatching** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded.
+> **Ribbon-only requests** — go directly to the ribbon path below; skip MerchantContext and promotion-strategy discovery.
+>
+> **Before dispatching promotion requests** — confirm MerchantContext is loaded. If `siteData.country` is not in your conversation context, load it via [Load Merchant Context](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/e-commerce-load-context). Skip if already loaded.
 >
 > **Promotion dispatch.** Score each entry below by (a) the merchant's query → `intent:*` tags, (b) MerchantContext → context tags. Load the **highest-scoring** entry. Ties → highest `priority`. No match → follow the base recipe at the bottom.
 >
@@ -24,9 +26,33 @@ Discount rules, coupon codes, sales, ribbons, bundles, tiered pricing, and the s
 
 > - [Create coupon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-coupon) — tags: `[intent:create-coupon]` · priority 0
 > - [Create discount rule (auto-apply)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:create-discount-rule]` · priority 0
-> - [Add sale ribbon / new ribbon](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:add-ribbon]` · priority 0 · *ribbons are configured via Discount Rules; same recipe*
+> - [Create or reuse a Catalog V3 ribbon](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/ribbons-v3/get-or-create-ribbon) — tags: `[intent:add-ribbon]` · priority 0 · *a ribbon is a visual product label, not a discount rule; follow the ribbon path below*
 > - [Schedule a future sale](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule) — tags: `[intent:schedule-sale]` · priority 0 · *uses Discount Rules with `startTime` in the future*
 
+### Ribbon path
+
+For a Catalog V3 request such as "Create a Bestseller ribbon", use the idempotent name-based [Get or Create Ribbon](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/ribbons-v3/get-or-create-ribbon) method:
+
+```http
+POST https://www.wixapis.com/stores/v3/ribbons/get-or-create
+Content-Type: application/json
+
+{"ribbonName":"Bestseller"}
+```
+
+Read the returned `ribbon.id`. If the user requested only the ribbon definition, report that result and stop. If they also requested assignment to a product, read the product's current `revision` with `GET https://www.wixapis.com/stores/v3/products/{productId}`, as in [Update Product with Options](../stores/update-product-with-options.md). Then send only the ribbon with that `revision` through [Update Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/update-product); fields you omit are left unchanged:
+
+```http
+PATCH https://www.wixapis.com/stores/v3/products/{productId}
+Content-Type: application/json
+
+{"product":{"id":"<PRODUCT_ID>","revision":"<CURRENT_REVISION>","ribbon":{"id":"<RIBBON_ID>"}}}
+```
+
+This path covers Catalog V3.
+
+Do not create a coupon, discount rule, or price change just because a ribbon says "Sale". Those require a separate discount request. An explicit ribbon creation or assignment request authorizes that operation; otherwise confirm the intended change first. Merchant context needed for promotion recommendations is not a prerequisite to creating a named visual ribbon.
+
 ### Business flows — the orchestrator
 
 The single business-flow orchestrator (`recommend-ecommerce-strategy`) handles all strategic discount intents. It classifies internally (SEASONAL / UPSELL_BOOST / STOCK_MOVER / BUNDLE_AND_SAVE / ABANDONED_CART) and loads its `goal-*` / `flow-*` support files from the kept ecommerce-root siblings.