@wix/agent-skills 1.22.0 → 1.24.0

package/skills/{wix-headless-fast → wix-headless-kit}/install/setup.mjs

@@ -1,33 +1,42 @@
 // Set up the project in the current folder — one deterministic call from "the folder and the
-// brief" to "brand layer can start", for a folder that is NOT yet a Wix project:
+// brief" to "brand layer can start". The folder decides (install/context.mjs folderShape, five file
+// facts: wix.config.json, its site.outputDirectory, the migration variables in .env.local,
+// package.json, index.html):
 //
-//   node <SKILL_ROOT>/install/setup.mjs --vertical <storefront|bookings|…> \
+//   node <SKILL_ROOT>/install/setup.mjs --vertical <storefront|bookings|…>[,<vertical>…] \
 //        [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] \
 //        [--subfolder [--folder-name <npm-safe-name>]]
 //
-//   - `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.
-//   - 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
-//     vertical's composed template (templates/<vertical>/project: the CLI's blank scaffold with the
-//     vertical deployed and a lockfile), placed in the current directory (`--business-name` required).
+//   empty (or loose files: a CSV, a brief) → CREATE: `wix create` with the vertical's composed template
+//     (templates/<vertical>/project), placed in the current directory (`--business-name` required).
+//   a frontend, no wix.config.json (a package.json, or an index.html at the root) → ADOPT: `init` in
+//     place gives the project a new, empty site, then deploy. `--stack` required.
+//   CREATE and ADOPT are the two cases that seed: the run made the site, it is empty by construction,
+//     and the plan's content goes in (with --plan; without one the agent drafts a plan and seeds it, SKILL.md step 2).
+//   a config and no frontend, .env.local declaring a MIGRATION PREVIEW → MIGRATE: the composed template
+//     is copied in around the config, the code deploys with the parent's app as its client, the install
+//     starts. Nothing seeded: the parent owns its content.
+//   a config, index.html at the root, no package.json → PUBLISHED STATIC (a site published through the
+//     drop flow and downloaded): the config's site, no init; site/ becomes the upload, the REST layer
+//     deploys there, the pages move in (the agent's step). Nothing seeded.
+//   a config and a frontend (package.json, or index.html in the output folder) → refuses: iterate.
+//   a config and nothing else → refuses: attach.mjs's case.
 //
-// The script reads file markers only (wix.config.json, a package.json or index.html); everything
-// else is the agent's call: when connecting, `--stack` is required and comes from SKILL.md step 1,
-// and what the project needs for that stack on Wix hosting is prose there, not detection here. The
-// seed runs only when `--plan` is given: a brief that has not supplied any content gets no seed.
+// Setup seeds only a site it created in this run. A site that existed before the run is never seeded
+// by setup: the agent reads what the site holds (the vertical's read-site.mjs) and runs the seed module
+// deliberately when the brief supplies or describes content. Seeds are additive and idempotent by name.
 //
 // Composes pieces that also remain individually runnable (deploy.mjs, the vertical's seed module)
 // to recover one failed step. Emits ONE JSON event per line and exits in ~35s with the two long
 // 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 { folderShape, siteContext } from "./context.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -45,7 +54,12 @@ const flag = (name) => {
 };
 const businessName = flag("business-name");
 const planPath = flag("plan");
-const vertical = flag("vertical");
+// Every vertical the brief needs, comma-separated. The first one's composed template scaffolds the
+// project and its seed runs from --plan; the others deploy in the same call so the ONE install covers
+// them (adding a vertical after the install has started costs a second install). Their seeds run
+// afterwards, each with its own plan, when the brief gives them content.
+const verticals = (flag("vertical") ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+const vertical = verticals[0] ?? null;
 const stackFlag = flag("stack");
 // Opt-in: keep a CREATE's project in a subfolder instead of the current directory.
 const subfolder = argv.includes("--subfolder");
@@ -53,11 +67,11 @@ const subfolder = argv.includes("--subfolder");
 let TEMPLATES;
 try { TEMPLATES = templatesDir(); } catch (e) { fail("templates", e.message); }
 const knownVerticals = listVerticals(TEMPLATES);
-const usage = `usage: setup.mjs --vertical <${knownVerticals.join("|")}> [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] [--subfolder]`;
+const usage = `usage: setup.mjs --vertical <${knownVerticals.join("|")}>[,<vertical>…] [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] [--subfolder]`;
 // --vertical is REQUIRED: a defaulted vertical deploys the wrong code and runs the wrong seed.
 if (!vertical) fail("args", usage);
-if (!knownVerticals.includes(vertical)) {
-  fail("args", `unknown vertical "${vertical}" — shipped verticals: ${knownVerticals.join(", ")}`);
+for (const v of verticals) {
+  if (!knownVerticals.includes(v)) fail("args", `unknown vertical "${v}" — shipped verticals: ${knownVerticals.join(", ")}`);
 }
 if (stackFlag && !["astro", "react", "lib", "static"].includes(stackFlag)) {
   fail("args", `unknown --stack "${stackFlag}" — astro, react, lib or static`);
@@ -67,17 +81,28 @@ 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));
+const pkg = has("package.json") ? JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) : null;
+let ctx = null;
+let shape = folderShape(cwd).shape;
 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");
+  ctx = siteContext({ cwd }); // pulls .env.local when missing — where a migration is declared
+  shape = ctx.folder.shape;
+  if (shape !== "migration" && shape !== "published-static") {
+    fail("place", `this folder is already a Wix project (wix.config.json), shape "${shape}": nothing to set up. ${ctx.folder.next} (SKILL.md step 3)` + (ctx.pullError ? ` — note: env pull failed here (${ctx.pullError.slice(0, 120)})` : ""));
+  }
+  if (shape === "published-static" && stackFlag && stackFlag !== "static") {
+    fail("args", `a published static site (index.html beside wix.config.json, no package.json) is the static stack; --stack ${stackFlag} does not apply`);
+  }
 }
-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";
-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 mode = { migration: "migrate", "published-static": "published-static", project: "adopt", empty: "create" }[shape];
+const migrating = mode === "migrate";
+const publishedStatic = mode === "published-static";
+const hasProject = shape === "project";
+if (mode === "adopt" && !stackFlag) {
+  fail("args", "adopting 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 });
+const stack = publishedStatic ? "static" : (stackFlag ?? "astro");
+emit("folder", { mode, shape, stack, project: hasProject ? (pkg?.name ?? basename(cwd)) : null, ...(ctx ? { deploySiteId: ctx.deploy.siteId, warnings: ctx.warnings } : {}), ...(migrating ? { migration: ctx.migration } : {}) });
 
 let projectDir = cwd;
 let folderName = null;
@@ -119,12 +144,39 @@ 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. The download usually carries the CLI's blank Astro
+  // starter beside the config: then the project is kept and deploy below adds the vertical's code and
+  // dependencies into it, as for an adopted project. A bare config (no package.json) gets the
+  // vertical's composed template copied in around it on managed Astro; any other stack is code-only.
+  if (stack === "astro" && has("package.json")) {
+    emit("migration_project_kept", { folder: cwd, project: pkg?.name ?? basename(cwd) });
+  } else 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 if (publishedStatic) {
+  // ---- 1 · a published static site: the config came with the folder, the site exists -------------
+  // No init: `wix.config.json` already names the site the pages are published on (and its app). The
+  // pages stay where they are; the static handling below points the upload at site/ and the `next`
+  // says to move them in.
+  emit("preparing", { folder: cwd, siteId: ctx.deploy.siteId, from: "published static site" });
 } else {
   // ---- 1 · init in place --------------------------------------------------------------------------
   // The CLI's `init` links the folder to a NEW site: creates the site and its OAuth app, writes
   // wix.config.json and .env.local, touches nothing else. Non-interactive under CI=1; the site is
   // named after the folder (rename it in the dashboard).
-  emit("initializing", { folder: cwd });
+  emit("adopting", { folder: cwd });
   const init = spawnSync("npm", ["create", "@wix/new@latest", "--", "init"],
     { cwd, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 });
   if (init.status !== 0 || !has("wix.config.json")) {
@@ -141,14 +193,17 @@ 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({ create: "scaffolded", migrate: "migration_preview", adopt: "adopted", "published-static": "prepared" }[mode], {
+  folder: folderName ?? cwd, stack,
+  ...(migrating ? { 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
-// reports the project; a CONNECT gets the code and its dependencies here.
+// reports the project; an ADOPT gets the code and its dependencies here.
 const deploy = spawnSync(
   "node",
-  [join(SKILL_ROOT, "install", "deploy.mjs"), vertical, "--stack", stack, ...(stack === "static" ? ["--out", STATIC_OUT] : []), ...(planPath ? ["--plan", resolve(planPath)] : [])],
+  [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack, ...(stack === "static" ? ["--out", STATIC_OUT] : []), ...(planPath ? ["--plan", resolve(planPath)] : [])],
   { cwd: projectDir, encoding: "utf8", timeout: 60_000 },
 );
 if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
@@ -189,7 +244,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, ...(migrating ? { 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
@@ -209,13 +264,19 @@ if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
   emit("install_started", install);
 }
 
-// ---- 4 · start the seed, detached (only with a plan) ---------------------------------------------
+// ---- 4 · start the seed, detached (a site this run created, with a plan) ---------------------------
 // The seed includes a Wix-side provisioning wait of unpredictable length (10-80s); running it in
 // the caller's foreground would idle the agent for exactly that long. Detach it like the install:
-// 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.
+// result JSON + exit-code marker land as files the caller syncs on before release. Only a site this
+// run created is seeded here; every other site existed before the run and is read first, then the
+// agent runs the seed module itself when the brief supplies content. Seeds are additive and
+// idempotent by name.
+const madeTheSite = mode === "create" || mode === "adopt";
 let seed = null;
-if (planPath) {
+if (planPath && !madeTheSite) {
+  emit("seed_skipped", { reason: `${mode}: the site existed before this run; setup seeds only a site it created. Read what the site holds (templates/${vertical}/seed/read-site.mjs), then run templates/${vertical}/seed/seed-*.mjs ${planPath} yourself when the brief supplies or describes content` });
+}
+if (planPath && madeTheSite) {
   const seedDir = join(TEMPLATES, vertical, "seed");
   const seedName = existsSync(seedDir)
     ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
@@ -230,7 +291,7 @@ if (planPath) {
   );
   seedChild.unref();
   seed = { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" };
-  emit("seeding_started", { vertical, ...seed });
+  emit("seeding_started", { vertical, ...seed, ...(verticals.length > 1 ? { note: `the plan seeds ${vertical}; the other verticals' seeds run afterwards, each with its own plan` } : {}) });
 }
 
 // ---- done ----------------------------------------------------------------------------------------
@@ -240,20 +301,33 @@ 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.
+const others = verticals.slice(1);
 emit("ready_for_brand_layer", {
   mode,
+  shape,
   stack,
+  verticals,
   projectDir,
-  siteId,
+  siteId: migrating ? ctx.content.siteId : siteId,
+  ...(migrating ? { deploySiteId: ctx.deploy.siteId, migration: { parentSiteId: ctx.migration.parentSiteId } } : {}),
   dashboardUrl: deployResult.dashboardUrl,
   productsUrl: deployResult.productsUrl,
   categoriesUrl: deployResult.categoriesUrl,
   install,
   seed,
   next:
-    (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; ") +
+    (publishedStatic ? "a published static site: its pages are live on this site already and keep their URL; move index.html, the other pages, styles and assets into site/ (the root keeps the config, the plan, the seed output and the skills) and wire the solution into the page that needs it; " : "") +
+    (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; "
+      : madeTheSite
+      ? (planPath ? "theme + write the home page; " : "the site is new and empty and no plan was given, so nothing was seeded yet: seed it now (a plan per step 2 — the brief's content, or one drafted per the vertical's SEED.md — then the vertical's seed module), and name the placeholder content in the closing message; theme + write the home page; ")
+      : `nothing was seeded (setup seeds only a site it created): read what the site holds with templates/${vertical}/seed/read-site.mjs, then run templates/${vertical}/seed/seed-*.mjs <plan> when the brief supplies or describes content; theme + write the home page; `) +
+    (others.length && mode !== "migrate"
+      ? `${others.join(", ")} deployed too, no further install needed: run each one's seed module (templates/<vertical>/seed/) with its own plan when the brief gives it content (the members seed installs the Members Area app and needs no plan); `
+      : "") +
     (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-headless-fast → wix-headless-kit}/install/templates.mjs

@@ -142,7 +142,7 @@ function fetchTemplates(cache) {
 
 // A sparse, shallow clone of templates/ at a ref (branch, tag, or commit id) into a temp dir.
 function cloneSparse(repo, ref) {
-  const tmp = mkdtempSync(join(tmpdir(), "wix-headless-fast-templates-"));
+  const tmp = mkdtempSync(join(tmpdir(), "wix-headless-kit-templates-"));
   let r;
   if (ref && /^[0-9a-f]{40}$/i.test(ref)) {
     // a commit: shallow-fetch just it (GitHub serves any reachable commit by id)

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/cms/cms-dashboard-navigation.md

@@ -28,8 +28,8 @@ Fetch the entity via REST, then link the matching dashboard page. All calls use
 
 | Entity | Read API | Dashboard link |
 |---|---|---|
-| Collection (schema) | `GET /wix-data/v2/collections/{collectionId}` · `GET /wix-data/v2/collections` (list) | `wix-cms/data/{collectionId}` |
-| Data item | `POST /wix-data/v2/items/query` (body includes `dataCollectionId`) · `GET /wix-data/v2/items/{itemId}?dataCollectionId=...` | `wix-cms/data/{collectionId}` (the collection's items table) |
+| Collection (schema) | `GET https://www.wixapis.com/wix-data/v2/collections/{collectionId}` · `GET https://www.wixapis.com/wix-data/v2/collections` (list) | `wix-cms/data/{collectionId}` |
+| Data item | `POST https://www.wixapis.com/wix-data/v2/items/query` (body includes `dataCollectionId`) · `GET https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId=...` | `wix-cms/data/{collectionId}` (the collection's items table) |
 
 Example — after creating a collection and inserting items:
 

package/skills/wix-manage/references/cms/cms-data-items-crud.md

@@ -25,8 +25,8 @@ This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix
 Before inserting or updating items, you need to know the collection's field names and types. If you don't already know the schema:
 
 1. **Query existing items** - Fetch a few items to infer field names from the data
-2. **Get collection schema** - Use `GET /collections/{dataCollectionId}` for full field definitions, **including `plugins`** — don't omit the `plugins` field when fetching or listing schemas
-3. **List collections** - Use `GET /collections?fields=displayName,plugins` to see what collections exist (see [Schema Management](cms-schema-management.md))
+2. **Get collection schema** - Use `GET https://www.wixapis.com/wix-data/v2/collections/{dataCollectionId}` for full field definitions, **including `plugins`** — don't omit the `plugins` field when fetching or listing schemas
+3. **List collections** - Use `GET https://www.wixapis.com/wix-data/v2/collections?fields=displayName,plugins` to see what collections exist (see [Schema Management](cms-schema-management.md))
 
 It may be, that user refers to schema by its `displayName` rather than `id`, if collection is not found list all collections to find the right `id` (`dataCollectionId`) to use.
 
@@ -36,7 +36,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Insert Data Item
 
-**Endpoint**: `POST /wix-data/v2/items`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items`
 
 **Request Body**:
 ```json
@@ -73,7 +73,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Bulk Insert Items
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/insert`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert`
 
 **Request Body**:
 ```json
@@ -108,7 +108,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Query Data Items
 
-**Endpoint**: `POST /wix-data/v2/items/query`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/query`
 
 **Basic Query**:
 ```json
@@ -163,7 +163,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Get Single Item
 
-**Endpoint**: `GET /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
+**Endpoint**: `GET https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
 
 ```bash
 curl -X GET \
@@ -173,7 +173,7 @@ curl -X GET \
 
 ## Update Data Item
 
-**Endpoint**: `PUT /wix-data/v2/items/{itemId}`
+**Endpoint**: `PUT https://www.wixapis.com/wix-data/v2/items/{itemId}`
 
 **Request Body**:
 ```json
@@ -192,7 +192,7 @@ curl -X GET \
 
 ## Patch Data Item (Partial Update - Single Item)
 
-**Endpoint**: `PATCH /wix-data/v2/items/{dataItemId}`
+**Endpoint**: `PATCH https://www.wixapis.com/wix-data/v2/items/{dataItemId}`
 
 Unlike Update, this only modifies the specified fields — all other fields remain unchanged.
 
@@ -229,7 +229,7 @@ Unlike Update, this only modifies the specified fields — all other fields rema
 
 ## Bulk Update Items
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/update`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/update`
 
 > **Important**: Use `id` (not `_id`) at the element level. The `data` object should NOT contain `_id`.
 
@@ -259,7 +259,7 @@ Unlike Update, this only modifies the specified fields — all other fields rema
 
 ## Bulk Patch Items (Partial Update)
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/patch`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/patch`
 
 Unlike bulk update, this only modifies the specified fields - other fields remain unchanged. **Use this for partial updates.**
 
@@ -330,15 +330,15 @@ Unlike bulk update, this only modifies the specified fields - other fields remai
 >
 > **For MULTI_REFERENCE operations (add speakers, assign tags, link categories, etc.):**
 > **READ [CMS References & Relationships](cms-references-and-relationships.md)** for the exact endpoints and request bodies:
-> - `POST /wix-data/v2/bulk/items/insert-references` - add references
-> - `POST /wix-data/v2/items/replace-references` - replace all references
-> - `POST /wix-data/v2/bulk/items/remove-references` - remove references
+> - `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert-references` - add references
+> - `POST https://www.wixapis.com/wix-data/v2/items/replace-references` - replace all references
+> - `POST https://www.wixapis.com/wix-data/v2/bulk/items/remove-references` - remove references
 >
 > Error `WDE0303` occurs when attempting to set multi-reference fields via data operations.
 
 ## Delete Data Item
 
-**Endpoint**: `DELETE /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
+**Endpoint**: `DELETE https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
 
 ```bash
 curl -X DELETE \
@@ -348,7 +348,7 @@ curl -X DELETE \
 
 ## Bulk Delete Items
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/remove`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/remove`
 
 ```json
 {
@@ -452,7 +452,7 @@ POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
 }
 ```
 
-After the installation succeeds, retry the original `POST /wix-data/v2/items` request. If the
+After the installation succeeds, retry the original `POST https://www.wixapis.com/wix-data/v2/items` request. If the
 user only asks what the error means or how to fix it, explain this installation step and ask for
 confirmation before performing the install.
 

package/skills/wix-manage/references/cms/cms-publishing-flow.md

@@ -68,7 +68,7 @@ Reads target a specific surface — there is no merged view:
 - **Published items**: query the published collection (`articles`).
 - **Drafts**: query the drafts collection resolved from `draftItemsPluginOptions.draftsCollectionId` (e.g. `articles__drafts`).
 
-**Endpoint**: `POST /wix-data/v2/items/query`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/query`
 
 ```json
 {
@@ -92,7 +92,7 @@ Reads target a specific surface — there is no merged view:
 
 Insert into the **drafts** collection. The item starts as **DRAFT**.
 
-**Endpoint**: `POST /wix-data/v2/items`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items`
 
 ```json
 {
@@ -117,7 +117,7 @@ Editing a live item does **not** overwrite the live copy — it stages a **pendi
 
 Replaces the published item's data with the draft's content; the draft is then deleted. Pass the **published** collection id.
 
-**Endpoint**: `POST /wix-data/v2/items/publish-draft`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/publish-draft`
 
 ```bash
 curl -X POST \
@@ -147,7 +147,7 @@ curl -X POST \
 
 Retracts a published item back to draft state. Pass the **published** collection id.
 
-**Endpoint**: `POST /wix-data/v2/items/unpublish`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/unpublish`
 
 ```bash
 curl -X POST \
@@ -198,7 +198,7 @@ curl -X DELETE 'https://www.wixapis.com/wix-data/v2/items/<id>?dataCollectionId=
 
 **Enable** — add the Draft Items plugin (requires collection-management permission). Use the dedicated endpoint; the Draft Items plugin cannot be added through the generic add-plugin call.
 
-**Endpoint**: `POST /wix-data/v2/collections/add-draft-items-plugin`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin`
 
 ```bash
 curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin' \
@@ -219,7 +219,7 @@ curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/add-draft-items-pl
 
 **Disable** — remove the plugin:
 
-**Endpoint**: `POST /wix-data/v2/collections/delete-draft-items-plugin`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/delete-draft-items-plugin`
 
 ```bash
 curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/delete-draft-items-plugin' \
@@ -252,17 +252,17 @@ At the REST level, every read/author/publish/unpublish call here goes through th
 | Collection state | Desired action | API call | Permission needed |
 |------------------|----------------|----------|-------------------|
 | Draft Items plugin absent | Any write | Normal insert/update — writes go live immediately | Write Data Items |
-| Draft Items enabled | Detect workflow | `GET /collections/{id}` → inspect plugins for the Draft Items plugin; read `draftItemsPluginOptions.draftsCollectionId` | (read) |
-| Draft Items enabled | Read published items | `POST /items/query` on the published id | read |
-| Draft Items enabled | Read drafts | `POST /items/query` on the drafts collection id | read |
+| Draft Items enabled | Detect workflow | `GET https://www.wixapis.com/wix-data/v2/collections/{id}` → inspect plugins for the Draft Items plugin; read `draftItemsPluginOptions.draftsCollectionId` | (read) |
+| Draft Items enabled | Read published items | `POST https://www.wixapis.com/wix-data/v2/items/query` on the published id | read |
+| Draft Items enabled | Read drafts | `POST https://www.wixapis.com/wix-data/v2/items/query` on the drafts collection id | read |
 | PUBLISHED | Edit into a pending draft (→ CHANGED) | Create the draft (`createDataItemDraft`), then edit it on the drafts collection | Write Data Items |
-| — | Create new draft (→ DRAFT) | `POST /items` on the drafts collection | Write Data Items |
-| DRAFT / CHANGED | Publish (→ PUBLISHED) | `POST /items/publish-draft` (published id) | Write Data Items |
-| PUBLISHED / CHANGED | Unpublish, keep as draft (→ DRAFT) | `POST /items/unpublish` `copyToDraft:true` | Write Data Items |
-| PUBLISHED / CHANGED | Unpublish, discard | `POST /items/unpublish` `copyToDraft:false` | Write Data Items |
-| CHANGED | Revert to live version (discard edit) | `DELETE /items/{id}?dataCollectionId=<drafts id>` | Write Data Items |
+| — | Create new draft (→ DRAFT) | `POST https://www.wixapis.com/wix-data/v2/items` on the drafts collection | Write Data Items |
+| DRAFT / CHANGED | Publish (→ PUBLISHED) | `POST https://www.wixapis.com/wix-data/v2/items/publish-draft` (published id) | Write Data Items |
+| PUBLISHED / CHANGED | Unpublish, keep as draft (→ DRAFT) | `POST https://www.wixapis.com/wix-data/v2/items/unpublish` `copyToDraft:true` | Write Data Items |
+| PUBLISHED / CHANGED | Unpublish, discard | `POST https://www.wixapis.com/wix-data/v2/items/unpublish` `copyToDraft:false` | Write Data Items |
+| CHANGED | Revert to live version (discard edit) | `DELETE https://www.wixapis.com/wix-data/v2/items/{id}?dataCollectionId=<drafts id>` | Write Data Items |
 | any | Delete entirely (both versions) | Delete on the published id (+ drafts id if a draft exists) | Write Data Items |
-| plain, no plugin | Enable workflow | `POST /collections/add-draft-items-plugin` | Manage Data Collections |
+| plain, no plugin | Enable workflow | `POST https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin` | Manage Data Collections |
 
 ---