@wix/agent-skills 1.20.1 → 1.21.0

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

@@ -1,21 +1,41 @@
-// Attach a NEW headless frontend to an EXISTING Wix site — the fast path for a site that already
+// Attach a NEW headless frontend to an EXISTING Wix site — setup's sibling for a site that already
 // 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
-// fast-path.mjs. Nothing on the site is created, changed or deleted; there is no seed step.
+// setup.mjs. Nothing on the site is created, changed or deleted; there is no seed step.
 //
-//   node <SKILL_ROOT>/install/attach.mjs --site <metaSiteId> --business-name "<Brand>" \
-//        --vertical <a>[,<b>…] [--stack astro|react|static] [--subfolder [--folder-name <name>]]
+//   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>]]] \
+//        [--subfolder [--folder-name <name>]]
 //
+// --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
+//                  project, no Wix address, no Astro template; the OAuth app, wix.config.json and
+//                  .env.local are still set up, the code deploys for --stack, and the origins given
+//                  in --origin go on the OAuth app's redirect allow-list, which is what a Wix-hosted
+//                  flow (checkout) needs to return to a frontend on another host.
+//
+// --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).
-// --stack       astro (default): scaffolds the CLI's blank Astro template with the hosting adapter,
-//               ready for `wix build` / `wix release`. react|static: writes wix.config.json into the
-//               folder and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md.
-// The project is created in the CURRENT DIRECTORY — the folder that already holds the installed
-// skills — so it is self-contained. `--subfolder` (opt-in) creates it in a new folder named after
-// the business instead.
+// --stack          astro (default) in a folder without a project: scaffolds the CLI's blank Astro
+//                  template with the hosting adapter. react|static there: writes wix.config.json
+//                  and stops — the caller scaffolds (Vite / plain HTML) per SKILL.md. In a folder
+//                  that holds a project, --stack is required and nothing is scaffolded.
+//
+// The FOLDER decides, on file markers only:
+//   - a project (package.json or index.html) AND wix.config.json → refuses: a Wix project with a
+//     frontend already; deploy.mjs adds a solution to it.
+//   - a project, no config → LINK: the hosting calls, then wix.config.json and .env.local are
+//     written into the project as it is, the shipped code deploys for --stack, the install starts.
+//   - no project (empty, or only a config for this same site) → the scaffold path above.
+//   - a config naming a different site → refuses: never re-point a folder; use --subfolder.
+// The project lives in the CURRENT DIRECTORY — the folder that already holds the installed skills —
+// so it is self-contained. `--subfolder` (opt-in) creates it in a new folder named after the
+// 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`)
@@ -23,11 +43,13 @@
 import { spawn, spawnSync, execFileSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { writeAgentsMd } from "./agents-md.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const MANAGE = "https://manage.wix.com";
+const API = "https://www.wixapis.com";
 const HEADLESS_PROJECT_TYPE_ID = "eb363dea-85a0-4159-9b05-949542be5079";
 const TEMPLATES_REPO = "https://github.com/wix/headless-templates.git";
 const TEMPLATE_PATH = "astro/blank";
@@ -44,9 +66,17 @@ const flag = (name) => {
   const i = argv.indexOf(`--${name}`);
   return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
 };
-const siteId = flag("site");
-const stack = flag("stack") ?? "astro";
+const stackFlag = flag("stack");
+const hosting0 = flag("hosting") ?? "wix";
+const origins = (flag("origin") ?? "").split(",").map((o) => o.trim().replace(/\/$/, "")).filter(Boolean);
 const subfolder = argv.includes("--subfolder");
+// ---- the folder ---------------------------------------------------------------------------------
+const cwd = process.cwd();
+const has = (p) => existsSync(join(cwd, p));
+const cwdConfig = has("wix.config.json") ? JSON.parse(readFileSync(join(cwd, "wix.config.json"), "utf8")) : null;
+const hasProject = has("package.json") || has("index.html");
+const siteId = flag("site") ?? cwdConfig?.siteId ?? cwdConfig?.projectId ?? null;
+const stack = stackFlag ?? "astro";
 const knownVerticals = readdirSync(join(SKILL_ROOT, "references"), { withFileTypes: true })
   .filter((d) => d.isDirectory() && d.name !== "shared" && existsSync(join(SKILL_ROOT, "references", d.name, "app")))
   .map((d) => d.name);
@@ -56,13 +86,28 @@ const verticals = argv
   .filter(Boolean);
 const businessName = flag("business-name");
 if (!siteId || !/^[0-9a-f-]{36}$/i.test(siteId) || !businessName || !verticals.length) {
-  fail("args", `usage: attach.mjs --site <metaSiteId> --business-name "<Brand>" --vertical <${knownVerticals.join("|")}>[,…] [--stack astro|react|static]`);
+  fail("args", `usage: attach.mjs [--site <metaSiteId>] --business-name "<Brand>" --vertical <${knownVerticals.join("|")}>[,…] [--stack astro|react|lib|static] (--site may be omitted when wix.config.json is here)`);
 }
 for (const v of verticals) if (!knownVerticals.includes(v)) fail("args", `unknown vertical "${v}" — shipped verticals: ${knownVerticals.join(", ")}`);
-if (!["astro", "react", "static"].includes(stack)) fail("args", `unknown stack "${stack}" — astro, react or static`);
-if (existsSync(join(process.cwd(), "wix.config.json"))) {
-  fail("args", "the current directory is already a Wix project (wix.config.json) — attach creates a new frontend; run deploy.mjs here instead");
+if (!["astro", "react", "lib", "static"].includes(stack)) fail("args", `unknown stack "${stack}" — astro, react, lib or static`);
+if (!["wix", "self"].includes(hosting0)) fail("args", `unknown --hosting "${hosting0}" — wix or self`);
+for (const o of origins) if (!/^https?:\/\/[^/\s]+$/.test(o)) fail("args", `--origin must be a scheme and host such as https://shop.example.com or http://localhost:8000, got "${o}"`);
+if (hosting0 === "self" && stack === "astro" && !hasProject && !stackFlag) {
+  fail("args", "--hosting self scaffolds nothing: pass --stack for the frontend you will host (react|lib|static), or attach from inside the project on disk");
+}
+if (!subfolder) {
+  if (hasProject && cwdConfig) {
+    fail("place", "this folder is already a Wix project with a frontend (wix.config.json and a project): nothing to attach. deploy.mjs <vertical> adds this skill's code or a solution to it; then ONE npm install");
+  }
+  if (cwdConfig && (cwdConfig.siteId ?? cwdConfig.projectId) !== siteId) {
+    fail("place", `this folder is attached to site ${cwdConfig.siteId ?? cwdConfig.projectId}, not ${siteId} — a folder is never re-pointed; attach the other site with --subfolder`);
+  }
+  if (hasProject && !stackFlag) {
+    fail("args", "attaching a project on disk needs --stack astro|react|lib|static — the stack you resolved in SKILL.md step 1 for this project");
+  }
 }
+const mode = !subfolder && hasProject ? "link" : hosting0 === "self" ? "config-only" : "scaffold";
+emit("folder", { mode, stack, hosting: hosting0, project: hasProject, config: cwdConfig ? "same site" : null });
 
 // ---- http ---------------------------------------------------------------------------------------
 const cliToken = (site) => {
@@ -92,25 +137,27 @@ async function call(base, path, { method = "POST", token, site, body, query } =
 }
 
 const folderName = flag("folder-name") ?? (businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "site");
-const projectDir = subfolder ? resolve(process.cwd(), folderName) : process.cwd();
+const projectDir = subfolder ? resolve(cwd, folderName) : cwd;
 if (subfolder && existsSync(join(projectDir, "wix.config.json"))) fail("args", `${folderName}/ is already a Wix project — pick --folder-name, or run deploy.mjs there`);
 
 // ---- 1 · attach: OAuth app + hosting + env, on the manage host with a site token -----------------
 // The same calls `init` makes after it has created a site, in the same order.
 const siteToken = cliToken(siteId);
 const opts = { token: siteToken, site: siteId };
-let appId, appProject, instanceId, secrets, hosting = "created";
+let appId, appProject = null, instanceId, secrets, hosting = hosting0 === "self" ? "self" : "created";
 try {
   const comp = await call(MANAGE, "/_api/companion-apps/v1/companion-apps/get-or-create", { ...opts, body: {} });
   appId = comp.companionApp?.id;
   if (!appId) throw new Error("get-or-create returned no companion app id");
   const slug = folderName;
-  try { appProject = (await call(MANAGE, `/_api/wix-code-app-projects/v1/app-projects/${appId}`, { ...opts, method: "GET" })).appProject; } catch { appProject = null; }
-  if (appProject) {
-    hosting = "reused";
-  } else {
-    try { await call(MANAGE, `/apps-service/v1/apps/${appId}/set-namespace`, { ...opts, method: "PATCH", body: { appId, appName: businessName, namespace: slug } }); }
-    catch (e) { emit("note", { step: "set-namespace", detail: String(e.message).slice(0, 200) }); }
+  if (hosting0 === "wix") {
+    try { appProject = (await call(MANAGE, `/_api/wix-code-app-projects/v1/app-projects/${appId}`, { ...opts, method: "GET" })).appProject; } catch { appProject = null; }
+    if (appProject) {
+      hosting = "reused";
+    } else {
+      try { await call(MANAGE, `/apps-service/v1/apps/${appId}/set-namespace`, { ...opts, method: "PATCH", body: { appId, appName: businessName, namespace: slug } }); }
+      catch (e) { emit("note", { step: "set-namespace", detail: String(e.message).slice(0, 200) }); }
+    }
   }
   try {
     const inst = await call(MANAGE, "/apps-installer-service/v1/app-instance/install", { ...opts, body: { tenant: { id: siteId, tenantType: "SITE" }, appInstance: { appDefId: appId, version: "latest" } } });
@@ -118,9 +165,23 @@ try {
   } catch (e) { emit("note", { step: "install", detail: String(e.message).slice(0, 200) }); }
   secrets = (await call(MANAGE, `/apps-service/v1/apps/${appId}`, { ...opts, method: "GET", query: { withSecrets: true } })).app?.appSecrets;
   if (!secrets?.appSecret) throw new Error("app secrets unavailable for this app");
-  if (!appProject) {
+  if (hosting0 === "self") {
+    // No Wix hosting. The one thing a frontend on another host needs from the site: its origins on
+    // the OAuth app's redirect allow-list, so checkout and the other Wix-hosted flows can return.
+    // The public OAuth Apps API (wix-manage: Manage OAuth Apps), merged with what is already there.
+    if (origins.length) {
+      const current = (await call(API, `/oauth-app/v1/oauth-apps/${appId}`, { ...opts, method: "GET" })).oAuthApp ?? {};
+      const merged = [...new Set([...(current.allowedRedirectDomains ?? []), ...origins])];
+      await call(API, `/oauth-app/v1/oauth-apps/${appId}`, { ...opts, method: "PATCH", body: { oAuthApp: { allowedRedirectDomains: merged }, mask: { paths: ["allowedRedirectDomains"] } } });
+      emit("origins_allowed", { appId, allowedRedirectDomains: merged });
+    } else {
+      emit("note", { step: "origins", detail: "no --origin given: add the frontend's origins to the OAuth app's allowedRedirectDomains (wix-manage: Manage OAuth Apps) before the first checkout test" });
+    }
+  }
+  if (hosting0 === "wix" && !appProject) {
     appProject = (await call(MANAGE, "/_api/wix-code-app-projects/v1/app-projects", { ...opts, body: { appProject: { id: appId, displayName: businessName.slice(0, 50), slug, appProjectTypeId: HEADLESS_PROJECT_TYPE_ID } } })).appProject;
   }
+  if (hosting0 === "wix") {
   if (!appProject?.baseUrl) throw new Error("app project has no baseUrl");
   const prod = String(appProject.baseUrl).replace(/\/$/, "");
   const host = new URL(appProject.baseUrl).hostname;
@@ -146,15 +207,45 @@ try {
   await call(MANAGE, `/_api/wix-code-app-environments/v2/bulk/app-projects/${appProject.id}/app-environment-variables/upsert`, { ...opts, body: {
     appProjectId: appProject.id, environment: "system_global", mutability: "STATIC", returnEntity: true, returnAllEnvironment: true, variables,
   } });
+  }
 } catch (e) {
   fail("attach", e?.message || e);
 }
-const baseUrl = String(appProject.baseUrl).replace(/\/$/, "");
-emit("attached", { siteId, appId, baseUrl, hosting, note: hosting === "reused" ? "this site already has a headless frontend at baseUrl; `wix release` from this project replaces it" : undefined });
+const baseUrl = appProject ? String(appProject.baseUrl).replace(/\/$/, "") : null;
+// Is a frontend serving at that address? The hosting project says nothing about it (init and the
+// provisioning call create one with nothing behind it). The site's release slots do: the release
+// with slug `prod` is production traffic and names the deployment it serves — the same read the
+// headless back office makes for its frontend status. Absent means nothing was ever released.
+// Deployments keep their own addresses, so a replaced one is not lost; prod can be pointed back.
+// A folder that reaches this point is not the one that released (a linked project never runs
+// attach), so a `prod` release here means a NEW project is about to take over a live frontend.
+let frontend = null;
+if (appProject) {
+  try {
+    const r = await call(MANAGE, `/_api/wix-code-app-releases/v1/app-projects/${appProject.id}/app-releases/query`, { ...opts, body: { query: { cursorPaging: { limit: 20 } } } });
+    const prod = (r.appReleases ?? []).find((x) => x.releaseSlug === "prod");
+    frontend = prod
+      ? { serving: true, releasedAt: prod.updatedDate ?? prod.createdDate ?? null, deploymentId: prod.appDeploymentId ?? null }
+      : { serving: false };
+  } catch (e) {
+    emit("note", { step: "releases", detail: String(e.message).slice(0, 200) });
+    frontend = { serving: null };
+  }
+}
+const note =
+  hosting === "self" ? "no Wix hosting: the frontend is yours to host; its origins must be on the OAuth app's allow-list"
+  : frontend?.serving === true
+    ? `a frontend is SERVING at ${baseUrl}, released ${frontend.releasedAt}. This is a new project: a \`wix release\` from here replaces it (the current deployment keeps its own address and prod can be pointed back). Tell the user before releasing; unless the brief asked for a new frontend, ask.`
+  : frontend?.serving === false
+    ? `${hosting === "created" ? "hosting created" : "hosting exists"} at ${baseUrl}; nothing served yet — the first release from this project fills it`
+  : frontend
+    ? `could not read whether a frontend is serving at ${baseUrl}; check the address before releasing`
+    : undefined;
+emit("attached", { siteId, appId, baseUrl, hosting, frontend, origins: hosting0 === "self" ? origins : undefined, note });
 
-// ---- 2 · scaffold -------------------------------------------------------------------------------
+// ---- 2 · scaffold (only where there is no project) -------------------------------------------------
 mkdirSync(projectDir, { recursive: true });
-if (stack === "astro") {
+if (stack === "astro" && mode === "scaffold") {
   // The CLI's own blank template (what `wix create` copies), then what its extender adds: the
   // hosting adapter, React islands, the `wix` scripts. Pinned like a freshly created project.
   const tmp = mkdtempSync(join(tmpdir(), "wix-template-"));
@@ -211,11 +302,14 @@ writeFileSync(join(projectDir, ".env.local"), [
   `WIX_CLIENT_SECRET=${quote(secrets.appSecret)}`,
   "",
 ].join("\n"));
-emit("scaffolded", { folder: folderName, stack, template: stack === "astro" ? `${TEMPLATES_REPO}#${TEMPLATE_PATH}` : null });
+emit(mode === "link" ? "linked" : mode === "config-only" ? "configured" : "scaffolded", { folder: folderName, stack, template: mode === "scaffold" && stack === "astro" ? `${TEMPLATES_REPO}#${TEMPLATE_PATH}` : null });
+// the agent config files `wix create` writes (attach never runs the CLI's scaffold at all); fill-only
+emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack }));
 
-if (stack !== "astro") {
-  emit("ready", { projectDir, siteId, appId, baseUrl, hosting, 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` });
+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` +
+      (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);
 }
 
@@ -229,12 +323,16 @@ let deployResult = {};
   emit("deployed", deployResult);
 }
 
-// ---- 4 · dependency install, detached -----------------------------------------------------------
-const installLog = join(projectDir, "npm-install.log");
-const logFd = openSync(installLog, "a");
-const install = spawn("sh", ["-c", "npm ci --ignore-scripts || npm install --ignore-scripts"], { cwd: projectDir, detached: true, stdio: ["ignore", logFd, logFd] });
-install.unref();
-emit("install_started", { log: installLog, doneMarker: "node_modules/.package-lock.json" });
+// ---- 4 · dependency install, detached (any project with a package.json) --------------------------
+let install = null;
+if (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);
+}
 
 // ---- done ----------------------------------------------------------------------------------------
 emit("ready_for_brand_layer", {
@@ -243,11 +341,20 @@ emit("ready_for_brand_layer", {
   appId,
   baseUrl,
   hosting,
+  frontend,
   verticals,
   dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
   productsUrl: deployResult.productsUrl,
   categoriesUrl: deployResult.categoriesUrl,
-  install: { log: installLog, doneMarker: "node_modules/.package-lock.json" },
+  mode,
+  stack,
+  install,
   seed: null,
-  next: "the site's content is live already — nothing to seed; read what it holds through the deployed data layer, theme SiteLayout + write the pages; wait for the install marker, build, release",
+  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" +
+    (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"
+      ? `; you host it — no wix release; origins on the OAuth app allow-list now: ${origins.join(", ") || "none — add them before the first checkout test"}; add the public one when it goes live`
+      : "; then release as step 5 says for the stack"),
 });

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

@@ -0,0 +1,239 @@
+// 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: scaffold the Wix CLI's
+//     Astro template and place it 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 } 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";
+
+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");
+const knownVerticals = readdirSync(join(SKILL_ROOT, "references"), { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name !== "shared" && existsSync(join(SKILL_ROOT, "references", d.name, "app")))
+  .map((d) => d.name);
+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 {
+    emit("scaffolding", { folder: folderName });
+    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", "--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;
+emit(mode === "create" ? "scaffolded" : "connected", { folder: folderName ?? cwd, siteId, stack });
+
+// ---- 2 · deploy shipped code + deps + lockfile ---------------------------------------------------
+const deploy = spawnSync(
+  "node",
+  [join(SKILL_ROOT, "install", "deploy.mjs"), vertical, "--stack", stack, ...(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(SKILL_ROOT, "references", 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; wix.config.json site.outputDirectory points at the folder the pages live in",
+}[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/references/blog/INSTRUCTIONS.md

@@ -253,6 +253,8 @@ plugins — deploy added the dep). Routes: `/blog` → your feed on `useBlogFeed
 shape; `notFound` → your 404 view). Deploy wrote the public client id into `wix/config.ts`;
 nothing else to configure.
 
+Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).
+
 ## Hard rules
 
 - **The body renders only through `RichContent`** where it deploys (Astro, React) — a post body

package/skills/wix-headless-fast/references/blog/seed/read-site.mjs

@@ -0,0 +1,22 @@
+// What the blog holds: posts, categories, tags.
+//   node <SKILL_ROOT>/references/blog/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const BLOG_APP_ID = "14bcded7-0066-7c35-14d7-466cb3f09103";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/blog";
+
+await runReader({
+  vertical: "blog",
+  appId: BLOG_APP_ID,
+  async read(api, { limit }) {
+    const posts = await api.call({ path: "/v3/posts/query", body: { fieldsets: ["URL"], query: { paging: { limit } } }, docs: `${D}/posts-stats/query-posts` });
+    const cats = await api.tryCall({ path: "/blog/v3/categories/query", body: { query: { paging: { limit: 100 } } }, docs: `${D}/category/query-categories` });
+    const tags = await api.tryCall({ path: "/v3/tags/query", body: { query: { paging: { limit: 100 } } }, docs: `${D}/tags/query-tags` });
+    return {
+      postCount: posts.metaData?.total ?? posts.pagingMetadata?.total ?? (posts.posts ?? []).length,
+      posts: (posts.posts ?? []).map((p) => ({ title: p.title, slug: p.slug, published: p.firstPublishedDate ?? null, cover: !!p.coverMedia?.image, categories: (p.categoryIds ?? []).length, tags: (p.tagIds ?? []).length, minutesToRead: p.minutesToRead ?? null })),
+      categories: (cats?.categories ?? []).map((c) => ({ id: c.id, label: c.label, slug: c.slug, postCount: c.postCount ?? null })),
+      tags: (tags?.tags ?? []).map((t) => ({ id: t.id, label: t.label, postCount: t.postCount ?? null })),
+    };
+  },
+});

package/skills/wix-headless-fast/references/bookings/INSTRUCTIONS.md

@@ -223,6 +223,8 @@ fetch with `fetchServiceBySlug(slug)` client-side, then your booking surface on
 `useBookingFlow(service)`. Deploy wrote the public client id into `wix/config.ts`; nothing else
 to configure.
 
+Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).
+
 ## Hard rules
 
 - **Booking logic only through the shipped exports** — `useBookingFlow`/`bookService` own the

package/skills/wix-headless-fast/references/bookings/seed/read-site.mjs

@@ -0,0 +1,28 @@
+// What the booking business holds: services, staff, categories.
+//   node <SKILL_ROOT>/references/bookings/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/bookings";
+
+await runReader({
+  vertical: "bookings",
+  appId: BOOKINGS_APP_ID,
+  async read(api, { limit }) {
+    const services = await api.call({ path: "/_api/bookings/v2/services/query", body: { query: { paging: { limit }, filter: { hidden: { $eq: false } } } }, docs: `${D}/services/services-v2/query-services` });
+    const staff = await api.tryCall({ path: "/bookings/v1/staff-members/query", body: { query: {}, fields: ["RESOURCE_DETAILS"] }, docs: `${D}/staff-members/staff-members/query-staff-members` });
+    const cats = await api.tryCall({ path: "/bookings/v2/categories/query", body: { query: {} }, docs: `${D}/services/categories-v2/query-categories` });
+    return {
+      serviceCount: services.pagingMetadata?.total ?? (services.services ?? []).length,
+      services: (services.services ?? []).map((s) => ({
+        name: s.name, slug: s.mainSlug?.name ?? null, type: s.type ?? null,
+        category: s.category?.name ?? null,
+        price: s.payment?.fixed?.price ? `${s.payment.fixed.price.value} ${s.payment.fixed.price.currency}` : s.payment?.varied?.defaultPrice ? `from ${s.payment.varied.defaultPrice.value} ${s.payment.varied.defaultPrice.currency}` : (s.payment?.rateType ?? null),
+        durationMinutes: s.schedule?.availabilityConstraints?.sessionDurations?.[0] ?? null,
+        online: s.payment?.options?.online ?? false, inPerson: s.payment?.options?.inPerson ?? false, media: s.media?.mainMedia ? 1 : 0,
+      })),
+      staff: (staff?.staffMembers ?? []).map((m) => m.name),
+      categories: (cats?.categories ?? []).map((c) => ({ id: c.id, name: c.name })),
+    };
+  },
+});

package/skills/wix-headless-fast/references/cms/INSTRUCTIONS.md

@@ -289,6 +289,8 @@ plugins — deploy added the dep). Routes are yours: a list route per collection
 fetch client-side when no `initialItems` / `initialItem` is passed). Deploy wrote the public
 client id into `wix/config.ts`; nothing else to configure.
 
+Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).
+
 ## Hard rules
 
 - **Data only through the shipped exports** — never re-derive a Wix Data request, never