@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-harmony-editor/scripts/launch.sh

@@ -0,0 +1,359 @@
+#!/bin/bash
+# Launch a separate, headed Chrome profile for a Wix Harmony editor session.
+# The Chrome DevTools endpoint is loopback-only and is never printed.
+#
+# Cross-platform: macOS, Linux (including headless boxes with no physical
+# display), WSL, and Windows Git Bash/MSYS are detected and a usable
+# Chrome/Chromium binary is located for each. Nothing here is ever
+# substituted silently: if no browser can be found, the script fails with
+# an actionable message naming what to install.
+#
+# Headless Linux note: Wix Harmony intentionally requires a HEADED browser
+# (never --headless) so a human can interact with a Wix sign-in page if one
+# appears. A machine with no physical monitor can still run headed Chrome
+# against a virtual framebuffer (Xvfb) - this script will start one
+# automatically on Linux if $DISPLAY isn't already set and Xvfb is
+# installed. Xvfb itself is a prerequisite install (see the error message
+# below); this script does not silently `sudo apt-get install` anything on
+# your behalf.
+#
+# If Wix shows a sign-in page while running under a virtual display, you
+# need some way to actually see and interact with it. Options, from
+# simplest to most complete:
+#   - Take a screenshot from Playwright (page.screenshot()) to see the
+#     current page - good enough to tell what state the editor is in, but
+#     not interactive.
+#   - Run a lightweight VNC server against the same DISPLAY, e.g.:
+#       x11vnc -display :99 -localhost -nopw
+#     then forward the VNC port (default 5900) to a machine with a VNC
+#     client. This gives full interactive mouse/keyboard control, but you
+#     are responsible for setting up that port forward for your sandbox.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PORT="${PW_PORT:-9333}"
+PROFILE="${WIX_HARMONY_PROFILE_DIR:-${TMPDIR:-/tmp}/wix-harmony-editor-profile}"
+EDITOR_URL="${1:-about:blank}"
+
+umask 077
+mkdir -p "$PROFILE"
+chmod 700 "$PROFILE"
+
+CHROME_PID_FILE="${PROFILE}/chrome.pid"
+
+# True when the process recorded at launch is still alive and was started with THIS profile and
+# port, so a responding CDP endpoint is provably the Chrome this script launched for this profile.
+launched_chrome_is_ours() {
+  local pid cmd
+  [[ -f "$CHROME_PID_FILE" ]] || return 1
+  pid="$(tr -d '[:space:]' <"$CHROME_PID_FILE" 2>/dev/null || true)"
+  [[ "$pid" =~ ^[0-9]+$ ]] || return 1
+  kill -0 "$pid" 2>/dev/null || return 1
+  cmd="$(ps -p "$pid" -o args= 2>/dev/null || true)"
+  [[ "$cmd" == *"--user-data-dir=${PROFILE}"* && "$cmd" == *"--remote-debugging-port=${PORT}"* ]]
+}
+
+# If a Wix Harmony Chrome is already up on this port, nothing else to do. Any other responding
+# CDP endpoint (another Chrome, a Playwright browser) is NOT reused: the copy tools would drive the
+# wrong browser, profile or site.
+if curl -fsS -m 2 "http://127.0.0.1:${PORT}/json/version" >/dev/null 2>&1; then
+  if launched_chrome_is_ours; then
+    echo "Wix Harmony Chrome is already running on local CDP port ${PORT}."
+    exit 0
+  fi
+  echo "Local CDP port ${PORT} is already served by a browser this script did not launch for" >&2
+  echo "profile ${PROFILE}. Not reusing it. Stop that browser, or set PW_PORT to a free port" >&2
+  echo "(and use the same PW_PORT for every script), then re-run." >&2
+  exit 1
+fi
+
+# --- OS detection -----------------------------------------------------
+detect_os() {
+  local uname_s
+  uname_s="$(uname -s 2>/dev/null || echo unknown)"
+  case "$uname_s" in
+    Darwin)
+      echo macos
+      ;;
+    Linux)
+      if grep -qi microsoft /proc/version 2>/dev/null; then
+        echo wsl
+      else
+        echo linux
+      fi
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      echo windows
+      ;;
+    *)
+      echo unknown
+      ;;
+  esac
+}
+
+OS_TYPE="$(detect_os)"
+
+# --- Chrome/Chromium discovery -----------------------------------------
+# Prints the resolved binary path on stdout, or nothing if not found.
+find_chrome_macos() {
+  local candidates=(
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    "$HOME/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    "/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
+    "/Applications/Chromium.app/Contents/MacOS/Chromium"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    if [[ -x "$c" ]]; then
+      echo "$c"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Finds the newest Playwright-managed Chromium build under its cache dir,
+# e.g. ~/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome. This is
+# the browser `npx playwright install` downloads; it's a reasonable
+# fallback on Linux boxes with no system Chrome package installed.
+find_chrome_playwright_linux() {
+  local pw_dir="${PLAYWRIGHT_BROWSERS_PATH:-$HOME/.cache/ms-playwright}"
+  [[ -d "$pw_dir" ]] || return 1
+  local newest
+  newest="$(find "$pw_dir" -maxdepth 1 -type d -iname 'chromium-*' 2>/dev/null | sort -V | tail -1)"
+  [[ -n "$newest" ]] || return 1
+  local sub
+  for sub in chrome-linux64/chrome chrome-linux/chrome; do
+    if [[ -x "$newest/$sub" ]]; then
+      echo "$newest/$sub"
+      return 0
+    fi
+  done
+  return 1
+}
+
+find_chrome_linux() {
+  local bin
+  for bin in google-chrome google-chrome-stable chromium chromium-browser; do
+    if command -v "$bin" >/dev/null 2>&1; then
+      command -v "$bin"
+      return 0
+    fi
+  done
+  find_chrome_playwright_linux && return 0
+  return 1
+}
+
+find_chrome_wsl() {
+  # Prefer a native Linux Chrome/Chromium installed inside the WSL distro,
+  # then fall back to the Windows-side install reachable under /mnt/c.
+  find_chrome_linux && return 0
+  local candidates=(
+    "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
+    "/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    if [[ -x "$c" ]]; then
+      echo "$c"
+      return 0
+    fi
+  done
+  return 1
+}
+
+find_chrome_windows() {
+  local bin
+  for bin in chrome.exe chromium.exe; do
+    if command -v "$bin" >/dev/null 2>&1; then
+      command -v "$bin"
+      return 0
+    fi
+  done
+  local candidates=(
+    "/c/Program Files/Google/Chrome/Application/chrome.exe"
+    "/c/Program Files (x86)/Google/Chrome/Application/chrome.exe"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    if [[ -x "$c" ]]; then
+      echo "$c"
+      return 0
+    fi
+  done
+  return 1
+}
+
+CHROME=""
+case "$OS_TYPE" in
+  macos)   CHROME="$(find_chrome_macos || true)" ;;
+  linux)   CHROME="$(find_chrome_linux || true)" ;;
+  wsl)     CHROME="$(find_chrome_wsl || true)" ;;
+  windows) CHROME="$(find_chrome_windows || true)" ;;
+esac
+
+if [[ -z "$CHROME" ]]; then
+  case "$OS_TYPE" in
+    macos)
+      echo "No Google Chrome or Chromium install was found under /Applications." >&2
+      echo "Install Google Chrome (https://www.google.com/chrome/) and retry." >&2
+      ;;
+    linux)
+      echo "No Chrome/Chromium binary was found on PATH (checked: google-chrome," >&2
+      echo "google-chrome-stable, chromium, chromium-browser), and no Playwright-managed" >&2
+      echo "Chromium was found under \${PLAYWRIGHT_BROWSERS_PATH:-~/.cache/ms-playwright}." >&2
+      echo "Install one of:" >&2
+      echo "  sudo apt-get install -y chromium-browser   # Debian/Ubuntu" >&2
+      echo "  sudo dnf install -y chromium               # Fedora/RHEL" >&2
+      echo "or fetch Playwright's bundled browser: npx playwright install chromium" >&2
+      ;;
+    wsl)
+      echo "No Chrome/Chromium binary was found inside WSL or under /mnt/c/Program Files." >&2
+      echo "Install Chrome/Chromium inside the WSL distro, or install Google Chrome on" >&2
+      echo "the Windows host so it is reachable at /mnt/c/Program Files/Google/Chrome/..." >&2
+      ;;
+    windows)
+      echo "No chrome.exe/chromium.exe was found on PATH or under Program Files." >&2
+      echo "Install Google Chrome (https://www.google.com/chrome/) and retry." >&2
+      ;;
+    *)
+      echo "Could not detect this OS (uname -s reported an unrecognized value) and" >&2
+      echo "no Chrome/Chromium binary could be located automatically." >&2
+      ;;
+  esac
+  exit 1
+fi
+
+# --- Headless Linux: provide a virtual display if none exists ----------
+# Real desktops (macOS, WSL with WSLg, Windows) already have a display.
+# A headless Linux sandbox does not, but headed Chrome still needs one to
+# start; Xvfb provides a virtual framebuffer it can render into.
+if [[ "$OS_TYPE" == "linux" && -z "${DISPLAY:-}" ]]; then
+  XVFB_DISPLAY_NUM="${WIX_HARMONY_XVFB_DISPLAY:-99}"
+  XVFB_LOCK="/tmp/.X${XVFB_DISPLAY_NUM}-lock"
+  # An X11 lock file's mere existence is not proof a usable Xvfb is behind it: if a prior Xvfb
+  # was killed uncleanly (OOM, `kill -9`, a container restart) the lock file survives with no
+  # process left to serve the display, and Chrome would then fail against a dead display with
+  # only a generic ~20s CDP-timeout error instead of this script's own actionable diagnosis. Per
+  # the standard X11 lock-file convention, the file's content IS the owning process's pid (ASCII
+  # decimal, whitespace-padded) -- check it directly rather than trusting the file's presence.
+  if [[ -e "$XVFB_LOCK" ]]; then
+    xvfb_lock_pid="$(tr -d '[:space:]' < "$XVFB_LOCK" 2>/dev/null || true)"
+    xvfb_lock_stale=0
+    if [[ -z "$xvfb_lock_pid" ]]; then
+      xvfb_lock_stale=1
+    elif [[ ! -e "/proc/$xvfb_lock_pid" ]]; then
+      # BUG FIX (code review, round 3): `kill -0` alone cannot tell "no such process" (ESRCH,
+      # truly stale) apart from "process alive, owned by a different user" (EPERM) -- both return
+      # the same nonzero exit code. Checking /proc/<pid> directly (this branch only runs under
+      # linux, see the OS_TYPE guard above) answers the ESRCH question on its own: no /proc entry
+      # means the process is genuinely gone.
+      # NOTE (code review, round 6): this is the same EPERM/ESRCH distinction as
+      # `skills/wix-replatform/lib/local-state.js`'s `isProcessAlive` (consolidated there with
+      # `execution-health-check.js` in round 5), reimplemented here in bash since JS and bash
+      # can't share code cheaply. A future fix to one should prompt a check of the other.
+      xvfb_lock_stale=1
+    elif ! kill -0 "$xvfb_lock_pid" 2>/dev/null; then
+      # /proc/<pid> exists (a real process is running under that pid) but kill -0 still failed:
+      # this is EPERM, not ESRCH -- a live Xvfb owned by a different UID (e.g. a shared
+      # container/sandbox). Misdiagnosing this as dead and deleting its lock would let a second
+      # Xvfb start and race to bind the same display. Fail loudly instead of guessing.
+      echo "Xvfb lock ${XVFB_LOCK} names pid ${xvfb_lock_pid}, which is running but owned by a" >&2
+      echo "different user (kill -0 was denied) -- this looks like a LIVE Xvfb this script does" >&2
+      echo "not have permission to inspect or replace, not a stale lock from a dead process." >&2
+      echo "Remove ${XVFB_LOCK} yourself once you've confirmed it's safe, or export DISPLAY to" >&2
+      echo "point at a display this script can use." >&2
+      exit 1
+    fi
+    if [[ "$xvfb_lock_stale" -eq 1 ]]; then
+      echo "Removing stale Xvfb lock ${XVFB_LOCK} (pid ${xvfb_lock_pid:-unknown} is not running)." >&2
+      # `|| true`: under `set -e`, an `rm -f` that genuinely fails (permission denied, or the
+      # path turning out not to be a plain file) would otherwise abort the script right here with
+      # rm's own generic error, before the verification below ever runs. Trust the follow-up
+      # existence check, not rm's exit code, to decide whether removal actually happened.
+      rm -f "$XVFB_LOCK" || true
+      if [[ -e "$XVFB_LOCK" ]]; then
+        # BUG FIX (code review, round 3): `rm -f` exits 0 even when it silently fails to remove a
+        # path it lacks permission for (e.g. a sticky /tmp directory owned by another user, or the
+        # path turning out not to be a plain file at all) -- verify removal actually happened
+        # rather than trusting rm's exit code. Falling through here with the lock still present
+        # would skip starting a fresh Xvfb below and export DISPLAY at a dead display.
+        echo "Failed to remove stale Xvfb lock ${XVFB_LOCK} (no permission, or it is not a" >&2
+        echo "plain file?). Remove it manually and re-run, or export DISPLAY yourself." >&2
+        exit 1
+      fi
+    fi
+  fi
+  if [[ ! -e "$XVFB_LOCK" ]]; then
+    if ! command -v Xvfb >/dev/null 2>&1; then
+      echo "No \$DISPLAY is set and Xvfb is not installed, so headed Chrome cannot" >&2
+      echo "start on this headless Linux machine. Install it, e.g.:" >&2
+      echo "  sudo apt-get install -y xvfb   # Debian/Ubuntu" >&2
+      echo "  sudo dnf install -y xorg-x11-server-Xvfb   # Fedora/RHEL" >&2
+      echo "then re-run this script (or export DISPLAY yourself if you already have" >&2
+      echo "a virtual/real display running)." >&2
+      exit 1
+    fi
+    nohup Xvfb ":${XVFB_DISPLAY_NUM}" -screen 0 1280x800x24 \
+      >"${PROFILE}/xvfb.log" 2>&1 &
+    xvfb_pid=$!
+    disown
+    # A backgrounded Xvfb takes a moment to create its lock file and start serving the display;
+    # `sleep 1` then unconditionally exporting DISPLAY assumed it always makes that window, with no
+    # check that it actually came up. If Xvfb itself failed fast (missing X extension, a stale
+    # /tmp permission problem, port/display already in some other conflicting state), the old code
+    # would still export DISPLAY and hand Chrome a dead display -- Chrome would then fail ~20s
+    # later against a generic CDP-timeout, with nothing pointing back at Xvfb as the real cause.
+    # Poll for the lock file actually appearing (proof Xvfb bound the display), or the backgrounded
+    # pid dying (proof it won't), across a short retry window -- the same diagnostic quality as the
+    # stale-lock check above this block, rather than a blind fixed sleep.
+    xvfb_ready=0
+    for _ in $(seq 1 30); do
+      if [[ -e "$XVFB_LOCK" ]]; then
+        # The lock appearing is not proof Xvfb stays up: it can create the lock and then exit.
+        # Re-check the pid after a short settle before trusting the display.
+        sleep 0.3
+        if kill -0 "$xvfb_pid" 2>/dev/null; then
+          xvfb_ready=1
+        fi
+        break
+      fi
+      if ! kill -0 "$xvfb_pid" 2>/dev/null; then
+        break
+      fi
+      sleep 0.1
+    done
+    if [[ "$xvfb_ready" -ne 1 ]]; then
+      echo "Xvfb did not come up on display :${XVFB_DISPLAY_NUM} within 3s (lock file" >&2
+      echo "${XVFB_LOCK} never appeared). Check ${PROFILE}/xvfb.log for its own error output," >&2
+      echo "e.g. a missing X extension, a permissions problem under /tmp, or the display" >&2
+      echo "number already being used by something else that isn't Xvfb itself." >&2
+      exit 1
+    fi
+  fi
+  export DISPLAY=":${XVFB_DISPLAY_NUM}"
+  echo "No \$DISPLAY was set; using virtual display ${DISPLAY} (Xvfb) for headed Chrome." >&2
+  echo "If Wix shows a sign-in page, you'll need a way to see/interact with this" >&2
+  echo "virtual display - e.g. 'x11vnc -display ${DISPLAY} -localhost -nopw' plus a" >&2
+  echo "forwarded VNC port, or take Playwright screenshots to inspect page state." >&2
+fi
+
+nohup "$CHROME" \
+  --user-data-dir="$PROFILE" \
+  --remote-debugging-address=127.0.0.1 \
+  --remote-debugging-port="$PORT" \
+  --no-first-run \
+  --no-default-browser-check \
+  "$EDITOR_URL" >"${PROFILE}/chrome.log" 2>&1 &
+echo "$!" >"$CHROME_PID_FILE"
+
+for _ in $(seq 1 40); do
+  if curl -fsS -m 2 "http://127.0.0.1:${PORT}/json/version" >/dev/null 2>&1; then
+    echo "Wix Harmony Chrome is ready on local CDP port ${PORT}."
+    exit 0
+  fi
+  sleep 0.5
+done
+
+echo "Chrome did not expose its local CDP endpoint. Check ${PROFILE}/chrome.log." >&2
+exit 1

package/skills/wix-headless/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-headless
-description: "Connect Wix business services (Stores, Bookings, CMS, Blog, Events, Forms, and more) to a Wix Headless frontend — infer the needed capabilities, install the apps, seed backend content, and produce an SDK-integration guide. For managed (Wix-hosted) projects it can also build the frontend: scaffold a new site (create) or wire an existing/brought-in design (connect), then build and release. Works across managed, self-managed, and stripe project types. Triggers: set up a Wix Headless backend, add Wix business features to my app, build or host a Wix site, connect/implement this design with Wix."
+description: "Connect Wix business services (Stores, Bookings, Donations, CMS, Blog, Events, Forms, and more) to a Wix Headless frontend — infer the needed capabilities, install the apps, seed backend content, and produce an SDK-integration guide. For managed (Wix-hosted) projects it can also build the frontend: scaffold a new site (create) or wire an existing/brought-in design (connect), then build and release. Works across managed, self-managed, and stripe project types. Triggers: set up a Wix Headless backend, add Wix business features to my app, accept donations, build or host a Wix site, connect/implement this design with Wix."
 allowed-tools:
   - Bash(curl *)
   - Bash(npx @wix/cli@latest *)
@@ -107,6 +107,11 @@ Each Wix call uses the universal call shape (`SETUP.md` §1) with `$TOKEN`/`$SIT
 
 > **Don't smoke-test the frontend locally unless the user asks to verify.** The deliverable is the built-and-released site (managed) or the SDK guide (backend-only) — not a local test report. By **default do not** start a dev server (`wix dev` / `astro dev` / `npm run dev`) to curl pages, drive the cart / booking / login flow, or launch a headless browser: correctness comes from following the recipes, real errors surface at `wix build` / `wix release`, and a headless run can't complete an interactive login or a real payment anyway — so these loops routinely burn minutes of wall for little signal (this is distinct from, and in addition to, the "release once at the very end" rule — that one only bans extra *build+release* cycles, not dev-server testing). **Only** spin up a dev server and smoke-test when the user's prompt **explicitly asks to verify / test / confirm it works** — and then keep it to a single lightweight pass (pages compile and render), not a full purchase/booking/login drive. The one post-release check in `<TYPE_DIR>/DEPLOYMENT.md` is the sanctioned verification.
 
+**Donations exception to the smoke-test policy above:** for a build that accepts donations, follow
+the bounded anonymous API handoff check in `references/inline-recipes/how-to-code-donations.md`
+before claiming it works. It does not authorize a payment or campaign mutation, and does not require
+a dev-server testing loop. That recipe also defines the separate hosted-checkout and payment checks.
+
 ## Path resolution
 
 Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL.md`); hold the absolute path in scratch. Then resolve the project type to its folder and hold it too:
@@ -123,7 +128,7 @@ Compute `<SKILL_ROOT>` from this file (`<SKILL_ROOT>/SKILL.md` — strip `/SKILL
 | Image generation (opt-in; agnostic) | `<SKILL_ROOT>/references/IMAGE_GENERATION.md` |
 | Design — fallback visual quality bar for the built frontend, when the user gave no design direction of their own (managed **create** only) | `<SKILL_ROOT>/references/DESIGN.md` |
 | Content — fallback copy quality bar for the built frontend, when the user gave no copy/voice direction of their own (managed **create** only) | `<SKILL_ROOT>/references/CONTENT.md` |
-| Experience overlays — a vertical's own design + copy bar on top of DESIGN/CONTENT (optional per vertical; read when that vertical is loaded) | `<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md` (today: `experience-store.md`) |
+| Experience overlays — a vertical's own design + copy bar on top of DESIGN/CONTENT (optional per vertical; read when that vertical is loaded) | `<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md` (today: `experience-store.md`, `experience-donations.md`) |
 | AI features — text/chat + embeddings (opt-in; agnostic) | `<SKILL_ROOT>/references/AI_FEATURES.md` |
 | Feedback — relay the user's headless-experience feedback to Wix (opt-in; user-approved) | `<SKILL_ROOT>/references/FEEDBACK.md` |
 | **Authentication** — obtain `$TOKEN`/`$SITE_ID`/`clientId` (project-type-specific) | `<TYPE_DIR>/AUTHENTICATION.md` |

package/skills/wix-headless/references/CAPABILITIES.md

@@ -19,7 +19,12 @@ Each built vertical has three parts (the latter two scoped to `create`/backend-o
 
 ## Built verticals — installed, seeded, and described in the Handoff
 
-The verticals the skill operates end-to-end today: **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio** (with `forms` as the floor when nothing richer is named).
+The verticals the skill operates end-to-end today: **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio · donations** (with `forms` as the floor when nothing richer is named).
+
+### donations — accept contributions to a cause
+- **Intent:** donate / fundraising / charitable giving / donation campaign / recurring donation. This is not a generic contact form, merchandise purchase or Pricing Plans membership.
+- **Required site features:** a clear giving entry point; live campaign discovery when there are several causes (a single-cause form otherwise); campaign detail with the configured amount/frequency choices and optional features; a working hosted checkout handoff; an honest return/thank-you state.
+- **Implementation checklist:** design from the cause and supplied content; bound mobile imagery so the giving decision is easy to reach; show configured impact text, custom limits, notes and optional fee coverage; make recurring commitments explicit; progress only when configured/readable; no fabricated tax, donor or impact claims. Read the shared Donations experience reference linked by `how-to-code-donations.md`.
 
 ### stores — sell products
 - **Intent:** sell / shop / products / catalog / merch / store.

package/skills/wix-headless/references/DISCOVERY.md

@@ -32,7 +32,7 @@ Discovery is pure inference — it needs **no authentication** and is **agnostic
 
 Read the **user intent** (+ optional project signals: `package.json` name, README, visible copy) against the vertical index in `references/CAPABILITIES.md` — each entry there carries the intent signals that point to it. Pick every vertical that genuinely fits → `verticals[]`. Multiple signals → multiple capabilities. On ambiguity, prefer the more specific vertical; if nothing dynamic is named, fall to the **forms** floor (a contact form). **Never return an empty set.**
 
-Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio** (`CAPABILITIES.md` § "Built verticals"). If intent points squarely at a vertical outside that set, note it plainly as not-yet-wired (per the index) and resolve the rest; don't force an unrelated capability in its place.
+Resolve to the skill's operational set — **stores · blog · cms · forms · events · bookings · rentals · pricing-plans · restaurants · portfolio · donations** (`CAPABILITIES.md` § "Built verticals"). If intent points squarely at a vertical outside that set, note it plainly as not-yet-wired (per the index) and resolve the rest; don't force an unrelated capability in its place.
 
 ## 2 · Infer brand
 
@@ -54,6 +54,7 @@ For each capability, build its `intent.<cap>` block — the inputs the seed step
 | pricing-plans | `{ planCount, tiersNamed: [] }` | `planCount: 2` (e.g. Basic / Pro), monthly billing |
 | restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (chef's table, tasting menu) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
 | portfolio | `{ collections: [{ name }], projectCount }` | one brand-derived collection, `projectCount: 3` |
+| donations | `{ campaigns: [{ name, frequencies?, presets?, customAmount?, goal?, comments?, askCoverFee? }] }` | Reuse existing campaigns. For an authorized new setup, one cause; use only approved amounts/impact claims/goals and offered frequencies. Do not invent fundraising facts. |
 
 Counts are deliberately small (the seed shows the shape, not a full catalog).
 

package/skills/wix-headless/references/SDK_HANDOFF.md

@@ -36,6 +36,7 @@ Before implementing a capability, Read the local recipe linked in its row.
 
 | Capability | Package(s) | Required recipe |
 |---|---|---|
+| donations | `@wix/donations` + `@wix/ecom` + `@wix/redirects` | `how-to-code-donations.md` — campaign reads, numeric donation options, Cart V2 → hosted redirect, diagnostics and anonymous verification; follow its shared experience reference. |
 | stores | `@wix/stores` + `@wix/categories` (+ `@wix/ecom`, `@wix/redirects` for cart/checkout) | `how-to-code-a-store.md` — Catalog V3 gallery (sort/filter/paging), product page (variants, prices, ribbons), Cart V2 + checkout, and what a complete storefront shows. |
 | blog | `@wix/blog` (+ `@wix/ricos` to render `richContent`; **`@wix/comments` + `@wix/members`** when the blog has comments/members; `@wix/blog` `likes` when the site has members) | `how-to-code-a-blog.md` — Blog V3 read/render + member features (likes, comments). Supplement: <https://dev.wix.com/docs/sdk/business-solutions/blog.md>. |
 | cms | `@wix/data` | `how-to-code-cms.md` — `items.query` read contract. |
@@ -74,10 +75,14 @@ Everything else the host resolves live from the queries in §3. (Static platform
 - **Gating is a LIVE signal, never a hardcoded id list.** Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read **at request time** — a queryable flag carried on the content (a `members-only` blog category/tag or a boolean CMS field) and live coverage/eligibility (Cart V2's `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships`, or the member's active-order `planId`s matched against **live** Benefit-Program coverage). **Never** gate on a frozen set of "premium" slugs/ids or a seed-time `plan→service` map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See `how-to-code-a-blog.md` (member features) and `how-to-code-pricing-plans.md` (coverage read).
 
 ### 6 · What a complete site must include (per loaded capability)
+When **donations** is loaded, carry the donor-experience reference linked in `how-to-code-donations.md`
+into the handoff. Distinguish anonymous API verification, hosted-checkout verification and an actual
+payment; do not claim one from another or omit the bounded donation handoff check.
+
 For each loaded capability, carry its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` into the guide — in plain product language, lightly tailored to what was seeded. **This is the build spec, not optional polish:** the host should build every *required feature* and cover every *checklist* item. For example, a blog must show the **author** (name + photo), the publish date and reading time, the cover image, and the **full formatted content** (not flattened text) — a posts-list-plus-plain-text-body is incomplete. The host maps these onto its own components using the packages/docs in §3 and the seeded schema in §4.
 
 - State them as the *what* (product behaviour), not the *how* (no component code, no API calls) — the host owns the build.
-- **When a loaded vertical ships an experience overlay** (`references/inline-recipes/experience-<vertical>.md`; today `experience-store.md`), point the host at it alongside the checklist — it is that vertical's design and copy bar (surfaces, first-viewport rules, truthful copy), read after the general `DESIGN.md`/`CONTENT.md`.
+- **When a loaded vertical ships an experience overlay** (`references/inline-recipes/experience-<vertical>.md`; today `experience-store.md`, `experience-donations.md`), point the host at it alongside the checklist — it is that vertical's design and copy bar (surfaces, first-viewport rules, truthful copy), read after the general `DESIGN.md`/`CONTENT.md`.
 - If a *required feature* depends on backend support that **Seed** enabled (e.g., comments), note it's available so the host wires it. If Seed could **not** enable it, say so plainly rather than implying the site is complete.
 - **When pricing-plans is loaded, `login / account / gated content` is a *required* feature, not optional polish** — a plans grid with no way to log in and subscribe is incomplete (subscribing requires a member; §5 member-auth note). Point the host at the matching `how-to-code-members-*.md` recipe. For the other verticals, a "my …" surface (my orders / my bookings / my registrations) is a member-gated *enhancement* — list it only if the run's intent calls for an account view, and flag it needs the same login mechanism.
 - **Curation / hero / nav must come from a LIVE query, never a pinned slug/id.** A "featured" or "latest" item, a hero, and every nav/category bar must be driven by a query — "next upcoming" (`queryEvents` filtered to `UPCOMING`/`STARTED`, sorted by start date), "newest" (`queryPosts`), `queryCategories`, etc. — resolved at request time. A pinned "featured event" slug not only fails to rotate as the owner adds content, it can go **stale/past**. Even a **single-item** site (one event, one product) must drive its homepage from the *listing query*, not a hardcoded lone slug — so a second item the owner adds later surfaces automatically instead of staying invisible.

package/skills/wix-headless/references/SEED.md

@@ -17,7 +17,7 @@ Use `$TOKEN` / `$SITE_ID` from the provided authentication mechanism (see `<TYPE
 
 ## 1 · Where the *how* comes from — the inline recipes
 
-Each built capability's create flow lives in a **self-contained local recipe** at `inline-recipes/setup-<capability>.md` (§2 maps each capability to its file). The recipe inlines every endpoint, request body, and representative response — **open it with the file Read tool and seed from it alone**; it supersedes the live REST doc pages, so don't go fetch them. **Read a recipe once per run** — if you already opened it while planning, proceed from what you have — and only read a capability's recipe if you're going to seed it yourself (a separate concurrent unit reads its own; see the concurrency note above).
+Each built capability's create flow lives in a **local recipe** at `inline-recipes/setup-<capability>.md` (§2 maps each capability to its file). Most inline their endpoints and bodies; Donations delegates to the shared management recipe to avoid a second maintained contract. **Open the mapped recipe and follow its local references**; do not rediscover covered calls. **Read a recipe once per run** — if you already opened it while planning, proceed from what you have — and only read a capability's recipe if you're going to seed it yourself (a separate concurrent unit reads its own; see the concurrency note above).
 
 For a capability with **no** inline recipe (e.g. `coupons`), or for a field/error/endpoint a recipe doesn't cover, **`DOC_DISCOVERY.md` is the fallback** — never the first move.
 
@@ -29,8 +29,9 @@ Two cautions apply to every capability regardless of recipe:
 
 ## 2 · What to seed per capability
 
-Each entry states only the entities, where their count/content comes from, the policy that is genuinely the skill's call, the IDs to keep, and **which inline recipe carries the calls** — read that recipe (local; Read it, don't curl — it's self-contained and supersedes the doc pages) for everything else.
+Each entry states only the entities, where their count/content comes from, the policy that is genuinely the skill's call, the IDs to keep, and **which inline recipe carries the calls** — read that local recipe and any shared recipe it delegates to for everything else.
 
+- **donations** — *Donation campaigns.* Recipe: **`setup-donations.md`**. Read existing campaigns first; do not seed for a frontend-only request. For an authorized new setup, use `intent.donations.campaigns` and the shared recipe's constraints. Keep created IDs transiently for readback and cover-image attachment; campaigns are discovered live in the frontend. Goals, deadlines and impact claims require supplied/approved content; payment readiness is separate from campaign creation.
 - **stores** — *A product catalog.* Recipe: **`setup-online-store.md`**. `intent.stores.productCount` products whose names/prices fit `brand`. If `intent.stores.categoriesNamed` is non-empty, create exactly those categories and assign products into them; **if empty, create none** (skill policy — overrides any docs default). **Variant cardinality — keep it small by default:** unless `intent.stores` calls for specific options, give each product **at most one option with ≤3 choices** (so ≤3 variants/product); many products legitimately have **no** options (a single variant). Seeding cost scales with the variant Cartesian product and the field count per variant, so don't manufacture options the brief doesn't need — but **honor a larger/explicit option set when intent names one** (this default is a floor, not a cap). Text-only by default (images only when `imagery` is on — §1, §4). **Keep (seed-time only):** `categoryIds[]` to assign products into their categories; **nothing goes to the handoff** — the frontend lists products and categories **live** (`queryProducts` / `searchProducts` / `queryCategories`), so owner-added products/categories appear with no code change.
 - **blog** — *Initial posts.* Recipe: **`setup-blog.md`**. `intent.blog.postCount` posts on `intent.blog.topics` (or brand-derived topics). Text-only (no covers). **Keep:** nothing for the handoff — posts are discovered **live** (`queryPosts`, `[...slug]` routes). Track created post ids only transiently (to confirm success / assign categories).
 - **cms** — *Content collections.* Recipe: **`setup-cms.md`**. One collection per `intent.cms.collections` entry; `itemCount` items each, content from `brand`. Collections are **public-read** (visitor reads on the frontend) by default. **(Opt-in, members only)** if the brief calls for per-user-private or member-only data **and** members login is in the run, seed that collection **member-scoped** instead (per-user or member-only — see `setup-cms.md`); a per-user collection is seeded **empty** (members populate it), since admin-seeded rows are owned by the admin. **Keep (→ handoff):** `collectionIds{<name>}` + each collection's **field keys** — this is *structural* (the frontend must know the collection name and its fields to query and bind; it doesn't change when an owner adds a row). `itemIds{<name>:[]}` only transiently, for wiring multi-references during seeding.

package/skills/wix-headless/references/SETUP.md

@@ -27,6 +27,7 @@ For each capability in `verticals[]`, install its app by `appDefId` (these are t
 - **pricing-plans** → `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`
 - **restaurants** → `b278a256-2757-4f19-9313-c05c783bec92` (Wix Restaurants **Menus** — the seedable core). Online ordering and table reservations are **separate optional apps**, install only if intent calls for them: Orders (New) → `9a5d83fd-8570-482e-81ab-cfa88942ee60`, Table Reservations → `f9c07de2-5341-40c6-b096-8eb39de391fb`. **Experiences** (special dining occasions guests reserve — chef's tables, tasting menus; see `CAPABILITIES.md`) are a **feature of the Table Reservations app, not a separate install** — installing Table Reservations is all that's needed to create and book them (`setup-restaurant-experiences.md`).
 - **portfolio** → `d90652a2-f5a1-4c7c-84c4-d4cdcc41f130` (Wix Portfolio; the install ships a default sample collection + projects — `setup-portfolio.md` STEP 0 cleans them)
+- **donations** → `333b456e-dd48-4d6b-b32b-9fd48d74e163` (Wix Donations), plus Checkout & Orders `1380b703-ce81-ff05-f115-39571d94dfcd`. Confirm installed state and authorized changes first; do not reinstall to fix a malformed cart payload.
 - **cms** → **no install** (Wix Data is core) — skip
 
 For any vertical added later, its appDefId is in the docs — "Apps Created by Wix": <https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md>.

package/skills/wix-headless/references/inline-recipes/experience-donations.md

@@ -0,0 +1,102 @@
+---
+name: "Donations Experience"
+description: The donor-facing design and copy bar for a Wix Donations site, covering cause discovery, campaign pages, accessible giving forms, recurring intent, draft recovery, truthful progress and checkout returns. Read when building or wiring a donation experience; the API contract lives in how-to-code-donations.md.
+---
+**EXPERIENCE OVERLAY**: What makes a donation experience good — read after the general `DESIGN.md` and `CONTENT.md` when using those guides.
+
+Read alongside [How to Code Donations](how-to-code-donations.md). These are defaults, not
+a prescribed design: the user's brief wins. Configure campaigns only when asked; presentation must
+follow their live settings. These principles are framework- and hosting-independent; this is a
+Headless experience, not instructions to install an Editor widget.
+
+## Design from the cause
+
+Inspect campaign count, names, imagery, amounts/impact text, frequencies, goals and giving rules
+before choosing layout and tokens. Use the organization's supplied story and brand to choose a
+distinctive visual direction; “nonprofit” does not imply one palette, stock photograph or page formula.
+Treat approved imagery with dignity; do not present generated beneficiaries or events as documentary
+evidence. The campaign entity has no story field; keep authored narrative separate from its data.
+
+- **Homepage:** explain who is helped, what the organization does and one clear route to give in the
+  first screen. Follow with the content that earns the decision: a real featured cause, supplied impact
+  explanations, a story, or verified trust information. A single-cause site need not invent a campaign
+  gallery. Distinguish receiving help, volunteering, sponsorship and merchandise from donating.
+- **Several campaigns:** offer meaningful discovery with image, name, optional real progress, status
+  and a direct campaign link. Keep cards aligned with long names and missing images. One campaign
+  can open directly at `/donate`; do not add an unnecessary selection step. On phones, keep the
+  introduction and covers compact enough that the first cause's name and entry point appear in the
+  first screen, not just a large image. This is discovery, not a second homepage hero.
+- **Campaign page:** show the cause, concise context and giving form together. On phones, bound the
+  image and long story: at about 390px wide, the first screen should expose the cause, the start of
+  amount/frequency selection and a clear Donate action. Let longer choices/details scroll rather
+  than shrinking every control to fit. On desktop a side-by-side layout is useful, not mandatory.
+  Keep readable type and price labels without clipping.
+  Use real missing/archived states; never silently substitute another cause.
+
+## Make the giving decision clear
+
+- Show configured presets and their impact text. Offer custom giving only when enabled, and expose
+  its actual bounds near the field. Validate empty, invalid, non-positive and out-of-range input; show
+  errors after interaction/attempt, retain the donor's work and prevent handoff until corrected.
+- Offer only configured frequencies. Use clearly selected, keyboard-operable controls; even when
+  only one frequency exists, make a recurring commitment explicit. Amount shortcuts must preserve
+  their advertised amount and cadence; no silent conversion from one-time to monthly. Carry explicit
+  monthly-giving intent through discovery into the selected campaign's form when offered; later
+  donor edits take precedence. Explain an unavailable frequency instead of silently substituting it.
+- Prefer native radios with a shared name and a fieldset/legend for amount and frequency choices.
+  Custom radios must implement labelled groups, arrow-key navigation, selection and visible focus.
+  Associate errors/hints with their inputs and focus the first invalid control after an attempted
+  submission, not on every keystroke. See [form feedback](https://www.w3.org/WAI/tutorials/forms/notifications/).
+- Show currency and the selected amount/frequency in the primary action or its adjacent summary.
+  Fee coverage, when enabled, is visible, reversible and explained beside its checkbox, including its
+  recurring effect. Use the catalog fee flag, not a second local surcharge. Totals must agree at checkout.
+- Show a note only when enabled. A contextual dedication label is useful only when the control and
+  its persistence work; free text is not tribute notification or a restricted fund. Do not collect the
+  donor's billing/payment data again when hosted checkout already owns that step.
+- One Donate action owns the pending/redirect flow. Disable repeated activation, show progress and a
+  recoverable error. No merchandise-cart drawer or cart-page detour is required for direct giving.
+
+## Preserve the donor's work
+
+Restore a per-campaign draft after navigation, refresh and checkout cancellation: preset/custom mode,
+amount, frequency, fee choice and note. Scope short-lived, per-tab state to the content site, visitor
+and campaign; keep notes out of URLs, logs and long-lived storage. Revalidate restored choices against
+current campaign settings and show a correction when necessary; do not silently replace an amount or
+cadence. Expire drafts and clear them on explicit reset, visitor change or verified completion. A
+checkout return alone is neither completion nor a reason to reset the form.
+
+## Progress and confidence without invented claims
+
+Use goals and metrics only when configured and readable. No goal means no progress module. A failed
+metrics read is not zero donations; omit unavailable figures while keeping the form usable. Counts
+are donations, not unique donors. A bar stays within its track above 100%, while the real number may
+exceed the goal. Let the API's status/acceptance rules decide closure, not an inferred percentage.
+
+Use organization-supplied identity, contact, policies and substantiated claims. Do not invent tax
+deductibility, matching grants, certifications, urgency, donors, receipts or outcomes. For recurring
+giving, include the actual cancellation/help route or policy when supplied; no nonfunctional “manage
+subscription” control. Keep offline giving and other support paths secondary and accurately labeled.
+Avoid unsolicited signup/promotional popups that interrupt giving. Metadata, social links and policy
+destinations must belong to the organization, with no template placeholders. Give each campaign its
+own title, description and sharing image from its name and approved content, not a repeated generic
+homepage description. Do not invent a campaign SEO API field.
+
+## Finish the whole donor journey
+
+Verify loading, empty, closed, missing, invalid, submitting, failed and return states, not only the
+happy-path screenshot. Test desktop, a common phone width (around 390px) and a narrow phone (320px),
+including long campaign names, header/logo/CTA fit, discovery density, form controls and focus/error
+states. No horizontal overflow or clipped actions; do not just hide overflow. A sticky region must
+not cover controls; any modal/sheet needs scroll and focus management. Follow a monthly entry link
+through cause selection, then test custom amount + fee + note → checkout → cancel/back; choices must
+survive. Check refresh recovery too, without submitting a payment.
+
+Check the anonymous API → hosted-checkout handoff as required by the integration recipe. Verify that
+the checkout names the right cause and commitment. On return, show paid/order facts only when
+verified with appropriate access; an abandoned flow or direct thank-you visit is not proof of payment.
+Keep a generic acknowledgement when order details cannot be read. Do not claim a tax receipt or
+successful payment from the URL alone. Even an unverified return needs a meaningful heading, a clear
+verification-status message and a useful next step, not an empty page or a disclaimer alone. Verify
+hosted checkout separately from the custom form; qualify a desktop-viewport-only mobile check and
+confirm suspected hosted rendering problems on a real mobile browser. No live payment without
+explicit authorization.