@wix/agent-skills 1.30.0 → 1.31.1

package/skills/wix-headless-kit/install/AGENTS.md

@@ -20,12 +20,14 @@ call is memory, and an empty or error reply to it says nothing about the site.
 Installed at `.agents/skills/` (by the Wix plugin, or by
 `npx skills add wix/skills --skill {{SKILL}} --skill wix-docs --skill wix-manage`).
 
-- `{{SKILL}}` — the code in this app and how to extend it. The shipped code sits in
+- `{{SKILL}}` — the code in this app and how to extend it. The shipped code is the
+  `wix-headless-templates` skill: `node .agents/skills/{{SKILL}}/install/templates.mjs` prints where it
+  is (`.agents/skills/wix-headless-templates/` when installed beside this skill, else
   `.agents/skills/{{SKILL}}/templates/`, fetched once from the skill's repository and kept with this
-  project at the commit it was built from (`templates/.source`); if that folder is missing,
-  `node .agents/skills/{{SKILL}}/install/templates.mjs` fetches it. Each business solution has a playbook at
-  `templates/<solution>/INSTRUCTIONS.md`; `node .agents/skills/{{SKILL}}/install/deploy.mjs <solution> --stack {{STACK}}`
-  adds one; `node .agents/skills/{{SKILL}}/templates/<solution>/seed/read-site.mjs` reads what the
+  project at the commit it was built from, `templates/.source`) and fetches it when neither exists;
+  `<templates>` below is that folder. Each business solution has a playbook at
+  `<templates>/<solution>/INSTRUCTIONS.md`; `node .agents/skills/{{SKILL}}/install/deploy.mjs <solution> --stack {{STACK}}`
+  adds one; `node <templates>/<solution>/seed/read-site.mjs` reads what the
   site holds for it, with the documentation URL of every call it made. A code change ends with a release; the live URL shows it, the dev server does not count.
   `node .agents/skills/{{SKILL}}/install/check.mjs` says whether the skill or its templates have a newer
   version and prints the update commands; an update touches the skill folder or `templates/`, never `src/`.

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

@@ -304,7 +304,7 @@ emit("agent_configs", writeAgentsMd(projectDir, { skill: basename(SKILL_ROOT), s
 if (mode !== "link" && (stack !== "astro" || mode === "config-only")) {
   emit("ready", { projectDir, siteId, appId, baseUrl, hosting, frontend, stack, dashboardUrl: `https://manage.wix.com/dashboard/${siteId}`,
     next: `scaffold the ${stack} project in this folder per SKILL.md, then deploy.mjs <vertical…> --stack ${stack}${planPath ? ` --plan ${planPath}` : ""} (the client id is read from wix.config.json); ` +
-      (planPath ? `then seed with the plan: node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs ${planPath}` : `no plan given, so nothing seeds — the site owns its content`) +
+      (planPath ? `then seed with the plan: node ${join(TEMPLATES, verticals[0], "seed", `seed-${verticals[0]}.mjs`)} ${planPath}` : `no plan given, so nothing seeds — the site owns its content`) +
       (hosting === "self" ? `; you host it: origins on the OAuth app allow-list now: ${origins.join(", ") || "none — add them before the first checkout test"}` : "") });
   process.exit(0);
 }
@@ -349,10 +349,10 @@ if (planPath) {
   emit("seeding_started", { vertical: verticals[0], ...seed, ...(verticals.length > 1 ? { note: `the plan seeds ${verticals[0]}; the other verticals' seeds run afterwards, each with its own plan` } : {}) });
 } else {
   if (siteOrigin === "init") {
-    emit("note", { step: "seed", detail: `this site was made for this run (init) and is empty: draft a plan per templates/${verticals[0]}/seed/SEED.md — the brief's content, else demo content — and run node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs plan.json from the project root` });
+    emit("note", { step: "seed", detail: `this site was made for this run (init) and is empty: draft a plan per ${join(TEMPLATES, verticals[0], "seed", "SEED.md")} — the brief's content, else demo content — and run node <SKILL_ROOT>/templates/${verticals[0]}/seed/seed-<vertical>.mjs plan.json from the project root` });
   }
   if (verticals.includes("members")) {
-    emit("note", { step: "seed", detail: "members: the Members Area app (the profile layer, no content) is installed by templates/members/seed/seed-members.mjs — run it unless the site already has the app" });
+    emit("note", { step: "seed", detail: `members: the Members Area app (the profile layer, no content) is installed by ${join(TEMPLATES, "members", "seed", "seed-members.mjs")} — run it unless the site already has the app` });
   }
 }
 

package/skills/wix-headless-kit/install/context.mjs

@@ -78,7 +78,9 @@ export function pullEnv(cwd) {
 /**
  * Whether a frontend exists in this folder: a `package.json` (a bundled project), an `index.html` at
  * the root (plain pages), or an `index.html` inside the folder the config's `site.outputDirectory`
- * names (a static site laid out for release, pages under site/). Nothing else counts — not this
+ * names (a static site laid out for release, pages under site/). `publicIndex` and `astroPages` tell
+ * a dropped site on its Wix Dev Machine apart from an Astro project: the machine copies the drop's
+ * pages into public/ of an Astro starter that has no src/pages/. Nothing else counts — not this
  * skill's code, not the skills folder, not AGENTS.md: those say who ran here, not what is here.
  */
 export function frontendPresent(cwd = process.cwd()) {
@@ -89,13 +91,16 @@ export function frontendPresent(cwd = process.cwd()) {
     rootIndex: has("index.html"),
     outputIndex: !!outDir && outDir !== "." && has(join(outDir, "index.html")),
     outputDirectory: outDir || null,
+    publicIndex: has(join("public", "index.html")),
+    astroPages: has(join("src", "pages")),
   };
 }
 
 /**
- * What the folder IS, from five file facts — the one classification every script and SKILL.md
+ * What the folder IS, from a few file facts — the one classification every script and SKILL.md
  * step 3 share: wix.config.json, its site.outputDirectory, the migration variables in .env.local,
- * package.json, index.html. `migrationActive` comes from siteContext (it needs `.env.local`).
+ * package.json, index.html (at the root or in public/), src/pages/. `migrationActive` comes from
+ * siteContext (it needs `.env.local`).
  *
  *   empty             nothing that reads as a project → setup CREATE: the run makes the site, seeds the plan
  *   project           a frontend, no wix.config.json → setup ADOPT: `init` gives it a new, empty site, seeds the plan
@@ -103,6 +108,9 @@ export function frontendPresent(cwd = process.cwd()) {
  *   migration         a config whose .env.local declares an ACTIVE editor migration, with or without the blank
  *                     Astro starter the download carries → setup MIGRATE; nothing seeded. Decided before the
  *                     frontend test: the starter's package.json must not read as a project to iterate on
+ *   static-in-astro   a config, a package.json, public/index.html and no src/pages/ (a site published
+ *                     through the drop flow, on its Wix Dev Machine) → the pages stay plain files in
+ *                     public/; the static REST layer deploys beside them; build and release
  *   wix-project       a config AND a frontend (package.json, or index.html in the output folder) → iterate:
  *                     never scaffold, init or reseed; deploy.mjs adds a solution, edits, release
  *   published-static  a config, index.html at the ROOT, no package.json, no laid-out output folder (a site
@@ -117,12 +125,14 @@ export function folderShape(cwd = process.cwd(), { migrationActive = false } = {
     project: "setup.mjs --vertical <v> --stack <stack> [--plan]: init links the folder to a new, empty site, seeds the plan and deploys (ADOPT)",
     "config-only": "attach.mjs: the site exists and has no frontend yet; read what it holds (the vertical's read-site.mjs) — nothing is seeded; the vertical's seed module with a plan only when the brief supplies or describes content",
     migration: "setup.mjs (MIGRATE): the shipped code into the starter the download carries (or the composed template around a bare config); the site being migrated owns its content — guides/migration.md",
+    "static-in-astro": "a dropped site on its Dev Machine: the pages are plain files in public/, served as they are. deploy.mjs <vertical…> --stack static --out public puts the REST layer in public/js/wix/; wire the pages in place with <script type=\"module\">: do the least that makes them work: connect each control the pages show and add only what a control can't work without (more only when the brief asks), and no Astro pages. Read the site (read-site.mjs); run the vertical's seed module with a plan only for content the brief supplies or describes. Release with npx @wix/cli@latest build && npx @wix/cli@latest release; the URL stays",
     "wix-project": "iterate: never scaffold, init or reseed. deploy.mjs <vertical…> --stack <stack> adds a solution, then ONE npm install; file edits for a change; release. Read the site (read-site.mjs) before any seed module runs",
     "published-static": "setup.mjs --vertical <v>: the config's site, no init; site/ becomes the upload and the REST layer lands in site/js/wix/; move the pages, styles and assets into site/. Nothing is seeded: read the site, then run the vertical's seed module with a plan when the brief gives content; release keeps the URL",
   };
   let shape;
   if (!config) shape = f.packageJson || f.rootIndex ? "project" : "empty";
   else if (migrationActive) shape = "migration";
+  else if (f.packageJson && f.publicIndex && !f.astroPages) shape = "static-in-astro";
   else if (f.packageJson || f.outputIndex) shape = "wix-project";
   else if (f.rootIndex) shape = "published-static";
   else shape = "config-only";

package/skills/wix-headless-kit/install/deploy.mjs

@@ -18,8 +18,8 @@
 //                  <out>/js/wix/ — shared/rest/ (client, media, config) + each vertical's rest/ + the
 //                  vertical's transport-agnostic core files (types, *-core) from its app/ — writes
 //                  the client id, and strips it to browser-ready ESM with tsc (comments kept, the
-//                  .ts sources kept beside the .js). No package.json is touched. Storefront only
-//                  until other verticals ship a rest/. `--out <dir>` (default: the project root)
+//                  .ts sources kept beside the .js). No package.json is touched. Every vertical
+//                  with a rest/ folder is supported. `--out <dir>` (default: the project root)
 //                  is the folder the site is served from — the one wix.config.json's
 //                  site.outputDirectory points at — so the modules land where the pages import
 //                  them and nothing else in the project gets uploaded.
@@ -431,7 +431,7 @@ if (siteSearch) {
   result.capabilities = { ...result.capabilities, siteSearch: true };
   if (siteSearch.install) {
     // Indexing needs the Wix Site Search app on the site — a site mutation the deploy never makes.
-    result.note = [result.note, "siteSearch.install: run `node <SKILL_ROOT>/templates/shared/capabilities/site-search/seed/install.mjs` from the project root after the seed (results appear about half a minute later)"].filter(Boolean).join("; ");
+    result.note = [result.note, `siteSearch.install: run node ${join(REF, "shared", "capabilities", "site-search", "seed", "install.mjs")} from the project root after the seed (results appear about half a minute later)`].filter(Boolean).join("; ");
   }
 }
 

package/skills/wix-headless-kit/install/pins.json

@@ -3,6 +3,6 @@
   "@wix/create-new": "0.0.124",
   "typescript": "5.8.3",
   "templates": {
-    "ref": "v1.30.0"
+    "ref": "v1.31.1"
   }
 }

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

@@ -276,7 +276,7 @@ if (stack !== "static" && existsSync(join(projectDir, "package.json"))) {
 const madeTheSite = mode === "create" || mode === "adopt";
 let seed = null;
 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` });
+  emit("seed_skipped", { reason: `${mode}: the site existed before this run; setup seeds only a site it created. Read what the site holds (${join(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");
@@ -325,7 +325,7 @@ emit("ready_for_brand_layer", {
       ? "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; "
       : 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; `) +
+      : `nothing was seeded (setup seeds only a site it created): read what the site holds with ${join(TEMPLATES, vertical, "seed", "read-site.mjs")}, then run ${join(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); `
       : "") +

package/skills/wix-headless-kit/install/templates.mjs

@@ -7,7 +7,8 @@
 //
 // Resolution, in order:
 //   1. the sibling skill folder, `<SKILL_ROOT>/../wix-headless-templates/`: a checkout of the repository,
-//      or a plugin install that carries both skills (every plugin manifest lists the templates skill).
+//      or an install that carries both skills (the cold start's `npx skills add`, the npm package,
+//      the Codex and Cursor plugins; the Claude plugin leaves it out, so there it is fetched).
 //   2. the cache `<SKILL_ROOT>/templates/`, filled by an earlier call (`--refresh` refetches).
 //   3. a fetch: a sparse, shallow clone of `skills/wix-headless-templates/` from the repository the skill was installed
 //      from (skills-lock.json's `source`, default wix/skills), at the branch or tag the install

package/skills/wix-headless-templates/blog/seed/SEED.md

@@ -52,7 +52,7 @@ feed without covers looks broken.
 - Cover — the default is a `coverImagePrompt` (AI-generated, ~1 Wix AI credit per image,
   account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting — always
   ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use
-  `coverImagePath` (a file on this machine — uploaded to Wix Media) or `coverImageUrl` (their
+  `coverImageMediaId` (a file already in the site's Media Manager, such as one the user uploaded there: used as it is, no copy; a `static.wixstatic.com/media/<file id>` URL of a site file counts as one), `coverImagePath` (a file on this machine — uploaded to Wix Media) or `coverImageUrl` (their
   own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Covers resolve
   in parallel and never block the seed; a failed cover leaves that post text-only (the script
   re-publishes each post it covers).

package/skills/wix-headless-templates/blog/seed/seed-blog.mjs

@@ -12,7 +12,7 @@
 // Plan shape (see SEED.md):
 //   { "categories"?: [name], "tags"?: [name],
 //     "posts": [{ "title", "content": [blocks] | "richContent"?, "category"?|"categories"?,
-//                 "tags"?, "coverImageUrl"? | "coverImagePrompt"? }] }
+//                 "tags"?, "coverImageMediaId"? | "coverImageUrl"? | "coverImagePrompt"? }] }
 //   content blocks: { type:"heading", text, level? } | { type:"paragraph", text }
 //     | { type:"quote", text } | { type:"bulleted"|"ordered", items:[text,…] }
 //
@@ -255,7 +255,7 @@ export async function setupBlog(ctx, { posts = [], categories = [], tags = [] }
   // never depends on images.
   const files = await resolveItemImages(ctx, created.map((c, i) => (
     c?.id && c?.success
-      ? { path: posts[i]?.coverImagePath, url: posts[i]?.coverImageUrl, prompt: posts[i]?.coverImagePrompt, displayName: `post-${i}.png` }
+      ? { mediaId: posts[i]?.coverImageMediaId, path: posts[i]?.coverImagePath, url: posts[i]?.coverImageUrl, prompt: posts[i]?.coverImagePrompt, displayName: `post-${i}.png` }
       : null
   )));
   const covers = created

package/skills/wix-headless-templates/bookings/seed/SEED.md

@@ -19,7 +19,7 @@ service an image — the default is an `imagePrompt` (AI-generated, ~1 Wix AI cr
 account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting — always ending
 "no text, no watermarks". At least one image in the set shows the real subject of the business —
 the actual product/space/service, not abstract decoration. For an asset the user actually supplied
-use `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl` (their own hosted
+use `imageMediaId` (a file already in the site's Media Manager, such as one the user uploaded there: used as it is, no copy; a `static.wixstatic.com/media/<file id>` URL of a site file counts as one), `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl` (their own hosted
 URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in
 parallel and never block the seed; a failed image leaves that service text-only.
 

package/skills/wix-headless-templates/bookings/seed/seed-bookings.mjs

@@ -17,7 +17,7 @@
 //                    "price"? (number | { "from": number }), "priceText"?, "free"?, "deposit"?, "payInFull"?,
 //                    "duration"? (APPOINTMENT, minutes), "capacity"?, "waitlist"?, "maxParticipants"?,
 //                    "requireManualApproval"?, "conferencing"?, "staff"? (name | [names]), "location"? (name),
-//                    "category"? (name), "imageUrl"? | "imagePath"? | "imagePrompt"?,
+//                    "category"? (name), "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"?,
 //                    "sessions"?: [{ "start", "end", "capacity"? }],            // CLASS: one-off sessions, local "YYYY-MM-DDThh:mm:ss"
 //                    "weekly"?: { "days": ["MONDAY"], "time": "18:00", "duration": 60, "start", "end" } }] }  // CLASS or COURSE: recurring
 //
@@ -355,6 +355,7 @@ export async function setupBookings(ctx, { services = [], staff = [], locations
   // Pass 2 — images: resolve (import by url / generate by prompt) in one parallel wave, then
   // attach. Failures leave the service text-only; the seed's exit never depends on images.
   const files = await resolveItemImages(ctx, created.map((c, i) => ({
+    mediaId: services[i]?.imageMediaId,
     url: services[i]?.imageUrl,
     path: services[i]?.imagePath,
     prompt: services[i]?.imagePrompt,

package/skills/wix-headless-templates/donations/seed/SEED.md

@@ -16,7 +16,7 @@ amount with a minimum, the note and the cover-fee prompt on. A second campaign (
 only when the brief lists several causes. Every campaign gets a cover image — the default is an
 `imagePrompt` (AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
 mood, palette, lighting — always ending "no text, no watermarks"; a real subject of the cause, not
-abstract decoration. For an asset the user supplied use `imagePath` (a file on this machine) or
+abstract decoration. For an asset the user supplied use `imageMediaId` (a file already in the site's Media Manager, such as one the user uploaded there: used as it is, no copy; a `static.wixstatic.com/media/<file id>` URL of a site file counts as one), `imagePath` (a file on this machine) or
 `imageUrl` (their own hosted URL; verify with `curl -sI` → 200) — never a stock or guessed URL.
 Images resolve in parallel and never block the seed; a failed image leaves the campaign text-only.
 

package/skills/wix-headless-templates/donations/seed/seed-donations.mjs

@@ -16,7 +16,7 @@
 //                     "customAmount"?: { "enabled", "min"?, "max"? },
 //                     "goal"?: { "target", "endDate"?, "acceptAfterGoal"?, "acceptAfterEndDate"? },
 //                     "comments"?: false, "askCoverFee"?: false,
-//                     "imageUrl"? | "imagePath"? | "imagePrompt"? }] }
+//                     "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"? }] }
 //
 // Seeding is ADDITIVE and idempotent — a non-archived campaign with the same name is reused, never
 // duplicated; nothing is deleted or overwritten. Unexpected shapes → read the live API reference;
@@ -196,8 +196,9 @@ export async function setupDonations(ctx, { campaigns = [], currency } = {}) {
 
   // Pass 2 — images: resolve (upload a local file / import by url / generate by prompt) in one
   // parallel wave, then attach. Failures leave the campaign text-only; the exit never depends on them.
-  const wanted = created.filter((c) => c.created && (c.plan.imageUrl || c.plan.imagePath || c.plan.imagePrompt));
+  const wanted = created.filter((c) => c.created && (c.plan.imageMediaId || c.plan.imageUrl || c.plan.imagePath || c.plan.imagePrompt));
   const files = await resolveItemImages(ctx, wanted.map((c) => ({
+    mediaId: c.plan.imageMediaId,
     url: c.plan.imageUrl,
     path: c.plan.imagePath,
     prompt: c.plan.imagePrompt,

package/skills/wix-headless-templates/events/seed/SEED.md

@@ -17,7 +17,7 @@ the shape; the owner adds the rest in the dashboard) and make them exercise the
 image (an events page without images looks broken) — the default is an `imagePrompt`
 (AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
 aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually
-supplied use `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
+supplied use `imageMediaId` (a file already in the site's Media Manager, such as one the user uploaded there: used as it is, no copy; a `static.wixstatic.com/media/<file id>` URL of a site file counts as one), `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
 (their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the
 seed; a failed image leaves that event text-only.
 

package/skills/wix-headless-templates/events/seed/seed-events.mjs

@@ -14,7 +14,7 @@
 //                  "startDate", "endDate" (future ISO-8601 UTC), "timeZoneId",
 //                  "location" ({name,type:"VENUE",address} | {name,type:"ONLINE"} | {locationTbd:true,name}),
 //                  "ticketTiers"?: [{ "name" (≤30 chars), "price" (decimal STRING), "description"?, "initialLimit"?, "feeType"? }],
-//                  "category"? (name), "imageUrl"? | "imagePrompt"?, "rsvpResponseType"? }] }
+//                  "category"? (name), "imageMediaId"? | "imageUrl"? | "imagePrompt"?, "rsvpResponseType"? }] }
 //
 // Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →
 // read the live API reference; every call below
@@ -260,7 +260,7 @@ export async function setupEvents(ctx, { events = [], currency } = {}) {
       catch (err) { console.error(`guest control skipped for "${ev.title}": ${err.message}`); }
     }
     await publishEvent(ctx, e.id);
-    created.push({ ...e, category: ev.category, imageUrl: ev.imageUrl, imagePrompt: ev.imagePrompt, ticketCount: tiers.length, feeTypes: tiers.map((t) => t.feeType), ...(ev.guests ? { guestControl } : {}) });
+    created.push({ ...e, category: ev.category, imageMediaId: ev.imageMediaId, imageUrl: ev.imageUrl, imagePrompt: ev.imagePrompt, ticketCount: tiers.length, feeTypes: tiers.map((t) => t.feeType), ...(ev.guests ? { guestControl } : {}) });
   }
 
   const names = [...new Set(created.map((e) => e.category).filter(Boolean))];
@@ -273,6 +273,7 @@ export async function setupEvents(ctx, { events = [], currency } = {}) {
   // Pass 2 — images: resolve (import by url / generate by prompt) in one parallel wave, then
   // attach. Failures leave the event text-only; the seed's exit never depends on images.
   const files = await resolveItemImages(ctx, created.map((e) => ({
+    mediaId: e.imageMediaId,
     url: e.imageUrl,
     path: e.imagePath,
     prompt: e.imagePrompt,

package/skills/wix-headless-templates/portfolio/seed/SEED.md

@@ -53,8 +53,10 @@ rows (Role, Year, Client…).
 - Every image field's default is a prompt (`coverImagePrompt` / `items[].imagePrompt` —
   AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
   aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied
-  use a path (`coverImagePath` / `items[].imagePath` — a file on this machine, uploaded to
-  Wix Media) or a url (`coverImageUrl` / `items[].imageUrl` — their own hosted URL; verify it
+  use a Media Manager file (`coverImageMediaId` / `items[].imageMediaId` — a file already in the
+  site's Media Manager, such as one the user uploaded there: used as it is, no copy; a
+  `static.wixstatic.com/media/<file id>` URL of a site file counts as one), a path
+  (`coverImagePath` / `items[].imagePath` — a file on this machine, uploaded to Wix Media) or a url (`coverImageUrl` / `items[].imageUrl` — their own hosted URL; verify it
   with `curl -sI` → 200) — never a stock-photo or guessed URL. All images —
   covers and gallery items alike — resolve in one parallel wave and never block the seed; a
   failed image skips just that item/cover. The **cover** is the

package/skills/wix-headless-templates/portfolio/seed/seed-portfolio.mjs

@@ -9,12 +9,12 @@
 // project's gallery items, and imports+attaches cover images. Prints a JSON result to stdout.
 //
 // Plan shape (see SEED.md):
-//   { "collections": [{ "title", "description"?, "hidden"?, "coverImageUrl"? | "coverImagePrompt"? }],
+//   { "collections": [{ "title", "description"?, "hidden"?, "coverImageMediaId"? | "coverImageUrl"? | "coverImagePrompt"? }],
 //     "projects":    [{ "title", "description"?, "hidden"?,
 //                       "collection"? (title),        // resolved to that collection's id
 //                       "details"?: [{ "label", "text" }],
-//                       "coverImageUrl"? | "coverImagePrompt"?,
-//                       "items"?: [{ "sortOrder", "title"?, "imageUrl" | "imagePrompt" }] }] }
+//                       "coverImageMediaId"? | "coverImageUrl"? | "coverImagePrompt"?,
+//                       "items"?: [{ "sortOrder", "title"?, "imageMediaId" | "imageUrl" | "imagePrompt" }] }] }
 //
 // Seeding is ADDITIVE — never deletes or overwrites existing content. A fresh Portfolio
 // install ships its own sample content ("My Portfolio" + sample projects); removing it is the
@@ -186,13 +186,13 @@ export async function setupPortfolio(ctx, { collections = [], projects = [] } =
   projects.forEach((p, pi) => {
     for (const it of p.items ?? []) {
       galleryRefs.push({ pi, it, spec: specs.length });
-      specs.push({ path: it.imagePath, url: it.imageUrl, prompt: it.imagePrompt, displayName: `${it.title || "item"}.png` });
+      specs.push({ mediaId: it.imageMediaId, path: it.imagePath, url: it.imageUrl, prompt: it.imagePrompt, displayName: `${it.title || "item"}.png` });
     }
   });
   const projCoverAt = specs.length;
-  projects.forEach((p) => specs.push({ path: p.coverImagePath, url: p.coverImageUrl, prompt: p.coverImagePrompt, displayName: `${p.title || "project"}-cover.png` }));
+  projects.forEach((p) => specs.push({ mediaId: p.coverImageMediaId, path: p.coverImagePath, url: p.coverImageUrl, prompt: p.coverImagePrompt, displayName: `${p.title || "project"}-cover.png` }));
   const colCoverAt = specs.length;
-  collections.forEach((c) => specs.push({ path: c.coverImagePath, url: c.coverImageUrl, prompt: c.coverImagePrompt, displayName: `${c.title || "collection"}-cover.png` }));
+  collections.forEach((c) => specs.push({ mediaId: c.coverImageMediaId, path: c.coverImagePath, url: c.coverImageUrl, prompt: c.coverImagePrompt, displayName: `${c.title || "collection"}-cover.png` }));
   const files = await resolveItemImages(ctx, specs);
   const dims = { height: 1024, width: 1024 };
 

package/skills/wix-headless-templates/rentals/seed/SEED.md

@@ -19,7 +19,7 @@ exercise the UI: one hourly and one daily rental when the business allows it, a
 approval-gated one where it fits, and an image per rental — the default is an `imagePrompt`
 (AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
 aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image shows
-the real thing being rented. For an asset the user actually supplied use `imagePath` (a file on this
+the real thing being rented. For an asset the user actually supplied use `imageMediaId` (a file already in the site's Media Manager, such as one the user uploaded there: used as it is, no copy; a `static.wixstatic.com/media/<file id>` URL of a site file counts as one), `imagePath` (a file on this
 machine — uploaded to Wix Media) or `imageUrl` (their own hosted URL; verify it with `curl -sI` →
 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the seed.
 

package/skills/wix-headless-templates/rentals/seed/seed-rentals.mjs

@@ -17,7 +17,7 @@
 //     "resourceTypes": [{ "name": "Kayaks", "resources": ["Kayak 1", "Kayak 2"] }],
 //     "rentals": [{ "name", "description", "tagLine"?, "unit": "HOUR"|"DAY", "rate": 25, "min"?, "max"?,
 //                   "resourceType": "Kayaks", "resources"?: ["Kayak 1"], "free"?, "requireManualApproval"?,
-//                   "imageUrl"? | "imagePath"? | "imagePrompt"? }] }
+//                   "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"? }] }
 //
 // Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →
 // read the live API reference; every call below carries a docs: line with its reference page.
@@ -268,6 +268,7 @@ export async function setupRentals(ctx, { resourceTypes = [], rentals = [], curr
   // Pass 2 — images: resolve (import by url / generate by prompt) in one parallel wave, then attach.
   // Failures leave the rental text-only; the seed's exit never depends on images.
   const files = await resolveItemImages(ctx, created.map((c, i) => ({
+    mediaId: rentals[i]?.imageMediaId,
     url: rentals[i]?.imageUrl,
     path: rentals[i]?.imagePath,
     prompt: rentals[i]?.imagePrompt,

package/skills/wix-headless-templates/restaurants/seed/SEED.md

@@ -16,7 +16,7 @@ of 2–3 items each** (the seed shows the shape; the owner adds the rest in the
 every item with an image (a menu without photos looks broken) — the default is an
 `imagePrompt` (AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual —
 subject, aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually
-supplied use `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
+supplied use `imageMediaId` (a file already in the site's Media Manager, such as one the user uploaded there: used as it is, no copy; a `static.wixstatic.com/media/<file id>` URL of a site file counts as one), `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
 (their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never
 block the seed, a failed image leaves that item text-only — and both add-ons on for a
 restaurant that takes orders and reservations. Give at least one dish a choice (a `variants`

package/skills/wix-headless-templates/restaurants/seed/seed-restaurants.mjs

@@ -14,7 +14,7 @@
 //                 "items": [{ "name", "description"?, "price"? | "variants"?: [{ "name", "price" }],
 //                             "modifierGroups"?: [{ "name", "required"?, "min"?, "max"?,
 //                               "modifiers": [{ "name", "price"?, "preSelected"?, "inStock"? }] }],
-//                             "acceptSpecialRequests"?, "imageUrl"? | "imagePath"? | "imagePrompt"? }] }] }],
+//                             "acceptSpecialRequests"?, "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"? }] }] }],
 //     "ordering"?: true | { "address"? },        // menu-first add-on; address is STEP 0
 //     "reservations"?: true | { "partySize"? { "min","max" }, "address"? } }
 //
@@ -459,12 +459,13 @@ export async function setupRestaurants(ctx, plan) {
     const flat = m.sections.flatMap((s) => s.items || []);
     flat.forEach((it, i) => {
       const created = createdMenus[mi]?.items?.[i];
-      if ((it.imageUrl || it.imagePath || it.imagePrompt) && created?.id) {
-        imageItems.push({ ...created, imageUrl: it.imageUrl, imagePath: it.imagePath, imagePrompt: it.imagePrompt, name: it.name });
+      if ((it.imageMediaId || it.imageUrl || it.imagePath || it.imagePrompt) && created?.id) {
+        imageItems.push({ ...created, imageMediaId: it.imageMediaId, imageUrl: it.imageUrl, imagePath: it.imagePath, imagePrompt: it.imagePrompt, name: it.name });
       }
     });
   });
   const files = await resolveItemImages(ctx, imageItems.map((it) => ({
+    mediaId: it.imageMediaId,
     url: it.imageUrl,
     path: it.imagePath,
     prompt: it.imagePrompt,

package/skills/wix-headless-templates/shared/seed/images.mjs

@@ -124,6 +124,37 @@ async function findExisting(ctx, displayName) {
   }
 }
 
+/**
+ * The Media Manager file a spec names, when it names one: `mediaId`, or the file id at the end of a
+ * `static.wixstatic.com/media/<fileId>` URL. Returns { id, url, existing: true } for a file on this
+ * site, waiting out a short PENDING (an upload still processing), or null when the URL's file is
+ * not on this site (it is then imported like any external URL). An explicit `mediaId` that is not
+ * on the site throws, so the product is reported text-only with the reason.
+ */
+// docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/get-file-descriptor.md
+const WIX_MEDIA_URL = /^https?:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/;
+async function existingMediaFile(ctx, s) {
+  const id = s.mediaId ?? s.url?.match(WIX_MEDIA_URL)?.[1];
+  if (!id) return null;
+  for (let attempt = 0; attempt < 10; attempt++) {
+    const res = await fetch(`${API}/site-media/v1/files/get-file-by-id?fileId=${encodeURIComponent(id)}`, {
+      headers: { Authorization: `Bearer ${ctx.token}`, "wix-site-id": ctx.siteId },
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (res.status === 404) {
+      if (s.mediaId) throw new Error(`no Media Manager file ${id} on this site`);
+      return null;
+    }
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(`GET get-file-by-id -> ${res.status}: ${JSON.stringify(json).slice(0, 200)}`);
+    const f = json.file;
+    if (f?.operationStatus === "FAILED") throw new Error(`Media Manager file ${id} failed processing`);
+    if (f?.url && f.operationStatus !== "PENDING") return { id: f.id, url: f.url, existing: true };
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  throw new Error(`Media Manager file ${id} still processing`);
+}
+
 /** Short stable fingerprint of an image's source (url, prompt + size, or file bytes). */
 function sourceHash(s) {
   const h = createHash("sha1");
@@ -149,12 +180,17 @@ export async function importImage(ctx, url, displayName = "image.png") {
 
 /**
  * THE seed entry point. Resolves a batch of image specs to Wix Media files in ONE parallel
- * wave. Each spec: { path } (LOCAL file — the user's own asset, uploaded) OR { url }
- * (verified external URL — imported) OR { prompt } (generated, ~1 credit) — plus optional
- * displayName, width, height. Returns an array aligned with the input: { id, url } per
- * success, null per failure or empty spec. Never throws.
+ * wave. Each spec: { mediaId } (a file already in this site's Media Manager — used as it is,
+ * as is a static.wixstatic.com/media URL of one) OR { path } (LOCAL file — the user's own asset,
+ * uploaded) OR { url } (verified external URL — imported) OR { prompt } (generated, ~1 credit) —
+ * plus optional
+ * displayName, width, height. Returns an array aligned with the input: { file, error } per
+ * spec — `file` is { id, url } on success and null otherwise; `error` is the reason it is null
+ * (the thrown message, "empty spec", or "timed out"). Never throws. Every failure is also
+ * printed to stderr, so a seed log names the image and the reason even when the seed's
+ * own report does not.
  */
-export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000 } = {}) {
+export async function resolveItemImagesDetailed(ctx, specs, { perImageBudgetMs = 120_000 } = {}) {
   // unref: the budget timer must never keep the seed process alive after the work is done —
   // a lingering timer delays the seed's exit (and the run's .seed-exit marker) by the budget.
   const deadline = new Promise((r) => {
@@ -163,8 +199,11 @@ export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000
   });
   const results = await Promise.allSettled(
     (specs ?? []).map(async (s) => {
-      if (!s || (!s.path && !s.url && !s.prompt)) return null;
+      if (!s || (!s.path && !s.url && !s.prompt && !s.mediaId)) return null;
       const resolve = (async () => {
+        // A file already in this site's Media Manager is used as it is: no import, no copy.
+        const inMedia = await existingMediaFile(ctx, s);
+        if (inMedia) return inMedia;
         const name = stableName(s);
         // uploadImage swaps in the file's own extension; look for what it will actually be named
         const uploadedName = s.path ? name.replace(/\.[a-z0-9]+$/i, "") + extname(s.path).toLowerCase() : name;
@@ -179,5 +218,22 @@ export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000
       return Promise.race([resolve, deadline]);
     }),
   );
-  return results.map((r) => (r.status === "fulfilled" ? r.value : null));
+  return results.map((r, i) => {
+    const spec = specs?.[i] ?? {};
+    const label = spec.displayName ?? spec.mediaId ?? spec.path ?? spec.url ?? (spec.prompt ? "(prompt)" : "(empty)");
+    if (r.status === "fulfilled") {
+      if (r.value) return { file: r.value, error: null };
+      const error = !spec.path && !spec.url && !spec.prompt && !spec.mediaId ? "empty spec" : `timed out after ${perImageBudgetMs} ms`;
+      if (error !== "empty spec") console.error(`image ${label}: ${error}`);
+      return { file: null, error };
+    }
+    const error = r.reason?.message ?? String(r.reason);
+    console.error(`image ${label}: ${error.slice(0, 200)}`);
+    return { file: null, error };
+  });
+}
+
+/** The plain array of { id, url } | null the seeds consume today; failures are still printed. */
+export async function resolveItemImages(ctx, specs, opts) {
+  return (await resolveItemImagesDetailed(ctx, specs, opts)).map((r) => r.file);
 }

package/skills/wix-headless-templates/storefront/seed/SEED.md

@@ -54,8 +54,8 @@ to a file if you want it later). `.seed-exit` and `seed-result.json` are written
   `type: "color"` renders as real swatches (give every color choice a `colorCode`); anything
   else renders as text pills. Variants are expanded automatically (full cross-product, each
   carrying the product's price/compareAtPrice/quantity) — keep option counts small.
-  A choice may carry its own photo — `imageUrl` | `imagePath` | `imagePrompt` (+ `altText`), the
-  same three forms as a product image: it joins the product's gallery and the product page shows
+  A choice may carry its own photo — `imageMediaId` | `imageUrl` | `imagePath` | `imagePrompt`
+  (+ `altText`), the same forms as a product image: it joins the product's gallery and the product page shows
   it when that choice is picked (a colour's photo). Give it when the source has one per colour.
 - `variantPrices` — `{ "<choice name>": price }` when one option's choices are priced differently
   ("L": 74): every variant carrying that choice takes that price (the first priced choice wins);
@@ -76,9 +76,14 @@ to a file if you want it later). `.seed-exit` and `seed-result.json` are written
 - **Give every product an image** (a store without product images looks broken: gray boxes on
   tiles, PDP, and cart) — the default is an `imagePrompt` (AI-generated, ~1 Wix AI credit
   per image, account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting —
-  always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use `imagePath` (a file on
-  this machine — uploaded to Wix Media) or `imageUrl` (their own hosted URL; verify it with
-  `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the seed; a failed image leaves
+  always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use `imageMediaId` (a file
+  already in the site's Media Manager, such as one the user uploaded there: the product uses that
+  file as it is, no copy), `imagePath` (a file on this machine — uploaded to Wix Media) or
+  `imageUrl` (their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or
+  guessed URL. A `static.wixstatic.com/media/<file id>` URL of a file on this site counts as its
+  `imageMediaId`. List the site's files to find an id: the
+  [Media Manager](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/list-files.md)
+  names each by the name it was uploaded under. Images resolve in parallel and never block the seed; a failed image leaves
   that product text-only. Seed text-only only when the user explicitly asks.
 - `digitalFilePath` (a file on this machine) or `digitalFileUrl` — makes the product a digital
   download, uploaded and created with both the file and stock (`quantity` is ignored). It's also the
@@ -95,6 +100,13 @@ to a file if you want it later). `.seed-exit` and `seed-result.json` are written
 - `quantity` — tracked stock, a non-negative integer. For stock that isn't counted (made to
   order, print on demand, unlimited) use `"inStock": true` **instead** of `quantity`; sending
   both is rejected.
+  Right after the bulk create, a product's own stock summary can still read `OUT_OF_STOCK`
+  while its inventory items are already stocked; the items are what a buyer's add is checked
+  against. A product **without options** can still end up with no item (a create that ran while
+  the catalog was provisioning): the script stocks those afterwards with one Bulk Create
+  Inventory Items call (`productId`, its single `variantId`, and `inStock: true` or the
+  `quantity`), where `ALREADY_EXISTS` means the item is already there. A seed made call by call
+  reads the items (Query Inventory Items) and creates only the missing ones.
 - `currency` — 3-letter ISO code. Set it **only when the brief names one**: a sentence about
   currency ("prices in euros") or a price written with its unit ("9 dollars", "$9", "€20"). Do **not** infer it from a language, a country, or an address
   — an unrequested switch silently reprices the whole catalog. The seed applies it before