@wix/agent-skills 1.6.0 → 1.7.0

package/skills/wix-headless/scripts/check-manifest.mjs

@@ -3,7 +3,7 @@
 //
 // Verifies that every file declared in each loaded pack's `creates:` array
 // for the named phase exists on disk. If a file is missing, attempts to
-// recover by copying the canonical template from <SKILL_ROOT>/templates/<pack>/.
+// recover by copying the canonical template from <SKILL_ROOT>/references/astro/templates/<pack>/.
 // Outputs a JSON summary of present / recovered / errored files.
 //
 // Usage (both modes work):
@@ -26,7 +26,7 @@
 //     `creates:` array.
 //   - For each `creates:` entry where phase matches:
 //       * If file exists in the project → "present"
-//       * If missing AND a template exists at `templates/<pack>/<tail>`
+//       * If missing AND a template exists at `references/astro/templates/<pack>/<tail>`
 //         (where <tail> is the path under src/pages/ for page files, or the
 //         basename for everything else) → copy/fetch it; record as "recovered".
 //       * Otherwise → record as "missing" with a remediation hint.
@@ -101,12 +101,12 @@ if (phase !== "components" && phase !== "pages") {
 const packs = packsCsv.split(",").map((p) => p.trim()).filter(Boolean);
 
 // Map a `creates:` file path to its template path (relative to skill root).
-// Heuristic: `src/pages/<X>` preserves <X> under templates/<pack>/; everything
-// else uses basename only.
+// Heuristic: `src/pages/<X>` preserves <X> under references/astro/templates/<pack>/;
+// everything else uses basename only.
 function templateRelPath(packName, srcPath) {
   const pagesMatch = srcPath.match(/^src\/pages\/(.+)$/);
   const tail = pagesMatch ? pagesMatch[1] : basename(srcPath);
-  return `templates/${packName}/${tail}`;
+  return `references/astro/templates/${packName}/${tail}`;
 }
 
 // Parse `creates:` block from a vertical pack's markdown frontmatter.

package/skills/wix-headless/scripts/emit-design-tokens.mjs

@@ -1,45 +1,58 @@
 #!/usr/bin/env node
-// Generate .wix/design-tokens.css and .wix/site.d.ts deterministically from
-// .wix/site.json.designTokens. Invoked by the wix-headless skill orchestrator
-// after the Phase 2 Design System agent's return is merged into site.json.
+// Generate .wix/design-tokens.css and .wix/site.d.ts deterministically from a
+// designTokens JSON payload piped in on stdin. Invoked by the wix-headless
+// skill orchestrator immediately after the Phase 2 Design System agent
+// returns — the orchestrator pipes designerReturn.data.designTokens directly,
+// no site.json round-trip.
 //
 // Why a script (not agent work): both files are pure projections of the
 // designTokens JSON — no judgment, no brand-context dependence. An LLM
 // emitting them is wasted tokens AND a drift risk (malformed :root blocks,
 // missing token groups, divergent .d.ts skeletons).
+//
+// Usage:
+//   echo '<designTokens-json>' | node emit-design-tokens.mjs <project-dir>
 
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
 const projectDir = process.argv[2] ?? process.cwd();
-const sitePath = join(projectDir, ".wix/site.json");
 
-let site;
+if (process.stdin.isTTY) {
+  console.error("emit-design-tokens: expected designTokens JSON on stdin (pipe in the designer's data.designTokens block)");
+  process.exit(2);
+}
+
+let tokens;
 try {
-  site = JSON.parse(readFileSync(sitePath, "utf8"));
+  const raw = readFileSync(0, "utf8").trim();
+  if (!raw) {
+    console.error("emit-design-tokens: stdin was empty — pass the designTokens JSON object");
+    process.exit(2);
+  }
+  tokens = JSON.parse(raw);
 } catch (e) {
-  console.error(`emit-design-tokens: cannot read ${sitePath} (${e.message}). Has Phase 2 Design System returned and merged?`);
-  process.exit(1);
+  console.error(`emit-design-tokens: stdin is not valid JSON (${e.message})`);
+  process.exit(2);
 }
 
-const tokens = site.designTokens ?? {};
-if (!tokens || Object.keys(tokens).length === 0) {
-  console.error("emit-design-tokens: site.json.designTokens is empty — designer return not merged.");
-  process.exit(1);
+if (!tokens || typeof tokens !== "object" || Array.isArray(tokens) || Object.keys(tokens).length === 0) {
+  console.error("emit-design-tokens: designTokens payload must be a non-empty JSON object");
+  process.exit(2);
 }
 
 const wixDir = join(projectDir, ".wix");
 mkdirSync(wixDir, { recursive: true });
 
-// .wix/design-tokens.css ----------------------------------------------------
 const PREFIX = {
   colors: "--color-",
   fonts: "--font-",
   radii: "--radius-",
   spacing: "--spacing-",
+  containers: "--container-",
 };
 
-const cssLines = ["/* Generated from .wix/site.json.designTokens. Do not edit. */", ":root {"];
+const cssLines = ["/* Generated by emit-design-tokens.mjs. Do not edit. */", ":root {"];
 for (const [group, prefix] of Object.entries(PREFIX)) {
   const entries = tokens[group] ?? {};
   for (const [key, value] of Object.entries(entries)) {
@@ -49,7 +62,6 @@ for (const [group, prefix] of Object.entries(PREFIX)) {
 cssLines.push("}", "");
 writeFileSync(join(wixDir, "design-tokens.css"), cssLines.join("\n"));
 
-// .wix/site.d.ts ------------------------------------------------------------
 const typeFor = (group) => {
   const keys = Object.keys(tokens[group] ?? {});
   if (keys.length === 0) return "Record<string, string>";
@@ -57,19 +69,13 @@ const typeFor = (group) => {
   return `Record<${literal}, string>`;
 };
 
-const dts = `// Generated from .wix/site.json.designTokens. Do not edit.
-export type Brand = { name: string; description: string };
+const dts = `// Generated by emit-design-tokens.mjs. Do not edit.
 export type DesignTokens = {
   colors: ${typeFor("colors")};
   fonts: ${typeFor("fonts")};
   radii: ${typeFor("radii")};
   spacing: ${typeFor("spacing")};
-};
-export type Product = { id: string; name: string; slug: string; price: number; variantId: string };
-export declare const site: {
-  brand: Brand;
-  designTokens: DesignTokens;
-  seeded: { products?: Product[]; posts?: unknown[]; collections?: Record<string, unknown[]> };
+  containers: ${typeFor("containers")};
 };
 `;
 writeFileSync(join(wixDir, "site.d.ts"), dts);

package/skills/wix-headless/scripts/init-site-json.mjs

@@ -1,30 +1,70 @@
 #!/usr/bin/env node
-// Write the initial .wix/site.json shape during Setup. Site.json is the
-// single source of truth that every downstream phase reads from / appends
-// to. This script writes the canonical initial structure deterministically
-// so the orchestrator never has to compose the shape inline (which used
-// to be LLM-emitted JSON, with the obvious drift risks).
+// Write the initial .wix/site.json — slim metadata snapshot for resume
+// detection + run.json composition. Subagents do NOT read this file during
+// the run; the orchestrator is the sole reader/writer and inlines anything
+// downstream phases need into their prompts.
 //
-// Usage:
-//   node init-site-json.mjs <project-dir> <brand-name> <brand-description> <verticals-csv>
+// Final shape:
+//   {
+//     "brand":     { "name": "...", "description": "..." },
+//     "frontend":  "astro" | "custom",
+//     "verticals": ["stores", "cms", ...],
+//     "siteId":    "..." (optional — Setup Step 1 may patch later),
+//     "appId":     "..." (optional — Setup Step 1 may patch later)
+//   }
 //
-// Example:
-//   node init-site-json.mjs /tmp/proj "Acme Coffee" "Warm cream-and-forest editorial" "stores,ecom,cms,gift-cards"
+// Usage:
+//   node init-site-json.mjs <project-dir> <brand-name> <brand-description> \
+//     <verticals-csv> --frontend <astro|custom> \
+//     [--site-id <id>] [--app-id <id>]
+//   (In practice only "astro" reaches this step — custom frontends route to the
+//    not-available stub before Discovery's approval/site.json write.)
 //
 // Behavior:
 //   - Refuses to overwrite an existing .wix/site.json (exit 2). The orchestrator
-//     should call this exactly once during Setup. To re-init for testing, the
-//     caller can rm the file first.
+//     should call this exactly once during Discovery's "After Approval" step.
+//     To re-init for testing, the caller can rm the file first.
 //   - Creates .wix/ if it doesn't exist.
 //   - Outputs a JSON summary to stdout.
 
 import { writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
-const [, , projectDir, brandName, brandDescription, verticalsCsv] = process.argv;
+const ALLOWED_FRONTENDS = new Set(["astro", "custom"]);
+
+let frontend = "astro";
+let siteId;
+let appId;
+const positional = [];
+const rawArgs = process.argv.slice(2);
+for (let i = 0; i < rawArgs.length; i++) {
+  const arg = rawArgs[i];
+  if (arg === "--frontend") {
+    frontend = rawArgs[++i];
+  } else if (arg.startsWith("--frontend=")) {
+    frontend = arg.slice("--frontend=".length);
+  } else if (arg === "--site-id") {
+    siteId = rawArgs[++i];
+  } else if (arg.startsWith("--site-id=")) {
+    siteId = arg.slice("--site-id=".length);
+  } else if (arg === "--app-id") {
+    appId = rawArgs[++i];
+  } else if (arg.startsWith("--app-id=")) {
+    appId = arg.slice("--app-id=".length);
+  } else {
+    positional.push(arg);
+  }
+}
+
+if (!ALLOWED_FRONTENDS.has(frontend)) {
+  console.error(`init-site-json: --frontend must be one of ${[...ALLOWED_FRONTENDS].join(", ")}; got ${JSON.stringify(frontend)}`);
+  process.exit(2);
+}
+
+const [projectDir, brandName, brandDescription, verticalsCsv] = positional;
 
 if (!projectDir || !brandName || brandDescription === undefined || !verticalsCsv) {
-  console.error("usage: init-site-json.mjs <project-dir> <brand-name> <brand-description> <verticals-csv>");
+  console.error("usage: init-site-json.mjs <project-dir> <brand-name> <brand-description> <verticals-csv> --frontend <astro|custom> [--site-id <id>] [--app-id <id>]");
   process.exit(2);
 }
 
@@ -42,22 +82,20 @@ const wixDir = join(projectDir, ".wix");
 const sitePath = join(wixDir, "site.json");
 
 if (existsSync(sitePath)) {
-  console.error(`init-site-json: ${sitePath} already exists — refusing to overwrite. Setup should call this exactly once.`);
+  console.error(`init-site-json: ${sitePath} already exists — refusing to overwrite. Discovery should call this exactly once.`);
   process.exit(2);
 }
 
 mkdirSync(wixDir, { recursive: true });
 
 const site = {
-  brand: {
-    name: brandName,
-    description: brandDescription,
-  },
-  seeded: {},
-  designTokens: {},
+  brand: { name: brandName, description: brandDescription },
+  frontend,
   verticals,
 };
+if (siteId) site.siteId = siteId;
+if (appId) site.appId = appId;
 
 writeFileSync(sitePath, JSON.stringify(site, null, 2) + "\n");
 
-console.log(JSON.stringify({ status: "ok", path: sitePath, verticals }, null, 2));
+console.log(JSON.stringify({ status: "ok", path: sitePath, frontend, verticals, ...(siteId ? { siteId } : {}), ...(appId ? { appId } : {}) }, null, 2));

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/preview.sh

@@ -6,7 +6,7 @@
 #
 # Run from the project directory (CWD = <project>/). Requires wix.config.json.
 #
-# Output: stdout is the preview URL that `npx @wix/cli preview` printed; the
+# Output: stdout is the preview URL that `npx @wix/cli@latest preview` printed; the
 # orchestrator captures it and records as outcome.previewUrl in run.json. All
 # other CLI output goes to stderr.
 #
@@ -23,14 +23,14 @@
 set -euo pipefail
 
 # Build first; surface compile errors verbatim if it fails.
-npx @wix/cli build 1>&2
+npx @wix/cli@latest build 1>&2
 
 # Preview captures the deployed URL on stdout. We tee its output to stderr for
 # the user-visible log AND parse the URL out for the orchestrator's stdout.
 PREVIEW_OUTPUT="$(mktemp)"
 trap 'rm -f "$PREVIEW_OUTPUT"' EXIT
 
-npx @wix/cli preview 2>&1 | tee "$PREVIEW_OUTPUT" 1>&2
+npx @wix/cli@latest preview 2>&1 | tee "$PREVIEW_OUTPUT" 1>&2
 
 # Wix CLI prints `Site preview URL: <url>` (or similar) — extract the first
 # https URL from the output. If multiple are printed, the first is the canonical

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

@@ -9,7 +9,7 @@
 #
 # Run from the project directory (CWD = <project>/). Requires wix.config.json.
 #
-# Output: stdout is the released URL that `npx @wix/cli release` printed
+# Output: stdout is the released URL that `npx @wix/cli@latest release` printed
 # (extracted from the line `Site published on <url>`); the orchestrator
 # captures it as outcome.releaseUrl in run.json. All other CLI output goes
 # to stderr.
@@ -19,12 +19,12 @@
 #   <other> — build or release failed; stderr surfaces the underlying error.
 #             Build failures are code bugs (TypeScript / Astro / missing
 #             module) — the orchestrator does NOT retry. Release auth failures
-#             surface as `Run npx @wix/cli login and retry.`
+#             surface as `Run npx @wix/cli@latest login and retry.`
 #             Known transient release failures are retried by this script.
 
 set -euo pipefail
 
-npx @wix/cli build 1>&2
+npx @wix/cli@latest build 1>&2
 
 RELEASE_OUTPUT="$(mktemp)"
 trap 'rm -f "$RELEASE_OUTPUT"' EXIT
@@ -39,7 +39,7 @@ RELEASE_STATUS=1
 for ((attempt = 1; attempt <= MAX_RELEASE_ATTEMPTS; attempt++)); do
   : >"$RELEASE_OUTPUT"
   set +e
-  npx @wix/cli release 2>&1 | tee "$RELEASE_OUTPUT" 1>&2
+  npx @wix/cli@latest release 2>&1 | tee "$RELEASE_OUTPUT" 1>&2
   RELEASE_STATUS=${PIPESTATUS[0]}
   set -e
 

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

@@ -1,53 +1,108 @@
 #!/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 <project-slug> "<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.
+# --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.
+# (project's appId) and siteId (used as --site for `wix token` and in REST call
+# bodies). The orchestrator does that read; this script just runs the npm create.
 #
 # Behavior:
 #   - Pre-flight validates the slug (regex ^[a-z0-9]{3,20}$).
-#   - Pre-flight requires both args.
+#   - 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").
 #
 # Exit codes:
 #   0 — ok
-#   2 — argument validation failed
+#   2 — argument validation failed (bad slug, 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)
 #   <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 project-slug='${POSITIONAL[0]:-}' brand-name='${POSITIONAL[1]:-}'." >&2
+  echo "Usage: bash scaffold.sh <slug> \"<Brand Name>\" [--frontend astro|custom] — slug 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
+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]{3,20}$ ]]; then
+  echo "scaffold.sh: project-slug='${POSITIONAL[0]}' 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
   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
 
 npm create @wix/new@latest headless -- \
-  --business-name "$2" \
-  --project-name "$1" \
-  --site-template "$TEMPLATE_ID" \
+  --business-name "${POSITIONAL[1]}" \
+  --project-name "${POSITIONAL[0]}" \
+  --site-template \
   --no-publish \
   --skip-install