@wix/agent-skills 1.21.0 → 1.23.0

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

@@ -7,10 +7,16 @@
 //
 //   - `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: scaffold the Wix CLI's
-//     Astro template and place it in the current directory (`--business-name` required).
+//   - 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).
 //
 // 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,
@@ -22,10 +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 } 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)), "..");
 
@@ -47,9 +55,10 @@ const vertical = flag("vertical");
 const stackFlag = flag("stack");
 // Opt-in: keep a CREATE's project in a subfolder instead of the current directory.
 const subfolder = argv.includes("--subfolder");
-const knownVerticals = readdirSync(join(SKILL_ROOT, "references"), { withFileTypes: true })
-  .filter((d) => d.isDirectory() && d.name !== "shared" && existsSync(join(SKILL_ROOT, "references", d.name, "app")))
-  .map((d) => d.name);
+// The shipped code: the repository's templates/ (a checkout, the cache, or fetched now, in a second).
+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]`;
 // --vertical is REQUIRED: a defaulted vertical deploys the wrong code and runs the wrong seed.
 if (!vertical) fail("args", usage);
@@ -64,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;
@@ -92,7 +107,13 @@ if (mode === "create") {
   if (existsSync(join(projectDir, "wix.config.json"))) {
     emit("scaffold_skipped", { reason: "project already exists", folder: folderName });
   } else {
-    emit("scaffolding", { folder: folderName });
+    // The composed template: the CLI copies it in place of its blank one, creates the site and
+    // writes wix.config.json; the vertical's code and its lockfile arrive with it. Any other
+    // stack takes the CLI's blank Astro scaffold, as before, and deploy below adds the code.
+    // The composed project is the one part of the templates a project's repository does not keep;
+    // a committed copy fetches it here, at the commit the rest came from.
+    const template = stack === "astro" ? join(templatesDir({ need: `${vertical}/project` }), vertical, "project") : null;
+    emit("scaffolding", { folder: folderName, template });
     const scaffold = spawnSync(
       "npm",
       // --skip-git: this wrapper composes its own steps and leaves version control to
@@ -102,13 +123,33 @@ if (mode === "create") {
       // same reason: deps install in a detached step below.
       ["create", "@wix/new@latest", "--", "headless",
        "--folder-name", folderName, "--business-name", businessName,
-       "--site-template", "--skip-install", "--skip-git", "--no-publish"],
+       "--site-template", "blank", ...(template ? ["--template-path", template] : []),
+       "--skip-install", "--skip-git", "--no-publish"],
       { env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 300_000 },
     );
     if (scaffold.status !== 0 || !existsSync(join(projectDir, "wix.config.json"))) {
       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
@@ -123,12 +164,25 @@ if (mode === "create") {
 }
 const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
 const siteId = wixConfig.siteId ?? wixConfig.projectId;
-emit(mode === "create" ? "scaffolded" : "connected", { folder: folderName ?? cwd, siteId, stack });
+// Static: `wix release` uploads the output folder whole, so the project root (config, plan, seed
+// output, the skills) must not be it. The site lives in site/: the config points there and the REST
+// layer deploys into it; the pages, styles and assets are the agent's to move (the `next` says so).
+const STATIC_OUT = "site";
+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" : mode === "migrate" ? "migration_preview" : "connected", {
+  folder: folderName ?? cwd, stack,
+  ...(ctx ? { deploySiteId: ctx.deploy.siteId, contentSiteId: ctx.content.siteId } : { siteId }),
+});
 
-// ---- 2 · deploy shipped code + deps + lockfile ---------------------------------------------------
+// ---- 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.
 const deploy = spawnSync(
   "node",
-  [join(SKILL_ROOT, "install", "deploy.mjs"), vertical, "--stack", stack, ...(planPath ? ["--plan", resolve(planPath)] : [])],
+  [join(SKILL_ROOT, "install", "deploy.mjs"), vertical, "--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);
@@ -169,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
@@ -195,8 +249,8 @@ 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) {
-  const seedDir = join(SKILL_ROOT, "references", vertical, "seed");
+if (planPath && mode !== "migrate") {
+  const seedDir = join(TEMPLATES, vertical, "seed");
   const seedName = existsSync(seedDir)
     ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
     : undefined;
@@ -218,22 +272,28 @@ const release = {
   astro: "npx @wix/cli@latest build, then npx @wix/cli@latest release",
   react: "the project's own build, then npx @wix/cli@latest release of the build folder named in wix.config.json (what Wix hosting serves and how routes must be shaped: SKILL.md step 1)",
   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; wix.config.json site.outputDirectory points at the folder the pages live in",
+  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-headless-fast/install/templates.mjs

@@ -0,0 +1,168 @@
+// Where the shipped code is. The verticals live in the skill's repository under `templates/`
+// (each with its code layers, its tools and a composed project with a lockfile), not in the skill
+// folder: the skill stays small and the code is fetched once, when first needed.
+//
+//   node <SKILL_ROOT>/install/templates.mjs [--refresh]      # prints {templates, source, verticals}
+//
+// Resolution, in order:
+//   1. a checkout of the repository itself (the skill folder sits in it): `<repo>/templates/`.
+//   2. the cache `<SKILL_ROOT>/templates/`, filled by an earlier call (`--refresh` refetches).
+//   3. a fetch: a sparse, shallow clone of `templates/` from the repository the skill was installed
+//      from (skills-lock.json's `source`, default wix/skills), at the branch or tag the install
+//      named (its `ref`, falling back to the default branch when that ref no longer exists) or the
+//      repository's default branch. The lock records no commit, so there is nothing more exact to
+//      pin to; `WIX_HEADLESS_FAST_TEMPLATES_REF=<branch|tag|sha>` overrides the ref.
+// The cache stays with the project: its `.gitignore` leaves out only the composed `project/`
+// folders (the scaffolds with their lockfiles, read once, at create or attach) and the repository
+// tooling, so the code layers, playbooks, seeds and readers are committed at the commit the project
+// was built from, recorded in `.source`. A caller that needs a `project/` folder passes it as
+// `need`; when a committed copy lacks it, that part is fetched at the same commit.
+import { cpSync, existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const DEFAULT_REPO = "https://github.com/wix/skills.git";
+
+const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 180_000, ...opts });
+
+// The repository and ref the skill was installed from: the nearest skills-lock.json above the
+// skill folder, its entry for this skill. "wix/skills" → the default branch of that repository;
+// "https://github.com/owner/repo/tree/<ref>" → that ref.
+export function installSource() {
+  const skill = SKILL_ROOT.split("/").pop();
+  let dir = SKILL_ROOT;
+  for (let i = 0; i < 6; i++) {
+    const p = join(dir, "skills-lock.json");
+    if (existsSync(p)) {
+      try {
+        const entry = JSON.parse(readFileSync(p, "utf8")).skills?.[skill];
+        if (typeof entry?.source === "string" && entry.source) {
+          const parsed = parseSource(entry.source);
+          // `ref` is the branch or tag the install named (skills-lock.json v1 keeps it beside `source`)
+          return { ...parsed, ref: parsed.ref ?? (typeof entry.ref === "string" && entry.ref ? entry.ref : null) };
+        }
+      } catch { /* fall through to the default */ }
+      break;
+    }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return { repo: DEFAULT_REPO, ref: null };
+}
+
+function parseSource(src) {
+  const m = src.match(/^(?:https?:\/\/github\.com\/)?([^/\s]+)\/([^/\s#@]+?)(?:\.git)?(?:\/tree\/([^\s]+))?$/);
+  if (!m) return { repo: DEFAULT_REPO, ref: null };
+  return { repo: `https://github.com/${m[1]}/${m[2]}.git`, ref: m[3] ?? null };
+}
+
+export function listVerticals(dir) {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && d.name !== "shared" && d.name !== "blank" && existsSync(join(dir, d.name, "app")))
+    .map((d) => d.name)
+    .sort();
+}
+
+export function templatesDir({ refresh = false, need = null } = {}) {
+  const checkout = resolve(SKILL_ROOT, "..", "..", "templates");
+  if (existsSync(join(checkout, "shared", "app"))) return checkout;
+  const cache = join(SKILL_ROOT, "templates");
+  if (!refresh && existsSync(join(cache, "shared", "app"))) {
+    if (need && !existsSync(join(cache, need))) fetchIgnoredPart(cache, need);
+    return cache;
+  }
+  fetchTemplates(cache);
+  return cache;
+}
+
+// What a project's repository does not carry: the composed scaffolds (heavy, read once) and the
+// repository's own tooling. Everything else in the cache is committed with the project.
+const IGNORED = ["*/project/", "blank/", "compose.mjs"];
+
+// A committed copy lacks the ignored parts. Fetch them at the commit the copy came from, so the
+// scaffold a create copies matches the code committed beside it; the committed files are untouched.
+function fetchIgnoredPart(cache, need) {
+  const src = templatesSource(cache);
+  const { repo } = installSource();
+  const r = cloneSparse(src.repo ?? repo, src.commit ?? process.env.WIX_HEADLESS_FAST_TEMPLATES_REF ?? null);
+  const tmp = r.tmp;
+  if (r.status !== 0 || !existsSync(join(tmp, "templates", need))) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(`could not fetch templates/${need} from ${src.repo ?? repo}${src.commit ? ` @ ${src.commit.slice(0, 7)}` : ""}: ${(r.stderr || r.stdout || "not in the clone").trim().slice(-300)}`);
+  }
+  for (const part of ["blank", ...readdirSync(join(tmp, "templates"), { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync(join(tmp, "templates", d.name, "project"))).map((d) => `${d.name}/project`)]) {
+    const from = join(tmp, "templates", part);
+    if (existsSync(from) && !existsSync(join(cache, part))) cpSync(from, join(cache, part), { recursive: true });
+  }
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+export function templatesSource(dir) {
+  const p = join(dir, ".source");
+  if (existsSync(p)) { try { return JSON.parse(readFileSync(p, "utf8")); } catch { /* below */ } }
+  return { checkout: dir };
+}
+
+function fetchTemplates(cache) {
+  const { repo, ref: lockRef } = installSource();
+  const envRef = process.env.WIX_HEADLESS_FAST_TEMPLATES_REF || null;
+  let ref = envRef || lockRef || null;
+  let r = cloneSparse(repo, ref);
+  // The branch the skill was installed from can be gone by the time the code is first needed
+  // (merged and deleted). The lock's ref then falls back to the default branch; an explicit env
+  // ref does not.
+  let fellBack = false;
+  if (r.status !== 0 && ref && !envRef && /not found|couldn't find remote ref|unknown revision/i.test(r.stderr || "")) {
+    rmSync(r.tmp, { recursive: true, force: true });
+    fellBack = true; ref = null;
+    r = cloneSparse(repo, null);
+  }
+  const tmp = r.tmp;
+  if (r.error?.code === "ENOENT") {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error("git is not installed or not on PATH; the shipped code is fetched with a git clone of the skill's repository");
+  }
+  if (r.status !== 0 || !existsSync(join(tmp, "templates", "shared", "app"))) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw new Error(`could not fetch templates/ from ${repo}${ref ? ` @ ${ref}` : ""}: ${(r.stderr || r.stdout || "no templates/shared/app in the clone").trim().slice(-400)}`);
+  }
+  const commit = git(["-C", tmp, "rev-parse", "HEAD"]).stdout.trim();
+  rmSync(cache, { recursive: true, force: true });
+  mkdirSync(dirname(cache), { recursive: true });
+  try { renameSync(join(tmp, "templates"), cache); }
+  catch { cpSync(join(tmp, "templates"), cache, { recursive: true }); }
+  rmSync(tmp, { recursive: true, force: true });
+  writeFileSync(join(cache, ".gitignore"), IGNORED.join("\n") + "\n");
+  writeFileSync(join(cache, ".source"), JSON.stringify({ repo, ref: ref ?? (fellBack ? `default branch (${lockRef} not found)` : "default branch"), commit, fetchedAt: new Date().toISOString() }, null, 2) + "\n");
+}
+
+// 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-"));
+  let r;
+  if (ref && /^[0-9a-f]{40}$/i.test(ref)) {
+    // a commit: shallow-fetch just it (GitHub serves any reachable commit by id)
+    for (const args of [["init", "-q", tmp], ["-C", tmp, "remote", "add", "origin", repo], ["-C", tmp, "fetch", "-q", "--depth", "1", "--filter=blob:none", "origin", ref], ["-C", tmp, "sparse-checkout", "set", "templates"], ["-C", tmp, "checkout", "-q", "FETCH_HEAD"]]) {
+      r = git(args);
+      if (r.status !== 0) break;
+    }
+  } else {
+    r = git(["clone", "--quiet", "--depth", "1", "--filter=blob:none", "--sparse", ...(ref ? ["-b", ref] : []), repo, tmp]);
+    if (r.status === 0) r = git(["-C", tmp, "sparse-checkout", "set", "templates"]);
+  }
+  return { ...r, tmp };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const dir = templatesDir({ refresh: process.argv.includes("--refresh") });
+    console.log(JSON.stringify({ templates: dir, source: templatesSource(dir), verticals: listVerticals(dir) }));
+  } catch (e) {
+    console.log(JSON.stringify({ error: e.message }));
+    process.exit(1);
+  }
+}

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.