@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-kit/install/attach.mjs

@@ -2,12 +2,18 @@
 // exists (named in the prompt by its id). `init`/`wix create` cannot do this: they always create
 // a site. This script does what they do AFTER creating one — OAuth app, managed hosting, env
 // vars, `wix.config.json` — against the site id given, then scaffolds and deploys like
-// setup.mjs. Nothing on the site is created, changed or deleted; there is no seed step.
+// setup.mjs. Nothing on the site is changed or deleted. Seeding is the caller's decision: with
+// --plan the first vertical's seed runs with it (additive, idempotent by name; what the site already
+// held comes back as preexisting[]); without one nothing is seeded — the site owns its content.
 //
 //   node <SKILL_ROOT>/install/attach.mjs [--site <metaSiteId>] --business-name "<Brand>" \
-//        --vertical <a>[,<b>…] [--stack astro|react|lib|static] [--hosting wix|self [--origin <url>[,<url>]]] \
+//        --vertical <a>[,<b>…] [--plan plan.json] [--stack astro|react|lib|static] [--hosting wix|self [--origin <url>[,<url>]]] \
 //        [--subfolder [--folder-name <name>]]
 //
+// --plan           the content to seed, per the vertical's SEED.md — given when the brief supplies or
+//                  describes content (SKILL.md step 2). Also carries plan.capabilities (mediaUpload,
+//                  siteSearch) into deploy. Without it: no seed, and no capabilities.
+//
 // --hosting        wix (default): the frontend releases to Wix hosting — the site's app project is
 //                  created or reused and `wix release` uploads to its *.wix-site-host.com address.
 //                  self: the frontend is hosted elsewhere (Vercel, a Flask server, …): no app
@@ -19,8 +25,8 @@
 // --site           the site. May be omitted when the folder holds a wix.config.json: then it is
 //                  the site in that config (what `init` left behind in an empty folder).
 // --business-name  the site's name (names the folder, the hosting slug and the app project).
-// --vertical       which shipped code deploys (no seed runs — the site owns its content). Both are
-//                  the caller's decision, read off the site before calling this (SKILL.md step 3).
+// --vertical       which shipped code deploys, and whose seed runs with --plan (the first one). Both
+//                  are the caller's decision, read off the site before calling this (SKILL.md step 3).
 // --stack          astro (default) in a folder without a project: copies the first vertical's
 //                  composed template (templates/<vertical>/project). react|static there: writes wix.config.json
 //                  and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md. In a folder
@@ -38,15 +44,17 @@
 // business instead.
 //
 // Emits ONE JSON event per line (attached, scaffolded, deployed, install_started,
-// ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@latest whoami`)
+// ready_for_brand_layer, or error). Requires a logged-in Wix CLI (`npx @wix/cli@<pinned> whoami`, the version in pins.json)
 // whose account owns or co-manages the site.
 import { spawn, spawnSync, execFileSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeAgentsMd } from "./agents-md.mjs";
 import { frontendPresent, siteContext } from "./context.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const MANAGE = "https://manage.wix.com";
@@ -69,6 +77,8 @@ const flag = (name) => {
   return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
 };
 const stackFlag = flag("stack");
+const planPath = flag("plan");
+if (planPath && !existsSync(resolve(planPath))) fail("args", `--plan ${planPath}: no such file`);
 const hosting0 = flag("hosting") ?? "wix";
 const origins = (flag("origin") ?? "").split(",").map((o) => o.trim().replace(/\/$/, "")).filter(Boolean);
 const subfolder = argv.includes("--subfolder");
@@ -90,6 +100,10 @@ if (cwdConfig) {
   }
 }
 const siteId = flag("site") ?? cwdConfig?.siteId ?? cwdConfig?.projectId ?? null;
+// Where the site came from decides the seed (SKILL.md step 3). A config in this folder for this site
+// is what `init` leaves behind, and `init` always creates a site: that site was made for this run and
+// is empty. A site named with --site (and not already this folder's) existed before the run.
+const siteOrigin = cwdConfig && (cwdConfig.siteId === siteId || cwdConfig.projectId === siteId) ? "init" : "given";
 const stack = stackFlag ?? "astro";
 const knownVerticals = listVerticals(TEMPLATES);
 const verticals = argv
@@ -119,13 +133,13 @@ if (!subfolder) {
   }
 }
 const mode = !subfolder && hasProject ? "link" : hosting0 === "self" ? "config-only" : "scaffold";
-emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cwdConfig ? "same site" : null });
+emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cwdConfig ? "same site" : null, siteOrigin });
 
 // ---- http ---------------------------------------------------------------------------------------
 const cliToken = (site) => {
-  const r = spawnSync("npx", ["-y", "@wix/cli@latest", "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
+  const r = spawnSync("npx", ["-y", WIX_CLI, "token", ...(site ? ["--site", site] : [])], { encoding: "utf8", timeout: 120_000 });
   const t = (r.stdout || "").trim();
-  if (r.status !== 0 || !t) fail("auth", (r.stderr || r.stdout || "no token — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").slice(-400));
+  if (r.status !== 0 || !t) fail("auth", (r.stderr || r.stdout || `no token — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-400));
   return t;
 };
 async function call(base, path, { method = "POST", token, site, body, query } = {}) {
@@ -289,7 +303,8 @@ emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), s
 
 if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
   emit("ready", { projectDir, siteId, appId, baseUrl, hosting, frontend, stack, dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
-    next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack} (the client id is read from wix.config.json); no seed — the site owns its content` +
+    next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack}${planPath ? ` --plan ${planPath}` : ""} (the client id is read from wix.config.json); ` +
+      (planPath ? `then seed with the plan: node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs ${planPath}` : `no plan given, so nothing seeds — the site owns its content`) +
       (hosting === "self" ? `; you host it: origins on the OAuth app allow-list now: ${origins.join(", ") || "none — add them before the first checkout test"}` : "") });
   process.exit(0);
 }
@@ -297,7 +312,7 @@ if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
 // ---- 3 · deploy shipped code + deps (adds nothing to a scaffold from the template) --------------
 let deployResult = {};
 {
-  const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
+  const deploy = spawnSync("node", [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack, ...(planPath ? ["--plan", resolve(planPath)] : [])], { cwd: projectDir, encoding: "utf8", timeout: 60_000 });
   if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
   try { deployResult = JSON.parse(deploy.stdout); } catch { /* keep going */ }
   if (deployResult.error) fail("deploy", deployResult.error);
@@ -315,6 +330,32 @@ if (existsSync(join(projectDir, "package.json"))) {
   emit("install_started", install);
 }
 
+// ---- 5 · the seed, detached, only with --plan ------------------------------------------------------
+// The site existed before this run, so content goes in only when the caller says so (the brief
+// supplied or described it). Same shape as setup: result JSON + exit marker, synced on before release.
+// Seeds are additive and idempotent by name; what the site already held is reported, never touched.
+let seed = null;
+if (planPath) {
+  const seedDir = join(TEMPLATES, verticals[0], "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 seedChild = spawn(
+    "sh",
+    ["-c", `node "${join(seedDir, seedName)}" "${resolve(planPath)}" > 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: verticals[0], ...seed, ...(verticals.length > 1 ? { note: `the plan seeds ${verticals[0]}; the other verticals' seeds run afterwards, each with its own plan` } : {}) });
+} else {
+  if (siteOrigin === "init") {
+    emit("note", { step: "seed", detail: `this site was made for this run (init) and is empty: draft a plan per templates/${verticals[0]}/seed/SEED.md — the brief's content, else demo content — and run node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs plan.json from the project root` });
+  }
+  if (verticals.includes("members")) {
+    emit("note", { step: "seed", detail: "members: the Members Area app (the profile layer, no content) is installed by templates/members/seed/seed-members.mjs — run it unless the site already has the app" });
+  }
+}
+
 // ---- done ----------------------------------------------------------------------------------------
 emit("ready_for_brand_layer", {
   projectDir,
@@ -330,9 +371,15 @@ emit("ready_for_brand_layer", {
   mode,
   stack,
   install,
-  seed: null,
+  seed,
+  siteOrigin,
   next:
-    "the site's content is live already — nothing to seed; get the measure of the site (SKILL.md step 3), theme + write the pages" +
+    (seed
+      ? "the plan is seeding in the background (additive; the result's preexisting[] names what the site already held) — sync on .seed-exit before release; "
+      : siteOrigin === "init"
+        ? "no plan given and this site was made for this run (empty): draft a plan per SEED.md and run the vertical's seed before release; "
+        : "no plan given, so nothing seeds — the site existed before this run and its content is its own; ") +
+    "get the measure of the site (SKILL.md step 3), theme + write the pages" +
     (mode === "link" && hosting !== "self" ? "; make the project what its stack needs on Wix hosting (SKILL.md step 1)" : "") +
     (install ? "; wait for the install marker" : "") +
     (hosting === "self"

package/skills/wix-headless-kit/install/bootstrap.mjs

@@ -3,6 +3,8 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 // ── tiny event protocol (one JSON object per line) ───────────────────────────
 const emit = (event, extra = {}) =>
@@ -15,7 +17,7 @@ const fail = (event, extra = {}) => {
 // ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
 const isWin = process.platform === 'win32';
 const bin = (name) => (isWin ? `${name}.cmd` : name);
-const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no global install/mutation
+const WIX = [bin('npx'), '-y', WIX_CLI]; // run the CLI via npx — no global install/mutation
 
 // Force the CLI into non-interactive "agent" mode. Without an agent signal in
 // the env, `wix login` renders an interactive Ink TUI (device code + keypress)

package/skills/wix-headless-kit/install/check.mjs

@@ -5,7 +5,7 @@
 //   node <SKILL_ROOT>/install/check.mjs
 //
 // Two layers, two answers:
-//   skill      the installed skill folder (SKILL.md, guides/, install/, cold-start/) against the
+//   skill      the installed skill folder (SKILL.md, guides/, install/) against the
 //              repository head: `current`, `behind` (with the files that differ), or `unknown`.
 //   templates  `templates/.source` commit against the head: `current` or `behind`, with the
 //              verticals touched and the commit messages in between.
@@ -15,7 +15,7 @@ import { mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { spawnSync } from "node:child_process";
-import { SKILL_ROOT, installSource, templatesDir, templatesSource } from "./templates.mjs";
+import { SKILL_ROOT, TEMPLATES_PATH, installSource, templatesDir, templatesSource } from "./templates.mjs";
 
 const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 120_000, ...opts });
 const skillName = SKILL_ROOT.split("/").pop();
@@ -64,11 +64,11 @@ if (dir) {
   else if (src.commit === head) out.templates = { status: "current", commit: src.commit };
   else {
     out.templates = { status: "behind", commit: src.commit, head };
-    const files = git(["-C", tmp, "diff", "--name-only", `${src.commit}..${head}`, "--", "templates"]).stdout.split("\n").filter(Boolean);
-    const log = git(["-C", tmp, "log", "--format=%s", `${src.commit}..${head}`, "--", "templates"]).stdout.split("\n").filter(Boolean);
+    const files = git(["-C", tmp, "diff", "--name-only", `${src.commit}..${head}`, "--", TEMPLATES_PATH]).stdout.split("\n").filter(Boolean);
+    const log = git(["-C", tmp, "log", "--format=%s", `${src.commit}..${head}`, "--", TEMPLATES_PATH]).stdout.split("\n").filter(Boolean);
     if (files.length || log.length) {
       out.templates.commitsBehind = log.length;
-      out.templates.verticals = [...new Set(files.map((f) => f.split("/")[1]).filter((v) => v && !v.endsWith(".mjs")))].sort();
+      out.templates.verticals = [...new Set(files.map((f) => f.split("/")[2]).filter((v) => v && !v.endsWith(".mjs") && !v.endsWith(".md")))].sort();
       out.templates.commits = log.slice(0, 20);
     } else {
       out.templates.detail = git(["-C", tmp, "cat-file", "-e", src.commit]).status === 0 ? "no template changes between the two commits" : "the recorded commit is not in the repository's history (a branch that was deleted?)";

package/skills/wix-headless-kit/install/context.mjs

@@ -19,6 +19,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 // The variables the editor-to-headless migration writes into the child project's `prod`
 // environment (headless-bo, editorMigrations/environmentMetadata.ts), which `wix env pull` copies
@@ -57,7 +59,7 @@ export function readWixConfig(cwd) {
   try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
 }
 
-const ENV_PULL = ["-y", "@wix/cli@latest", "env", "pull"];
+const ENV_PULL = ["-y", WIX_CLI, "env", "pull"];
 const runPull = (dir) => spawnSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
 
 /**
@@ -70,7 +72,7 @@ export function pullEnv(cwd) {
   const envFile = join(cwd, ".env.local");
   const r = runPull(cwd);
   if (r.status === 0 && existsSync(envFile)) return { ok: true, via: "in place" };
-  return { ok: false, error: (r.stderr || r.stdout || "env pull produced no .env.local — is the Wix CLI logged in? (npx @wix/cli@latest whoami)").trim().slice(-400) };
+  return { ok: false, error: (r.stderr || r.stdout || `env pull produced no .env.local — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).trim().slice(-400) };
 }
 
 /**

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

@@ -46,6 +46,8 @@ import { fileURLToPath } from "node:url";
 import { templatesDir } from "./templates.mjs";
 import { syncLockRoot } from "./lock.mjs";
 import { siteContext } from "./context.mjs";
+const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // The shipped code: the repository's templates/ (a checkout, the cache, or fetched now).
@@ -80,6 +82,8 @@ const CAPABILITY_DEPS = {
   "media-upload": {
     "@wix/media": "^1.0.271",
     "@wix/essentials": "^1.0.10",
+    // the endpoint reads the caller's own session for a members policy
+    "@wix/members": "^1.0.511",
   },
   "site-search": {
     "@wix/search": "^1.0.90",
@@ -273,7 +277,7 @@ if (stack === "static") {
   // .env.local (`wix env pull`; on a migration preview the parent site's app), else the config's appId.
   let clientId = clientIdFlag ?? (existsSync(join(PROJECT, "wix.config.json")) ? siteContext({ cwd: PROJECT }).content.clientId : null);
   if (!clientId) {
-    console.log(JSON.stringify({ error: "static stack needs the public OAuth client id — run `npm create @wix/new@latest init` here first, or pass --client-id" }));
+    console.log(JSON.stringify({ error: `static stack needs the public OAuth client id — run \`npm create @wix/new@${PINS["@wix/create-new"]} init\` here first, or pass --client-id` }));
     process.exit(1);
   }
   const missing = requested.filter((v) => !existsSync(join(REF, v, "rest")));
@@ -297,7 +301,8 @@ if (stack === "static") {
       // Every vertical has a types.ts; flat in one folder they would collide, so each lands as
       // <vertical>-types.ts and the vertical's own files are pointed at it below.
       if (f === "types.ts") cpSync(join(appWix, f), join(JS, `${vertical}-types.ts`), COPY);
-      else if (f.endsWith("-core.ts") || f.endsWith("-store.ts")) cpSync(join(appWix, f), join(JS, f), COPY);
+      // *.generated.ts: data a core file imports (the forms' per-country address templates).
+      else if (f.endsWith("-core.ts") || f.endsWith("-store.ts") || f.endsWith(".generated.ts")) cpSync(join(appWix, f), join(JS, f), COPY);
     }
     const own = new Set([...readdirSync(join(root, "rest")), ...readdirSync(appWix)].filter((f) => f.endsWith(".ts") && f !== "types.ts"));
     for (const f of own) {
@@ -333,7 +338,7 @@ if (stack === "static") {
   const sources = readdirSync(JS).filter((f) => f.endsWith(".ts")).map((f) => join(JS, f));
   const tsc = spawnSync(
     "npx",
-    ["-y", "-p", "typescript@5", "tsc", ...sources, "--outDir", JS, "--module", "esnext", "--target", "es2022",
+    ["-y", "-p", `typescript@${PINS.typescript}`, "tsc", ...sources, "--outDir", JS, "--module", "esnext", "--target", "es2022",
      "--moduleResolution", "bundler", "--lib", "es2022,dom", "--strict", "--skipLibCheck", "--removeComments", "false"],
     { encoding: "utf8", timeout: 180_000 },
   );
@@ -362,9 +367,10 @@ for (const policy of uploadPolicies) {
     !Array.isArray(policy.accept) ||
     !policy.accept.every((mime) => typeof mime === "string") ||
     !Number.isSafeInteger(policy.maxBytes) ||
-    policy.maxBytes < 1
+    policy.maxBytes < 1 ||
+    (policy.audience !== undefined && policy.audience !== "members" && policy.audience !== "visitors")
   ) {
-    console.log(JSON.stringify({ error: "each mediaUpload policy needs id, accept: string[], and positive integer maxBytes" }));
+    console.log(JSON.stringify({ error: 'each mediaUpload policy needs id, accept: string[], positive integer maxBytes, and optionally audience: "members" (default) | "visitors"' }));
     process.exit(1);
   }
 }

package/skills/wix-headless-kit/install/pins.json

@@ -0,0 +1,8 @@
+{
+  "@wix/cli": "1.1.257",
+  "@wix/create-new": "0.0.123",
+  "typescript": "5.8.3",
+  "templates": {
+    "ref": "v1.28.0"
+  }
+}

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

@@ -37,6 +37,8 @@ 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 PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
+const WIX_CLI = `@wix/cli@${PINS["@wix/cli"]}`;
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -134,14 +136,14 @@ if (mode === "create") {
       // 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",
+      ["create", `@wix/new@${PINS["@wix/create-new"]}`, "--", "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));
+      fail("scaffold", (scaffold.stderr || scaffold.stdout || `scaffold produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
     }
   }
 } else if (mode === "migrate") {
@@ -177,10 +179,10 @@ if (mode === "create") {
   // 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("adopting", { folder: cwd });
-  const init = spawnSync("npm", ["create", "@wix/new@latest", "--", "init"],
+  const init = spawnSync("npm", ["create", `@wix/new@${PINS["@wix/create-new"]}`, "--", "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));
+    fail("init", (init.stderr || init.stdout || `init produced no wix.config.json — is the Wix CLI logged in? (npx ${WIX_CLI} whoami)`).slice(-600));
   }
 }
 const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
@@ -296,10 +298,10 @@ if (planPath && madeTheSite) {
 
 // ---- 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`,
+  astro: `npx ${WIX_CLI} build, then npx ${WIX_CLI} release`,
+  react: `the project's own build, then npx ${WIX_CLI} 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} release of the build folder named in wix.config.json (SKILL.md step 1)`,
+  static: `npx ${WIX_CLI} 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.

package/skills/wix-headless-kit/install/templates.mjs

@@ -1,17 +1,23 @@
-// 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.
+// Where the shipped code is. The verticals live in the skill's repository as a skill of their own,
+// `skills/wix-headless-templates/` (each with its code layers, its tools and a composed project
+// with a lockfile), not in this skill's folder: this 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/`.
+//   1. the sibling skill folder, `<SKILL_ROOT>/../wix-headless-templates/`: a checkout of the repository,
+//      or a plugin install that carries both skills (every plugin manifest lists the templates skill).
 //   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
+//   3. a fetch: a sparse, shallow clone of `skills/wix-headless-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.
+//      named (its `ref`, falling back to the default branch when that ref no longer exists), else
+//      the repository's default branch: a skill installed from the repository tracks the repository,
+//      so the templates match the kit beside them. A kit that came from a package (no skills-lock.json
+//      above it) fetches at the release tag in `install/pins.json` (`templates.ref`, kept equal to the
+//      package version by the release flow), the code it was released with; the package carries the
+//      templates skill beside the kit anyway, so that fetch is the rare path.
+//      `WIX_HEADLESS_FAST_TEMPLATES_REF=<branch|tag|sha>` overrides all of it.
 // 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
@@ -25,6 +31,10 @@ 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";
+/** The templates skill's folder in the repository. */
+export const TEMPLATES_PATH = "skills/wix-headless-templates";
+/** Pinned versions, shared by the install scripts; `templates.ref` is the release tag the fetch defaults to. */
+export const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
 
 const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 180_000, ...opts });
 
@@ -42,7 +52,7 @@ export function installSource() {
         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) };
+          return { ...parsed, ref: parsed.ref ?? (typeof entry.ref === "string" && entry.ref ? entry.ref : null), fromLock: true };
         }
       } catch { /* fall through to the default */ }
       break;
@@ -51,7 +61,7 @@ export function installSource() {
     if (up === dir) break;
     dir = up;
   }
-  return { repo: DEFAULT_REPO, ref: null };
+  return { repo: DEFAULT_REPO, ref: null, fromLock: false };
 }
 
 function parseSource(src) {
@@ -68,7 +78,7 @@ export function listVerticals(dir) {
 }
 
 export function templatesDir({ refresh = false, need = null } = {}) {
-  const checkout = resolve(SKILL_ROOT, "..", "..", "templates");
+  const checkout = resolve(SKILL_ROOT, "..", "wix-headless-templates");
   if (existsSync(join(checkout, "shared", "app"))) return checkout;
   const cache = join(SKILL_ROOT, "templates");
   if (!refresh && existsSync(join(cache, "shared", "app"))) {
@@ -90,12 +100,12 @@ function fetchIgnoredPart(cache, need) {
   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))) {
+  if (r.status !== 0 || !existsSync(join(tmp, TEMPLATES_PATH, 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)}`);
+    throw new Error(`could not fetch ${TEMPLATES_PATH}/${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);
+  for (const part of ["blank", ...readdirSync(join(tmp, TEMPLATES_PATH), { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync(join(tmp, TEMPLATES_PATH, d.name, "project"))).map((d) => `${d.name}/project`)]) {
+    const from = join(tmp, TEMPLATES_PATH, part);
     if (existsSync(from) && !existsSync(join(cache, part))) cpSync(from, join(cache, part), { recursive: true });
   }
   rmSync(tmp, { recursive: true, force: true });
@@ -108,15 +118,19 @@ export function templatesSource(dir) {
 }
 
 function fetchTemplates(cache) {
-  const { repo, ref: lockRef } = installSource();
+  const { repo, ref: lockRef, fromLock } = installSource();
   const envRef = process.env.WIX_HEADLESS_FAST_TEMPLATES_REF || null;
-  let ref = envRef || lockRef || null;
+  // Installed from the repository (a lock above the skill) and no ref named: the default branch, so
+  // the templates match the kit. No lock at all is a package install: the release tag it shipped with.
+  const pinnedRef = fromLock ? null : (PINS.templates?.ref || null);
+  let ref = envRef || lockRef || pinnedRef || 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 || "")) {
+    // (the pinned tag, too: a fork or a pre-release checkout may not carry it)
     rmSync(r.tmp, { recursive: true, force: true });
     fellBack = true; ref = null;
     r = cloneSparse(repo, null);
@@ -126,33 +140,33 @@ function fetchTemplates(cache) {
     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"))) {
+  if (r.status !== 0 || !existsSync(join(tmp, TEMPLATES_PATH, "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)}`);
+    throw new Error(`could not fetch ${TEMPLATES_PATH}/ from ${repo}${ref ? ` @ ${ref}` : ""}: ${(r.stderr || r.stdout || `no ${TEMPLATES_PATH}/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 }); }
+  try { renameSync(join(tmp, TEMPLATES_PATH), cache); }
+  catch { cpSync(join(tmp, TEMPLATES_PATH), 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");
+  writeFileSync(join(cache, ".source"), JSON.stringify({ repo, ref: ref ?? (fellBack ? `default branch (${lockRef || pinnedRef} 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.
+// A sparse, shallow clone of the templates skill's folder at a ref (branch, tag, or commit id) into a temp dir.
 function cloneSparse(repo, ref) {
   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)
-    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"]]) {
+    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_PATH], ["-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"]);
+    if (r.status === 0) r = git(["-C", tmp, "sparse-checkout", "set", TEMPLATES_PATH]);
   }
   return { ...r, tmp };
 }

package/skills/wix-headless-templates/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wix-headless-templates
+description: "The shipped, verified code behind Wix Headless sites, one folder per Wix Business Solution: an online store, bookings, rentals, a blog, CMS collections, forms, members, events, restaurants, donations, pricing plans, a portfolio, an FAQ. Each ships a typed framework-agnostic data layer and stores over @wix/sdk, React hooks and reference components, Astro pages with owner-editable SEO, a REST twin for sites without a bundler, a seed script that fills the site from a plan, a reader that reports what a site already holds, and a playbook (INSTRUCTIONS.md) with the contracts. Shared across them: design and content floors, the capabilities (site search, media upload), the seed helpers, and a composed, lock-pinned project per solution that a create copies whole. Used by wix-headless-kit, which fetches, deploys and seeds from this folder; readable on its own to see what a solution's code does and how it is seeded."
+---
+
+# Wix Headless Templates
+
+The code a Wix Headless site is built from, one folder per Wix Business Solution. `wix-headless-kit`
+is the skill that runs a build: its `install/templates.mjs` fetches this folder once into the kit's
+own `templates/` (a sparse clone of `skills/wix-headless-templates/`, or the checkout when the kit
+runs from one) and the kit copies, deploys and seeds from there. This skill holds no flow of its
+own; it is the material, kept as a skill so it is published, mirrored and readable like one.
+
+## Layout
+
+| path | what it is |
+|---|---|
+| `<solution>/INSTRUCTIONS.md` | the solution's playbook: what ships, the contracts of every hook, store and DTO, the pages, the dashboard links |
+| `<solution>/app/` | the framework-agnostic core: `wix/<solution>/*-core.ts` (pure logic), the SDK transport, `*-store.ts` state machines, `types.ts`; `hooks/` (React bindings) and `components/` (reference implementations, correct and plain) |
+| `<solution>/app-astro/` | Astro pages and layouts with owner-editable SEO pre-wired |
+| `<solution>/rest/` | the data layer a second time over plain `fetch`, same exports, for a site with no bundler |
+| `<solution>/seed/` | `SEED.md` (the plan shape and the traps), `seed-<solution>.mjs` (fills the site from a plan, idempotent), `read-site.mjs` (reports what the site already holds) |
+| `<solution>/project/` | the composed project: the CLI's blank scaffold with the solution deployed and a `package-lock.json`, copied whole at create or attach so `npm ci` installs without resolving |
+| `shared/` | `DESIGN.md` and `CONTENT.md` (the floors every site meets), `CUSTOM_OPERATIONS.md` (server-side work that needs elevated calls), `app/` and `rest/` (the client, media and config seams), `capabilities/` (site search, media upload), `seed/` (the CLI resolver, token, image resolver and site context every seed uses) |
+| `blank/` | the pristine CLI scaffold the composed projects start from |
+| `compose.mjs` | repository tooling: rebuilds a solution's `project/` from `blank/` plus a deploy, and its lock |
+
+The solutions: `storefront`, `bookings`, `rentals`, `blog`, `cms`, `forms`, `members`, `events`,
+`restaurants`, `donations`, `pricing-plans`, `portfolio`, `faq`.
+
+## Reading it on its own
+
+- What a solution does and how its pieces fit: `<solution>/INSTRUCTIONS.md`, then `app/wix/<solution>/types.ts`.
+- How a site is filled and what the seed refuses: `<solution>/seed/SEED.md`.
+- What an existing site holds before anything is written: `node <solution>/seed/read-site.mjs --site <siteId>` (a logged-in Wix CLI).
+- A seed by hand, from a project folder with a `wix.config.json`: `node <solution>/seed/seed-<solution>.mjs plan.json`.
+
+## Changing it
+
+Code under `app/`, `app-astro/`, `rest/` and `seed/` is the source; `project/` is generated from it
+with `node compose.mjs <solution>` from a checkout of the repository (it reinstalls the project's
+dependencies, so run `npm ci` in the project before a typecheck). A composed project is checked
+with `tsc` on its own `tsconfig.json`. Locks are resolved locally, never on a sandbox mirror.

package/skills/wix-headless-templates/blank/project/README.md

@@ -0,0 +1,15 @@
+# Wix Astro Blank Template
+
+**[Live demo](https://h6s-1a31f9730cd85b-headlessstack.wix-site-host.com)**
+
+Our Astro templates are still in development and subject to change.
+
+To use a template, follow the [Wix CLI for Headless Quick Start](https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli), and select the desired template during the setup process.
+
+## Need help?
+
+For documentation and support, check out:
+
+- [Wix Headless Documentation](https://dev.wix.com/docs/go-headless)
+- [Wix SDK Documentation](https://dev.wix.com/docs/sdk)
+- [Community on Discord](https://discord.gg/n6TBrSnYTp)

package/skills/wix-headless-templates/blank/project/astro.config.mjs

@@ -0,0 +1,20 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  output: "server",
+});