@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,359 +0,0 @@
-#!/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,151 +0,0 @@
----
-name: wix-headless
-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 *)
-  - Bash(npx @wix/cli *)
-  - Bash(npm create @wix/new@latest *)
-  - Bash(npm install *)
-  - Bash(npm run *)
-  - Bash(node *)
-  - Bash(cd *)
-  - Bash(ls *)
-  - Bash(mkdir *)
-  - Bash(cp *)
-  - Bash(mv *)
-  - Bash(uuidgen)
-  - Read
-  - Write
-  - Edit
----
-
-# Wix Headless
-
-This skill connects **Wix business services** to a **Wix Headless frontend**. Its core job is to **configure the Wix backend**: infer the needed capabilities, **install the Wix apps**, **seed the backend content**, and produce an SDK-integration guide describing how to call Wix from the frontend.
-
-What happens with the frontend depends on the project type and operation:
-- **Backend-only** (self-managed, stripe, or a managed "just set up the backend" run) — the skill **emits the SDK guide** as its final output; the **host owns** the frontend, build, and hosting.
-- **Managed create / connect** — the skill **also owns the frontend**: it scaffolds a new project (create) or attaches Wix to an existing one (connect), wires it to the backend using that same guide, builds, and releases to Wix. (There is no Designer or template library — the frontend is built ad-hoc to intent.)
-
-> **On a backend-only run the skill does not own the project scaffolding.** When the work needs a frontend, **scaffold it according to user intent** — framework and structure follow the prompt; the skill's job is the Wix backend plus the **emitted SDK guide** describing how to call Wix from whatever frontend exists, not choosing or generating the app. This is the norm for a **stripe** run: the project is provisioned via Stripe Projects (credentials land in `.env` — see `stripe/AUTHENTICATION.md`), the skill configures the backend and emits the guide, and the live site is finalized per `stripe/DEPLOYMENT.md` — while the frontend is scaffolded and wired to intent, by the host.
-
-## Project types
-
-The skill behaves identically across project types **except for authentication and deployment**, which are isolated in a per-type folder under `references/`:
-
-| Project type | Hosting | Authentication & deployment live in |
-|---|---|---|
-| `managed` | Wix infrastructure (maintained by Wix) | `references/managed/` |
-| `self-managed` | the user's own host (TBD) | `references/self-managed/` |
-| `stripe` | the user's own host, provisioned via Stripe Projects | `references/stripe/` |
-
-Everything else — Discovery, Setup, Seed, the SDK handoff — is **project-type-agnostic** and refers to "the provided authentication mechanism" rather than any specific method.
-
-### Resolving the project type
-
-Resolve the type **before Discovery**, in this order — stop at the first that decides:
-
-1. **Caller-provided.** If the host/caller passed a project type (`managed` | `self-managed` | `stripe`), use it. An explicit value always wins.
-2. **Detect from project signals (on disk).** Check the working directory (read-only):
-   - **`stripe`** — `.env` carries `WIX_WIX_CLIENT_ID` / `WIX_WIX_CLIENT_SECRET` / `WIX_WIX_METASITE_ID` (or the plain `WIX_*` fallback). This is the Stripe-Projects fingerprint.
-   - **`managed`** — a Wix CLI project: `wix.config.json` present, or a `.wix/` directory, or `@wix/cli` / `@wix/astro` in `package.json`.
-   - **`self-managed`** — a frontend project on disk (e.g. `package.json` with a bundler/framework) with **neither** the Stripe `.env` fingerprint **nor** the Wix-CLI markers above.
-3. **Detect from user intent.** If disk is inconclusive, read the prompt:
-   - **`managed`** — "managed", "host on Wix", "Wix-hosted", "deploy to Wix", "`wix release`".
-   - **`stripe`** — "stripe projects", "I added Wix via Stripe", a Stripe-Projects context.
-   - **`self-managed`** — "self-hosted", "my own host", names a non-Wix host, "I'll deploy it myself".
-4. **Ask.** If signals are absent or conflict, **ask the user** which type applies — don't guess.
-
-Hold the resolved type in scratch; it selects `<TYPE_DIR>` (see Path resolution). Note `self-managed` is **TBD** — once resolved to it, the auth step will stop with a clear "not wired yet" error.
-
-### Resolving the operation (managed only)
-
-create/connect/iterate are **managed-only**. For `managed`, resolve the operation **by intent first, directory second** — never let an empty directory override what the user is asking for. Check `iterate` first (it's decided by an unambiguous on-disk signal):
-
-- **`iterate`** → `references/managed/CONNECT.md`. The project is **already connected to Wix** — a `wix.config.json` (or `.wix/`) is already present — and the owner wants to add or change capabilities. Same flow as `connect`, but §1 **skips `init`** and reuses the existing `wix.config.json`; **never re-`init` an already-connected project**.
-- **`connect`** → `references/managed/CONNECT.md`. The user **brings a design not yet connected to Wix and wants it wired**: a frontend project on disk **without** a `wix.config.json`, **or** a brought-in/fetched design (a `.zip`/folder/file you unzip or read, a design-file URL, a Claude-Design/v0/Lovable export), **or** language like "connect this / implement this design (… connecting to Wix) / host this on Wix / deploy this to Wix / add Wix Headless to this project". **A brought-in or fetched design is `connect` even when the current directory is empty** — the design arrives from elsewhere (zip/fetch/URL), so emptiness at trigger time is *not* a create signal. (`CONNECT.md` step 1 places the brought design into CWD, then `init`s it.)
-- **`create`** → `references/managed/CREATE.md`. The user wants a **new site built from a prompt with nothing brought in** — "build me a site / store / blog…", no design file, no project on disk.
-- **`backend-only`** — the user only wants the backend configured (no frontend work). → the shared spine + emit the SDK handoff.
-
-For `self-managed` and `stripe`, the operation is always **backend-only** (the host owns the frontend). Only when there is **genuinely no brought-in design and no connect language** does directory emptiness decide: empty → `create`; an existing frontend on disk → `connect`.
-
-## Preconditions (the host provides these — we read, never create)
-
-1. **The project type** — `managed` | `self-managed` | `stripe` — provided by the caller, else **detected from project signals / user intent** (see Project types § "Resolving the project type"), else asked. It selects `<TYPE_DIR>` (see Path resolution).
-2. **A Wix metasite + a headless OAuth app exist, and credentials are available** — obtained via the project type's `AUTHENTICATION.md`. The skill needs a bearer token authorized for the metasite and the metasite id.
-3. **The user intent** — free text describing what Wix should power ("add a store", "blog + contact form", "persist my app's data").
-4. *(Optional)* the project on disk — read-only, to sharpen brand/capability inference.
-
-If the credentials are absent, the Wix backend isn't reachable — **stop with a clear error**.
-
-## What this skill does
-
-**Always open `DISCOVERY.md` first** (it's agnostic — capability/brand/intent inference + the imagery gate, no auth). Then route by project type + operation:
-
-**Backend-only** (self-managed, stripe, or managed backend-only) — the lean spine:
-1. **Discovery** (`references/DISCOVERY.md`) — infer capabilities + brand + intent + imagery.
-2. **Setup** (`references/SETUP.md`) — **install** the Wix apps those capabilities need.
-3. **Seed** (`references/SEED.md`) — **create** the backend content (+ entity images if imagery is on).
-4. **Handoff** (`references/SDK_HANDOFF.md`) — after Setup and Seed, **emit** the integration guide: SDK bootstrap, per-capability call shapes, the **seeded IDs**, and the `@wix/*` package list.
-5. **Finalize deployment** (`<TYPE_DIR>/DEPLOYMENT.md`) — run the project-type's finalize steps.
-
-**Throughout any run** — if the user asks to send feedback to Wix, complains/gets frustrated, or the
-run hits any real friction (a confusing error, a doc gap, a tooling dead end, a workaround you had to
-invent — it doesn't need to repeat), **offer** to relay it to Wix per `references/FEEDBACK.md`. Default
-to offering rather than waiting to be asked. Every flow's finalize step (`<TYPE_DIR>/DEPLOYMENT.md` /
-`managed/CREATE.md` / `managed/CONNECT.md`) ends with the same checkpoint — treat it as a required
-self-check, not optional. Send only after an explicit yes — never automatically.
-
-**Managed create / connect / iterate** — after Discovery, hand the whole run to the managed flow:
-- **create** → **`references/managed/CREATE.md`** (scaffold → Setup → Seed → build the frontend → release).
-- **connect** → **`references/managed/CONNECT.md`** (init → Setup → Seed → wire the existing UI → release).
-- **iterate** → **`references/managed/CONNECT.md`** — the project is already connected, so it reuses the existing `wix.config.json` (no `init`). Setup / Seed / wiring are **incremental**: it may already be set up and seeded from a prior run, so the agent **checks current state first** (installed apps, already-seeded content, existing wiring) and applies only the delta the new intent needs — never blindly re-installing or re-seeding. Re-release only if the frontend build output changed.
-  These reuse the same `SETUP.md`/`SEED.md`/`SDK_HANDOFF.md`, but **apply** the SDK guide to build/wire the frontend themselves rather than emitting it, and release via `managed/DEPLOYMENT.md`.
-
-Each Wix call uses the universal call shape (`SETUP.md` §1) with `$TOKEN`/`$SITE_ID` obtained per `<TYPE_DIR>/AUTHENTICATION.md`. The skill runs non-interactively except for the one imagery question (and asking the project type if it can't be resolved).
-
-> **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:
-
-> **`<TYPE_DIR>` = `<SKILL_ROOT>/references/<projectType>/`** — one of `managed/`, `self-managed/`, `stripe/`.
-
-| What | Path |
-|---|---|
-| Vertical index (intent matching + per-vertical site spec) | `<SKILL_ROOT>/references/CAPABILITIES.md` |
-| Discovery (infer capabilities + brand + intent; existing site → the Dynamic Context call in §1) | `<SKILL_ROOT>/references/DISCOVERY.md` |
-| Setup (install apps) | `<SKILL_ROOT>/references/SETUP.md` |
-| Seed (create backend content) | `<SKILL_ROOT>/references/SEED.md` |
-| SDK-integration handoff (emitted, or applied by create/connect) | `<SKILL_ROOT>/references/SDK_HANDOFF.md` |
-| 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-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` |
-| **Deployment** — finalize the live site (project-type-specific) | `<TYPE_DIR>/DEPLOYMENT.md` |
-| Managed **create** flow (scaffold a new project) | `<SKILL_ROOT>/references/managed/CREATE.md` |
-| Managed **connect** flow (wire an existing project) | `<SKILL_ROOT>/references/managed/CONNECT.md` |
-| Frontend-axis references (how a frontend wires to Wix) | `<SKILL_ROOT>/references/astro.md`, `non-astro.md` |
-
-**Start a run by opening `DISCOVERY.md`.** The flow files (`CAPABILITIES`, `DISCOVERY`, `SETUP`, `SEED`, `SDK_HANDOFF`, `IMAGE_GENERATION`, `AI_FEATURES`) are project-type-agnostic; the per-type specifics live under `<TYPE_DIR>/` (`AUTHENTICATION.md`, `DEPLOYMENT.md`, and — managed only — `CREATE.md`/`CONNECT.md`).
-
-## Where the *how* comes from
-
-This skill has **no skill upstream** — the *how* is read from the **live Wix docs** at `dev.wix.com/docs`. **Read-priority: a page this skill links is read by `curl`-ing its `.md` twin directly (first priority — don't re-discover a curated link with search); the Wix MCP doc/search tools are second priority, for finding pages the skill doesn't link or as a fallback if a fetch fails.** (Append `.md` to any docs URL for raw markdown; menu pages list child links, content pages carry the schema.)
-
-**Doc discovery is the shared fallback for both tracks — never the first move.** Each track's *primary* source is its pinned material (below); when that doesn't cover what you need, fall back to `references/DOC_DISCOVERY.md` — a semantic doc-search + schema lookup that works with or without the Wix MCP.
-
-- **Seed** reads each capability's create flow from its **inline recipe** — a **self-contained local `inline-recipes/setup-*.md`** (mapped per capability in `SEED.md` § "What to seed per capability") that inlines the calls and **supersedes** the REST doc pages, so read it and seed from it alone. Only a capability with **no** inline recipe (e.g. `coupons`) falls back to doc discovery (`DOC_DISCOVERY.md`).
-- **Handoff** links the **SDK docs** for each capability's API shape, and supplies the runtime package set from the inlined map in `SDK_HANDOFF.md` (the SDK `.md` pages don't expose `@wix/*` import strings to navigation, so packages are mapped, not navigated).
-
-Setup carries its app-install call (and the appDefId constants) inline in `SETUP.md`; `CAPABILITIES.md` is the vertical index that lets Discovery match intent **and** declares, per built vertical, the *Required site features* + *Implementation checklist* that Seed enables (backend-backed features) and the Handoff carries into the guide (so the host builds a complete site, not a bare data dump). This skill carries the *what* (which capabilities, how much content, what a finished site includes) and reads the *how* off the docs.