@wix/agent-skills 1.23.0 → 1.25.0

package/skills/{wix-headless-fast → wix-headless-kit}/install/setup.mjs

@@ -1,27 +1,30 @@
 // 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:
+// brief" to "brand layer can start". The folder decides (install/context.mjs folderShape, five file
+// facts: wix.config.json, its site.outputDirectory, the migration variables in .env.local,
+// package.json, index.html):
 //
-//   node <SKILL_ROOT>/install/setup.mjs --vertical <storefront|bookings|…> \
+//   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>]]
 //
-//   - `wix.config.json` present → refuses. The folder is already a Wix project; deploy.mjs adds
-//     this skill's code or a solution to it, then one install, then the seed if there is content.
-//     One exception: a config and NO project whose `.env.local` (`wix env pull`, run here) declares a
-//     MIGRATION PREVIEW — the config names a site created only to host the deployment, the env names
-//     the site being migrated. Then → MIGRATE: the composed template is copied in around the config,
-//     the code deploys with the parent's app as its client, the install starts, and NO seed runs: the
-//     parent owns its content. Release still goes where the config says (install/context.mjs).
-//   - a project but no `wix.config.json` (a package.json, or an index.html at the root) → CONNECT:
-//     `npm create @wix/new@latest init` in place creates the site and the config, then deploy.
-//   - otherwise (empty, or loose files such as a CSV or a brief) → CREATE: `wix create` with the
-//     vertical's composed template (templates/<vertical>/project: the CLI's blank scaffold with the
-//     vertical deployed and a lockfile), placed in the current directory (`--business-name` required).
+//   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).
+//   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,
+//     and the plan's content goes in (with --plan; without one the agent drafts a plan and seeds it, SKILL.md step 2).
+//   a config and no frontend, .env.local declaring a MIGRATION PREVIEW → MIGRATE: the composed template
+//     is copied in around the config, the code deploys with the parent's app as its client, the install
+//     starts. Nothing seeded: the parent owns its content.
+//   a config, index.html at the root, no package.json → PUBLISHED STATIC (a site published through the
+//     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.
+//   a config and nothing else → refuses: attach.mjs's case.
 //
-// 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.
+// Setup seeds only a site it created in this run. A site that existed before the run is never seeded
+// by setup: the agent reads what the site holds (the vertical's read-site.mjs) and runs the seed module
+// deliberately when the brief supplies or describes content. Seeds are additive and idempotent by name.
 //
 // 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
@@ -33,7 +36,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AGENT_CONFIG_FILES, writeAgentsMd } from "./agents-md.mjs";
 import { listVerticals, templatesDir } from "./templates.mjs";
-import { siteContext } from "./context.mjs";
+import { folderShape, siteContext } from "./context.mjs";
 
 const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -51,7 +54,12 @@ const flag = (name) => {
 };
 const businessName = flag("business-name");
 const planPath = flag("plan");
-const vertical = flag("vertical");
+// Every vertical the brief needs, comma-separated. The first one's composed template scaffolds the
+// project and its seed runs from --plan; the others deploy in the same call so the ONE install covers
+// them (adding a vertical after the install has started costs a second install). Their seeds run
+// afterwards, each with its own plan, when the brief gives them content.
+const verticals = (flag("vertical") ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+const vertical = verticals[0] ?? null;
 const stackFlag = flag("stack");
 // Opt-in: keep a CREATE's project in a subfolder instead of the current directory.
 const subfolder = argv.includes("--subfolder");
@@ -59,11 +67,11 @@ const subfolder = argv.includes("--subfolder");
 let TEMPLATES;
 try { TEMPLATES = templatesDir(); } catch (e) { fail("templates", e.message); }
 const knownVerticals = listVerticals(TEMPLATES);
-const usage = `usage: setup.mjs --vertical <${knownVerticals.join("|")}> [--plan plan.json] [--business-name "<Brand>"] [--stack astro|react|lib|static] [--subfolder]`;
+const usage = `usage: setup.mjs --vertical <${knownVerticals.join("|")}>[,<vertical>…] [--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(", ")}`);
+for (const v of verticals) {
+  if (!knownVerticals.includes(v)) fail("args", `unknown vertical "${v}" — shipped verticals: ${knownVerticals.join(", ")}`);
 }
 if (stackFlag && !["astro", "react", "lib", "static"].includes(stackFlag)) {
   fail("args", `unknown --stack "${stackFlag}" — astro, react, lib or static`);
@@ -74,22 +82,27 @@ if (planPath && !existsSync(planPath)) fail("args", `plan file not found: ${plan
 const cwd = process.cwd();
 const has = (p) => existsSync(join(cwd, p));
 const pkg = has("package.json") ? JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) : null;
-const hasProject = !!pkg || has("index.html");
-// A config here: refuse, unless it is a migration preview with no project yet (the site context
-// pulls .env.local when missing — that is where the migration is declared).
 let ctx = null;
+let shape = folderShape(cwd).shape;
 if (has("wix.config.json")) {
-  ctx = siteContext({ cwd });
-  if (hasProject || !ctx.migration.active) {
-    fail("place", "this folder is already a Wix project (wix.config.json): nothing to set up. deploy.mjs <vertical> adds this skill's code or a solution to it; then ONE npm install; then the vertical's seed module if there is content to create. A config with no project is attach.mjs's case (SKILL.md step 3)" + (ctx.pullError ? ` — note: env pull failed here (${ctx.pullError.slice(0, 120)})` : ""));
+  ctx = siteContext({ cwd }); // pulls .env.local when missing — where a migration is declared
+  shape = ctx.folder.shape;
+  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)})` : ""));
+  }
+  if (shape === "published-static" && stackFlag && stackFlag !== "static") {
+    fail("args", `a published static site (index.html beside wix.config.json, no package.json) is the static stack; --stack ${stackFlag} does not apply`);
   }
 }
-const mode = ctx ? "migrate" : hasProject ? "connect" : "create";
-if (mode === "connect" && !stackFlag) {
-  fail("args", "connecting a project on disk needs --stack astro|react|lib|static — the stack you resolved in SKILL.md step 1 for this project");
+const mode = { migration: "migrate", "published-static": "published-static", project: "adopt", empty: "create" }[shape];
+const migrating = mode === "migrate";
+const publishedStatic = mode === "published-static";
+const hasProject = shape === "project";
+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 = stackFlag ?? "astro";
-emit("folder", { mode, stack, project: hasProject ? (pkg?.name ?? basename(cwd)) : null, ...(ctx ? { migration: ctx.migration, deploySiteId: ctx.deploy.siteId, warnings: ctx.warnings } : {}) });
+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 } : {}) });
 
 let projectDir = cwd;
 let folderName = null;
@@ -134,11 +147,13 @@ if (mode === "create") {
 } else if (mode === "migrate") {
   // ---- 1 · a migration preview: the config and credentials came with the folder -------------------
   // No site is created and nothing is provisioned: `wix.config.json` already names the deploy site
-  // and its app, `.env.local` the parent's. Managed Astro gets the vertical's composed template copied
-  // in around them (what `wix create` would have copied; the config and env are never overwritten);
-  // any other stack is code-only and deploy below adds it.
-  if (planPath) emit("seed_skipped", { reason: `migration preview of site ${ctx.migration.parentSiteId}: the site owns its content and nothing is seeded — the plan is ignored` });
-  if (stack === "astro") {
+  // and its app, `.env.local` the parent's. The download usually carries the CLI's blank Astro
+  // starter beside the config: then the project is kept and deploy below adds the vertical's code and
+  // dependencies into it, as for an adopted project. A bare config (no package.json) gets the
+  // vertical's composed template copied in around it on managed Astro; any other stack is code-only.
+  if (stack === "astro" && has("package.json")) {
+    emit("migration_project_kept", { folder: cwd, project: pkg?.name ?? basename(cwd) });
+  } else if (stack === "astro") {
     const template = join(templatesDir({ need: `${vertical}/project` }), vertical, "project");
     emit("scaffolding", { folder: cwd, template, from: "migration preview" });
     cpSync(template, cwd, { recursive: true, force: false, errorOnExist: false });
@@ -150,12 +165,18 @@ if (mode === "create") {
   const gi = join(cwd, ".gitignore");
   const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
   if (!/\.env/.test(cur)) writeFileSync(gi, cur + "\n# local env (pulled from Wix)\n.env.local\n.env\n");
+} else if (publishedStatic) {
+  // ---- 1 · a published static site: the config came with the folder, the site exists -------------
+  // No init: `wix.config.json` already names the site the pages are published on (and its app). The
+  // pages stay where they are; the static handling below points the upload at site/ and the `next`
+  // says to move them in.
+  emit("preparing", { folder: cwd, siteId: ctx.deploy.siteId, from: "published static site" });
 } 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 });
+  emit("adopting", { 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")) {
@@ -172,17 +193,17 @@ if (stack === "static") {
   wixConfig.site = { ...(wixConfig.site ?? {}), outputDirectory: `./${STATIC_OUT}` };
   writeFileSync(join(projectDir, "wix.config.json"), JSON.stringify(wixConfig, null, 2) + "\n");
 }
-emit(mode === "create" ? "scaffolded" : mode === "migrate" ? "migration_preview" : "connected", {
+emit({ create: "scaffolded", migrate: "migration_preview", adopt: "adopted", "published-static": "prepared" }[mode], {
   folder: folderName ?? cwd, stack,
-  ...(ctx ? { deploySiteId: ctx.deploy.siteId, contentSiteId: ctx.content.siteId } : { siteId }),
+  ...(migrating ? { deploySiteId: ctx.deploy.siteId, contentSiteId: ctx.content.siteId } : { siteId }),
 });
 
 // ---- 2 · deploy shipped code + deps ---------------------------------------------------------------
 // A CREATE from the composed template already holds the code and the lock: deploy adds nothing and
-// reports the project; a CONNECT gets the code and its dependencies here.
+// reports the project; an ADOPT gets the code and its dependencies here.
 const deploy = spawnSync(
   "node",
-  [join(SKILL_ROOT, "install", "deploy.mjs"), vertical, "--stack", stack, ...(stack === "static" ? ["--out", STATIC_OUT] : []), ...(planPath ? ["--plan", resolve(planPath)] : [])],
+  [join(SKILL_ROOT, "install", "deploy.mjs"), ...verticals, "--stack", stack, ...(stack === "static" ? ["--out", STATIC_OUT] : []), ...(planPath ? ["--plan", resolve(planPath)] : [])],
   { cwd: projectDir, encoding: "utf8", timeout: 60_000 },
 );
 if (deploy.status !== 0) fail("deploy", deploy.stderr || deploy.stdout);
@@ -223,7 +244,7 @@ if (mode === "create" && !subfolder && projectDir !== cwd) {
 // ---- 2d · the agent config files `wix create` would have written --------------------------------
 // Skipped by the CLI because of --skip-install. Fill-only: a project that has its own AGENTS.md
 // keeps it (the event says `kept`).
-emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack, ...(ctx ? { migration: { parentSiteId: ctx.migration.parentSiteId, deploySiteId: ctx.deploy.siteId } } : {}) }));
+emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), stack, ...(migrating ? { migration: { parentSiteId: ctx.migration.parentSiteId, deploySiteId: ctx.deploy.siteId } } : {}) }));
 
 // ---- 3 · start the dependency install, detached --------------------------------------------------
 // ONE install, here, for any project with a package.json (deploy patched it). The static stack has
@@ -243,13 +264,19 @@ if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
   emit("install_started", install);
 }
 
-// ---- 4 · start the seed, detached (only with a plan) ---------------------------------------------
+// ---- 4 · start the seed, detached (a site this run created, 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.
+// result JSON + exit-code marker land as files the caller syncs on before release. Only a site this
+// run created is seeded here; every other site existed before the run and is read first, then the
+// agent runs the seed module itself when the brief supplies content. Seeds are additive and
+// idempotent by name.
+const madeTheSite = mode === "create" || mode === "adopt";
 let seed = null;
-if (planPath && mode !== "migrate") {
+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 (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) {
   const seedDir = join(TEMPLATES, vertical, "seed");
   const seedName = existsSync(seedDir)
     ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
@@ -264,7 +291,7 @@ if (planPath && mode !== "migrate") {
   );
   seedChild.unref();
   seed = { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" };
-  emit("seeding_started", { vertical, ...seed });
+  emit("seeding_started", { vertical, ...seed, ...(verticals.length > 1 ? { note: `the plan seeds ${vertical}; the other verticals' seeds run afterwards, each with its own plan` } : {}) });
 }
 
 // ---- done ----------------------------------------------------------------------------------------
@@ -276,23 +303,30 @@ const release = {
 }[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.
+const others = verticals.slice(1);
 emit("ready_for_brand_layer", {
   mode,
+  shape,
   stack,
+  verticals,
   projectDir,
-  siteId: ctx ? ctx.content.siteId : siteId,
-  ...(ctx ? { deploySiteId: ctx.deploy.siteId, migration: { parentSiteId: ctx.migration.parentSiteId } } : {}),
+  siteId: migrating ? ctx.content.siteId : siteId,
+  ...(migrating ? { deploySiteId: ctx.deploy.siteId, migration: { parentSiteId: ctx.migration.parentSiteId } } : {}),
   dashboardUrl: deployResult.dashboardUrl,
   productsUrl: deployResult.productsUrl,
   categoriesUrl: deployResult.categoriesUrl,
   install,
   seed,
   next:
+    (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; "
-      : 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; ") +
+      : 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 templates/${vertical}/seed/read-site.mjs, then run templates/${vertical}/seed/seed-*.mjs <plan> when the brief supplies or describes content; theme + write the home page; `) +
+    (others.length && mode !== "migrate"
+      ? `${others.join(", ")} deployed too, no further install needed: run each one's seed module (templates/<vertical>/seed/) with its own plan when the brief gives it content (the members seed installs the Members Area app and needs no plan); `
+      : "") +
     (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" : ""),

package/skills/{wix-headless-fast → wix-headless-kit}/install/templates.mjs

@@ -142,7 +142,7 @@ function fetchTemplates(cache) {
 
 // A sparse, shallow clone of templates/ at a ref (branch, tag, or commit id) into a temp dir.
 function cloneSparse(repo, ref) {
-  const tmp = mkdtempSync(join(tmpdir(), "wix-headless-fast-templates-"));
+  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)

package/skills/wix-manage/SKILL.md

@@ -135,19 +135,13 @@ Uses Calendar Events API to create WORKING_HOURS events on the business schedule
 ## CMS
 
 ### [CMS Data Items CRUD](references/cms/cms-data-items-crud.md)
-"Add, query, update, and delete items in CMS collections. Use this to insert content, bulk insert/update/patch/delete items, query with filters, and manage collection data. Key endpoints: /wix-data/v2/items, /wix-data/v2/bulk/items/*."
-
-### [CMS Data Operations Extended](references/cms/cms-data-operations-extended.md)
-Additional CMS data operations including count, upsert (bulk save), and update by filter patterns.
+"Add, query, update, and delete items in CMS collections, one at a time or in bulk. Also covers counting items, upserting with bulk save, truncating a collection, aggregating data with a pipeline, linking items through single- and multi-reference fields, and reading items with their referenced items expanded."
 
 ### [CMS eCommerce Catalog Integration](references/cms/cms-ecommerce-catalog-integration.md)
 The recommended way to sell existing CMS collection items (tickets, bookings, memberships) through Wix checkout. Add the CATALOG plugin to convert any CMS collection into purchasable products with cart and payment integration.
 
-### [CMS References And Relationships](references/cms/cms-references-and-relationships.md)
-"Add, replace, or remove items from MULTI_REFERENCE fields. Use insert-references, replace-references, remove-references endpoints. Required for managing multi-reference relationships - these CANNOT be set via regular insert/update/patch operations. Also covers single references and querying with expanded references."
-
 ### [CMS Schema Management](references/cms/cms-schema-management.md)
-Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields, and updating collection settings.
+Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields (including single- and multi-reference fields that link two collections), and updating collection settings.
 
 ### [CMS Draft & Publish Workflow (Draft Items plugin)](references/cms/cms-publishing-flow.md)
 "Interact with CMS collections that gate their items behind a draft/publish workflow via the Draft Items plugin. Covers detecting the plugin, locating the paired drafts collection, reading published vs draft items, authoring/editing drafts, and publishing, unpublishing, reverting, and deleting items. Key endpoints: /wix-data/v2/items/publish-draft, /wix-data/v2/items/unpublish, /wix-data/v2/collections/add-draft-items-plugin, and the paired drafts collection referenced by draftItemsPluginOptions.draftsCollectionId."

package/skills/wix-manage/references/cms/cms-dashboard-navigation.md

@@ -28,8 +28,8 @@ Fetch the entity via REST, then link the matching dashboard page. All calls use
 
 | Entity | Read API | Dashboard link |
 |---|---|---|
-| Collection (schema) | `GET /wix-data/v2/collections/{collectionId}` · `GET /wix-data/v2/collections` (list) | `wix-cms/data/{collectionId}` |
-| Data item | `POST /wix-data/v2/items/query` (body includes `dataCollectionId`) · `GET /wix-data/v2/items/{itemId}?dataCollectionId=...` | `wix-cms/data/{collectionId}` (the collection's items table) |
+| Collection (schema) | `GET https://www.wixapis.com/wix-data/v2/collections/{collectionId}` · `GET https://www.wixapis.com/wix-data/v2/collections` (list) | `wix-cms/data/{collectionId}` |
+| Data item | `POST https://www.wixapis.com/wix-data/v2/items/query` (body includes `dataCollectionId`) · `GET https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId=...` | `wix-cms/data/{collectionId}` (the collection's items table) |
 
 Example — after creating a collection and inserting items: