@wix/agent-skills 1.20.0 → 1.20.1

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) {
@@ -462,22 +445,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
@@ -529,23 +502,21 @@ export async function setupStore(ctx, { products = [], categories = {}, currency
   // 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, 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-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/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 }));