@wix/agent-skills 1.7.0 → 1.8.0

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

@@ -1,83 +1,160 @@
 #!/usr/bin/env node
-// 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.
+// Project .wix/design-tokens.css + .wix/site.d.ts from the Designer's DESIGN.md.
 //
-// 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).
+// The Designer authors DESIGN.md directly (the run is single-folder — CWD is the
+// project — so the Designer can write it during Phase 2). This script does NOT
+// write DESIGN.md; it reads the frontmatter the Designer wrote and projects the
+// two MECHANICAL artifacts an LLM must not hand-write (a malformed :root block or
+// divergent type union is a silent build/drift bug):
+//   .wix/design-tokens.css  — :root custom properties (build-consumed; any frontend imports it).
+//   .wix/site.d.ts          — typed token-name unions.
+//
+// DESIGN.md frontmatter is the single design source — compose.mjs (astro) reads
+// the same file. Runs in the Setup-window bridge, after the Designer returns. On
+// the own-build (SPA) path it runs too (the SPA imports design-tokens.css);
+// compose.mjs does NOT run there (it is astro-only).
 //
 // Usage:
-//   echo '<designTokens-json>' | node emit-design-tokens.mjs <project-dir>
+//   node emit-design-tokens.mjs <project-dir>                    # reads <project-dir>/DESIGN.md
+//   node emit-design-tokens.mjs <project-dir> --design-md <path> # explicit DESIGN.md path
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-const projectDir = process.argv[2] ?? process.cwd();
-
-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);
+// ── args ─────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+let designMdPath = null;
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === "--design-md") designMdPath = argv[++i];
+  else if (argv[i].startsWith("--design-md=")) designMdPath = argv[i].slice("--design-md=".length);
+  else positional.push(argv[i]);
 }
+const projectDir = positional[0] ?? process.cwd();
+const designMd = designMdPath ?? join(projectDir, "DESIGN.md");
 
-let tokens;
-try {
-  const raw = readFileSync(0, "utf8").trim();
-  if (!raw) {
-    console.error("emit-design-tokens: stdin was empty — pass the designTokens JSON object");
-    process.exit(2);
+// ── DESIGN.md frontmatter parser ──────────────────────────────────────────────
+// Mirrors compose.mjs's parser for the restricted DESIGN.md shape (groups of
+// `key: scalar`, typography tokens with an indented or flow-style fontFamily).
+// The format contract is references/shared/DESIGN_MD.md; both readers must agree.
+// Color values are quoted because an unquoted `#hex` after `: ` is a YAML comment.
+function unquote(v) {
+  v = v.trim();
+  const qc = v[0];
+  if (qc === '"' || qc === "'") {
+    let out = "";
+    for (let i = 1; i < v.length; i++) {
+      const c = v[i];
+      if (qc === '"' && c === "\\" && i + 1 < v.length) { out += v[++i]; continue; }
+      if (c === qc) break;
+      out += c;
+    }
+    return out;
+  }
+  const hash = v.search(/\s#/); // strip trailing inline comment on bare scalars
+  if (hash !== -1) v = v.slice(0, hash).trim();
+  return v;
+}
+function parseInlineObject(s) {
+  const inner = s.trim().replace(/^\{/, "").replace(/\}$/, "");
+  const obj = {};
+  let buf = "", inq = null;
+  const parts = [];
+  for (const ch of inner) {
+    if (inq) { if (ch === inq) inq = null; buf += ch; continue; }
+    if (ch === '"' || ch === "'") { inq = ch; buf += ch; continue; }
+    if (ch === ",") { parts.push(buf); buf = ""; continue; }
+    buf += ch;
   }
-  tokens = JSON.parse(raw);
-} catch (e) {
-  console.error(`emit-design-tokens: stdin is not valid JSON (${e.message})`);
+  if (buf.trim()) parts.push(buf);
+  for (const p of parts) {
+    const ci = p.indexOf(":");
+    if (ci === -1) continue;
+    obj[p.slice(0, ci).trim()] = unquote(p.slice(ci + 1));
+  }
+  return obj;
+}
+function parseFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const root = {};
+  let group = null, sub = null;
+  for (const raw of m[1].split(/\r?\n/)) {
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+    const indent = raw.match(/^ */)[0].length;
+    const ci = raw.indexOf(":");
+    if (ci === -1) continue;
+    const key = raw.slice(0, ci).trim();
+    const rest = raw.slice(ci + 1).trim();
+    if (indent === 0) {
+      if (rest === "") { root[key] = {}; group = key; sub = null; }
+      else if (rest.startsWith("{")) { root[key] = parseInlineObject(rest); group = null; sub = null; }
+      else { root[key] = unquote(rest); group = null; sub = null; }
+    } else if (indent === 2 && group) {
+      if (rest === "") { root[group][key] = {}; sub = key; }
+      else if (rest.startsWith("{")) { root[group][key] = parseInlineObject(rest); sub = null; }
+      else { root[group][key] = unquote(rest); sub = null; }
+    } else if (indent >= 4 && group && sub) {
+      if (typeof root[group][sub] !== "object") root[group][sub] = {};
+      root[group][sub][key] = unquote(rest);
+    }
+  }
+  return root;
+}
+
+// ── read + validate the Designer's DESIGN.md ──────────────────────────────────
+if (!existsSync(designMd)) {
+  console.error(`emit-design-tokens: no DESIGN.md at ${designMd} — the Designer must author it first`);
+  process.exit(2);
+}
+const design = parseFrontmatter(readFileSync(designMd, "utf8"));
+if (!design || typeof design !== "object" || Object.keys(design).length === 0) {
+  console.error(`emit-design-tokens: could not parse YAML frontmatter from ${designMd} (check it starts with '---', values are quoted, 2-space indent)`);
   process.exit(2);
 }
 
-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");
+const colors = design.colors ?? {};
+const typography = design.typography ?? {};
+const spacing = design.spacing ?? {};
+const rounded = design.rounded ?? {};
+const containers = design.containers ?? {};
+const fontFamilyOf = (lvl) => (typography[lvl] && typeof typography[lvl] === "object" ? typography[lvl].fontFamily : typography[lvl]);
+
+if (Object.keys(colors).length === 0) {
+  console.error(`emit-design-tokens: DESIGN.md frontmatter has no 'colors' group — cannot project tokens (${designMd})`);
   process.exit(2);
 }
 
 const wixDir = join(projectDir, ".wix");
 mkdirSync(wixDir, { recursive: true });
 
-const PREFIX = {
-  colors: "--color-",
-  fonts: "--font-",
-  radii: "--radius-",
-  spacing: "--spacing-",
-  containers: "--container-",
-};
-
+// ── .wix/design-tokens.css ────────────────────────────────────────────────────
 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)) {
-    cssLines.push(`  ${prefix}${key}: ${value};`);
-  }
+for (const [k, v] of Object.entries(colors)) cssLines.push(`  --color-${k}: ${v};`);
+for (const lvl of Object.keys(typography)) {
+  const fam = fontFamilyOf(lvl);
+  if (fam) cssLines.push(`  --font-${lvl}: ${fam};`);
 }
+for (const [k, v] of Object.entries(rounded)) cssLines.push(`  --radius-${k}: ${v};`);
+for (const [k, v] of Object.entries(spacing)) cssLines.push(`  --spacing-${k}: ${v};`);
+for (const [k, v] of Object.entries(containers)) cssLines.push(`  --container-${k}: ${v};`);
 cssLines.push("}", "");
 writeFileSync(join(wixDir, "design-tokens.css"), cssLines.join("\n"));
 
-const typeFor = (group) => {
-  const keys = Object.keys(tokens[group] ?? {});
+// ── .wix/site.d.ts ────────────────────────────────────────────────────────────
+const recordType = (keys) => {
   if (keys.length === 0) return "Record<string, string>";
-  const literal = keys.map((k) => JSON.stringify(k)).join(" | ");
-  return `Record<${literal}, string>`;
+  return `Record<${keys.map((k) => JSON.stringify(k)).join(" | ")}, 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")};
-  containers: ${typeFor("containers")};
+  colors: ${recordType(Object.keys(colors))};
+  fonts: ${recordType(Object.keys(typography))};
+  radii: ${recordType(Object.keys(rounded))};
+  spacing: ${recordType(Object.keys(spacing))};
+  containers: ${recordType(Object.keys(containers))};
 };
 `;
 writeFileSync(join(wixDir, "site.d.ts"), dts);
 
-console.log(`emit-design-tokens: wrote ${join(wixDir, "design-tokens.css")} and ${join(wixDir, "site.d.ts")}`);
+console.log(`emit-design-tokens: projected ${join(wixDir, "design-tokens.css")} and ${join(wixDir, "site.d.ts")} from ${designMd}`);

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Flatten a scaffolded subdir up into the current directory — the framework-
+# agnostic half of single-folder bootstrap for the own-build path.
+#
+# WHY THIS EXISTS: every framework scaffolder (Vite, Vue, SvelteKit, …) insists
+# on creating a *named subdir* and offers no reliable in-place option. The skill
+# wants the project in CWD (one `.wix`, CWD == project == site-root — same layout
+# astro's scaffold.sh produces). The flatten is identical regardless of framework,
+# so it lives here as ONE tested script instead of being re-derived in prose every
+# run (the orchestrator otherwise burns a long turn agonizing over mv -n vs rsync
+# vs cp --no-clobber and BSD-vs-GNU portability). Scaffold into a temp subdir with
+# the framework's own command, then call this.
+#
+# astro's scaffold.sh ALSO delegates its in-place flatten here (same logic), so
+# this is the single source for the flatten. Remove the flatten entirely when the
+# CLI gains `--folder-name .` (or --cwd) — the in-place flag obviates it.
+#
+# Usage:
+#   bash <SKILL_ROOT>/scripts/flatten.sh <scaffold-subdir>
+#
+# <scaffold-subdir>: the transient directory the framework scaffolder created
+#                    (e.g. "_scaffold_tmp"). Everything inside it — including
+#                    dotfiles — is moved up into CWD; its `.wix/*` is merged into
+#                    the existing `.wix/` WITHOUT overwriting any pre-existing
+#                    `.wix/` entries (mv -n); then the subdir is removed.
+#
+# Exit codes:
+#   0 — ok (or subdir absent / already flat — no-op)
+#   2 — argument missing
+#   5 — could not fully flatten (name collision left files behind)
+
+set -euo pipefail
+
+SUBDIR="${1:-}"
+if [[ -z "$SUBDIR" ]]; then
+  echo "flatten.sh: scaffold-subdir argument required." >&2
+  echo "Usage: bash flatten.sh <scaffold-subdir>" >&2
+  exit 2
+fi
+
+# Absent or not a dir → nothing to flatten (scaffolder may have gone in-place).
+[[ -d "$SUBDIR" ]] || { echo "flatten.sh: '$SUBDIR' is not a directory — nothing to flatten."; exit 0; }
+
+shopt -s dotglob nullglob
+mkdir -p .wix
+if [[ -d "$SUBDIR/.wix" ]]; then
+  for f in "$SUBDIR"/.wix/*; do
+    mv -n "$f" .wix/      # -n: never overwrite pre-existing `.wix/` entries
+  done
+  rmdir "$SUBDIR/.wix" 2>/dev/null || rm -rf "$SUBDIR/.wix"
+fi
+for f in "$SUBDIR"/*; do
+  mv -n "$f" ./
+done
+shopt -u dotglob nullglob
+
+if ! rmdir "$SUBDIR" 2>/dev/null; then
+  echo "flatten.sh: could not fully flatten '$SUBDIR' into CWD — leftover:" >&2
+  ls -A "$SUBDIR" >&2
+  exit 5
+fi

package/skills/wix-headless/scripts/generate-images.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// Parallel image generator + Wix Media importer.
+//
+// WHY THIS EXISTS. Image generation is N independent (generate → import) chains
+// with no cross-image dependency, so it is embarrassingly parallel. When the
+// agent drives it by hand the chains serialize into minutes of avoidable wall.
+// The agent ALSO cannot use the
+// single-array batch form on the default model (`google:4@2` 504s when one
+// request carries N≥3 tasks). This script resolves both: it fires N *separate
+// single-task* requests CONCURRENTLY in-process (Promise.all), so there is no
+// per-turn serialization to lose and no N≥3-in-one-request 504 to hit. It is
+// the deterministic analog of the "one concurrent batch" rule the prose docs
+// ask the agent to follow by hand.
+//
+// SCOPE. Generation + Wix Media import ONLY — the parallelizable, recipe-free
+// half. It returns a key→{url,fileId} map. Attachment stays where the recipe
+// knowledge lives: Phase 1 decorative URLs flow into write-decorative-json.mjs;
+// Phase 2 entity URLs flow into the per-entity PATCH/PUT/publish plan from
+// plan-entity-image-waves.mjs. This script never touches frontend source or
+// Wix entities.
+//
+// Phase-agnostic: `key` is a slot name for Phase 1 (`hero`, `about`) or an
+// entityId for Phase 2. The caller interprets the returned map.
+//
+// AUTH (references/shared/AUTHENTICATION.md). Site-scoped REST token, minted
+// once per run and reused. Pass it in via the WIX_TOKEN env var (preferred —
+// honors mint-once) or the stdin `token` field. As a last resort the script
+// mints one itself with `npx @wix/cli@latest token --site <siteId>` in
+// <projectDir>; that costs a CLI spin-up, so prefer passing the cached token.
+//
+// USAGE
+//   echo '{
+//     "siteId": "ed57...",
+//     "model": "google:4@2",
+//     "projectDir": "/abs/path/frenchiesgoodies",   // only needed if minting
+//     "images": [
+//       {"key":"hero","positivePrompt":"...","width":1376,"height":768},
+//       {"key":"about","positivePrompt":"...","width":1200,"height":896}
+//     ]
+//   }' | WIX_TOKEN="$TOKEN" node generate-images.mjs
+//
+// OUTPUT (stdout, JSON)
+//   {
+//     "status": "complete" | "partial" | "failed",
+//     "model": "google:4@2",
+//     "count": { "requested": 2, "ok": 2, "failed": 0 },
+//     "map":   { "hero": {"url":"https://static.wixstatic.com/...","fileId":"..~mv2.png"} },
+//     "slots": { "hero": "https://static.wixstatic.com/..." },   // key→url, ready for write-decorative-json.mjs
+//     "results": [ {"key":"hero","taskUUID":"..","status":"ok","genReqId":"..","importReqId":".."} ],
+//     "errors":  [ {"key":"about","stage":"generate","code":"504","message":".."} ]
+//   }
+// Exit 0 on complete/partial, 1 on failed (zero images succeeded) or bad input.
+// x-wix-request-id is captured per call into results[] for trace analysis — it
+// is never printed to stderr or narrated (CLAUDE.md run policy).
+
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+const RUNWARE_URL = "https://www.wixapis.com/runwareschemaless/v1/request";
+const MEDIA_IMPORT_URL = "https://www.wixapis.com/site-media/v1/files/import";
+const GEN_TIMEOUT_MS = 120_000;   // google:4@2 is slow; generous per-task cap
+const IMPORT_TIMEOUT_MS = 60_000;
+const ALLOWED_DIMS = [[1024, 1024], [1376, 768], [1200, 896]];
+
+function fail(reason) {
+  console.log(JSON.stringify({ status: "failed", reason }, null, 2));
+  process.exit(1);
+}
+
+// ---- input ----------------------------------------------------------------
+let input;
+try {
+  input = JSON.parse(readFileSync(0, "utf8"));
+} catch (e) {
+  fail(`stdin is not valid JSON (${e.message})`);
+}
+const siteId = input.siteId;
+const model = input.model || "google:4@2";
+const images = Array.isArray(input.images) ? input.images : [];
+if (!siteId) fail("siteId is required");
+if (images.length === 0) fail("no images in input — nothing to generate");
+
+// ---- token (mint-once: prefer env/field, mint only as fallback) -----------
+let token = process.env.WIX_TOKEN || input.token;
+if (!token) {
+  try {
+    token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
+      cwd: input.projectDir || process.cwd(),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch (e) {
+    fail(`no token: pass WIX_TOKEN env or stdin "token", or run where the CLI can mint (${e.message})`);
+  }
+}
+if (!token) fail("token minting returned empty");
+
+const baseHeaders = {
+  Authorization: `Bearer ${token}`,
+  "wix-site-id": siteId,
+  "Content-Type": "application/json",
+};
+
+// ---- one fetch with timeout + reqid capture -------------------------------
+async function call(url, body, timeoutMs) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: baseHeaders,
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    const reqId = res.headers.get("x-wix-request-id") || null;
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* keep raw */ }
+    return { ok: res.ok, status: res.status, reqId, json, raw: text };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+function normalizeDims(w, h) {
+  if (ALLOWED_DIMS.some(([aw, ah]) => aw === w && ah === h)) return [w, h];
+  return [1024, 1024]; // safe default — Runware rejects free-form sizes (400)
+}
+
+// Generate one image (single-task body — the form the default model accepts),
+// then import it to Wix Media. Returns a per-image record; never throws.
+async function genAndImport(img) {
+  const key = img.key;
+  const taskUUID = img.taskUUID || randomUUID();
+  const [width, height] = normalizeDims(img.width ?? 1024, img.height ?? 1024);
+  const outputFormat = (img.outputFormat || "PNG").toUpperCase();
+  const rec = { key, taskUUID, status: "failed", genReqId: null, importReqId: null };
+
+  if (!img.positivePrompt) {
+    return { ...rec, error: { key, stage: "input", code: "NO_PROMPT", message: "positivePrompt missing" } };
+  }
+
+  // --- generate (retry once on transient 5xx/504/timeout) ---
+  const task = {
+    taskType: "imageInference",
+    taskUUID,
+    outputType: "URL",
+    outputFormat,
+    positivePrompt: img.positivePrompt,
+    width,
+    height,
+    model,
+    numberResults: 1,
+    // NB: never send `steps`/`CFGScale` — google:4@2 rejects them (400).
+  };
+  let gen, imageURL;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      gen = await call(RUNWARE_URL, [task], GEN_TIMEOUT_MS);
+    } catch (e) {
+      gen = { ok: false, status: e.name === "AbortError" ? 504 : 0, reqId: null, json: null, raw: String(e) };
+    }
+    rec.genReqId = gen.reqId;
+    const data = Array.isArray(gen.json?.data) ? gen.json.data : null;
+    imageURL = data?.[0]?.imageURL;
+    if (gen.ok && imageURL) break;
+    // transient → retry once; hard 4xx (except 504-shaped) → give up
+    const transient = gen.status >= 500 || gen.status === 504 || gen.status === 0;
+    if (!transient || attempt === 1) {
+      return {
+        ...rec,
+        error: {
+          key, stage: "generate", code: String(gen.status),
+          message: gen.json?.errors?.[0]?.message || gen.json?.errorMessage || gen.raw?.slice(0, 200) || "no imageURL in response",
+          reqId: gen.reqId,
+        },
+      };
+    }
+  }
+
+  // --- import to Wix Media ---
+  let imp;
+  try {
+    imp = await call(MEDIA_IMPORT_URL, {
+      url: imageURL,
+      mimeType: outputFormat === "JPG" ? "image/jpeg" : "image/png",
+      displayName: img.displayName || `${key}.${outputFormat.toLowerCase()}`,
+    }, IMPORT_TIMEOUT_MS);
+  } catch (e) {
+    imp = { ok: false, status: 0, reqId: null, json: null, raw: String(e) };
+  }
+  rec.importReqId = imp.reqId;
+  const file = imp.json?.file;
+  if (!imp.ok || !file?.url) {
+    return {
+      ...rec,
+      error: {
+        key, stage: "import", code: String(imp.status),
+        message: imp.json?.message || imp.raw?.slice(0, 200) || "no file.url in import response",
+        reqId: imp.reqId,
+      },
+      // generation succeeded — surface the raw URL so the caller can decide
+      genURL: imageURL,
+    };
+  }
+
+  return { ...rec, status: "ok", url: file.url, fileId: file.fileUrl }; // Wix returns the file ID in .fileUrl (not .url)
+}
+
+// ---- run all in parallel --------------------------------------------------
+const settled = await Promise.allSettled(images.map(genAndImport));
+const results = settled.map((s, i) =>
+  s.status === "fulfilled" ? s.value
+    : { key: images[i].key, status: "failed", error: { key: images[i].key, stage: "internal", message: String(s.reason) } });
+
+const map = {};
+const slots = {};
+const errors = [];
+let okCount = 0;
+for (const r of results) {
+  if (r.status === "ok") {
+    okCount++;
+    map[r.key] = { url: r.url, fileId: r.fileId };
+    slots[r.key] = r.url;
+  } else if (r.error) {
+    errors.push(r.error);
+  }
+}
+
+const status = okCount === images.length ? "complete" : okCount === 0 ? "failed" : "partial";
+console.log(JSON.stringify({
+  status,
+  model,
+  count: { requested: images.length, ok: okCount, failed: images.length - okCount },
+  map,
+  slots,
+  results: results.map(({ url, fileId, genURL, ...keep }) => keep), // keep slim; urls live in map
+  errors,
+}, null, 2));
+
+process.exit(status === "failed" ? 1 : 0);

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

@@ -2,11 +2,17 @@
 # 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>" [--frontend astro|custom]
+#   bash <SKILL_ROOT>/scripts/scaffold.sh <folder-name> "<Brand Name>" [--frontend astro|custom]
 #
-# <project-slug>: 3-20 lowercase alphanumeric chars (no hyphens, no spaces) — the
-#                 Wix CLI rejects anything else. Becomes the project directory name.
-# <Brand Name>:   human-readable business name; quote if it contains spaces.
+# <folder-name>:  lowercase letters, numbers, and hyphens only; must start with a
+#                 letter or number. The CLI scaffolds into a subdir of this name,
+#                 which this script then FLATTENS into the current directory (see
+#                 "In-place flatten" below) — so the project ends up *in CWD*, not
+#                 in a nested folder. The name is still required (the CLI mandates
+#                 it) but the local folder is transient.
+# <Brand Name>:   human-readable business name; quote if it contains spaces. The
+#                 CLI derives the Wix project display-name and URL slug from it, so
+#                 it must include at least one English letter or number.
 # --frontend:     the frontend axis. Defaults to "astro" — the only supported (and
 #                 only scaffolded) frontend. "custom" (any non-astro frontend) is
 #                 NOT scaffolded yet: Discovery routes custom to the not-available
@@ -14,12 +20,13 @@
 #                 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 as --site for `wix token` and in REST call
-# bodies). The orchestrator does that read; this script just runs the npm create.
+# After scaffold succeeds, the project lives in the CURRENT directory (the subdir
+# was flattened away). Read ./wix.config.json to extract appId (project's appId)
+# and siteId (used as --site for `wix token` and in REST call bodies). The
+# orchestrator does that read; this script runs the npm create + the flatten.
 #
 # Behavior:
-#   - Pre-flight validates the slug (regex ^[a-z0-9]{3,20}$).
+#   - Pre-flight validates the folder name syntax (regex ^[a-z0-9][a-z0-9-]*$).
 #   - Pre-flight requires both positional args.
 #   - Runs `npm create @wix/new@latest headless` with --no-publish + --skip-install
 #     so the orchestrator can deferred-install with its own package set.
@@ -27,12 +34,15 @@
 #     blank starter. Without it, @wix/create-new (>=0.0.72) prompts for a template
 #     choice and aborts in a non-TTY agent shell ("not supported in non-interactive
 #     terminals").
+#   - FLATTENS the scaffolded subdir into CWD (single-folder layout: one `.wix`,
+#     CWD == project == site-root). Interim until the CLI supports in-place create.
 #
 # Exit codes:
 #   0 — ok
-#   2 — argument validation failed (bad slug, missing args, unknown --frontend value)
+#   2 — argument validation failed (bad folder name, missing args, unknown --frontend value)
 #   3 — Wix CLI not logged in (defensive; the Discovery pre-flight is the primary check)
 #   4 — frontend value recognized but not scaffolded yet (custom today)
+#   5 — scaffold succeeded but the subdir could not be flattened into CWD (name collision)
 #   <other> — npm create failed; stderr surfaced to caller for orchestrator-side
 #             recovery (auth / other scaffold failures live in the orchestrator).
 
@@ -62,8 +72,8 @@ while [[ $# -gt 0 ]]; do
 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
+  echo "scaffold.sh: both positional args required. Got folder-name='${POSITIONAL[0]:-}' brand-name='${POSITIONAL[1]:-}'." >&2
+  echo "Usage: bash scaffold.sh <folder-name> \"<Brand Name>\" [--frontend astro|custom] — folder name first, brand quoted." >&2
   exit 2
 fi
 
@@ -81,10 +91,10 @@ case "$FRONTEND" in
     ;;
 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
+if [[ ! "${POSITIONAL[0]}" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+  echo "scaffold.sh: folder-name='${POSITIONAL[0]}' is not valid." >&2
+  echo "Folder name must contain only lowercase letters, numbers, and hyphens, and start with a letter or number." >&2
+  echo "Derive it from the brand as a lowercase, npm-safe directory name." >&2
   exit 2
 fi
 
@@ -100,9 +110,30 @@ if ! npx @wix/cli@latest whoami >/dev/null 2>&1; then
   exit 3
 fi
 
+FOLDER="${POSITIONAL[0]}"
+
 npm create @wix/new@latest headless -- \
   --business-name "${POSITIONAL[1]}" \
-  --project-name "${POSITIONAL[0]}" \
+  --folder-name "$FOLDER" \
   --site-template \
   --no-publish \
   --skip-install
+
+# --- In-place flatten (interim hack) -----------------------------------------
+# The CLI always scaffolds into a named subdir; there is NO in-place option —
+# `headless init` regex-rejects `--folder-name .` ("must contain only lowercase
+# letters, numbers, and hyphens") and offers no --cwd/--here flag. To keep the
+# whole run single-folder (one `.wix`, CWD == project == site-root, no nested
+# `.wix` to reason about), fold the scaffolded subdir up into the current dir.
+#
+# The .wix-merge + mv -n + rmdir logic is identical to flatten.sh (the own-build
+# path's framework-agnostic flatten), so we delegate to it rather than duplicate.
+# flatten.sh lives next to this script; resolve its path relative to our own dir
+# so the call works regardless of CWD. (Both exit 5 on the same name-collision.)
+# When the CLI gains `--folder-name .` (or --cwd), the TODO to drop the flatten
+# lives in flatten.sh.
+if [[ -d "$FOLDER" ]]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  bash "$SCRIPT_DIR/flatten.sh" "$FOLDER"
+fi
+# -----------------------------------------------------------------------------