@wix/agent-skills 1.6.0 → 1.8.0

package/skills/wix-headless/scripts/patch-decorative-slots.mjs

@@ -1,59 +1,88 @@
 #!/usr/bin/env node
-// Inject Image-Phase-1 decorative URLs into the designer-emitted page shells.
+// Inject Image-Phase-1 decorative URLs into the page shells.
 //
-// The Phase 2 designer writes `<div data-decorative-slot="<key>">…</div>`
-// placeholders in src/pages/*.astro. Image Phase 1 writes resolved URLs to
-// .wix/image-urls.md. This script reads both, then injects an <img> element
-// as the first child of each matching slot div — pure string substitution,
-// no LLM, no file rewrites.
+// The design-system Composer (index.astro) and the Phase 4 page designers write
+// `<div data-decorative-slot="<key>">…</div>` placeholders in src/pages/*.astro. Image Phase 1 returns a slot→URL map
+// in its JSON return; the orchestrator pipes that map (as JSON) into this
+// script's stdin. This script reads the map + walks src/pages/*.astro,
+// then injects an <img> as the first child of each matching slot div —
+// pure string substitution, no LLM, no file rewrites.
 //
 // Usage:
-//   node patch-decorative-slots.mjs <project-dir>
+//   echo '{"hero":"https://...","about":"https://..."}' \
+//     | node patch-decorative-slots.mjs <scaffold-dir>
+//
+// <scaffold-dir> is the dir that contains src/pages/. The orchestrator
+// passes the scaffold subdir explicitly — no eval-dir vs scaffold-dir
+// auto-detection is needed for the URL map (it's on stdin), but src/pages
+// is still resolved per-input since the orchestrator may call this from
+// either the scaffold subdir or the eval root.
 //
 // Behavior:
-//   - If .wix/image-urls.md doesn't exist, exit 0 silently (Image Phase 1
-//     timed out / failed; the slot placeholders look complete on their own).
+//   - Empty stdin or no slot→URL pairs → exit 0 status="skipped" (themed-
+//     blocks mode or Image Phase 1 had no URLs to publish).
+//   - src/pages missing at <scaffold-dir> and in any single subdir one
+//     level down → exit 2 status="error".
 //   - For each `data-decorative-slot="<key>"` in src/pages/*.astro:
-//       * If <key> has no URL in image-urls.md → leave the div alone.
-//       * If the div is self-closing or already has a child element other
-//         than whitespace/comments → skip with a warning (don't clobber).
+//       * Key has no URL in the input map → leave the div alone.
+//       * Div already has a non-comment child → skip with a warning.
 //       * Otherwise inject <img …> as the first child.
-//   - Output a JSON summary of patches/skips/warnings to stdout.
-//   - Exit 0 even when some slots couldn't be patched — placeholders fall
-//     back to the designer's aspect-ratio + background-color rendering.
+//   - Output JSON summary of patches/skips/warnings to stdout.
 
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 const projectDir = process.argv[2] ?? process.cwd();
 
-const imageUrlsPath = join(projectDir, ".wix/image-urls.md");
-if (!existsSync(imageUrlsPath)) {
-  console.log(JSON.stringify({ status: "skipped", reason: "no .wix/image-urls.md (Image Phase 1 didn't write — failed or timed out)" }));
+let urlMap = {};
+if (!process.stdin.isTTY) {
+  const raw = readFileSync(0, "utf8").trim();
+  if (raw) {
+    try {
+      urlMap = JSON.parse(raw);
+    } catch (e) {
+      console.error(JSON.stringify({ status: "error", reason: `stdin is not valid JSON (${e.message})` }));
+      process.exit(2);
+    }
+    if (!urlMap || typeof urlMap !== "object" || Array.isArray(urlMap)) {
+      console.error(JSON.stringify({ status: "error", reason: "expected a JSON object mapping slot keys to URLs" }));
+      process.exit(2);
+    }
+  }
+}
+
+if (Object.keys(urlMap).length === 0) {
+  console.log(JSON.stringify({ status: "skipped", reason: "no slot→URL pairs on stdin (themed-blocks mode or Image Phase 1 produced none)" }));
   process.exit(0);
 }
 
-// Parse `## <key>\n- url: <url>` blocks from .wix/image-urls.md.
-const imageUrlsRaw = readFileSync(imageUrlsPath, "utf8");
-const urlMap = {};
-// Match `## key\n…- url: <url>` per section. The inner `(?:(?!^##\s)[\s\S])*?`
-// forbids the lazy span from crossing into the next `## ` line — without
-// that guard, an empty `- url:` for one slot silently steals the next
-// section's URL on partial-failure runs.
-const sectionRegex = /^##\s+(\S+)\s*\n(?:(?!^##\s)[\s\S])*?-\s*url:\s*(https?:\/\/\S+)/gm;
-let m;
-while ((m = sectionRegex.exec(imageUrlsRaw)) !== null) {
-  urlMap[m[1]] = m[2];
+function findPagesDir() {
+  const direct = join(projectDir, "src/pages");
+  if (existsSync(direct)) return { path: direct, source: "projectDir" };
+  const hits = [];
+  for (const entry of readdirSync(projectDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const candidate = join(projectDir, entry.name, "src/pages");
+    if (existsSync(candidate)) hits.push(candidate);
+  }
+  if (hits.length === 1) return { path: hits[0], source: "scaffold-subdir" };
+  if (hits.length > 1) return { path: null, source: "ambiguous", hits };
+  return { path: null, source: "missing" };
 }
 
-if (Object.keys(urlMap).length === 0) {
-  console.log(JSON.stringify({ status: "skipped", reason: ".wix/image-urls.md exists but has no parseable `## key` + `- url:` blocks" }));
-  process.exit(0);
+const pagesResolved = findPagesDir();
+if (!pagesResolved.path) {
+  console.error(JSON.stringify({
+    status: "error",
+    reason: "src/pages not found at <projectDir>/src/pages or in any scaffold subdir; pass the scaffold dir explicitly",
+    projectDir,
+    pagesSearchedAt: pagesResolved.source === "ambiguous" ? pagesResolved.hits : [join(projectDir, "src/pages")],
+  }, null, 2));
+  process.exit(2);
 }
 
-// Find candidate page files: src/pages/*.astro, recursively (designer may emit
-// /about.astro at top level OR /pages/about.astro).
-const pagesDir = join(projectDir, "src/pages");
+const pagesDir = pagesResolved.path;
+
 const candidates = [];
 const walk = (dir) => {
   if (!existsSync(dir)) return;
@@ -80,22 +109,17 @@ for (const file of candidates) {
   modified = modified.replace(SLOT_DIV_REGEX, (match, openTag, slotKey, inner, closeTag) => {
     const url = urlMap[slotKey];
     if (!url) {
-      skipped.push({ file, slot: slotKey, reason: "no URL for this slot in image-urls.md" });
+      skipped.push({ file, slot: slotKey, reason: "no URL for this slot in input map" });
       return match;
     }
 
-    // Strip HTML comments before any content checks — the designer's placeholder
-    // is a comment like `<!-- orchestrator injects <img> here -->`, which would
-    // otherwise false-positive both the idempotency and clobber-guard checks.
     const stripped = inner.replace(/<!--[\s\S]*?-->/g, "").trim();
 
-    // Skip if div already contains an <img> element (idempotency).
     if (/<img\b/i.test(stripped)) {
       skipped.push({ file, slot: slotKey, reason: "div already contains an <img> tag (idempotent skip)" });
       return match;
     }
 
-    // Skip if div has substantive child content beyond whitespace/comments.
     if (stripped.length > 0) {
       warnings.push({ file, slot: slotKey, reason: "div has existing non-image child content; not patching to avoid clobber" });
       return match;
@@ -104,7 +128,6 @@ for (const file of candidates) {
     fileChanged = true;
     const img = `<img src="${url}" alt="" loading="lazy" decoding="async" class="decorative-slot-img" />`;
     patched.push({ file, slot: slotKey });
-    // Preserve any whitespace inside the div (e.g., the newline + indent).
     return `${openTag}\n      ${img}${inner}${closeTag}`;
   });
 
@@ -115,10 +138,11 @@ for (const file of candidates) {
 
 const summary = {
   status: warnings.length > 0 ? "partial" : "ok",
-  imageUrls: Object.keys(urlMap),
+  slots: Object.keys(urlMap),
   filesScanned: candidates.length,
   patched,
   skipped,
   warnings,
+  pagesFrom: pagesResolved.source,
 };
 console.log(JSON.stringify(summary, null, 2));

package/skills/wix-headless/scripts/plan-entity-image-waves.mjs

@@ -9,8 +9,8 @@
 //
 //   waves     — Runware generation requests, grouped into waves of <waveSize>
 //               (default 3) to match the google:4@2 throttle. Each wave is
-//               one orchestration step with N parallel CallWixSiteAPI tool
-//               calls; each tool call sends one task in the body array.
+//               one orchestration step with N parallel curls in one shell,
+//               backgrounded with `&`; each curl sends one task in the body array.
 //
 //   imports   — POST /site-media/v1/files/import requests, one per generated
 //               image. Indexed by taskUUID so the orchestrator threads the
@@ -155,7 +155,7 @@ for (const p of prompts) {
       process.exit(1);
     }
     // Read-merge-PUT: echo every existing data field, set the image field
-    // to the placeholder URL. Wipes nothing (the bug observed in 2026-04-19).
+    // to the placeholder URL. Echoing every existing field is what prevents wiping the rest of the record.
     const mergedData = { ...detail.data, [detail.imageField]: "__IMAGE_URL__" };
     patches.push({
       taskUUID: p.taskUUID,

package/skills/wix-headless/scripts/scaffold.sh

@@ -1,53 +1,139 @@
 #!/usr/bin/env bash
-# Scaffold a new Wix Managed Headless project with the pure-headless blank template.
+# Scaffold a new Wix Managed Headless project using the CLI's preset blank template.
 #
 # Usage:
-#   bash <SKILL_ROOT>/scripts/scaffold.sh <project-slug> "<Brand Name>"
+#   bash <SKILL_ROOT>/scripts/scaffold.sh <folder-name> "<Brand Name>" [--frontend astro|custom]
 #
-# <project-slug>: 3-20 lowercase alphanumeric chars (no hyphens, no spaces) — the
-#                 Wix CLI rejects anything else. Becomes the project directory name.
-# <Brand Name>:   human-readable business name; quote if it contains spaces.
+# <folder-name>:  lowercase letters, numbers, and hyphens only; must start with a
+#                 letter or number. The CLI scaffolds into a subdir of this name,
+#                 which this script then FLATTENS into the current directory (see
+#                 "In-place flatten" below) — so the project ends up *in CWD*, not
+#                 in a nested folder. The name is still required (the CLI mandates
+#                 it) but the local folder is transient.
+# <Brand Name>:   human-readable business name; quote if it contains spaces. The
+#                 CLI derives the Wix project display-name and URL slug from it, so
+#                 it must include at least one English letter or number.
+# --frontend:     the frontend axis. Defaults to "astro" — the only supported (and
+#                 only scaffolded) frontend. "custom" (any non-astro frontend) is
+#                 NOT scaffolded yet: Discovery routes custom to the not-available
+#                 stub (references/custom/INSTRUCTIONS.md) before scaffold ever runs,
+#                 so this script should only ever be invoked with "astro". If it is
+#                 invoked with "custom" it exits 4 (recognized, not staged).
 #
-# After scaffold succeeds, read <project-slug>/wix.config.json to extract appId
-# (project's appId) and siteId (used for MCP calls). The orchestrator does that
-# read; this script just runs the npm create.
+# After scaffold succeeds, the project lives in the CURRENT directory (the subdir
+# was flattened away). Read ./wix.config.json to extract appId (project's appId)
+# and siteId (used as --site for `wix token` and in REST call bodies). The
+# orchestrator does that read; this script runs the npm create + the flatten.
 #
 # Behavior:
-#   - Pre-flight validates the slug (regex ^[a-z0-9]{3,20}$).
-#   - Pre-flight requires both args.
+#   - Pre-flight validates the folder name syntax (regex ^[a-z0-9][a-z0-9-]*$).
+#   - Pre-flight requires both positional args.
 #   - Runs `npm create @wix/new@latest headless` with --no-publish + --skip-install
 #     so the orchestrator can deferred-install with its own package set.
-#   - Template ID is the pure-headless blank (vibe-compatible templates trigger
-#     an interactive prompt that blocks non-TTY runs).
+#   - Passes bare `--site-template` so non-interactive scaffolding stays on the
+#     blank starter. Without it, @wix/create-new (>=0.0.72) prompts for a template
+#     choice and aborts in a non-TTY agent shell ("not supported in non-interactive
+#     terminals").
+#   - FLATTENS the scaffolded subdir into CWD (single-folder layout: one `.wix`,
+#     CWD == project == site-root). Interim until the CLI supports in-place create.
 #
 # Exit codes:
 #   0 — ok
-#   2 — argument validation failed
+#   2 — argument validation failed (bad folder name, missing args, unknown --frontend value)
+#   3 — Wix CLI not logged in (defensive; the Discovery pre-flight is the primary check)
+#   4 — frontend value recognized but not scaffolded yet (custom today)
+#   5 — scaffold succeeded but the subdir could not be flattened into CWD (name collision)
 #   <other> — npm create failed; stderr surfaced to caller for orchestrator-side
-#             recovery (auth / invalid-template ladder lives in the orchestrator).
+#             recovery (auth / other scaffold failures live in the orchestrator).
 
 set -euo pipefail
 
-if [[ $# -lt 2 || -z "${1:-}" || -z "${2:-}" ]]; then
-  echo "scaffold.sh: both args required. Got project-slug='${1:-}' brand-name='${2:-}'." >&2
-  echo "Usage: bash scaffold.sh <slug> \"<Brand Name>\" — slug first, brand quoted." >&2
+FRONTEND="astro"
+POSITIONAL=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --frontend)
+      if [[ $# -lt 2 ]]; then
+        echo "scaffold.sh: --frontend requires a value (astro|custom)." >&2
+        exit 2
+      fi
+      FRONTEND="$2"
+      shift 2
+      ;;
+    --frontend=*)
+      FRONTEND="${1#--frontend=}"
+      shift
+      ;;
+    *)
+      POSITIONAL+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ ${#POSITIONAL[@]} -lt 2 || -z "${POSITIONAL[0]:-}" || -z "${POSITIONAL[1]:-}" ]]; then
+  echo "scaffold.sh: both positional args required. Got folder-name='${POSITIONAL[0]:-}' brand-name='${POSITIONAL[1]:-}'." >&2
+  echo "Usage: bash scaffold.sh <folder-name> \"<Brand Name>\" [--frontend astro|custom] — folder name first, brand quoted." >&2
   exit 2
 fi
 
-if [[ ! "$1" =~ ^[a-z0-9]{3,20}$ ]]; then
-  echo "scaffold.sh: project-slug='$1' is not valid." >&2
-  echo "Slug must be 3-20 lowercase alphanumeric chars (no hyphens, no spaces)." >&2
-  echo "Derive from the brand: lowercase, strip non-[a-z0-9], truncate to 20." >&2
+case "$FRONTEND" in
+  astro)
+    ;;
+  custom)
+    echo "scaffold.sh: --frontend=custom is not scaffolded yet — astro is the only supported frontend." >&2
+    echo "Discovery routes custom (non-astro) frontends to references/custom/INSTRUCTIONS.md (the not-available stub) before scaffold; this script should not be invoked with 'custom'." >&2
+    exit 4
+    ;;
+  *)
+    echo "scaffold.sh: unknown --frontend value '$FRONTEND'. Allowed: astro, custom." >&2
+    exit 2
+    ;;
+esac
+
+if [[ ! "${POSITIONAL[0]}" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+  echo "scaffold.sh: folder-name='${POSITIONAL[0]}' is not valid." >&2
+  echo "Folder name must contain only lowercase letters, numbers, and hyphens, and start with a letter or number." >&2
+  echo "Derive it from the brand as a lowercase, npm-safe directory name." >&2
   exit 2
 fi
 
-# Pure-headless blank template. Vibe-compatible templates show an interactive
-# vibe setup prompt that blocks non-TTY contexts — do not substitute.
-TEMPLATE_ID="blank"
+# Defensive auth check — DISCOVERY.md's pre-flight should have caught this
+# already, but scaffold.sh is also a documented standalone entry point
+# (SKILL.md § "When NOT to use this skill"). `npm create @wix/new` requires
+# an active CLI session and otherwise fails mid-run with an opaque error.
+# `wix whoami` exits non-zero on a logged-out session and prints the
+# authenticated email + user id when logged in.
+if ! npx @wix/cli@latest whoami >/dev/null 2>&1; then
+  echo "scaffold.sh: not logged in to Wix CLI." >&2
+  echo "Run 'npx @wix/cli@latest login' and retry." >&2
+  exit 3
+fi
+
+FOLDER="${POSITIONAL[0]}"
 
 npm create @wix/new@latest headless -- \
-  --business-name "$2" \
-  --project-name "$1" \
-  --site-template "$TEMPLATE_ID" \
+  --business-name "${POSITIONAL[1]}" \
+  --folder-name "$FOLDER" \
+  --site-template \
   --no-publish \
   --skip-install
+
+# --- In-place flatten (interim hack) -----------------------------------------
+# The CLI always scaffolds into a named subdir; there is NO in-place option —
+# `headless init` regex-rejects `--folder-name .` ("must contain only lowercase
+# letters, numbers, and hyphens") and offers no --cwd/--here flag. To keep the
+# whole run single-folder (one `.wix`, CWD == project == site-root, no nested
+# `.wix` to reason about), fold the scaffolded subdir up into the current dir.
+#
+# The .wix-merge + mv -n + rmdir logic is identical to flatten.sh (the own-build
+# path's framework-agnostic flatten), so we delegate to it rather than duplicate.
+# flatten.sh lives next to this script; resolve its path relative to our own dir
+# so the call works regardless of CWD. (Both exit 5 on the same name-collision.)
+# When the CLI gains `--folder-name .` (or --cwd), the TODO to drop the flatten
+# lives in flatten.sh.
+if [[ -d "$FOLDER" ]]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  bash "$SCRIPT_DIR/flatten.sh" "$FOLDER"
+fi
+# -----------------------------------------------------------------------------

package/skills/wix-headless/scripts/seed-utilities.sh

@@ -1,21 +1,30 @@
 #!/usr/bin/env bash
-# Copy the skill's shared utilities into the project's src/utils/ and strip the
-# Astro starter cruft that ships with the blank template.
+# Frontend-track project prep: copy the skill's shared utilities into the
+# project's src/utils/ and strip the Astro starter cruft that ships with the
+# blank template. This is local-project (frontend) work, not backend seeding —
+# the orchestrator only runs it in scaffold mode (integrate mode has no
+# skill-written frontend to prep, so it is never invoked there).
 #
 # Usage (both modes work):
-#   bash <SKILL_ROOT>/scripts/seed-utilities.sh                # installed tgz
-#   bash <(curl -s https://dev.wix.com/skills/wix-headless/scripts/seed-utilities.sh)
+#   bash <SKILL_ROOT>/scripts/seed-utilities.sh --template astro
+#   bash <(curl -s https://dev.wix.com/skills/wix-headless/scripts/seed-utilities.sh) --template astro
 #
-# Run from the project directory (CWD = <project>/). The script auto-detects
+# --template (optional, default astro): astro
+#   Astro is the only frontend the skill scaffolds and preps, so the value is
+#   always "astro". Custom (non-astro) frontends route to the not-available stub
+#   (references/custom/INSTRUCTIONS.md) and never reach this script.
+#
+# Run from the project directory (CWD = <scaffold>/). The script auto-detects
 # whether shared-utilities is available on disk (tgz install) and falls back
 # to fetching from the well-known URL when streamed via process substitution
 # (BASH_SOURCE is /dev/fd/N, so the on-disk lookup naturally falls through).
 #
 # Behavior:
-#   - Copies the three shared utility files into src/utils/ — never overwrites
-#     an existing file (users can drop in their own version to override).
-#   - Removes Astro starter cruft (Welcome.astro + marketing SVGs) that ships
-#     with the blank template but is never imported by the build skill.
+#   - Copies the three shared utility files into src/utils/ for both templates —
+#     never overwrites an existing file (users can drop in their own version).
+#   - On --template=astro, removes Astro starter cruft (Welcome.astro + marketing
+#     SVGs) that ships with the blank template but is never imported by the build
+#     skill.
 #
 # Shared utilities copied:
 #   - wix-image.ts  — media URL resolver (used by stores, blog, cms)
@@ -27,6 +36,33 @@ set -euo pipefail
 SKILL_URL="https://dev.wix.com/skills/wix-headless"
 UTILS=(analytics.ts ricos.ts wix-image.ts)
 
+TEMPLATE="astro"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --template)
+      TEMPLATE="$2"
+      shift 2
+      ;;
+    --template=*)
+      TEMPLATE="${1#--template=}"
+      shift
+      ;;
+    *)
+      echo "seed-utilities.sh: unexpected arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+case "$TEMPLATE" in
+  astro) ;;
+  *)
+    echo "seed-utilities.sh: --template must be 'astro' (the only supported frontend); got $TEMPLATE" >&2
+    echo "(Custom non-astro frontends route to the stub and never reach this script.)" >&2
+    exit 2
+    ;;
+esac
+
 # Mode detection: prefer on-disk skill root if the sibling dir exists, else
 # fetch over HTTP. Covers both tgz install and `bash <(curl ...)` streaming.
 SHARED_UTILS_DIR=""
@@ -50,6 +86,8 @@ for f in "${UTILS[@]}"; do
   fi
 done
 
-# Astro starter cruft cleanup.
-rm -f src/components/Welcome.astro
-rm -f src/assets/astro.svg src/assets/wix.svg src/assets/background.svg
+# Astro starter cruft cleanup — astro template only.
+if [[ "$TEMPLATE" == "astro" ]]; then
+  rm -f src/components/Welcome.astro
+  rm -f src/assets/astro.svg src/assets/wix.svg src/assets/background.svg
+fi

package/skills/wix-headless/scripts/write-decorative-json.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Write the decorative slot→URL map to src/decorative-images.json for a
+// framework-SPA (`own`) frontend. This is the `own`-branch analog of
+// patch-decorative-slots.mjs (which injects <img> into .astro source) — but
+// instead of patching framework source, the generated SPA *imports* this JSON
+// and its hero/about components read it, with a themed-block fallback when a
+// slot is empty/absent. This avoids fragile JSX/Vue/Svelte string-patching and
+// mirrors how the SPA already imports .wix/design-tokens.css.
+//
+// It is called twice in the `own` flow (BUILD-own-build.md):
+//   1. At bootstrap, with EMPTY stdin → writes `{}` (placeholder), so the app
+//      builds + renders themed blocks even if Image Phase 1 never runs.
+//   2. At the seed gate (ai-generated only), with Image Phase 1's data.slots
+//      piped in → OVERWRITES the file with the real URLs. This MUST happen
+//      before `npm run build` (Vite resolves the JSON import at build time).
+//
+// Writes to src/decorative-images.json (inside the Vite root, so it is always
+// importable — unlike .wix/, which may sit outside the bundler root).
+//
+// Usage:
+//   echo '{"hero":"https://...","about":"https://..."}' \
+//     | node write-decorative-json.mjs <project-dir>
+//   : | node write-decorative-json.mjs <project-dir>     # placeholder {}
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const projectDir = process.argv[2] ?? process.cwd();
+
+let slots = {};
+if (!process.stdin.isTTY) {
+  const raw = readFileSync(0, "utf8").trim();
+  if (raw) {
+    try {
+      slots = JSON.parse(raw);
+    } catch (e) {
+      console.error(JSON.stringify({ status: "error", reason: `stdin is not valid JSON (${e.message})` }));
+      process.exit(2);
+    }
+    if (!slots || typeof slots !== "object" || Array.isArray(slots)) {
+      console.error(JSON.stringify({ status: "error", reason: "expected a JSON object mapping slot keys to URLs" }));
+      process.exit(2);
+    }
+  }
+}
+
+// Drop empty/falsy URLs so the component's themed-block fallback kicks in.
+const clean = {};
+for (const [k, v] of Object.entries(slots)) {
+  if (typeof v === "string" && v.trim()) clean[k] = v.trim();
+}
+
+const srcDir = join(projectDir, "src");
+mkdirSync(srcDir, { recursive: true });
+const dest = join(srcDir, "decorative-images.json");
+writeFileSync(dest, JSON.stringify(clean, null, 2) + "\n");
+
+console.log(JSON.stringify({
+  status: Object.keys(clean).length ? "ok" : "placeholder",
+  file: dest,
+  slots: Object.keys(clean),
+}, null, 2));

package/skills/wix-manage/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: wix-manage
-description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, events, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce."
+description: "Wix business solution management recipes — REST API operations for configuring and managing Wix business solutions. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, rich-content, sites, blog, calendar, domains, site-properties, ecommerce."
 compatibility: Requires Wix REST API access (API key or OAuth).
 ---
 
 # Management Recipes Index
 
+> **Standard call shape for every curl example across these recipes.** The `<AUTH>` placeholder in example curls is shorthand for the `Authorization` header only; body-bearing calls also need `Content-Type: application/json`.
+
 ## What Are Management Recipes?
 
 **Management recipes are for REST API operations** that configure, set up, and manage Wix business entities on your site. These recipes use REST API calls and are designed for:
@@ -155,6 +157,7 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 #### Config & API References
 - [API: Recommendation Tracking](references/ecommerce/api-recommendation-tracking.md)
+- [API: Shipping Delivery](references/ecommerce/api-shipping.md)
 - [Setup: Discount Rules](references/ecommerce/setup-discount-rules.md)
 - [Setup: Coupons](references/ecommerce/setup-coupons.md)
 - [Setup: Shipping Regions](references/ecommerce/setup-shipping-regions.md)
@@ -171,13 +174,6 @@ These recipes do NOT cover frontend development or SDK usage for displaying data
 
 ---
 
-## Events
-
-### [List Events](references/events/list-events.md)
-**Technical:** Queries events from Wix Events using Events API. Covers field sets (DETAILS, URLS, REGISTRATION), filtering by status/date, and pagination.
-
----
-
 ## Forms
 
 ### [Create Form](references/forms/create-form.md)

package/skills/wix-manage/references/blog/how-to-create-blog-posts.md

@@ -5,6 +5,8 @@ description: Creates and publishes blog posts using Blog Posts API. Covers Ricos
 
 **Article: Create and Publish Blog Posts with Rich Content and Images**
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
+
 ---
 
 ## Description

package/skills/wix-manage/references/cms/cms-data-items-crud.md

@@ -4,6 +4,8 @@ description: "Add, query, update, and delete items in CMS collections. Use this
 ---
 # CMS Data Items CRUD
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
+
 This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
 
 ## Prerequisites
@@ -365,6 +367,8 @@ curl -X DELETE \
 | `IMAGE` | Image reference (HTTP url or wix:image://v1/{mediaId}/{friendlyName}) | `"wix:image://v1/3f72369f2219e2ee853e9e3df0217ce1.jpg/Colorful%20Business%20Cards.jpg"` |
 | `VIDEO` | Video reference (HTTP url or wix:video://v1/{mediaId}/{friendlyName}) | `"wix:video://v1/11062b_484182533ede4b9a81329daf20238867/Sketching%20Design%20Concepts#posterUri=11062b_484182533ede4b9a81329daf20238867f000.jpg&posterWidth=1920&posterHeight=1080"` |
 | `DOCUMENT` | Document reference  (HTTP url or wix:document://v1/{mediaId}) | `"wix:document://v1/..."` |
+| `MEDIA_IMAGE` | Wix Media Image | `{ "url": "http://...", "height": 640, "width": 480, "alt": "Picture" }` |
+| `MEDIA_VECTOR_ART` | Wix Media Vector Art | `{ "uri": "wix:vector://v1/...", "viewBox": "0 0 100 100", "contentType": "shape", "svgContent": "<svg>...</svg>" }` |
 | `URL` | Web URL | `"https://example.com"` |
 | `RICH_TEXT` | HTML content | `"<p>Rich text</p>"` |
 | `EMAIL` | Email | `"example@wix.com"` |

package/skills/wix-manage/references/cms/cms-references-and-relationships.md

@@ -4,6 +4,8 @@ description: "Add, replace, or remove items from MULTI_REFERENCE fields. Use ins
 ---
 # CMS References & Relationships
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
+
 This recipe covers linking CMS collections together using reference fields.
 
 ## Prerequisites

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -4,6 +4,8 @@ description: Create and modify CMS collection structures. Covers listing collect
 ---
 # CMS Schema Management
 
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
+
 This recipe covers managing the structure (schema) of Wix CMS collections using the REST API.
 
 ## Prerequisites
@@ -120,6 +122,8 @@ curl -X GET \
 | `DATE` | Date only | `"2024-01-15"` |
 | `DATETIME` | Date and time | `{ "$date": "2024-01-15T10:00:00.000Z" }` |
 | `IMAGE` | Image reference | `"wix:image://v1/..."` |
+| `MEDIA_IMAGE` | Wix Media Image | `{ "url": "http://...", "height": 640, "width": 480, "alt": "Picture" }` |
+| `MEDIA_VECTOR_ART` | Wix Media Vector Art | `{ "uri": "wix:vector://v1/...", "viewBox": "0 0 100 100", "contentType": "shape", "svgContent": "<svg>...</svg>" }` |
 | `URL` | Web URL | `"https://example.com"` |
 | `RICH_TEXT` | HTML content | `"<p>Rich text</p>"` |
 | `ARRAY_STRING` | Array of strings | `["tag1", "tag2"]` |