@wix/agent-skills 1.20.0 → 1.21.0

package/skills/wix-headless-fast/references/storefront/seed/seed-store.mjs

@@ -1,7 +1,7 @@
 // Storefront seed — a BUILD-TIME script, never shipped in the app. Run it from the project
 // root (where wix.config.json lives) with a plan file:
 //
-//   node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json [--fresh-site]
+//   node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
 //
 // It mints its own site token via the Wix CLI (the token never leaves this process), installs
 // the Wix Stores app if needed, waits for the V3 catalog, bulk-creates products (variants
@@ -367,23 +367,6 @@ export async function createCategories(ctx, names) {
   return out;
 }
 
-// The Stores install drops sample products ("I'm a product") into every new catalog. On a site the
-// fast path JUST created nothing else can exist, so they are deleted before seeding — otherwise the
-// storefront ships with the samples between the real products. Only called with --fresh-site; a
-// seed against an existing site never deletes anything (SEED.md: seeding is additive).
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-delete-products.md
-export async function deleteAllProducts(ctx) {
-  let deleted = 0;
-  for (let pass = 0; pass < 10; pass++) {
-    const r = await req(ctx, "/stores/v3/products/query", { body: { query: { cursorPaging: { limit: 100 } } } });
-    const ids = (r.products ?? []).map((p) => p.id).filter(Boolean);
-    if (!ids.length) break;
-    await req(ctx, "/stores/v3/bulk/products/delete", { body: { productIds: ids } });
-    deleted += ids.length;
-    if (ids.length < 100) break;
-  }
-  return deleted;
-}
 
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category.md
 export async function addProductsToCategories(ctx, mapping) {
@@ -401,19 +384,47 @@ export async function addProductsToCategories(ctx, mapping) {
 // current revision is read right before the update, so attach any number of times, any pass.
 // Wix re-hosts each url server-side; the media can take a little while to appear on read-back
 // (propagation) — normal, not a failure.
+// The bulk update returns 200 on PARTIAL failure, like the bulk create: each item's outcome is
+// in results[].itemMetadata (success, error, originalIndex). Seen live (runs 85 and 86,
+// 2026-09-26): one product of three came back with no media while the call succeeded — most
+// likely its revision moved between the read and the update (variant stocking runs just
+// before). So: pair results to inputs, retry the misses once with fresh revisions, and report
+// what actually persisted. Returns { attached: [id], failures: [{ id, error }] }.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-update-products.md
 export async function attachProductImages(ctx, items) {
-  if (!items?.length) return;
-  const ids = items.map((it) => it.id);
-  const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } } });
-  const revById = new Map((q.products ?? []).map((p) => [p.id, p.revision]));
-  return req(ctx, "/stores/v3/bulk/products/update", {
-    body: {
-      products: items.map((it) => ({
-        product: { id: it.id, revision: revById.get(it.id), media: { itemsInfo: { items: [{ url: it.url, altText: it.altText }] } } },
-      })),
-    },
-  });
+  if (!items?.length) return { attached: [], failures: [] };
+  const send = async (batch) => {
+    const ids = batch.map((it) => it.id);
+    const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } } });
+    const revById = new Map((q.products ?? []).map((p) => [p.id, p.revision]));
+    const r = await req(ctx, "/stores/v3/bulk/products/update", {
+      body: {
+        products: batch.map((it) => ({
+          product: { id: it.id, revision: revById.get(it.id), media: { itemsInfo: { items: [{ url: it.url, altText: it.altText }] } } },
+        })),
+      },
+    });
+    const ok = new Set();
+    const failed = [];
+    for (const x of r.results ?? []) {
+      const src = batch[x.itemMetadata?.originalIndex];
+      if (!src) continue;
+      if (x.itemMetadata?.success) ok.add(src.id);
+      else failed.push({ id: src.id, error: x.itemMetadata?.error?.description ?? x.itemMetadata?.error?.code ?? "unknown" });
+    }
+    // an input with no result at all did not persist either
+    for (const it of batch) if (!ok.has(it.id) && !failed.some((f) => f.id === it.id)) failed.push({ id: it.id, error: "no result for item" });
+    return { ok, failed };
+  };
+  const first = await send(items);
+  const attached = new Set(first.ok);
+  let failures = first.failed;
+  if (failures.length) {
+    const retry = await send(items.filter((it) => failures.some((f) => f.id === it.id)));
+    for (const id of retry.ok) attached.add(id);
+    failures = retry.failed;
+  }
+  return { attached: [...attached], failures };
 }
 
 // Reject plans the API would reject halfway through, while nothing has been created yet —
@@ -462,22 +473,12 @@ async function setSiteCurrency(ctx, currency) {
  * threaded in memory. This is the default path — call it once instead of the individual
  * functions.
  */
-export async function setupStore(ctx, { products = [], categories = {}, currency } = {}, { freshSite = false } = {}) {
+export async function setupStore(ctx, { products = [], categories = {}, currency } = {}) {
   validateProducts(products);
   await installStoresApp(ctx);
   // Before any product exists: a product's price is stored in the site currency at create time,
   // so switching afterwards leaves the catalog priced in the old one.
   if (currency) await setSiteCurrency(ctx, currency);
-  // A just-created site holds only the install's sample products — clear them (never on an
-  // existing site: the flag is the fast path's, set only when it created the site itself).
-  let samplesDeleted = 0;
-  if (freshSite) {
-    try {
-      samplesDeleted = await deleteAllProducts(ctx);
-    } catch (e) {
-      console.error(`sample cleanup failed (seeding on top): ${String(e.message).slice(0, 120)}`);
-    }
-  }
 
   // Idempotent by name: an errored bulk create (429/5xx) may still have applied server-side,
   // and SKILL.md tells the agent to re-run a failed seed — creating only the names that don't
@@ -518,34 +519,40 @@ export async function setupStore(ctx, { products = [], categories = {}, currency
   const imageItems = withNames
     .map((p, i) => (files[i] && p.id ? { id: p.id, url: files[i].url, altText: products[i]?.altText ?? p.slug } : null))
     .filter(Boolean);
+  // imagesAttached counts the attaches the API CONFIRMED (per-item results), not the ones sent;
+  // imageFailures names the products left text-only and why. Neither blocks the seed: a re-run of
+  // the same plan reuses the products and attaches again.
   let imagesAttached = 0;
+  const imageFailures = [];
+  const nameOf = (id) => withNames.find((p) => p.id === id)?.name;
   try {
-    if (imageItems.length) await attachProductImages(ctx, imageItems);
-    imagesAttached = imageItems.length;
-  } catch {
-    /* never block on image failure — the products stay text-only */
+    if (imageItems.length) {
+      const r = await attachProductImages(ctx, imageItems);
+      imagesAttached = r.attached.length;
+      for (const f of r.failures) imageFailures.push({ name: nameOf(f.id), error: f.error });
+    }
+  } catch (e) {
+    for (const it of imageItems) imageFailures.push({ name: nameOf(it.id), error: e?.message ?? String(e) });
   }
 
   // failures is part of the result, not an exception: a partial seed still leaves a usable
   // store, and the agent needs the names to report rather than silently shipping a short
   // catalog. Re-run the seed to retry them — existing names are skipped, not duplicated.
-  return { products: withNames, categories: cats, imagesAttached, samplesDeleted, failures };
+  return { products: withNames, categories: cats, imagesAttached, imageFailures, failures };
 }
 
 // ---- CLI entry ----------------------------------------------------------------------------------
 
 const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
 if (invokedDirectly) {
-  const args = process.argv.slice(2);
-  const freshSite = args.includes("--fresh-site");
-  const planPath = args.find((a) => !a.startsWith("--"));
+  const planPath = process.argv[2];
   if (!planPath) {
-    console.error("usage: node seed-store.mjs <plan.json> [--fresh-site]   (run from the project root)");
+    console.error("usage: node seed-store.mjs <plan.json>   (run from the project root)");
     process.exit(1);
   }
   const plan = JSON.parse(readFileSync(planPath, "utf8"));
   const ctx = makeCtx();
-  setupStore(ctx, plan, { freshSite })
+  setupStore(ctx, plan)
     .then((result) => console.log(JSON.stringify(result, null, 2)))
     .catch((e) => {
       console.error(e.message);

package/skills/wix-manage/references/ecommerce/ecom-shipping.md

@@ -29,7 +29,7 @@ Set up and tune how a store ships — what rates to charge, which regions are co
 
 > - [Set up shipping rates / rules](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-rates) — tags: `[intent:setup-rates]` · priority 0
 > - [Set up delivery regions / coverage](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-regions) — tags: `[intent:setup-regions]` · priority 0
-> - [Set up store pickup / local delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/local-delivery) — tags: `[intent:setup-pickup]` · priority 0
+> - [Set up store pickup / local delivery](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-set-up-pickup-local-delivery) — tags: `[intent:setup-pickup]` · priority 0
 > - [Add free shipping over $X](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/shipping-add-free-shipping) — tags: `[intent:free-shipping]` · priority 0
 
 ### Optimize & fix

package/skills/wix-manage/references/ecommerce/pricing-promotions/ecom-pricing-create-coupon.md

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

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

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

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -235,24 +235,6 @@ export default function ProductDetail() {
 - Render the PDP gallery from `images` — every image reachable (thumbnails, arrows, or a swipeable rail), not just the first; a single-image product gets no empty strip.
 - `submit()` resets `adding` after completion and preserves the cart result: `undefined` on success, `null` on failure. Add failures live in `useCart().error`, not the PDP load `error`; the shipped drawer opens to display them.
 
-For an optional **add and check out** shortcut, check the add result before checkout:
-```jsx
-// Inside ProductDetail, with the other hooks above any conditional returns:
-const { checkout, loading: cartLoading } = useCart(); // named import from @/context/CartContext
-async function addAndCheckout() {
-  if (!d.product || !d.canAdd || d.adding || cartLoading) return;
-  const result = await d.submit();
-  if (result === null) return; // add failed; preserve its error and do not check out the old cart
-  await checkout();
-}
-// <button disabled={!d.canAdd || d.adding || cartLoading} onClick={addAndCheckout}>Add and check out</button>
-```
-This adds to the shopper's **current cart** and checks that cart out — so label it that way. A true
-**Buy Now** (skip the cart, buy just this item) needs a standalone cart handed to the redirect session;
-it is not shipped, and routing "Buy now" through the current cart is wrong (it would carry whatever the
-cart already holds). For direct `addToCart(...)` calls, use the same `result === null` check before checkout.
-A resolved promise alone does not mean success; a truthiness check also rejects successful `undefined`.
-
 ### Variant and modifier controls
 The product-detail example above provides both groups:
 ```js
@@ -475,28 +457,6 @@ Path params are `$name` in both the filename and the route path; `useParams()` f
 reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
 [`../_shared/routing.md`](../_shared/routing.md).
 
-## What a complete storefront shows
-
-The wiring above is necessary, not sufficient. These are defaults for when the brief doesn't say
-otherwise — whatever the user asked for in their prompt wins over any line here. Look at the
-catalog before designing — categories, assortment size, media, options, sales — and design for this
-store, not for a stereotype of its category. Then:
-
-- **Home:** what the store sells and one shopping action in the first screen; real products from
-  the catalog under truthful headings; not a repeat of the shop page.
-- **Shop:** a real product card — image, name, price, link — in the first screen; sort and the
-  filters the catalog supports; loading, empty, no-results, and error states that look different.
-- **Product page:** image, name, price, the first choice, and the buy button with `blockedReason`
-  in the first screen; every ribbon; every image reachable in the gallery.
-- **Cart:** the shipped drawer — it opens after every add, and checkout is a button in it.
-- **Overlays you build** (quick-add, mobile nav, filters): mount at the document root, lock
-  background scroll, close on Escape, return focus on close — as the shipped `CartDrawer` does.
-- **Copy:** nothing the merchant didn't supply — no invented reviews, scarcity, or delivery
-  promises; no Wix IDs or technical words in visible text.
-
-Pre-order ships (`isPreorder`). Subscriptions, product groups, promotions, and notify-me are built
-only when the catalog has them — never fabricated; consult the documentation skill for their endpoints.
-
 ## Missing capabilities
 For anything these interfaces do not cover, consult the official Wix API documentation using
 the documentation skill available in your environment.

package/skills/wix-vibe-headless/references/storefront/seed/SEED.md

@@ -41,6 +41,9 @@ const result = await seed.setupStore(ctx, {
 //   currency: { requested, actual, status, warnings } }
 ```
 
+A product `name` is at most **80 characters** — Wix rejects the whole batch over that, so keep
+names short and put the detail in `description`.
+
 The optional `currency` sets the site's payment currency before product creation. Pass it only when
 the user explicitly asked for a currency, or when it's obvious for the store — otherwise omit it. Do
 not infer a currency from the builder's country/region or the brief's language; when in doubt, leave

package/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs

@@ -174,6 +174,12 @@ function buildOptions(options = []) {
 function validateProducts(products) {
   const seen = new Map();
   for (const product of products) {
+    // Wix caps a product name at 80 characters and the bulk create rejects the WHOLE batch over it
+    // ("name has size 175, expected 80 or less"), so the 81st character costs the entire seed.
+    if (typeof product.name === "string" && product.name.length > 80) {
+      throw new Error(`Product "${product.name.slice(0, 48)}…": the name is ${product.name.length} characters and Wix allows 80. ` +
+        `Shorten it and move the detail into description. No products were created by this call.`);
+    }
     if (product.inStock !== undefined && typeof product.inStock !== "boolean") {
       throw new Error(`Product "${product.name}": inStock must be a boolean. No products were created by this call.`);
     }

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

@@ -1,186 +0,0 @@
-// Fast path for a managed CREATE run — one deterministic call from "plan exists" to
-// "brand layer can start". Composes the pieces that also remain individually runnable
-// (deploy.mjs, the vertical's seed module); use those directly to recover a failed step,
-// or for connect/iterate runs (which must NOT scaffold and don't use this script).
-//
-//   node <SKILL_ROOT>/install/fast-path.mjs --business-name "<Brand>" --plan plan.json \
-//        --vertical <storefront|bookings|…> [--stack astro] [--folder-name <npm-safe-name>] [--flatten]
-//
-// --flatten (opt-in): leave the project directly in the current directory instead of a subfolder,
-// moving it before the background install starts. Default off — the normal output is a subfolder.
-//
-// It emits ONE JSON event per line and exits in ~35s with BOTH long steps — the dependency
-// install AND the seed — running detached in the background (logs + completion markers
-// reported in the final event), so the caller can build the brand layer while they finish.
-// Steps: scaffold (Wix CLI; requires a logged-in session) → deploy shipped code + deps +
-// lockfile → pin AGENTS.md → start `npm ci || npm install` detached → start the seed detached.
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-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 stack = flag("stack") ?? "astro";
-// Opt-in: leave the project in the current directory (flat) instead of a subfolder.
-const flatten = argv.includes("--flatten");
-// --vertical is REQUIRED: a defaulted vertical deploys the wrong code and runs the wrong
-// seed against the plan — fail loudly with the discovered choices instead.
-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);
-if (!businessName || !planPath || !vertical) {
-  fail("args", `usage: fast-path.mjs --business-name "<Brand>" --plan plan.json --vertical <${knownVerticals.join("|")}> [--stack astro]`);
-}
-if (!knownVerticals.includes(vertical)) {
-  fail("args", `unknown vertical "${vertical}" — shipped verticals: ${knownVerticals.join(", ")}`);
-}
-if (!existsSync(planPath)) fail("args", `plan file not found: ${planPath}`);
-const plan = JSON.parse(readFileSync(planPath, "utf8"));
-
-const folderName =
-  flag("folder-name") ??
-  businessName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
-// `let`: after deploy we flatten the scaffold up into the repo root and repoint
-// projectDir there, so the detached install/seed and every reported path use the
-// final location.
-let projectDir = resolve(process.cwd(), folderName);
-
-// ---- 1 · scaffold -------------------------------------------------------------------------------
-if (existsSync(join(process.cwd(), "wix.config.json"))) {
-  fail("scaffold", "the current directory is already a Wix project — this script is for CREATE runs only; use deploy.mjs + the seed module directly");
-}
-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));
-  }
-}
-const wixConfig = JSON.parse(readFileSync(join(projectDir, "wix.config.json"), "utf8"));
-const siteId = wixConfig.siteId ?? wixConfig.projectId;
-emit("scaffolded", { folder: folderName, siteId });
-
-// ---- 2 · deploy shipped code + deps + lockfile ---------------------------------------------------
-const deploy = spawnSync(
-  "node",
-  [
-    join(SKILL_ROOT, "install", "deploy.mjs"),
-    vertical,
-    "--stack",
-    stack,
-    "--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);
-
-// ---- 2b · record what this project is, for later sessions ---------------------------------------
-const pin = spawnSync(
-  "node",
-  [join(SKILL_ROOT, "install", "pin-agents-md.mjs"), "--vertical", vertical, "--stack", stack],
-  { cwd: projectDir, encoding: "utf8", timeout: 10_000 },
-);
-try { emit("agents_md", JSON.parse(pin.stdout)); } catch { /* never block the build on the note */ }
-
-// ---- 2c · optional --flatten: move the scaffold into the current directory ----------------------
-// OFF by default — the normal output is a self-contained subfolder, unchanged. Opt in when the
-// caller wants the project directly in the current directory (e.g. bootstrapping into an existing
-// repo that must stay one flat tree). 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 —
-// the failure mode when a project is flattened by hand after the background install has started.
-// A pure move: the scaffold was created with --skip-git (above), so there is no nested repo to
-// reconcile — git is whatever the destination already is.
-const targetDir = process.cwd();
-if (flatten && projectDir !== targetDir) {
-  try {
-    for (const entry of readdirSync(projectDir)) {
-      renameSync(join(projectDir, entry), join(targetDir, entry));
-    }
-    rmSync(projectDir, { recursive: true, force: true });
-    projectDir = targetDir;
-    emit("flattened", { into: targetDir });
-  } catch (e) {
-    fail("flatten", e?.stack || e);
-  }
-}
-
-// ---- 3 · start the 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 · start the seed, detached ----------------------------------------------------------------
-// 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.
-const seedDir = join(SKILL_ROOT, "references", vertical, "seed");
-const seedName = existsSync(seedDir)
-  ? readdirSync(seedDir).find((f) => f.startsWith("seed-") && f.endsWith(".mjs"))
-  : undefined;
-const seedFile = seedName ? join(seedDir, seedName) : null;
-if (!seedFile) fail("seed", `no seed module found under ${seedDir}`);
-const seedResultFile = join(projectDir, "seed-result.json");
-const seedLog = join(projectDir, "seed.log");
-const seedDoneMarker = join(projectDir, ".seed-exit");
-const planAbs = resolve(planPath);
-const seedChild = spawn(
-  "sh",
-  // --fresh-site: this script created the site moments ago, so the only products in it are the
-  // Stores install's samples — the seed clears them first (a seed run by hand never deletes).
-  ["-c", `node "${seedFile}" "${planAbs}" --fresh-site > seed-result.json 2> seed.log; echo $? > .seed-exit`],
-  { cwd: projectDir, detached: true, stdio: "ignore" },
-);
-seedChild.unref();
-emit("seeding_started", { vertical, resultFile: seedResultFile, log: seedLog, doneMarker: seedDoneMarker });
-
-// ---- done ----------------------------------------------------------------------------------------
-emit("ready_for_brand_layer", {
-  projectDir,
-  siteId,
-  dashboardUrl: deployResult.dashboardUrl,
-  productsUrl: deployResult.productsUrl,
-  categoriesUrl: deployResult.categoriesUrl,
-  install: { log: installLog, doneMarker: "node_modules/.package-lock.json" },
-  seed: { resultFile: "seed-result.json", log: "seed.log", doneMarker: ".seed-exit", success: "file contains 0" },
-  next: "theme SiteLayout + write the home page; then wait for BOTH done markers, verify .seed-exit is 0 (else read seed.log and re-run the seed module), build, release",
-});

package/skills/wix-headless-fast/install/pin-agents-md.mjs

@@ -1,57 +0,0 @@
-// Record what this project is in its agent instruction files, so a later session — which has
-// none of the build conversation and may never open SKILL.md — still knows the Wix site is the
-// source of truth and which skill answers which kind of question.
-//
-//   node <SKILL_ROOT>/install/pin-agents-md.mjs --vertical <name> [--stack astro]
-//
-// Run from the project root. Kept out of deploy.mjs on purpose: "copy a vertical's files" and
-// "record the project's ground rules" are separate concerns with separate reasons to change.
-// APPENDS to each file — a template's or the user's own content is never overwritten — and is
-// idempotent via the heading sentinel, so re-running fast-path.mjs writes at most once.
-// Project facts that live in the repo (site id, app id) are NOT copied here; they would go
-// stale against wix.config.json, which is the one place that owns them.
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-const argv = process.argv.slice(2);
-const flag = (n, d) => { const i = argv.indexOf(`--${n}`); return i >= 0 ? argv[i + 1] : d; };
-
-const vertical = flag("vertical");
-const stack = flag("stack", "astro");
-// "astro" means the Wix-managed flavour (ambient auth), which is worth naming. Any other stack
-// is echoed as given rather than mapped, so adding one can't silently mislabel the project.
-const frontend = stack === "astro" ? "Wix-managed Astro" : stack.charAt(0).toUpperCase() + stack.slice(1);
-
-const SENTINEL = "## This app — a Wix Headless frontend";
-const note = `
-${SENTINEL}
-
-A ${frontend} frontend for a live Wix site; \`wix.config.json\` identifies the site. Built on
-the **${vertical}** Wix business solution — more can be added to this same app. **The Wix site
-owns the content and commerce** — read and write it through the Wix APIs, never hardcode what
-it holds.
-
-The Wix skills are installed at \`.agents/skills/\` — read them from that exact path:
-
-- **\`wix-headless-fast\`** — the code already deployed in \`src/\` and how to extend it. Every
-  business solution it ships sits under \`references/<solution>/\`: \`INSTRUCTIONS.md\` is that
-  solution's playbook, \`seed/\` creates its content. To add one to this app, run from the
-  project root:
-  \`node .agents/skills/wix-headless-fast/install/deploy.mjs <solution> --stack ${stack}\`
-- **\`wix-docs\`** — the Wix API reference. Confirm any endpoint, request shape, field, or enum
-  here before writing code against it, frontend or backend. Never infer a contract from
-  generated SDK types or \`node_modules\`.
-- **\`wix-manage\`** — recipes for managing the live site itself, as opposed to changing this
-  codebase. No recipe for the task? Fall back to \`wix-docs\`.
-`;
-
-// Both files, independently — a project may have either, both, or neither, and agents differ
-// in which one they read.
-const pinned = ["AGENTS.md", "CLAUDE.md"].map((name) => {
-  const file = join(process.cwd(), name);
-  const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
-  const wrote = !existing.includes(SENTINEL);
-  if (wrote) appendFileSync(file, (existing && !existing.endsWith("\n") ? "\n" : "") + note);
-  return { file: name, wrote, created: wrote && !existing };
-});
-console.log(JSON.stringify({ event: "agents_md", pinned }));