@wix/agent-skills 1.33.1 → 1.35.0

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

@@ -10,13 +10,15 @@
 // They differ on a MIGRATION PREVIEW: a project whose config points at a fresh site created only to
 // host the deployment, while `.env.local` carries the credentials of the site being migrated (the
 // parent) and says so. Then every admin, discovery and seed call targets the parent, the SDK client
-// is the parent's, and only the release goes to the child. Completing the migration is a CLI step
-// that does not exist yet; this module only reads the state.
+// is the parent's, and only the release goes to the child. Completing the migration follows
+// guides/migration.md; this module only reads the state.
 //
 // `env pull` runs here when `.env.local` is missing (or --refresh): it is the source of the content
 // identity, and the Astro build refuses to run without it. Non-interactive (CI=1); a failure is
 // reported in `pullError` and the config's ids stand in, so a caller can still work offline.
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { failure, npmSync } from "./proc.mjs";
 const PINS = JSON.parse(readFileSync(new URL("./pins.json", import.meta.url), "utf8"));
@@ -59,6 +61,55 @@ export function readWixConfig(cwd) {
   try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
 }
 
+/**
+ * Where a release goes from this machine. `cli`: the Wix CLI's session file is here
+ * (`~/.wix/auth/account.json`, what `wix login` writes), so `wix release` and `wix env pull` work.
+ * `plugin`: no session; the Wix MCP's tools carry the user's login, the site is provisioned through
+ * them, and the Astro build is released by its upload tool.
+ */
+export function publisher() {
+  return existsSync(join(homedir(), ".wix", "auth", "account.json")) ? "cli" : "plugin";
+}
+
+/**
+ * Whether the kit runs here: `npm ping` against the configured registry, thirty seconds at most. A chat
+ * host's sandbox answers through a proxy that can take six seconds to the first byte (measured on one
+ * 2026-10-24), so a short limit reads an open sandbox as closed.
+ */
+export function npmReachable() {
+  const r = npmSync("npm", ["ping", "--no-fund", "--no-audit"], { encoding: "utf8", timeout: 30_000, env: { ...process.env, CI: "1" } });
+  return { ok: r.status === 0, detail: r.status === 0 ? null : failure(r, "npm ping failed").trim().slice(-200) };
+}
+
+/**
+ * Whether a build can travel from this shell: the upload tool's presigned URLs are on Amazon S3, and a
+ * sandbox limited to a few hosts gets a proxy's answer there instead of S3's (`Server: AmazonS3`). Measured
+ * with one HEAD request, twenty-five seconds at most (a sandbox proxy can take ten seconds to answer, and a
+ * short limit reads an open sandbox as closed); the client's attachment carrier is not measurable here.
+ */
+export async function s3Reachable() {
+  // curl first: it is what the shell's upload would use and it honours the shell's proxy settings.
+  // S3 answered when its own headers are there: `x-amz-request-id` always, `Server: AmazonS3` unless a
+  // proxy in front rewrote the Server header (one chat host's proxy answers `server: envoy` and keeps the
+  // x-amz headers). A proxy that refuses the host answers with neither.
+  const fromS3 = (headers) => /^x-amz-request-id:/im.test(headers) || /^server:\s*amazons3/im.test(headers);
+  const c = spawnSync("curl", ["-sI", "-m", "25", "https://s3.amazonaws.com"], { encoding: "utf8" });
+  if (c.status === 0 && c.stdout) {
+    const server = (c.stdout.match(/^server:\s*(.+)$/im) ?? [])[1]?.trim() ?? "";
+    const amz = /^x-amz-request-id:/im.test(c.stdout);
+    return { ok: fromS3(c.stdout), detail: `${c.stdout.split("\n")[0].trim()}${server ? `, server: ${server}` : ""}${amz ? ", x-amz-request-id present" : ", no S3 headers"}` };
+  }
+  if (c.status !== null && c.error?.code !== "ENOENT") return { ok: false, detail: `curl exited ${c.status}` };
+  try {
+    const r = await fetch("https://s3.amazonaws.com", { method: "HEAD", redirect: "manual", signal: AbortSignal.timeout(25_000) });
+    const server = r.headers.get("server") ?? "";
+    const amz = r.headers.has("x-amz-request-id");
+    return { ok: amz || /amazons3/i.test(server), detail: `status ${r.status}${server ? `, server: ${server}` : ""}${amz ? ", x-amz-request-id present" : ", no S3 headers"}` };
+  } catch (e) {
+    return { ok: false, detail: String(e?.cause?.code ?? e?.message ?? e).slice(0, 120) };
+  }
+}
+
 const ENV_PULL = ["-y", WIX_CLI, "env", "pull"];
 const runPull = (dir) => npmSync("npx", ENV_PULL, { cwd: dir, env: { ...process.env, CI: "1" }, encoding: "utf8", timeout: 180_000 });
 
@@ -165,7 +216,7 @@ export function folderShape(cwd = process.cwd(), { migrationActive = false } = {
     migration: "setup.mjs (MIGRATE): the shipped code into the starter the download carries (or the composed template around a bare config); the site being migrated owns its content — guides/migration.md",
     "static-in-astro": "a dropped site on its Dev Machine: the pages are plain files in public/, served as they are. deploy.mjs <vertical…> --stack static --out public puts the REST layer in public/js/wix/; wire the pages in place with <script type=\"module\">: do the least that makes them work: connect each control the pages show and add only what a control can't work without (more only when the brief asks), and no Astro pages. Read the site (read-site.mjs); run the vertical's seed module with a plan only for content the brief supplies or describes. Release with npx @wix/cli@latest build && npx @wix/cli@latest release; the URL stays",
     "blank-starter": "attach.mjs --business-name <brand> --vertical <v…> [--plan plan.json] (the site comes from wix.config.json): the CLI's blank starter with no work of its own, as a Dev Machine or a bare wix create leaves it. attach deploys the vertical onto it with its composed lock and starts the install and the seed detached: build the brand layer while they run, then sync on .install-exit and .seed-exit before release (SKILL.md step 3). Read the site first (read-site.mjs) when it may already hold content",
-    "wix-project": "iterate: never scaffold, init or reseed. deploy.mjs <vertical…> --stack <stack> adds a solution, then one install: node <SKILL_ROOT>/install/install.mjs (it skips when node_modules already satisfies the lock); file edits for a change; release. Read the site (read-site.mjs) before any seed module runs",
+    "wix-project": "iterate: never scaffold, init or reseed. deploy.mjs <vertical…> --stack <stack> adds a solution, then one install: node <SKILL_ROOT>/install/install.mjs (it skips when node_modules already satisfies the lock); file edits for a change; release. Read the site (read-site.mjs) before any seed module runs. On the plugin route, a project downloaded from the site's Code Store repository has no .env.local: setup.mjs --vertical <v> --site <siteId> --app <appId> writes it (and installs when node_modules is missing); the release is UploadHeadlessWebsiteFiles with the downloaded revision as expectedHeadRevisionId (SKILL.md step 5)",
     "published-static": "setup.mjs --vertical <v>: the config's site, no init; site/ becomes the upload and the REST layer lands in site/js/wix/; move the pages, styles and assets into site/. Nothing is seeded: read the site, then run the vertical's seed module with a plan when the brief gives content; release keeps the URL",
   };
   let shape;
@@ -193,7 +244,8 @@ export function siteContext({ cwd = process.cwd(), pull = "auto" } = {}) {
   const deploy = { siteId: config.siteId ?? config.projectId ?? null, appId: config.appId ?? null };
   const envFile = join(cwd, ".env.local");
   let pulled = false, pullError;
-  if (deploy.siteId && (pull === true || (pull === "auto" && !existsSync(envFile)))) {
+  // Only a machine with a CLI session can pull; on the plugin route setup.mjs wrote the env file.
+  if (deploy.siteId && publisher() === "cli" && (pull === true || (pull === "auto" && !existsSync(envFile)))) {
     const r = pullEnv(cwd);
     if (r.ok) pulled = r.via;
     else pullError = r.error;
@@ -214,12 +266,15 @@ export function siteContext({ cwd = process.cwd(), pull = "auto" } = {}) {
   if (active && migration.parentSiteId === deploy.siteId) {
     warnings.push("the migration's parent site is the deploy site itself — nothing is being migrated");
   }
-  return { folder: folderShape(cwd, { migrationActive: active }), deploy, content, migration, env: { file: envFile, present: Object.keys(env).length > 0, pulled }, ...(pullError ? { pullError } : {}), warnings };
+  return { folder: folderShape(cwd, { migrationActive: active }), publisher: publisher(), npm: npmReachable(), deploy, content, migration, env: { file: envFile, present: Object.keys(env).length > 0, pulled }, ...(pullError ? { pullError } : {}), warnings };
 }
 
 // ---- CLI ----------------------------------------------------------------------------------------
 if (process.argv[1] && /context\.mjs$/.test(process.argv[1])) {
   const argv = process.argv.slice(2);
   const pull = argv.includes("--no-pull") ? false : argv.includes("--refresh") ? true : "auto";
-  console.log(JSON.stringify(siteContext({ pull }), null, 2));
+  // The carrier is measured only when printing: the scripts that read siteContext() do not decide the route.
+  const ctx = siteContext({ pull });
+  ctx.carrier = { s3: await s3Reachable() };
+  console.log(JSON.stringify(ctx, null, 2));
 }

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

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.33.1"
+    "ref": "v1.35.0"
   }
 }

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

@@ -5,10 +5,14 @@
 //
 //   node <SKILL_ROOT>/install/setup.mjs --vertical <storefront|bookings|…>[,<vertical>…] \
 //        [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] \
-//        [--subfolder [--folder-name <npm-safe-name>]]
+//        [--site <metaSiteId> --app <appId>] [--subfolder [--folder-name <npm-safe-name>]]
 //
 //   empty (or loose files: a CSV, a brief) → CREATE: `wix create` with the vertical's composed template
 //     (templates/<vertical>/project), placed in the current directory (`--business-name` required).
+//     With --site and --app (a site provisioned through the Wix MCP: the metaSiteId and appId the
+//     provision call returned) the CLI is not run: the composed template is copied in, wix.config.json
+//     and .env.local are written for that site, and the release is the Wix MCP's upload tool with the
+//     Astro build (the plugin route). The seed runs through ExecuteWixAPI there, not here.
 //   a frontend, no wix.config.json (a package.json, or an index.html at the root) → ADOPT: `init` in
 //     place gives the project a new, empty site, then deploy. `--stack` required.
 //   CREATE and ADOPT are the two cases that seed: the run made the site, it is empty by construction,
@@ -20,6 +24,9 @@
 //     drop flow and downloaded): the config's site, no init; site/ becomes the upload, the REST layer
 //     deploys there, the pages move in (the agent's step). Nothing seeded.
 //   a config and a frontend (package.json, or index.html in the output folder) → refuses: iterate.
+//     With --site and --app matching the config and no .env.local (a project downloaded from the
+//     site's Code Store repository): writes .env.local as the plugin create does, installs when
+//     node_modules is missing, and nothing else: no scaffold, no deploy, no seed.
 //   a config and nothing else → refuses: attach.mjs's case.
 //
 // Setup seeds only a site it created in this run. A site that existed before the run is never seeded
@@ -31,7 +38,7 @@
 // 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 { spawnSync } from "node:child_process";
-import { cpSync, existsSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, 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";
@@ -65,13 +72,18 @@ const planPath = flag("plan");
 const verticals = (flag("vertical") ?? "").split(",").map((v) => v.trim()).filter(Boolean);
 const vertical = verticals[0] ?? null;
 const stackFlag = flag("stack");
+// The plugin route: a site already provisioned through the Wix MCP, named by the two ids the provision
+// call returned. No Wix CLI is run anywhere in this call; the release is the MCP's upload tool.
+const siteFlag = flag("site");
+const appFlag = flag("app");
+const publisher = siteFlag ? "plugin" : "cli";
 // 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("|")}>[,<vertical>…] [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] [--subfolder]`;
+const usage = `usage: setup.mjs --vertical <${knownVerticals.join("|")}>[,<vertical>…] [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] [--site <metaSiteId> --app <appId>] [--subfolder]`;
 // --vertical is REQUIRED: a defaulted vertical deploys the wrong code and runs the wrong seed.
 if (!vertical) fail("args", usage);
 for (const v of verticals) {
@@ -81,6 +93,43 @@ 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}`);
+if (!!siteFlag !== !!appFlag) fail("args", "--site and --app go together: the metaSiteId and the appId the provision call returned");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+if (siteFlag && !(UUID.test(siteFlag) && UUID.test(appFlag))) fail("args", "--site and --app are UUIDs (the provision call's metaSiteId and appId)");
+if (siteFlag && stackFlag && stackFlag !== "astro") fail("args", `--site takes the astro stack: the composed template is copied in and released as a build; --stack ${stackFlag} does not apply`);
+
+// The env the plugin route's build reads: the public client id, the cloud provider the hosting runs
+// the server build on, and stand-ins for the three values the hosting runtime injects at release (the
+// build only checks they exist).
+const writePluginEnv = (dir) => writeFileSync(join(dir, ".env.local"), [
+  "# Read by the build. WIX_CLIENT_ID is the site's public OAuth client id (the provision call's appId).",
+  "# The hosting runtime injects the real values of the last three at release; the build only checks they exist.",
+  `WIX_CLIENT_ID="${appFlag}"`,
+  'WIX_CLOUD_PROVIDER="KUBERNETES"',
+  'WIX_CLIENT_INSTANCE_ID="set-at-release"',
+  'WIX_CLIENT_PUBLIC_KEY="set-at-release"',
+  'WIX_CLIENT_SECRET="set-at-release"',
+  "",
+].join("\n"));
+
+// The plugin route's install: in the foreground, since it runs where a process may not outlive the
+// tool call that started it; the event says it is done.
+const foregroundInstall = (dir) => {
+  const installLog = join(dir, "npm-install.log");
+  emit("installing", { log: installLog, foreground: true });
+  const r = spawnSync("node", [join(SKILL_ROOT, "install", "install.mjs")], { cwd: dir, encoding: "utf8", timeout: 280_000 });
+  writeFileSync(installLog, `${r.stdout ?? ""}${r.stderr ?? ""}`);
+  let result = {};
+  try { result = JSON.parse((r.stdout ?? "").trim().split("\n").pop()); } catch { /* the log has it */ }
+  if (r.status !== 0) fail("install", failure(r, `install exited ${r.status}; see ${installLog}`).slice(-600));
+  const marker = join(dir, ".install-exit");
+  emit("install_done", { ...result, exit: existsSync(marker) ? readFileSync(marker, "utf8").trim() : String(r.status), log: installLog });
+};
+
+// The plugin route's release of an Astro project: the build, the two zips, the upload tool.
+const ZIP_PY = (name, skip) => `python3 -c "import zipfile,pathlib as P; X=(${skip.map((s) => `'${s}'`).join(",")}); z=zipfile.ZipFile('${name}','w',zipfile.ZIP_DEFLATED); [z.write(p) for p in P.Path('.').rglob('*') if p.is_file() and p.parts[0] not in X and not p.name.startswith('.env') and str(p) not in ('project.zip','build.zip','source.zip')]; z.close()"`;
+const pluginRelease = (head) =>
+  `npx astro build from the project root (the Wix hosting adapter writes .wix/build-metadata.json and dist/), then release with the Wix MCP's UploadHeadlessWebsiteFiles, siteId ${siteFlag}, in one of two forms. Attached: one zip of the project without node_modules (zip -qr project.zip . -x 'node_modules/*' '.astro/*' '.agents/*' '.env*'; without a zip binary: ${ZIP_PY("project.zip", ["node_modules", ".astro", ".agents"])}) passed as attachments. From a shell that reaches the internet (the upload URLs are on Amazon S3: curl -sI https://s3.amazonaws.com shows Server: AmazonS3 where they work; a sandbox limited to a few hosts gets a proxy's refusal without that header and cannot release this way): the build zip (zip -qr build.zip dist .wix) and the source zip (zip -qr source.zip . -x 'node_modules/*' 'dist/*' '.wix/*' '.astro/*' '.agents/*' '.env*' 'build.zip'; without a zip binary: ${ZIP_PY("source.zip", ["node_modules", "dist", ".wix", ".astro", ".agents"])}), then { siteId, prepare: true, size } with size from wc -c < build.zip, the curl -X PUT commands its reply gives, run as given, and the second call it names, { siteId, uploadKey, sourceUploadId, expectedHeadRevisionId }. ${head} The tool releases the build to the site's Wix hosting, stores the source in the site's Code Store repository and returns the live URL; EXPECTED_HEAD_REQUIRED or a 409 CODE_STORE_HEAD_CHANGED released nothing (SKILL.md step 5). Not wix build, not wix release: this run has no Wix CLI session`;
 
 // ---- 0 · read the folder --------------------------------------------------------------------------
 const cwd = process.cwd();
@@ -89,8 +138,25 @@ const pkg = has("package.json") ? JSON.parse(readFileSync(join(cwd, "package.jso
 let ctx = null;
 let shape = folderShape(cwd).shape;
 if (has("wix.config.json")) {
-  ctx = siteContext({ cwd }); // pulls .env.local when missing — where a migration is declared
+  ctx = siteContext({ cwd, ...(siteFlag ? { pull: false } : {}) }); // pulls .env.local when missing — where a migration is declared
   shape = ctx.folder.shape;
+  // A project downloaded from the site's Code Store repository: the config and the frontend came with
+  // it, the env did not. Only the env is written, and the install runs when node_modules is missing.
+  if (siteFlag && pkg && shape !== "migration" && ctx.deploy.siteId === siteFlag && !has(".env.local")) {
+    if (ctx.deploy.appId && ctx.deploy.appId !== appFlag) fail("args", `--app ${appFlag} differs from wix.config.json appId ${ctx.deploy.appId}`);
+    emit("folder", { mode: "iterate", shape, stack: "astro", publisher, project: pkg.name ?? basename(cwd), deploySiteId: ctx.deploy.siteId, warnings: ctx.warnings });
+    writePluginEnv(cwd);
+    ignoreEnvLocal(cwd);
+    emit("env_written", { file: join(cwd, ".env.local"), clientId: appFlag });
+    if (!has("node_modules")) foregroundInstall(cwd);
+    else emit("install_skipped", { reason: "node_modules is there" });
+    emit("ready_for_brand_layer", {
+      mode: "iterate", shape, stack: "astro", publisher, verticals, projectDir: cwd, siteId: siteFlag,
+      dashboardUrl: `https://manage.wix.com/dashboard/${siteFlag}`, install: null, seed: null,
+      next: `a project downloaded from the site's Code Store repository: nothing scaffolded, deployed or seeded. Edit the files the change needs (deploy.mjs <vertical…> --stack astro adds a solution, then node ${join(SKILL_ROOT, "install", "install.mjs")}); then ${pluginRelease("expectedHeadRevisionId is the revision.id the download returned, in either form.")}`,
+    });
+    process.exit(0);
+  }
   if (shape !== "migration" && shape !== "published-static") {
     fail("place", `this folder is already a Wix project (wix.config.json), shape "${shape}": nothing to set up. ${ctx.folder.next} (SKILL.md step 3)` + (ctx.pullError ? ` — note: env pull failed here (${ctx.pullError.slice(0, 120)})` : ""));
   }
@@ -99,6 +165,7 @@ if (has("wix.config.json")) {
   }
 }
 const mode = { migration: "migrate", "published-static": "published-static", project: "adopt", empty: "create" }[shape];
+if (siteFlag && mode !== "create") fail("args", `--site applies to an empty folder (shape "empty"); this folder is "${shape}": ${folderShape(cwd).next}`);
 const migrating = mode === "migrate";
 const publishedStatic = mode === "published-static";
 const hasProject = shape === "project";
@@ -106,7 +173,7 @@ if (mode === "adopt" && !stackFlag) {
   fail("args", "adopting a project on disk needs --stack astro|react|lib|static — the stack you resolved in SKILL.md step 1 for this project");
 }
 const stack = publishedStatic ? "static" : (stackFlag ?? "astro");
-emit("folder", { mode, shape, stack, project: hasProject ? (pkg?.name ?? basename(cwd)) : null, ...(ctx ? { deploySiteId: ctx.deploy.siteId, warnings: ctx.warnings } : {}), ...(migrating ? { migration: ctx.migration } : {}) });
+emit("folder", { mode, shape, stack, publisher, project: hasProject ? (pkg?.name ?? basename(cwd)) : null, ...(ctx ? { deploySiteId: ctx.deploy.siteId, warnings: ctx.warnings } : {}), ...(migrating ? { migration: ctx.migration } : {}) });
 
 let projectDir = cwd;
 let folderName = null;
@@ -123,6 +190,23 @@ if (mode === "create") {
   projectDir = resolve(cwd, folderName);
   if (existsSync(join(projectDir, "wix.config.json"))) {
     emit("scaffold_skipped", { reason: "project already exists", folder: folderName });
+  } else if (siteFlag) {
+    // ---- 1 · a site provisioned through the Wix MCP: the template copied in, the config and the env
+    // written here; no CLI. The env is what the build reads: the public client id, the cloud provider
+    // the hosting runs the server build on, and stand-ins for the three values the hosting runtime
+    // injects at release (the build only checks they exist).
+    const template = join(templatesDir({ need: `${vertical}/project` }), vertical, "project");
+    emit("scaffolding", { folder: folderName, template, siteId: siteFlag, from: "the Wix MCP's provision call" });
+    mkdirSync(projectDir, { recursive: true });
+    cpSync(template, projectDir, { recursive: true, force: false, errorOnExist: false });
+    const pkgPath = join(projectDir, "package.json");
+    if (existsSync(pkgPath)) {
+      const scaffolded = JSON.parse(readFileSync(pkgPath, "utf8"));
+      scaffolded.name = folderName || "site";
+      writeFileSync(pkgPath, JSON.stringify(scaffolded, null, 2) + "\n");
+    }
+    writeFileSync(join(projectDir, "wix.config.json"), JSON.stringify({ siteId: siteFlag, appId: appFlag }, null, 2) + "\n");
+    writePluginEnv(projectDir);
   } 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
@@ -257,9 +341,13 @@ emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), s
 let install = null;
 if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
   const installLog = join(projectDir, "npm-install.log");
-  startBackground("install", [], { cwd: projectDir, log: installLog });
-  install = { log: installLog, doneMarker: ".install-exit", success: "file contains 0" };
-  emit("install_started", install);
+  if (publisher === "plugin") {
+    foregroundInstall(projectDir);
+  } else {
+    startBackground("install", [], { cwd: projectDir, log: installLog });
+    install = { log: installLog, doneMarker: ".install-exit", success: "file contains 0" };
+    emit("install_started", install);
+  }
 }
 
 // ---- 4 · start the seed, detached (a site this run created, with a plan) ---------------------------
@@ -271,10 +359,12 @@ if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
 // idempotent by name.
 const madeTheSite = mode === "create" || mode === "adopt";
 let seed = null;
-if (planPath && !madeTheSite) {
+if (planPath && publisher === "plugin") {
+  emit("seed_skipped", { reason: `the seed modules run with the Wix CLI's session, and this run has none: on the plugin route the plan is seeded through ExecuteWixAPI, as ${join(SKILL_ROOT, "guides", "api-run.md")} section 4 describes, with the vertical's SEED.md (${join(TEMPLATES, vertical, "seed", "SEED.md")}) as the contract` });
+} else if (planPath && !madeTheSite) {
   emit("seed_skipped", { reason: `${mode}: the site existed before this run; setup seeds only a site it created. Read what the site holds (${join(TEMPLATES, vertical, "seed", "read-site.mjs")}), then run templates/${vertical}/seed/seed-*.mjs ${planPath} yourself when the brief supplies or describes content` });
 }
-if (planPath && madeTheSite) {
+if (planPath && madeTheSite && publisher === "cli") {
   const seedDir = join(TEMPLATES, vertical, "seed");
   const seedName = existsSync(seedDir)
     ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
@@ -288,7 +378,9 @@ if (planPath && madeTheSite) {
 }
 
 // ---- done ----------------------------------------------------------------------------------------
-const release = {
+const release = publisher === "plugin" ? {
+  astro: pluginRelease("expectedHeadRevisionId is the headRevisionId the prepare returned; an attached release of this new site's first build leaves it out (the repository has nothing in it yet)."),
+}[stack] : {
   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)`,
@@ -301,6 +393,7 @@ emit("ready_for_brand_layer", {
   mode,
   shape,
   stack,
+  publisher,
   verticals,
   projectDir,
   siteId: migrating ? ctx.content.siteId : siteId,
@@ -314,6 +407,8 @@ emit("ready_for_brand_layer", {
     (publishedStatic ? "a published static site: its pages are live on this site already and keep their URL; move index.html, the other pages, styles and assets into site/ (the root keeps the config, the plan, the seed output and the skills) and wire the solution into the page that needs it; " : "") +
     (mode === "migrate"
       ? "a migration preview: the site being migrated owns its content (read it with the vertical's read-site.mjs when the brief allows probing; never seed it); theme + write the home page; "
+      : madeTheSite && publisher === "plugin"
+      ? `the site is new and empty: seed it through ExecuteWixAPI (guides/api-run.md section 4, the plan per step 2 and the vertical's SEED.md as the contract${planPath ? `, the plan ${planPath}` : ", a plan drafted from the brief"}), and name the placeholder content in the closing message; theme + write the home page; `
       : madeTheSite
       ? (planPath ? "theme + write the home page; " : "the site is new and empty and no plan was given, so nothing was seeded yet: seed it now (a plan per step 2 — the brief's content, or one drafted per the vertical's SEED.md — then the vertical's seed module), and name the placeholder content in the closing message; theme + write the home page; ")
       : `nothing was seeded (setup seeds only a site it created): read what the site holds with ${join(TEMPLATES, vertical, "seed", "read-site.mjs")}, then run ${join(TEMPLATES, vertical, "seed")}/seed-*.mjs <plan> when the brief supplies or describes content; theme + write the home page; `) +
@@ -322,5 +417,5 @@ emit("ready_for_brand_layer", {
       : "") +
     (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}` +
-    (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" : ""),
+    (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 offer to complete the migration once they approve — guides/migration.md" : ""),
 });

package/skills/wix-headless-replatform/.publish-manifest.json

@@ -0,0 +1,8 @@
+{
+  "bundle": "wix-headless-replatform",
+  "version": "2.2.3",
+  "sourceRepo": "wix-private/replatform",
+  "sourcePath": "skills/wix-headless-replatform/",
+  "sourceCommit": "6bde03f",
+  "publishedAt": "2026-10-22T22:14:10Z"
+}

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

@@ -0,0 +1,116 @@
+---
+name: wix-headless-replatform
+description: Clone, rebuild, migrate, or reverse-engineer a public website home page into a Wix Headless frontend while preserving source identity, SEO, interactions, and visual fidelity.
+---
+
+# wix-headless-replatform
+
+## Role
+
+Drive a close-enough, visually polished Wix Headless frontend from a source website.
+The implemented scope is one resolved home page and the default output is
+`projects/<project-name>`, derived from the hostname. Use Wix CLI Headless, Astro,
+TypeScript, and Tailwind; use React only for complex interactive islands.
+Reject additional-page and explicit-URL scope with an actionable explanation until a later
+approved workflow defines page resolution and shared evidence across routes.
+
+This entry skill is the supervisor. It decides the next workflow stage and loads only the
+resource for that stage. Do not preload every resource or reference: stage-specific rules
+are deliberately demand-loaded.
+
+Two modes exist:
+
+- **Standalone clone:** source URL to a new, real Wix CLI Headless project.
+- **Migration phase:** `--handoff <migration-project>/website/handoff.json` continues on
+  the migration-owned destination. Never omit `--handoff` for an integrated migration:
+  the standalone command creates a second site.
+
+## Non-negotiable invariants
+
+- Treat the requested public branded homepage as authorized; apply the boundaries in
+  `references/safety.md` without asking a separate routine authorization question.
+- Browser-backed extraction is mandatory. Do not substitute HTML-only extraction.
+- Resolve the home page before capture. Build only from a validated frozen extraction
+  manifest; raw observations are never builder inputs.
+- A standalone output must be a successful Wix CLI scaffold with valid Wix identity and
+  runnable `dev` and `build` scripts. Never hand-create a Wix-shaped substitute.
+- In migration mode, reuse the handoff's site/project and route/data-binding intent; do
+  not create or retarget a second destination.
+- Preserve source structure, first-viewport evidence, chrome hierarchy, source assets,
+  fonts, core interactions, SEO, internal URL behavior, and branded fallback behavior.
+- A build is not completion. Completion requires the accepted post-build visual-review and
+  gap-loop evidence described by `rp-qa-gap-loop`, plus optional facelift acceptance only
+  when the user explicitly selected facelift mode.
+
+## Supervisor protocol
+
+On every new or resumed run:
+
+1. Resolve the source URL, output directory, and mode. In migration mode read
+   `website/handoff.json` and `docs/site-clone/frontend-automation-state.json` first.
+2. Select the first incomplete stage from the table below and read only that resource's
+   `SKILL.md` plus the references it explicitly needs.
+3. Execute that stage until it writes its required durable artifact, or records a specific
+   genuine blocker with evidence and an exact unblock action.
+4. Re-select the stage after every boundary. Do not say that a required next step “needs to
+   happen” and end the run; load its resource and perform it.
+
+| Stage | Load only when | Resource | Durable outcome |
+| --- | --- | --- | --- |
+| Context | mode, scope, project, or browser environment is unresolved | `resources/rp-project-context/SKILL.md` | valid context, approval record, runnable project/plan state, or blocker |
+| Evidence | frozen home-page extraction is absent or stale | `resources/rp-source-evidence/SKILL.md` | validated `extraction/latest.json` and frozen manifest, or global blocker |
+| Implementation | frozen build plan exists and home UI is incomplete | `resources/rp-ui-implementation/SKILL.md` | manifest-hash-aware runnable home implementation |
+| Verify and improve | build, QA, comparison, review, fix, report, release, or receipt is incomplete | `resources/rp-qa-gap-loop/SKILL.md` | accepted result, `done_with_gaps`, or global blocker |
+| Optional facelift | normal clone accepted and automation state says facelift is requested | `resources/rp-facelift/SKILL.md` | accepted facelift review, or blocker |
+
+When `frontendPhase.allowedNow` is `plan`, complete only the plan-eligible context and
+evidence work and leave a resumable plan-state record. When it is `build`, continue through
+implementation and verification against the migration-owned project.
+
+## One-click continuation
+
+A migration handoff declaring `automationMode: "one_click"` authorizes routine scope and
+frontend checkpoints. Record those approvals in
+`docs/site-clone/frontend-automation-state.json`; do not pause to ask whether to proceed
+with a required stage, screenshot review, or authorized gap-fix pass.
+An explicit facelift request may be carried from 1-click intake, but it remains gated until
+normal clone acceptance; 1-click never implies facelift by itself.
+
+In a one-click build run, keep selecting and executing stages until one of these durable
+outcomes exists:
+
+- `website/completion.json` is valid and the latest visual review is complete with no open
+  critical/high identity finding; or
+- five visual gap cycles have been completed and `website/completion.json` records the
+  truthful terminal status `done_with_gaps` with the final reviewed evidence; or
+- a genuine blocker is recorded with owner, evidence, attempted recovery, and exact next
+  authority/action needed.
+
+An owned local extraction gap is not a genuine blocker. Continue unrelated work, use no more
+than two distinct targeted recovery attempts, then build the affected dependency closure
+provisionally and surface post-assembly choices in `final-report.json` and `.md`.
+
+Before classifying a shell, browser, or network failure as a blocker, use the
+repo-local Wix/Yarn toolchain PATH ordering and follow the recovery order in
+`resources/rp-project-context/SKILL.md`: aligned-shell retry, then the
+required browser/network escalation and retry, then blocker only if it still
+fails or approval is pending. After every gap iteration, immediately return to
+the stage table; never treat a first build, a reported plan, or backend import
+as frontend completion.
+
+In migration mode the build must also leave the final route manifest that old-link
+preservation consumes (`output-contract.md`, "Migration terminal receipt"). A built site is
+not proof that old URLs work; redirect application and public verification stay pending
+until the cutover step runs them.
+
+## Commands
+
+Run `node scripts/site-clone.mjs <source-url>` for standalone mode, or
+`node scripts/site-clone.mjs <source-url> --handoff <path>` for migration mode. The active
+resource gives the exact commands and inputs for its stage.
+
+## References
+
+Resources load their own references. The shared contracts are kept under `references/`:
+`safety.md`, `workflow.md`, `extraction-schema.md`, `output-contract.md`,
+`qa-checklist.md`, and the interaction/layout/control/normalization/gap contracts.

package/skills/wix-headless-replatform/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Wix Headless RePlatform"
+  short_description: "Clone sites into Wix Headless frontends"
+  default_prompt: "Use $wix-headless-replatform to clone this website into a Wix Headless frontend."
+policy:
+  allow_implicit_invocation: true

package/skills/wix-headless-replatform/references/control-and-visual-fidelity-contract.md

@@ -0,0 +1,43 @@
+# Control and Visual Fidelity Contract
+
+This layer sits beside the scene and layout contracts. It is deliberately modular:
+
+- `control-state-contract.json` owns representative control states and transition owners;
+- `visual-assets.json` owns identity-bearing logos/icons, their variants, usage, and size;
+- `layout-blueprint.json` owns text geometry and wrapping;
+- `scene-contract.json` owns initial interactive state, item separation, and motion scope.
+
+## Control terminology
+
+Use `rest`, `hover`, `focus-visible`, `pressed`, `activated`, `current`, and `disabled`.
+Implement the recorded delta on the element that owns it: target, `::before`, `::after`, or
+nested icon. Source-observed states outrank normalization defaults. If source focus evidence
+is absent, add a perceivable `:focus-visible` treatment without replacing source hover or
+current styling.
+
+## Text geometry
+
+Important text records include `inlineSize`, `blockSize`, `lineCount`, `wrapPolicy`,
+`maxWidth`, `fontSize`, and `lineHeight`. At the canonical desktop viewport, a captured
+`single-line` heading is an identity lock. Match its container width before shrinking type.
+
+## Stateful collections
+
+Respect `initialState` and `initialActiveIndexes`. `all-collapsed` means no item may be
+opened during runtime initialization. Reproduce `separation.mechanism`: it distinguishes
+track gaps, geometric gaps, margins, dividers, inner insets, and flush items.
+
+## Motion ownership
+
+`data-rp-visual` marks the measured visual transform owner. `data-rp-content` marks copy
+whose geometry is verified separately. Never nest static content inside a scaling visual
+wrapper unless source evidence explicitly says the content scales.
+
+## Logos and icons
+
+Logo priority is exact source file or materialized source SVG. Preserve all observed
+variants and usage sizes. Never recreate a logo as text or substitute a library mark.
+
+Icon priority is exact source asset, then the source sprite/library, then a style-matched
+established library such as Iconify. Library fallback is only allowed when no source icon
+exists and never applies to logos.