@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -0,0 +1,259 @@
+// 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:
+//
+//   node <SKILL_ROOT>/install/setup.mjs --vertical <storefront|bookings|…> \
+//        [--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).
+//
+// 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.
+//
+// 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 { 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";
+
+const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const emit = (event, extra = {}) => console.log(JSON.stringify({ event, ...extra }));
+const fail = (step, detail) => {
+  emit("error", { step, detail: String(detail).slice(0, 600) });
+  process.exit(1);
+};
+
+// ---- args ---------------------------------------------------------------------------------------
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
+};
+const businessName = flag("business-name");
+const planPath = flag("plan");
+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");
+// 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);
+if (!knownVerticals.includes(vertical)) {
+  fail("args", `unknown vertical "${vertical}" — shipped verticals: ${knownVerticals.join(", ")}`);
+}
+if (stackFlag && !["astro", "react", "lib", "static"].includes(stackFlag)) {
+  fail("args", `unknown --stack "${stackFlag}" — astro, react, lib or static`);
+}
+if (planPath && !existsSync(planPath)) fail("args", `plan file not found: ${planPath}`);
+
+// ---- 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";
+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 });
+
+let projectDir = cwd;
+let folderName = null;
+
+if (mode === "create") {
+  // ---- 1 · scaffold -----------------------------------------------------------------------------
+  if (!businessName) fail("args", `an empty folder is a CREATE run and needs --business-name. ${usage}`);
+  folderName =
+    flag("folder-name") ??
+    businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+  // `let`: the Wix CLI can only scaffold into a subfolder; by default we then move the scaffold up
+  // into the current directory and repoint projectDir there, so the detached install/seed and every
+  // reported path use the final location.
+  projectDir = resolve(cwd, folderName);
+  if (existsSync(join(projectDir, "wix.config.json"))) {
+    emit("scaffold_skipped", { reason: "project already exists", folder: folderName });
+  } else {
+    // 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
+      // the caller / the enclosing repo; the scaffold's own `git init` + "Initial
+      // commit" is noise here, and becomes a nested-repo (submodule gitlink) hazard
+      // if the project is later placed inside an existing repo. --skip-install for the
+      // same reason: deps install in a detached step below.
+      ["create", "@wix/new@latest", "--", "headless",
+       "--folder-name", folderName, "--business-name", businessName,
+       "--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 {
+  // ---- 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 });
+  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")) {
+    fail("init", (init.stderr || init.stdout || "init produced no wix.config.json — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-600));
+  }
+}
+const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
+const siteId = wixConfig.siteId ?? wixConfig.projectId;
+// 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" : "connected", { folder: folderName ?? cwd, siteId, stack });
+
+// ---- 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, ...(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);
+let deployResult = {};
+try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going with raw output below */ }
+if (deployResult.error) fail("deploy", deployResult.error);
+emit("deployed", deployResult);
+
+// ---- 2c · place a CREATE's project in the current directory -------------------------------------
+// The Wix CLI scaffolds into a subfolder, so the scaffold is moved up into the current directory —
+// the folder that already holds the installed skills — and the subfolder removed. Done HERE, before
+// the detached install below, on purpose: no node_modules exists yet, so the move is instant and
+// cannot collide with a running install. A pure move: the scaffold was created with --skip-git, so
+// there is no nested repo to reconcile — git is whatever the folder already is. Refuses rather than
+// overwrite: an entry that already exists in the current directory stops the move before anything
+// is touched. `--subfolder` skips this step.
+if (mode === "create" && !subfolder && projectDir !== cwd) {
+  // The CLI's own agent config files, when its generator managed to write them, are dropped from
+  // the scaffold: ours (written below, after the move) carries the same CLI section plus this
+  // project's skills. A file the user's folder already has is never overwritten or merged into —
+  // it is kept as is, and the agent_configs event says so.
+  for (const f of AGENT_CONFIG_FILES) rmSync(join(projectDir, f), { recursive: true, force: true });
+  const entries = readdirSync(projectDir);
+  const clashes = entries.filter((e) => existsSync(join(cwd, e)));
+  if (clashes.length) {
+    fail("place", `the current directory already has: ${clashes.join(", ")} — run with --subfolder to keep the project in ${folderName}/, or start in an empty folder`);
+  }
+  try {
+    for (const entry of entries) renameSync(join(projectDir, entry), join(cwd, entry));
+    rmSync(projectDir, { recursive: true, force: true });
+    projectDir = cwd;
+    emit("project_placed", { into: cwd });
+  } catch (e) {
+    fail("place", e?.stack || e);
+  }
+}
+
+// ---- 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 }));
+
+// ---- 3 · start the dependency install, detached --------------------------------------------------
+// ONE install, here, for any project with a package.json (deploy patched it). The static stack has
+// no package.json and nothing to install. `npm ci` only where a lockfile exists: without one it fails
+// with a usage error that sits at the top of the log and reads as a failed install (run 109).
+let install = null;
+if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
+  const installLog = join(projectDir, "npm-install.log");
+  const logFd = openSync(installLog, "a");
+  const child = spawn("sh", ["-c", existsSync(join(projectDir, "package-lock.json")) ? "npm ci --ignore-scripts || npm install --ignore-scripts" : "npm install --ignore-scripts"], {
+    cwd: projectDir,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+  });
+  child.unref();
+  install = { log: installLog, doneMarker: "node_modules/.package-lock.json" };
+  emit("install_started", install);
+}
+
+// ---- 4 · start the seed, detached (only 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.
+let seed = null;
+if (planPath) {
+  const seedDir = join(TEMPLATES, vertical, "seed");
+  const seedName = existsSync(seedDir)
+    ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
+    : undefined;
+  if (!seedName) fail("seed", `no seed module found under ${seedDir}`);
+  const seedFile = join(seedDir, seedName);
+  const planAbs = resolve(planPath);
+  const seedChild = spawn(
+    "sh",
+    ["-c", `node "${seedFile}" "${planAbs}" > seed-result.json 2> seed.log; echo $? > .seed-exit`],
+    { cwd: projectDir, detached: true, stdio: "ignore" },
+  );
+  seedChild.unref();
+  seed = { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" };
+  emit("seeding_started", { vertical, ...seed });
+}
+
+// ---- done ----------------------------------------------------------------------------------------
+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; 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];
+emit("ready_for_brand_layer", {
+  mode,
+  stack,
+  projectDir,
+  siteId,
+  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; ") +
+    (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}`,
+});

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/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md

@@ -47,10 +47,7 @@ Before creating a coupon, check for code conflicts and existing promotions on th
         "code": "SUMMER20",
         "percentOffRate": 20,
         "scope": {
-          "namespace": "stores",
-          "group": {
-            "name": "product"
-          }
+          "namespace": "stores"
         },
         "startTime": 1717200000000,
         "expirationTime": 1719792000000,
@@ -91,10 +88,7 @@ Check for: duplicate codes, overlapping scopes with active coupons, and cross-me
     "code": "SPRING15",
     "percentOffRate": 15,
     "scope": {
-      "namespace": "stores",
-      "group": {
-        "name": "product"
-      }
+      "namespace": "stores"
     },
     "startTime": 1714521600000,
     "usageLimit": 200,
@@ -167,10 +161,7 @@ Check for: duplicate codes, overlapping scopes with active coupons, and cross-me
     "code": "SAVE10",
     "moneyOffAmount": 10,
     "scope": {
-      "namespace": "stores",
-      "group": {
-        "name": "product"
-      }
+      "namespace": "stores"
     },
     "startTime": 1714521600000,
     "active": true
@@ -230,11 +221,11 @@ Instead of targeting a scope, you can require a minimum cart subtotal. This is a
 
 ## Scope values for Wix Stores
 
-| Scope target | `namespace` | `group.name` | `group.entityId` |
-|---|---|---|---|
-| All store products | `"stores"` | `"product"` | Omit (applies to all) |
-| Specific product | `"stores"` | `"product"` | Product UUID |
-| Specific collection | `"stores"` | `"collection"` | Collection UUID |
+| Scope target | `namespace` | `group` |
+|---|---|---|
+| All store products | `"stores"` | Omit the `group` field entirely — a present-but-empty `group: {}` is rejected the same as a populated one missing `entityId` |
+| Specific product | `"stores"` | `{ "name": "product", "entityId": "<product UUID>" }` |
+| Specific collection | `"stores"` | `{ "name": "collection", "entityId": "<collection UUID>" }` |
 
 ---
 
@@ -246,7 +237,7 @@ When the recommendation output has `mechanism: "COUPON"`, use this mapping to co
 
 | Recommendation `scope` | Coupon `scope` |
 |---|---|
-| `SITE` | `{ "namespace": "stores", "group": { "name": "product" } }` (all products, no entityId) |
+| `SITE` | `{ "namespace": "stores" }` (all products — omit `group` entirely) |
 | `CATEGORY` | `{ "namespace": "stores", "group": { "name": "collection", "entityId": "<first categoryId>" } }` |
 | `ITEMS` | `{ "namespace": "stores", "group": { "name": "product", "entityId": "<first productId>" } }` |
 
@@ -340,7 +331,7 @@ When the recommendation output has `mechanism: "COUPON"`, use this mapping to co
 
 | Error | Cause | Fix |
 |---|---|---|
-| `"When scope or minimumSubtotal is not used - only FreeShipping coupon is allowed"` | Coupon sent without `scope` or `minimumSubtotal` | Add `scope: { "namespace": "stores", "group": { "name": "product" } }` for site-wide, or set `minimumSubtotal` |
+| `"When scope or minimumSubtotal is not used - only FreeShipping coupon is allowed"` | Coupon sent without `scope` or `minimumSubtotal` | Add `scope: { "namespace": "stores" }` for site-wide (omit `group` — do not send `group: {}`, which is rejected identically), or set `minimumSubtotal` |
 | Duplicate code | Another coupon uses the same code | Generate a different code |
 | Invalid startTime | Value too low (must be epoch ms, not seconds) | Multiply by 1000 if in seconds |
 | Both scope and minimumSubtotal set | These are oneOf — cannot use both | Choose scope OR minimumSubtotal |

package/skills/wix-manage/references/events/create-wix-event.md

@@ -200,7 +200,11 @@ The response is the definition under `ticketDefinition`:
 Keep `revision` — `PATCH /events/v3/ticket-definitions/{id}` requires the current value, and it
 increments on every update.
 
-- **`feeType` is required** — `FEE_ADDED_AT_CHECKOUT` or `FEE_INCLUDED`.
+- **`feeType` is required.** A free ticket (`fixedPrice` of `"0"`) takes `NO_FEE`. A paid ticket
+  takes `FEE_ADDED_AT_CHECKOUT` (the guest pays the service fee) unless the user asked to absorb it,
+  then `FEE_INCLUDED`. `NO_FEE` on a paid ticket is accepted only on sites that do not collect ticket
+  fees. If a paid ticket fails with `400 INVALID_FEE_TYPE`, the site is one that does not collect
+  ticket fees: retry that ticket once with `NO_FEE`.
 - **`value` is a string.** `"value": 10` fails `400 Unexpected value for field value`.
 - **No writable `free` flag** — `pricingMethod.free` is read-only; a free ticket is a `fixedPrice`
   of `"0"`.

package/skills/wix-manage/references/google-ads/google-ads-dashboard-navigation.md

@@ -12,6 +12,22 @@ Build direct links into the Google Ads page of a site's dashboard. For the gener
 | Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
 |---|---|---|
 | Google Ads | `google-ads` | The Google Ads account, campaigns, and their performance |
+| Keywords manager (campaign-scoped) | `google-ads/keywords-manager?campaignId={campaignId}` | Search themes and campaign exclusions: `excludedSearchTerms` for Smart campaigns and `excludedKeywords` for Performance Max Leads campaigns |
+
+## Resolve a Campaign-Scoped Destination
+
+A campaign-scoped URL requires the campaign's Wix `campaignId`. Never substitute a campaign name in the URL or omit the query parameter.
+
+1. Reuse a `campaignId` already established in the conversation or returned by the preceding campaign operation. A Campaign Success Guide flow has already resolved its campaign, so use that ID without listing campaigns again.
+2. If only the campaign name is known, list campaigns once in the selected site's context:
+
+   ```bash
+   curl -X GET 'https://www.wixapis.com/_serverless/pa-google/v1/campaigns' \
+     -H 'Authorization: <AUTH>'
+   ```
+
+   Read `campaigns[].id` and `campaigns[].name`, and use the ID only when one campaign clearly matches the user's name.
+3. If neither the campaign ID nor name is known, or the list does not yield exactly one clear match, ask the user for the campaign ID or a more specific name. Do not guess or build the link until the campaign is unambiguous.
 
 ## Pairing Entities with Their Read APIs
 
@@ -23,3 +39,14 @@ Example — after creating a campaign:
 Your Performance Max campaign is live.
 Manage it here: https://manage.wix.com/dashboard/{metaSiteId}/google-ads
 ```
+
+When a user explicitly prefers to add a campaign's search themes manually, link directly to that campaign's keywords manager. Do not substitute this manual route for an agent-supported update the user wants the agent to perform.
+
+```
+Add Search Themes: https://manage.wix.com/dashboard/{metaSiteId}/google-ads/keywords-manager?campaignId={campaignId}
+```
+
+The same campaign-scoped route manages exclusions. Name the destination after the campaign field the user is managing:
+
+- **Smart campaigns:** `excludedSearchTerms` → **Manage Excluded Search Terms**
+- **Performance Max Leads campaigns:** `excludedKeywords` → **Manage Excluded Keywords**