@wix/agent-skills 1.20.1 → 1.21.0

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

@@ -0,0 +1,20 @@
+// What the CMS holds: collections, their fields, item counts, a few sample items each.
+//   node <SKILL_ROOT>/references/cms/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/cms";
+
+await runReader({
+  vertical: "cms",
+  async read(api, { limit }) {
+    const r = await api.call({ method: "GET", path: "/wix-data/v2/collections", docs: `${D}/collection-management/data-collections/list-data-collections` });
+    const all = r.collections ?? r.dataCollections ?? [];
+    const own = all.filter((c) => c.collectionType !== "WIX_APP");
+    const collections = [];
+    for (const c of own.slice(0, limit)) {
+      const items = await api.tryCall({ path: "/wix-data/v2/items/query", body: { dataCollectionId: c.id, query: { paging: { limit: 3 } }, returnTotalCount: true }, docs: `${D}/data-items/query-data-items` });
+      collections.push({ id: c.id, displayName: c.displayName, fields: (c.fields ?? []).map((f) => `${f.key}:${f.type}`), itemCount: items?.pagingMetadata?.total ?? null, sample: (items?.dataItems ?? []).map((i) => i.data?.title ?? i.data?.name ?? i.id) });
+    }
+    return { collectionCount: own.length, collections, appCollections: all.filter((c) => c.collectionType === "WIX_APP").map((c) => c.id) };
+  },
+});

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

@@ -260,6 +260,8 @@ plugins — deploy already added the dep). Routes: `/events` → your listing; `
 callbacks point at that path). 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
 
 - **Registration logic only through the shipped exports** — `useEventRegistration` /

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

@@ -0,0 +1,26 @@
+// What the events site holds: events and their ticket definitions.
+//   node <SKILL_ROOT>/references/events/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/events/event-management";
+
+await runReader({
+  vertical: "events",
+  appId: EVENTS_APP_ID,
+  async read(api, { limit }) {
+    const ev = await api.call({ path: "/events/v3/events/query", body: { query: { filter: { status: { $ne: "CANCELED" } }, paging: { limit } }, fields: ["DETAILS", "REGISTRATION"] }, docs: `${D}/events-v3/query-events` });
+    const td = await api.tryCall({ path: "/events-ticket-definitions/v3/ticket-definitions/query", body: { query: { paging: { limit: 100 } } }, docs: `${D}/ticket-definitions-v3/query-ticket-definitions` });
+    const defs = td?.ticketDefinitions ?? [];
+    return {
+      eventCount: ev.pagingMetadata?.total ?? (ev.events ?? []).length,
+      events: (ev.events ?? []).map((e) => ({
+        title: e.title, slug: e.slug, status: e.status, start: e.dateAndTimeSettings?.startDate ?? null,
+        location: e.location?.name ?? e.location?.type ?? null, registration: e.registration?.type ?? null,
+        tickets: defs.filter((d) => d.eventId === e.id).map((d) => `${d.name}${d.pricingMethod?.fixedPrice?.formattedValue ? " " + d.pricingMethod.fixedPrice.formattedValue : ""}`),
+        image: !!e.mainImage,
+      })),
+      ticketDefinitionCount: defs.length,
+    };
+  },
+});

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

@@ -285,6 +285,8 @@ plugins — deploy already added the dep). `useWixForm(FORM_ID)` with no `initia
 skeleton while `form` is null. 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
 
 - **Never name a field in code.** Map `form.fields`. A page with `values.email` hardcoded

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

@@ -0,0 +1,20 @@
+// What forms the site has, with their fields.
+//   node <SKILL_ROOT>/references/forms/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const FORMS_APP_ID = "225dd912-7dea-4738-8688-4b8c6955ffc2";
+const NAMESPACE = "wix.form_app.form";
+const D = "https://dev.wix.com/docs/api-reference/crm/forms/form-schemas";
+
+await runReader({
+  vertical: "forms",
+  appId: FORMS_APP_ID,
+  async read(api, { limit }) {
+    const r = await api.call({ method: "GET", path: `/form-schema-service/v4/forms?namespace=${encodeURIComponent(NAMESPACE)}`, docs: `${D}/list-forms` });
+    const forms = (r.forms ?? []).slice(0, limit);
+    return {
+      formCount: (r.forms ?? []).length,
+      forms: forms.map((f) => ({ id: f.id, name: f.name, fields: (f.fields ?? []).filter((x) => !x.hidden).map((x) => `${x.view?.label ?? x.target ?? x.id} (${x.view?.fieldType ?? "?"})${x.validation?.required ? "*" : ""}`), steps: (f.steps ?? []).length })),
+    };
+  },
+});

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

@@ -271,6 +271,8 @@ Mount `MemberMenu` in the header (pass `LinkComponent` for router links). Deploy
 client id into `wix/config.ts` (`WIX_CLIENT_ID` and `WIX_MEMBERS_CLIENT_ID`); 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
 
 - **No Wix-hosted login flow** — no `/api/auth/login`, no OAuth callback page, no callback URI for

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

@@ -0,0 +1,15 @@
+// Whether the site has a members area, and how many members.
+//   node <SKILL_ROOT>/references/members/seed/read-site.mjs [--site <siteId>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const MEMBERS_AREA_APP_ID = "14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9";
+const D = "https://dev.wix.com/docs/api-reference/crm/members-contacts/members/members";
+
+await runReader({
+  vertical: "members",
+  appId: MEMBERS_AREA_APP_ID,
+  async read(api) {
+    const r = await api.call({ method: "GET", path: "/members/v1/members?fieldsets=PUBLIC&paging.limit=1", docs: `${D}/list-members` });
+    return { memberCount: r.metadata?.total ?? r.pagingMetadata?.total ?? null };
+  },
+});

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

@@ -280,6 +280,8 @@ deploy added the dep). Routes: `/portfolio` → your gallery on `useCollections(
 `useProjectDetail(slug)` (the hooks fetch client-side when no `initial*` is passed; route the 404
 view off `notFound`). 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
 
 - **Reads only through the shipped exports** — they filter `hidden`, sort collections by the

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

@@ -0,0 +1,20 @@
+// What the portfolio holds: collections and projects.
+//   node <SKILL_ROOT>/references/portfolio/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const PORTFOLIO_APP_ID = "d90652a2-f5a1-4c7c-84c4-d4cdcc41f130";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/portfolio";
+
+await runReader({
+  vertical: "portfolio",
+  appId: PORTFOLIO_APP_ID,
+  async read(api, { limit }) {
+    const cols = await api.call({ method: "GET", path: "/portfolio/v1/collections", docs: `${D}/collections/list-collections` });
+    const projs = await api.tryCall({ method: "GET", path: "/portfolio/v1/projects", docs: `${D}/projects/list-projects` });
+    return {
+      collections: (cols.collections ?? []).map((c) => ({ id: c.id, title: c.title, slug: c.slug, hidden: c.hidden ?? false, cover: !!c.coverImage })),
+      projectCount: (projs?.projects ?? []).length,
+      projects: (projs?.projects ?? []).slice(0, limit).map((p) => ({ title: p.title, slug: p.slug, hidden: p.hidden ?? false, collections: (p.collectionIds ?? []).length, cover: !!p.coverImage })),
+    };
+  },
+});

package/skills/wix-headless-fast/references/portfolio/seed/seed-portfolio.mjs

@@ -125,22 +125,25 @@ export { importImage } from "../../shared/seed/images.mjs";
 // Cover = the listing-card thumbnail. PATCH per entity, echoing the current revision (missing/
 // stale revision fails); height + width are required alongside the imported file id.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/update-project.md
-export async function attachProjectCovers(ctx, items) {
+// One PATCH per entity; a failure on one must not cost the rest theirs. Returns
+// { attached: [id], failures: [{ id, error }] } — the caller counts what persisted, not what was sent.
+async function attachEach(ctx, items, urlOf, bodyOf) {
+  const attached = [];
+  const failures = [];
   for (const it of items) {
-    await req(ctx, `/portfolio/v1/projects/${it.id}`, {
-      method: "PATCH",
-      body: { project: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } },
-    });
+    try { await req(ctx, urlOf(it), { method: "PATCH", body: bodyOf(it) }); attached.push(it.id); }
+    catch (e) { failures.push({ id: it.id, error: e?.message ?? String(e) }); }
   }
+  return { attached, failures };
+}
+export async function attachProjectCovers(ctx, items) {
+  return attachEach(ctx, items, (it) => `/portfolio/v1/projects/${it.id}`,
+    (it) => ({ project: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } }));
 }
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/update-collection.md
 export async function attachCollectionCovers(ctx, items) {
-  for (const it of items) {
-    await req(ctx, `/portfolio/v1/collections/${it.id}`, {
-      method: "PATCH",
-      body: { collection: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } },
-    });
-  }
+  return attachEach(ctx, items, (it) => `/portfolio/v1/collections/${it.id}`,
+    (it) => ({ collection: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } }));
 }
 
 // The detail-page gallery is a SEPARATE `item` entity — one POST per image; sortOrder (1,2,3…)
@@ -218,23 +221,18 @@ export async function setupPortfolio(ctx, { collections = [], projects = [] } =
       ? { id: c.id, revision: c.revision, imageId: files[colCoverAt + i].id, ...dims }
       : null))
     .filter(Boolean);
+  // coversAttached counts the PATCHes that succeeded; coverFailures names the rest. Neither blocks the seed.
   let coversAttached = 0;
-  try {
-    if (projCovers.length) { await attachProjectCovers(ctx, projCovers); coversAttached += projCovers.length; }
-  } catch {
-    /* those projects stay cover-less */
-  }
-  try {
-    if (colCovers.length) { await attachCollectionCovers(ctx, colCovers); coversAttached += colCovers.length; }
-  } catch {
-    /* those collections stay cover-less */
-  }
+  const coverFailures = [];
+  if (projCovers.length) { const r = await attachProjectCovers(ctx, projCovers); coversAttached += r.attached.length; coverFailures.push(...r.failures.map((f) => ({ project: f.id, error: f.error }))); }
+  if (colCovers.length) { const r = await attachCollectionCovers(ctx, colCovers); coversAttached += r.attached.length; coverFailures.push(...r.failures.map((f) => ({ collection: f.id, error: f.error }))); }
 
   return {
     collections: cols,
     projects: projs,
     itemsCreated: items.length,
     coversAttached,
+    coverFailures,
   };
 }
 

package/skills/wix-headless-fast/references/pricing-plans/INSTRUCTIONS.md

@@ -238,6 +238,8 @@ when no `initialPlans` is passed); `/plans/:slug` → fetch with `fetchPlanBySlu
 client-side, then your detail surface (null → your not-found state). 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
 
 - **Purchase only through the shipped exports** — `SubscribeButton` / `usePlanPurchase` /

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

@@ -0,0 +1,21 @@
+// What the site sells as plans: public pricing plans.
+//   node <SKILL_ROOT>/references/pricing-plans/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const PRICING_PLANS_APP_ID = "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans";
+
+await runReader({
+  vertical: "pricing-plans",
+  appId: PRICING_PLANS_APP_ID,
+  async read(api, { limit }) {
+    const r = await api.call({ path: "/pricing-plans/v3/plans/query", body: { query: { filter: { visibility: "PUBLIC" }, cursorPaging: { limit } } }, docs: `${D}/plans-v3/query-plans` });
+    return {
+      planCount: r.pagingMetadata?.total ?? (r.plans ?? []).length,
+      plans: (r.plans ?? []).map((p) => {
+        const v = p.pricingVariants?.[0]; const s = v?.pricingStrategies?.[0];
+        return { name: p.name, slug: p.slug ?? null, visibility: p.visibility, price: s?.flatRate?.amount ?? null, currency: p.currency ?? null, billing: v?.billingTerms?.billingCycle ? `${v.billingTerms.billingCycle.count} ${v.billingTerms.billingCycle.period}` : (v?.billingTerms?.startType ?? null), perks: (p.perks?.values ?? []).length };
+      }),
+    };
+  },
+});

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

@@ -298,6 +298,8 @@ client-side when no `initialMenus`); `/reservations` → your reservation surfac
 order button in the header and your drawer once. 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 and ordering logic only through the shipped exports** — `useOrderCart`/`addToOrder`

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

@@ -0,0 +1,25 @@
+// What the restaurant holds: menus, sections, items, locations.
+//   node <SKILL_ROOT>/references/restaurants/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const MENUS_APP_ID = "b278a256-2757-4f19-9313-c05c783bec92";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus";
+const DL = "https://dev.wix.com/docs/api-reference/business-management/locations";
+
+await runReader({
+  vertical: "restaurants",
+  appId: MENUS_APP_ID,
+  async read(api, { limit }) {
+    const menus = await api.call({ method: "GET", path: "/restaurants/menus/v1/menus", docs: `${D}/menus/list-menus` });
+    const sections = await api.tryCall({ method: "GET", path: "/restaurants/menus/v1/sections", docs: `${D}/sections/list-sections` });
+    const items = await api.tryCall({ method: "GET", path: "/restaurants/menus/v1/items", docs: `${D}/items/items/list-items` });
+    const locs = await api.tryCall({ method: "GET", path: "/locations/v1/locations", docs: `${DL}/list-locations` });
+    const secs = sections?.sections ?? []; const its = items?.items ?? [];
+    return {
+      menus: (menus.menus ?? []).map((m) => ({ name: m.name, visible: m.visible !== false, sections: (m.sectionIds ?? []).map((id) => secs.find((s) => s.id === id)?.name ?? id) })),
+      sectionCount: secs.length, itemCount: its.length,
+      items: its.slice(0, limit).map((i) => ({ name: i.name, price: i.priceInfo?.price ?? i.priceVariants ? "variants" : null, image: !!i.image, labels: (i.labels ?? []).length })),
+      locations: (locs?.locations ?? []).map((l) => ({ name: l.name, default: !!l.default, address: l.address?.formattedAddress ?? null })),
+    };
+  },
+});

package/skills/wix-headless-fast/references/restaurants/seed/seed-restaurants.mjs

@@ -207,8 +207,10 @@ export { importImage } from "../../shared/seed/images.mjs";
 // the binding field is the Wix Media file `id`.
 // items: [{ id, revision, price, image: { id, url, height, width } }]
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/bulk-update-item.md
+// The bulk update returns 200 on PARTIAL failure: each item's outcome is in
+// results[].itemMetadata (success, error, originalIndex). Returns { attached: [id], failures: [{ id, error }] }.
 export async function attachItemImages(ctx, items) {
-  return req(ctx, "/restaurants/menus/v1/bulk/items/update", {
+  const r = await req(ctx, "/restaurants/menus/v1/bulk/items/update", {
     body: {
       items: items.map((it) => ({
         item: {
@@ -220,6 +222,21 @@ export async function attachItemImages(ctx, items) {
       })),
     },
   });
+  return bulkOutcome(items, r.results);
+}
+
+// Pair a bulk response's results[] to the inputs by originalIndex; an input with no result did not persist.
+export function bulkOutcome(items, results) {
+  const attached = [];
+  const failures = [];
+  for (const x of results ?? []) {
+    const src = items[x.itemMetadata?.originalIndex];
+    if (!src) continue;
+    if (x.itemMetadata?.success) attached.push(src.id);
+    else failures.push({ id: src.id, error: x.itemMetadata?.error?.description ?? x.itemMetadata?.error?.code ?? "unknown" });
+  }
+  for (const it of items) if (!attached.includes(it.id) && !failures.some((f) => f.id === it.id)) failures.push({ id: it.id, error: "no result for item" });
+  return { attached, failures };
 }
 
 // ---- business location (shared STEP 0 for ordering + reservations) ------------------------------
@@ -383,12 +400,14 @@ export async function setupRestaurants(ctx, plan) {
           image: { id: files[i].id, url: files[i].url, width: 1024, height: 1024 } }
       : null))
     .filter(Boolean);
+  const imageFailures = [];
   if (toAttach.length) {
     try {
-      await attachItemImages(ctx, toAttach);
-      imagesAttached = toAttach.length;
-    } catch {
-      /* the items stay text-only */
+      const r = await attachItemImages(ctx, toAttach);
+      imagesAttached = r.attached.length;
+      for (const f of r.failures) imageFailures.push(f);
+    } catch (e) {
+      for (const it of toAttach) imageFailures.push({ id: it.id, error: e?.message ?? String(e) });
     }
   }
 
@@ -453,6 +472,7 @@ export async function setupRestaurants(ctx, plan) {
   return {
     menus: createdMenus.map(({ items, ...m }) => m),
     imagesAttached,
+    imageFailures,
     sampleMenuRemoved,
     ordering,
     reservations,

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

@@ -0,0 +1,99 @@
+// The shared runner behind every vertical's `seed/read-site.mjs` — the build-time read of what a
+// site holds, so the agent sizes the content without composing a single Wix request.
+//
+//   node <SKILL_ROOT>/references/<vertical>/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+//
+// The site is `--site`, else the `siteId` in ./wix.config.json. The token is minted by the Wix CLI
+// inside this process and never written anywhere. Output is ONE JSON object on stdout:
+//   { vertical, siteId, installed, ...what the vertical reads..., calls: [{ method, path, status, docs }] }
+// `calls` lists every request made, with the method's documentation URL — open one of those (the
+// URL plus `.md` is the full page) when the brief needs more than the summary shows. A failed call
+// is reported in `calls` with its status and message; the reader continues and marks the field null.
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+
+const API = "https://www.wixapis.com";
+const DOCS_INSTALLED_APPS = "https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps";
+
+function flag(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--") ? process.argv[i + 1] : null;
+}
+
+export function siteIdFromArgsOrConfig() {
+  const fromFlag = flag("site");
+  if (fromFlag) return fromFlag;
+  if (existsSync("wix.config.json")) {
+    const c = JSON.parse(readFileSync("wix.config.json", "utf8"));
+    return c.siteId ?? c.projectId ?? null;
+  }
+  return null;
+}
+
+export function makeApi(siteId) {
+  const token = execFileSync("npx", ["-y", "@wix/cli@latest", "token", "--site", siteId], { encoding: "utf8" }).trim();
+  if (!token) throw new Error("the Wix CLI returned no token — run `npx @wix/cli@latest login` first");
+  const calls = [];
+  async function call({ method = "POST", path, body, docs }) {
+    const entry = { method, path: path.split("?")[0], docs };
+    calls.push(entry);
+    const res = await fetch(API + path, {
+      method,
+      headers: { Authorization: token, "wix-site-id": siteId, "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    entry.status = res.status;
+    if (!res.ok) {
+      entry.error = text.slice(0, 200) || "(empty body)";
+      const e = new Error(`${method} ${entry.path} → ${res.status}: ${entry.error}`);
+      e.status = res.status;
+      throw e;
+    }
+    try { return text ? JSON.parse(text) : {}; } catch { return {}; }
+  }
+  // Same call, but a failure becomes null and stays in `calls` — for reads whose absence is data.
+  async function tryCall(opts) {
+    try { return await call(opts); } catch { return null; }
+  }
+  async function installed(appId) {
+    const r = await tryCall({ method: "GET", path: "/apps-installer-service/v1/app-instances", docs: DOCS_INSTALLED_APPS });
+    if (!r) return null;
+    return (r.appInstances ?? []).some((a) => a.appDefId === appId || a.appId === appId);
+  }
+  return { call, tryCall, installed, calls };
+}
+
+export const limit = () => Number(flag("limit") ?? 12);
+
+// read(api, { limit }) returns the vertical's summary; the runner adds the envelope and prints.
+export async function runReader({ vertical, appId, read }) {
+  const siteId = siteIdFromArgsOrConfig();
+  if (!siteId) {
+    console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
+    process.exit(1);
+  }
+  const api = makeApi(siteId);
+  const out = { vertical, siteId, scope: null };
+  out.installed = appId ? await api.installed(appId) : undefined;
+  let data = {};
+  if (out.installed === false) {
+    out.scope = `${vertical}: the app is not installed on this site — nothing to read; the vertical's seed installs it`;
+  } else {
+    try { data = await read(api, { limit: limit() }); }
+    catch (e) { out.error = String(e.message).slice(0, 300); }
+  }
+  // What this output is and is not: a SIZING. Every list is a sample page; the counts are the site.
+  const partial = Object.entries(data)
+    .filter(([k, v]) => Array.isArray(v) && typeof data[`${k.replace(/s$/, "")}Count`] === "number" && data[`${k.replace(/s$/, "")}Count`] > v.length)
+    .map(([k, v]) => `${k}: ${v.length} of ${data[`${k.replace(/s$/, "")}Count`]} shown`);
+  if (!out.scope) {
+    out.scope = "A sizing, not the content. Lists are one page (--limit, max 100); counts are the whole site. " +
+      (partial.length ? `Partial here: ${partial.join("; ")}. ` : "") +
+      "The pages read everything live through the deployed data layer. To read more or filter, page the same call: its method and documentation URL are in `calls`.";
+  }
+  Object.assign(out, data);
+  out.calls = api.calls;
+  out.docs = [...new Set(api.calls.map((c) => c.docs).filter(Boolean))];
+  console.log(JSON.stringify(out, null, 2));
+}

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

@@ -404,6 +404,8 @@ export default function ProductDetailView(props: {
   //       to full-width images stacked down the column (products with per-color
   //       linked media carry several gallery urls, so that stacks big duplicates).
   //       A single-image gallery is just the one primary — no empty strip.
+  //       When d.variant resolves and carries imageUrl, that image becomes the primary (it is
+  //       one of the gallery urls) — a shopper who picks a color sees that color.
   //     • name, EVERY ribbon (d.product.ribbons), live d.price (the range until every option
   //       is picked) with d.compareAtPrice as a labelled "was" when present — never invent one;
   //       descriptionHtml rendered as HTML, then d.product.infoSections as sections/accordions
@@ -546,6 +548,8 @@ client-side when no `initial` is passed).
 Mount the shipped `CartButton` in the header and `CartDrawer` once. 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 and commerce logic only through the shipped exports** — never rewrite their

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/catalog-core.ts

@@ -232,7 +232,10 @@ export function toModifiers(raw: Raw): ProductModifier[] {
 }
 
 /** Variants keyed by optionName → choiceName. Buyable when in stock OR pre-orderable. */
-export function toVariants(raw: Raw): ProductVariant[] {
+// `variant.media` is read-only on the API: Wix derives it from the media linked to the variant's
+// choice (a product with several options derives it only when the choices agree). Mapped to a
+// URL so a PDP can show the selected variant's picture without knowing how Wix derives it.
+export function toVariants(raw: Raw, imgSrc: ImgSrc): ProductVariant[] {
   return ((raw.variantsInfo?.variants ?? []) as Raw[])
     .filter((v) => v.visible !== false)
     .map((v) => {
@@ -242,6 +245,7 @@ export function toVariants(raw: Raw): ProductVariant[] {
         if (on && cn) choices[on] = cn;
       }
       const { current, original } = sellingPrice(v.price);
+      const vm = v.media ? (v.media.image ?? v.media) : null;
       return {
         variantId: id(v),
         choices,
@@ -249,6 +253,7 @@ export function toVariants(raw: Raw): ProductVariant[] {
         compareAtPrice: strike(original, current),
         inStock: v.inventoryStatus?.inStock !== false,
         preorderEnabled: v.inventoryStatus?.preorderEnabled === true,
+        imageUrl: vm ? imgSrc(vm, 1200, 1200) || null : null,
       };
     });
 }
@@ -264,7 +269,7 @@ export function toDetail(raw: Raw, imgSrc: ImgSrc, mediaKey: MediaKey): ProductD
     gallery: mediaEntries(raw, mediaKey).map((m) => imgSrc(m, 1200, 1200)).filter(Boolean),
     options: toOptions(raw),
     modifiers: toModifiers(raw),
-    variants: toVariants(raw),
+    variants: toVariants(raw, imgSrc),
   };
 }
 

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/types.ts

@@ -82,6 +82,8 @@ export interface ProductVariant {
   inStock: boolean;
   /** Out of stock but pre-orderable — still buyable (the add carries preOrderRequested). */
   preorderEnabled: boolean;
+  /** This variant's own image (from its choice's linked media), resolved to an https URL; null when it has none. */
+  imageUrl: string | null;
 }
 
 /** A product as the detail page needs it. */

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

@@ -17,7 +17,7 @@ node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
 
 Run this way, the result is the process itself: exit code `0` and the JSON on stdout (redirect it
 to a file if you want it later). `.seed-exit` and `seed-result.json` are written by
-`install/fast-path.mjs` when IT starts the seed — don't wait for them after a manual run.
+`install/setup.mjs` when IT starts the seed — don't wait for them after a manual run.
 
 `plan.json` is plain data — write it from the brief:
 
@@ -97,6 +97,12 @@ own sample products to a new catalog; they stay, and the owner removes them in t
 (the Manage products link is in your summary). If a cleanup genuinely seems needed, ask the user
 first. Categories are idempotent by name — a re-run reuses "Donuts" instead of creating a second one.
 
+**Images are confirmed, not assumed.** `imagesAttached` counts the attaches the API reported as
+successful; `imageFailures: [{ name, error }]` names the products left without an image and why
+(one miss out of three was seen live — a revision moved between read and update). The seed already
+retries a miss once. To retry again, re-run the same plan: existing products are reused and their
+images attached; nothing is duplicated.
+
 **A bulk create can partially succeed.** The result carries `failures: [{ name, error }]` next
 to `products` — read it. A non-empty `failures` means those products are genuinely absent, not
 mis-mapped, so the rest of the catalog is fine to build on. To retry, re-run the **same** plan:

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

@@ -0,0 +1,38 @@
+// What the store holds: products (names, prices, options, media, stock), categories. Run it before
+// designing a storefront for a site that already has content:
+//   node <SKILL_ROOT>/references/storefront/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+// Every request here is the one the deployed data layer makes (rest/catalog.ts); the doc URL of
+// each method is in the output's `calls`.
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3";
+const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"];
+const VISIBLE = { $and: [{ visible: true }] };
+const TREE = { appNamespace: "@wix/stores", treeKey: null };
+
+await runReader({
+  vertical: "storefront",
+  appId: STORES_APP_ID,
+  async read(api, { limit }) {
+    const count = await api.tryCall({ path: "/stores/v3/products/count", body: { filter: VISIBLE }, docs: `${D}/products-v3/count-products` });
+    const search = await api.call({ path: "/stores/v3/products/search", body: { fields: LIST_FIELDS, search: { filter: VISIBLE, cursorPaging: { limit } } }, docs: `${D}/products-v3/search-products` });
+    const cats = await api.tryCall({ path: "/categories/v1/categories/query", body: { treeReference: TREE, query: { filter: { name: { $exists: true } }, cursorPaging: { limit: 100 } } }, docs: `${D}/categories/query-categories` });
+    const products = (search.products ?? []).map((p) => ({
+      name: p.name, slug: p.slug,
+      price: p.actualPriceRange?.minValue?.formattedAmount ?? null,
+      priceMax: p.actualPriceRange?.maxValue?.formattedAmount ?? null,
+      compareAt: p.compareAtPriceRange?.minValue?.formattedAmount ?? null,
+      options: (p.options ?? []).map((o) => `${o.name} (${o.choicesSettings?.choices?.length ?? 0})`),
+      media: p.media?.itemsInfo?.items?.length ?? 0,
+      availability: p.inventory?.availabilityStatus ?? null,
+    }));
+    return {
+      currency: search.products?.[0]?.currency ?? null,
+      productCount: typeof count?.count === "number" ? count.count : null,
+      products,
+      productsShown: products.length,
+      categories: (cats?.categories ?? []).filter((c) => c.slug !== "all-products").map((c) => ({ id: c.id, name: c.name, slug: c.slug, visible: c.visible !== false })),
+    };
+  },
+});