@wix/agent-skills 1.7.0 → 1.8.0

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

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

package/skills/wix-manage/SKILL.md

@@ -6,7 +6,7 @@ compatibility: Requires Wix REST API access (API key or OAuth).
 
 # Management Recipes Index
 
-> **Standard call shape for every curl example across these recipes.** The `<AUTH>` placeholder in example curls is shorthand for the `Authorization` header only; every actual call ALSO needs `wix-site-id: <SITE_ID>` and `Content-Type: application/json`. **POST/PATCH against `wix-data/*`, `form-schema-service/*`, `stores/v3/*`, `blog/v3/*`, and other site-scoped REST families return 403 without `wix-site-id`** — observed seeder regression cost ~100 s rediscovering this on a 2026-05-24 run. Mint the token via `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape for every curl example across these recipes.** The `<AUTH>` placeholder in example curls is shorthand for the `Authorization` header only; body-bearing calls also need `Content-Type: application/json`.
 
 ## What Are Management Recipes?
 

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

@@ -5,7 +5,7 @@ description: Creates and publishes blog posts using Blog Posts API. Covers Ricos
 
 **Article: Create and Publish Blog Posts with Rich Content and Images**
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST against `blog/v3/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 ---
 

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

@@ -4,7 +4,7 @@ description: "Add, query, update, and delete items in CMS collections. Use this
 ---
 # CMS Data Items CRUD
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST/PATCH against `wix-data/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
 

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

@@ -4,7 +4,7 @@ description: "Add, replace, or remove items from MULTI_REFERENCE fields. Use ins
 ---
 # CMS References & Relationships
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST/PATCH against `wix-data/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 This recipe covers linking CMS collections together using reference fields.
 

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

@@ -4,7 +4,7 @@ description: Create and modify CMS collection structures. Covers listing collect
 ---
 # CMS Schema Management
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST/PATCH against `wix-data/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 This recipe covers managing the structure (schema) of Wix CMS collections using the REST API.
 

package/skills/wix-manage/references/domains/domain-search-and-purchase.md

@@ -218,13 +218,18 @@ Replace `{domain}` with the chosen domain (e.g. `mybakery.com`).
 ```json
 {
   "domainRegistrationIntent": {
-    "registrantContact": { "firstName": "...", "lastName": "...", "email": "...", "phone": "...", "address": { ... } },
+    "registrantContact": {
+      "firstName": "...", "lastName": "...", "email": "...", "phone": "...",
+      "streetAddress": "...", "city": "...", "country": "...", "postalCode": "..."
+    },
     "adminContact": { ... },
     "techContact": { ... }
   }
 }
 ```
 
+> Address fields are **flat** on each contact (`streetAddress`, `city`, `country`, `postalCode`) — there is no nested `address` sub-object.
+
 - **If contacts exist**: Show the info and explicitly ask "Should I use these details, or would you like to register with different info?" Wait for the user to confirm before proceeding to Step 3. Do NOT skip this confirmation.
 - **If contacts are empty**: Ask the user for: first name, last name, email, phone number, street address, city, country, and postal code. The user can provide country as a full name (e.g. "Israel", "United States") -- convert it to the 2-letter ISO country code (e.g. "IL", "US") before sending to the API. Wait for them to provide all fields before proceeding.
 
@@ -249,12 +254,10 @@ Body:
       "lastName": "Smith",
       "email": "john@email.com",
       "phone": "+1.5551234567",
-      "address": {
-        "streetAddress": "123 Main St",
-        "city": "New York",
-        "country": "US",
-        "postalCode": "10001"
-      }
+      "streetAddress": "123 Main St",
+      "city": "New York",
+      "country": "US",
+      "postalCode": "10001"
     },
     "adminContact": { ... same as registrant ... },
     "techContact": { ... same as registrant ... }

package/skills/wix-manage/references/forms/create-form.md

@@ -4,7 +4,7 @@ description: Creates a form with fields (name, email, etc.) using the Form Schem
 ---
 # RECIPE: Create a Wix Form
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST against `form-schema-service/v4/forms` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 Create a form on a Wix site that appears in the Forms & Submissions dashboard. The form collects visitor information (e.g., name, email) and can automatically upsert contacts on submission.
 
@@ -217,6 +217,7 @@ Verify the form in the dashboard: `https://manage.wix.com/dashboard/{siteId}/for
 - **CRITICAL: The `identifier` must be a recognized Wix value.** Custom identifiers like `"product_name"` or `"color_preference"` will cause the field to be silently dropped from the form — no error is thrown. For any generic/custom text field, use `"TEXT_INPUT"` as the identifier and set the display name via the `label` property in `textInputOptions`.
 - For plain text fields, use `"format": "UNKNOWN_FORMAT"`. For email fields, use `"format": "EMAIL"`. For phone fields, use `"format": "PHONE"`. Valid format values: `UNKNOWN_FORMAT`, `DATE`, `TIME`, `DATE_TIME`, `EMAIL`, `URL`, `UUID`, `PHONE`, `URI`, `HOSTNAME`, `COLOR_HEX`, `CURRENCY`, `LANGUAGE`, `DATE_OPTIONAL_TIME`.
 - The submit button is a `DISPLAY` field with `identifier: "SUBMIT_BUTTON"`.
+- **Build the complete form in one call — do not create throwaway "test" forms to probe field shapes.** A site has a **low form cap (~4 forms)**; iterative probing hits the cap (`maximum number of forms reached`), forcing you to `GET` the form list and `DELETE` the test forms before the real create can succeed. Assemble all fields (including any RADIO_GROUP/DROPDOWN per § "Choice fields") and POST once.
 
 ### Field Types Reference
 
@@ -228,9 +229,54 @@ Verify the form in the dashboard: `https://manage.wix.com/dashboard/{siteId}/for
 | `CONTACTS_EMAIL` | `TEXT_INPUT` | `EMAIL` | Contact email |
 | `CONTACTS_PHONE` | `TEXT_INPUT` | `PHONE` | Contact phone |
 | `SUBMIT_BUTTON` | N/A (`DISPLAY` field) | N/A | Submit button |
+| `TEXT_INPUT` | `RADIO_GROUP` | `UNKNOWN_FORMAT` | Single-choice from a fixed list (radio buttons) — see § "Choice fields" |
+| `TEXT_INPUT` | `DROPDOWN` | `UNKNOWN_FORMAT` | Single-choice from a fixed list (dropdown) — same shape as RADIO_GROUP |
 
 > **Note:** `LONG_TEXT_INPUT` is not supported as a `componentType` via REST — it throws `INVALID_ARGUMENT`. Use `TEXT_INPUT` for all text fields.
 
+### Choice fields (RADIO_GROUP / DROPDOWN)
+
+A single-choice field (radio buttons or a dropdown — e.g. an RSVP "Will you attend?") is a **`STRING` input field**, not a separate field type. It uses `identifier: "TEXT_INPUT"`, `inputType: "STRING"`, and sets `componentType` to `RADIO_GROUP` (or `DROPDOWN`) **inside `stringOptions`**. Two things must agree or the field breaks:
+
+1. **`stringOptions.validation.enum`** must list every option `value` (an empty `enum` is for free-text only).
+2. **`stringOptions.radioGroupOptions.options[]`** carries the rendered choices — each option needs its own **UUID `id`**, a `value`, and a `label`. (For `DROPDOWN`, use `dropdownOptions` with the same `{id, value, label}` shape.)
+
+> **CRITICAL — silent fallback to TEXT_INPUT.** If `radioGroupOptions` is missing/malformed (wrong key like `choices` instead of `options`, an option missing its `id`, or an empty `validation.enum`), the API does **not** error — it silently creates the field as a plain `TEXT_INPUT`. If a choice field renders as a text box, this is why. Build it correctly on the first call; do not probe.
+
+```json
+{
+  "id": "a1b2c3d4-1002-4e00-8001-000000000002",
+  "hidden": false,
+  "identifier": "TEXT_INPUT",
+  "fieldType": "INPUT",
+  "inputOptions": {
+    "target": "attending_0002",
+    "pii": false,
+    "required": true,
+    "inputType": "STRING",
+    "readOnly": false,
+    "stringOptions": {
+      "validation": {
+        "format": "UNKNOWN_FORMAT",
+        "enum": ["Joyfully accepts", "Regretfully declines"]
+      },
+      "componentType": "RADIO_GROUP",
+      "radioGroupOptions": {
+        "label": "Will you attend?",
+        "showLabel": true,
+        "numberOfColumns": "ONE",
+        "options": [
+          { "id": "c3d4e5f6-3001-4a00-8001-000000000001", "value": "Joyfully accepts", "label": "Joyfully accepts" },
+          { "id": "c3d4e5f6-3001-4a00-8001-000000000002", "value": "Regretfully declines", "label": "Regretfully declines" }
+        ]
+      }
+    }
+  }
+}
+```
+
+`numberOfColumns` is a string enum (`"ONE"`, `"TWO"`, `"THREE"`) controlling the radio layout — omit it and the field still works (defaults to one column).
+
 ### Layout
 
 The `steps[].layout.large.items` array controls how fields are positioned:
@@ -252,6 +298,8 @@ The Wix Forms app (appDefId: `14ce1214-b278-a7e4-1373-00cebd1bef7c`) must be ins
 |---|---|---|
 | `Unrecognized value passed for enum` | Invalid `componentType` value (e.g., `LONG_TEXT_INPUT`) | Use only `componentType` values from the schema: `TEXT_INPUT`, `RADIO_GROUP`, `DROPDOWN`, `DATE_TIME`, `PHONE_INPUT`, `DATE_INPUT`, `TIME_INPUT`, `DATE_PICKER`, `PASSWORD` |
 | Field silently missing from created form | Custom `identifier` value (e.g., `"product_name"`) | Use a recognized identifier like `TEXT_INPUT` and set display name via `label` |
+| Choice field rendered as a plain text box | `radioGroupOptions`/`dropdownOptions` malformed (wrong key, option missing `id`, empty `validation.enum`) — API silently falls back to `TEXT_INPUT` | Match the § "Choice fields" shape exactly: `componentType` in `stringOptions`, `options[]` each with a UUID `id`, and `validation.enum` listing all option values |
+| `maximum number of forms reached` / form-cap error | Sites cap at ~4 forms; reached by creating throwaway test forms | `GET form-schema-service/v4/forms` then `DELETE` the unwanted forms; build the real form in one call (don't probe) |
 | `Permissions for given namespace not found` | `wix.form_app.form` namespace not active | Ensure the Wix Forms app is installed; try creating a form through the UI first to activate the namespace |
 | `missing installed app` | Wix Forms app not installed | Install app `14ce1214-b278-a7e4-1373-00cebd1bef7c` via the [Install Wix Apps](../app-installation/install-wix-apps.md) recipe |
 

package/skills/wix-manage/references/stores/bulk-create-products-with-options.md

@@ -4,7 +4,7 @@ description: Uses bulk products endpoint to create multiple products with invent
 ---
 # RECIPE: Business Recipe - Bulk Creating Wix Store Products with inventory and options
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST against `stores/v3/bulk/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 Learn how to create multiple Wix store products with customizable options like colors, sizes, or other variants in a single bulk operation, allowing efficient creation of product catalogs.
 

package/skills/wix-manage/references/stores/setup-online-store-catalog-v3.md

@@ -4,7 +4,7 @@ description: Initializes a Stores catalog with Catalog V3 Products API, bulk pro
 ---
 **RECIPE**: Business Recipe – Initial Setup for a Wix Online Store (Catalog V3)
 
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Every actual call ALSO needs `wix-site-id: <SITE_ID>` and (for body-bearing requests) `Content-Type: application/json`. **POST/PATCH against `stores/v3/*` and `categories/v1/*` returns 403 without `wix-site-id`** — recipe examples below show `<AUTH>` only for brevity, but the header is required on every call you make. Token: `npx @wix/cli@latest token --site "$SITE_ID"`.
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
 
 A concise checklist for preparing any new Wix site that uses the Online Stores app with Catalog V3.
 **Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial catalog setup.

package/skills/wix-headless/references/astro/COMPOSE.md

@@ -1,142 +0,0 @@
----
-name: design-system-composer
-description: "The Composer role of the wix-headless design-system phase. Applies the Designer's framework-agnostic design spec to the astro frontend by SUBSTITUTING into pinned skeletons at references/astro/templates/ — it does not re-author the fixed bulk. Maps semantic token values to the @theme vocabulary, writes the 6 design-system files (global.css, astro.config.mjs, Layout.astro, Navigation.astro, Footer.astro, index.astro), and owns the component-CSS token contract (every var(--token) a components-<pack>.css references must resolve). Returns a manifest."
----
-
-# Composer — how the design becomes code
-
-You are the **Composer**. The Designer already decided *what the brand looks like* and returned it as a framework-agnostic spec. Your job is *how that becomes code* for the **astro** frontend: you map the spec onto the framework's token vocabulary and **substitute it into pinned skeletons**. You do **not** re-author the fixed bulk — the View-Transitions script, the view-transition / `.nav-progress` CSS, the `@utility btn` family, the `process.env` fix, the markers — all of that is literal in the skeletons. Read a skeleton, fill its `{{…}}` slots, write the file. Substitute; do not re-write.
-
-This is deterministic work against pinned templates, so it is fast and low-variance. The whole reason the rewrite-from-scratch failure mode (which roughly doubled the old design-system wall) is gone is that you never regenerate the bulk.
-
-> **Framework:** astro only. The skeletons live at `<SKILL_ROOT>/references/astro/templates/`. Custom (non-astro) frontends never reach the Composer — they route to the not-available-yet stub (`references/custom/INSTRUCTIONS.md`) before the build flow runs. If your prompt ever names a non-astro frontend, return `status: "failed"` with `errors: [{code: "FRONTEND_NOT_SUPPORTED"}]` — do not improvise a second framework.
-
-## Self-Loading
-
-1. Read `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` — structured-return format.
-2. Read `<SKILL_ROOT>/references/shared/STYLING.md` — the three styling categories and, in particular, § "Required tokens — the component-CSS template contract" (the token set you must guarantee). You own that contract now.
-
-No REST calls, no MCP — this is frontend-only work.
-
-**Do NOT `Read .wix/site.json`.** Every input is inlined in your prompt.
-
-## Inputs (entirely from your prompt)
-
-- **`designTokens`** — the Designer's spec (`colors`, `fonts`, `spacing`, `radii`, `containers`), bare-key form.
-- **`shell`** — brand-voice strings: `heroHeadline`, `heroSub`, `footerTagline`, `navBrandMark`.
-- **Brand** — `{ name, description }`.
-- **Navigation links** — JSON array of `{href, label}`. Use labels **verbatim**.
-- **Loaded packs**, **Packs with components**, **Disabled packs** — comma-joined lists.
-- **Project directory** — the scaffold subdir (CWD).
-
-## What you write (the 6 files)
-
-Read each skeleton from `<SKILL_ROOT>/references/astro/templates/`, substitute, write to the project. The fixed bulk in every skeleton is literal — change only the documented `{{…}}` slots.
-
-> **Read skeletons by file, never the directory (`EISDIR`).** `Read <SKILL_ROOT>/references/astro/templates/` fails with `EISDIR: illegal operation on a directory` and costs a wasted recovery round-trip. Read each of the six by its exact path: `<SKILL_ROOT>/references/astro/templates/global.css`, `…/astro.config.mjs`, `…/Layout.astro`, `…/Navigation.astro`, `…/Footer.astro`, `…/index.astro` (issue the six `Read`s as one concurrent batch). If you must discover them first, `Glob` the directory (`…/templates/*`) — never `Read` it.
-
-**Pre-write: scaffold may still be in flight.** A scaffold file you need (`Layout.astro` stub, `astro.config.mjs`) may not yet be present. Before reading one, if a `Read` returns "file does not exist", wait 5 s and retry, cap 6 attempts (~30 s). The 6-attempt cap is hard — do not check a 7th time; return `status: "failed"` with `errors: [{code: "SCAFFOLD_NOT_COMPLETE"}]` immediately on attempt 6's miss. (Reading the *skeletons* under `<SKILL_ROOT>` never needs this — they are always present.)
-
-**Read each destination before you overwrite it.** The scaffold ships stubs for several of your six targets (today: `src/layouts/Layout.astro`, `src/pages/index.astro`, `astro.config.mjs`). The harness **blocks a `Write` to an existing file you have not `Read` this run** (`File has not been read yet`). So your batched reads must include the *destination* project paths for any file the scaffold created — not only the `<SKILL_ROOT>` skeletons. Practically: in the same concurrent batch, `Read` both the skeleton and the destination for `Layout.astro`, `index.astro`, and `astro.config.mjs` (the latter you read anyway to merge); `global.css`, `Navigation.astro`, and `Footer.astro` are net-new, so a destination read isn't required (but is harmless if the scaffold happens to ship them).
-
-### Token contract (do this first — it gates everything)
-
-Map the Designer's `designTokens` into the `@theme` palette that goes in `global.css`, and **guarantee every required token resolves**. Per `STYLING.md` § "Required tokens", the `components-<pack>.css` templates reference a fixed set via `var(--token)`. Your `@theme` MUST declare all of:
-
-- `--color-{paper,paper-warm,ink,mute,rule,accent}` (required), `--color-{ink-soft,cream,error}` (recommended).
-- `--font-{display,body}`.
-- the full `--spacing-{2xs,xs,sm,md,lg,xl,2xl,3xl,4xl}` scale.
-- `--radius-{sm,md}` (required), `--radius-{lg,xl}` (recommended).
-- a **container scale** separate from spacing: `--container-{prose,md,3xl,6xl}` minimum.
-
-If the Designer's spec is missing a required role, **derive** a sensible value (e.g. `ink-soft` ≈ `ink` lightened, `paper-warm` ≈ `paper` warmed) rather than dropping the token — a missing required token renders components unstyled. Map each group with the fixed prefix: `colors.<k>` → `--color-<k>`, `fonts.<k>` → `--font-<k>`, `spacing.<k>` → `--spacing-<k>`, `radii.<k>` → `--radius-<k>`, `containers.<k>` → `--container-<k>`.
-
-> **Container ≠ spacing.** Tailwind v4 maps `max-w-3xl` → `var(--container-3xl)`, not `var(--spacing-3xl)`. Never set a `--container-*` to a spacing value — a reading column is ~`42rem`, not `5rem`, or pages collapse to one word per line.
-
-### 1. `global.css`
-
-Substitute the `{{theme}}` block in the skeleton with the `@theme` palette you built above — every `--color-*`, `--font-*`, `--spacing-*`, `--container-*`, `--radius-*` line. **Everything else in the skeleton is literal** (the `@utility container-reading`/`btn`, base layer, button family, decorative + site-shell + view-transition + nav-submenu + category-rail CSS). Do not add component-specific classes (`.product-card`, `.cart-summary`, …) — those live in `components-<pack>.css`, owned by Phase 3.
-
-### 2. `astro.config.mjs`
-
-This is a **merge, not a clobber** — the scaffold's config varies. Read the scaffold's `astro.config.mjs` and apply exactly two mutations (the skeleton shows the target shape):
-1. Register the Tailwind v4 Vite plugin: `import tailwindcss from "@tailwindcss/vite";` and merge `tailwindcss()` into `vite.plugins` (preserve any existing `vite` settings — `server.allowedHosts`, etc.).
-2. Fix the bare `process.env` line (`const isBuild = process.env.NODE_ENV == "production";`) to the `globalThis` guard so strict `tsc --noEmit` passes without `@types/node`.
-
-### 3. `Layout.astro`
-
-Fully replace the scaffold stub. Substitute:
-- `{{components-css-imports}}` — one `import '../styles/components-<pack>.css';` per pack in **"Packs with components"**, in that order. Packs without components (e.g. `cms`) get **no** import — importing a file no agent writes breaks the build. If "Packs with components" is empty, remove the placeholder line entirely.
-- `{{fonts.googleHref}}` — the Google Fonts stylesheet href for the chosen `display` + `body` families (e.g. `https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@...&family=Inter:wght@400;500;600&display=swap`). If both fonts are system fonts, remove the `<link rel="stylesheet">` line.
-- `{{brand.name}}` — the default `<title>`.
-
-The View-Transitions `<script>`, the `nav-progress` div, the `ClientRouter`, the `Props` interface, and the `hasSeoTags` pattern are **literal** — keep them.
-
-### 4. `Navigation.astro`
-
-Substitute `{{shell.navBrandMark}}` and `{{nav.links}}` (one `<li class="site-nav-item"><a href={href}>{label}</a></li>` per inlined nav link, labels **verbatim** — no editorial rebrands like "Journal" for `/about`). Keep the `<!-- nav:links -->` marker, the empty `<div class="nav-actions">`, the `transition:persist`, and the hamburger literal. Do **not** add `/products`, cart, login, or account links — packs splice those at the marker in Phase 4.
-
-### 5. `Footer.astro`
-
-Substitute `{{brand.name}}`, `{{shell.footerTagline}}`, and `{{nav.links}}` (mirror/subset of the same array, labels verbatim). Keep `transition:persist` literal.
-
-### 6. `index.astro`
-
-Substitute `{{shell.heroHeadline}}`, `{{shell.heroSub}}`, `{{brand.name}}`, and `{{home-markers}}`. For `{{home-markers}}`, emit one `<!-- home:<pack> -->` marker per **loaded pack that contributes a home section** (today: `stores`, `gift-cards`). Emit a marker **only** for such packs — never one no pack will fill (no `<!-- home:cms -->`; CMS owns brand-story directly, which the skeleton already renders). Keep the hero + brand-story structure and both `data-decorative-slot` placeholders literal and **empty** (the orchestrator injects `<img>` after Image Phase 1).
-
-## Disabled-pack discipline
-
-A pack in **"Disabled packs"** (today: only `gift-cards`) ships dormant. Its `<!-- home:<pack> -->` / `<!-- nav:links -->` markers are the **only** acceptable touchpoints. Do **not** add hero CTAs, footer links, brand-story callouts, or any other entry point pointing at a disabled pack's route — users click through to a feature that does not exist yet. Treat disabled packs as code-only: they appear in your marker emission, never in visible UI you author.
-
-## Self-checks before returning
-
-1. **Component-CSS imports.** For every pack in "Packs with components", grep your written `Layout.astro` for `components-<pack>.css`. If any is missing, add it. If unrecoverable, return `status: "partial"` with `errors: [{code: "MISSING_COMPONENT_CSS_IMPORT", pack: "<name>"}]`. (The orchestrator also re-verifies this after you return — at the seed gate — but catch it here.)
-2. **Required-token coverage.** Confirm every required token from the contract above is present in the `@theme` block you wrote. A missing one renders components unstyled.
-3. **Container vs spacing.** Confirm no `--container-*` was set to a spacing value.
-4. **Marker hygiene.** No marker emitted for a pack that does not contribute; both decorative slots present and empty.
-
-If a check fails and you cannot fix it, return `status: "partial"` with the specific `errors` code rather than shipping silently.
-
-## Return contract
-
-A single fenced JSON block per `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`, last content in your message — a manifest of what you wrote:
-
-```json
-{
-  "status": "complete",
-  "phase": "compose",
-  "data": {
-    "filesWritten": [
-      "src/styles/global.css",
-      "astro.config.mjs",
-      "src/layouts/Layout.astro",
-      "src/components/Navigation.astro",
-      "src/components/Footer.astro",
-      "src/pages/index.astro"
-    ],
-    "componentCssImports": ["stores", "ecom"],
-    "homeMarkers": ["home:stores"],
-    "tokensApplied": { "colors": 9, "spacing": 9, "containers": 4, "radii": 2, "fonts": 2 }
-  },
-  "files": [ "...same as filesWritten..." ]
-}
-```
-
-No trailing prose after the closing fence.
-
-## Anti-patterns
-
-| WRONG | CORRECT |
-|---|---|
-| Re-author the View-Transitions script, btn family, or view-transition CSS | Keep the skeleton bulk literal; substitute only `{{…}}` slots |
-| Rewrite `global.css` from scratch to "clean it up" | Substitute `{{theme}}`; the rest is pinned (this is the variance win) |
-| Overwrite `astro.config.mjs` with the skeleton verbatim | Merge the two mutations into the scaffold's own config |
-| `import '../styles/components-cms.css'` (cms has no components) | One import only per pack in "Packs with components" |
-| Drop a required token because the Designer omitted it | Derive a sensible value — required tokens must resolve |
-| Set `--container-3xl` to `--spacing-3xl`'s value | Containers are widths (~`42rem`+), a separate axis from spacing |
-| Coin label rebrands ("Journal" → /about) or add `/products`/cart links | Nav labels verbatim; packs splice their links at the marker |
-| Add a hero CTA / footer link to a disabled-pack route | Disabled packs are code-only — markers are the sole touchpoint |
-| Emit `<!-- home:cms -->` or a marker for a non-contributing pack | One marker per contributing loaded pack only |
-| `Read <SKILL_ROOT>/references/astro/templates/` (the directory) | `EISDIR` — Read each of the six skeletons by its exact file path (batch the six Reads); `Glob` if you must discover them |
-| `Read .wix/site.json` for brand/tokens | Every input is inlined in your prompt |
-| Branch to a non-astro / custom frontend | astro only; return `FRONTEND_NOT_SUPPORTED` otherwise |

package/skills/wix-headless/scripts/finalize-run-json.mjs

@@ -1,141 +0,0 @@
-#!/usr/bin/env node
-// Finalize and write .wix/run.json at the end of the build.
-//
-// The orchestrator collects agent returns, timings, and outcome data over the
-// run. This script takes the orchestrator's draft as a JSON blob via stdin,
-// runs the timing-completeness gate (every required phase MUST have non-null
-// seconds, otherwise emit MISSING_TIMING errors), computes totalSeconds from
-// started/ended, writes the canonical .wix/run.json, and prints the perf
-// one-liner the orchestrator shows in the final message.
-//
-// Usage:
-//   echo "$DRAFT_JSON" | node finalize-run-json.mjs <project-dir>
-//
-// Input shape (via stdin):
-//   {
-//     "run":   { started, ended, brand, prompt, verticals, packs },
-//     "outcome": { build, previewUrl, dashboardUrl, ... },
-//     "phases":  [ { phase, status, seconds, data?, errors? }, ... ],
-//     "recoveries": [ ... ],   // optional; from manifest-check script outputs
-//     "errors":     [ ... ],   // optional; from agent returns / orchestrator
-//     "notes":      [ ... ],   // optional
-//     "requiredPhases": ["scaffold","app-install-Wix Stores","env-pull",...]
-//   }
-//
-// `requiredPhases` is the orchestrator's set of skill-invoked phases that MUST
-// have a captured duration (scaffold, every app-install-*, env-pull,
-// seed-utilities, npm-install, build, release|preview, etc.). The set is
-// run-specific (number of app-install-* depends on loaded packs), so the
-// orchestrator passes it in rather than the script guessing.
-//
-// Output:
-//   - Writes .wix/run.json (full shape, with timing-completeness gate applied).
-//   - Prints to stdout: a JSON object with { perfLine, missingTiming, totalSeconds }.
-
-import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-const projectDir = process.argv[2];
-
-if (!projectDir) {
-  console.error("usage: cat draft.json | finalize-run-json.mjs <project-dir>");
-  process.exit(2);
-}
-
-let draft;
-try {
-  draft = JSON.parse(readFileSync(0, "utf8"));
-} catch (e) {
-  console.error(`finalize-run-json: stdin is not valid JSON (${e.message})`);
-  process.exit(2);
-}
-
-const run = draft.run ?? {};
-const phases = Array.isArray(draft.phases) ? [...draft.phases] : [];
-const errors = Array.isArray(draft.errors) ? [...draft.errors] : [];
-const recoveries = Array.isArray(draft.recoveries) ? draft.recoveries : [];
-const notes = Array.isArray(draft.notes) ? draft.notes : [];
-const outcome = draft.outcome ?? {};
-const requiredPhases = Array.isArray(draft.requiredPhases) ? draft.requiredPhases : [];
-
-// ---- 1. Timing completeness gate ------------------------------------------
-const phasesByName = new Map();
-for (const p of phases) {
-  phasesByName.set(p.phase, p);
-}
-
-const missingTiming = [];
-
-for (const required of requiredPhases) {
-  const existing = phasesByName.get(required);
-  if (!existing) {
-    // Missing entry entirely.
-    const entry = { phase: required, status: "unknown", seconds: null };
-    phases.push(entry);
-    phasesByName.set(required, entry);
-    errors.push({ code: "MISSING_TIMING", phase: required });
-    missingTiming.push(required);
-  } else if (existing.seconds === null || existing.seconds === undefined) {
-    existing.seconds = null;
-    if (!errors.some((e) => e.code === "MISSING_TIMING" && e.phase === required)) {
-      errors.push({ code: "MISSING_TIMING", phase: required });
-    }
-    missingTiming.push(required);
-  }
-}
-
-// ---- 2. totalSeconds derivation -------------------------------------------
-if (!run.totalSeconds && run.started && run.ended) {
-  const started = Date.parse(run.started);
-  const ended = Date.parse(run.ended);
-  if (!Number.isNaN(started) && !Number.isNaN(ended) && ended >= started) {
-    run.totalSeconds = Math.round((ended - started) / 1000);
-  }
-}
-
-// ---- 3. Compose final shape -----------------------------------------------
-const final = {
-  version: "1.0",
-  run,
-  outcome,
-  phases,
-  ...(recoveries.length > 0 ? { recoveries } : {}),
-  ...(errors.length > 0 ? { errors } : {}),
-  ...(notes.length > 0 ? { notes } : { notes: [] }),
-};
-
-const wixDir = join(projectDir, ".wix");
-mkdirSync(wixDir, { recursive: true });
-const runJsonPath = join(wixDir, "run.json");
-writeFileSync(runJsonPath, JSON.stringify(final, null, 2) + "\n");
-
-// ---- 4. Perf one-liner ----------------------------------------------------
-// Format: "Built in <Nm Ss> — design-system <n>s · images (phase 1 + phase 2) <n>s · build+release <n>s"
-const fmtSeconds = (sec) => (sec === null || sec === undefined ? "–" : `${sec}s`);
-const fmtTotal = (sec) => {
-  if (sec === null || sec === undefined) return "–";
-  const m = Math.floor(sec / 60);
-  const s = sec % 60;
-  return `${m}m ${s}s`;
-};
-const phaseSeconds = (name) => {
-  const p = phasesByName.get(name);
-  return p && p.seconds !== null && p.seconds !== undefined ? p.seconds : null;
-};
-const designSystem = phaseSeconds("design-system");
-const img1 = phaseSeconds("image-phase-1-decorative");
-const img2 = phaseSeconds("image-phase-2-entity");
-const imgTotal = img1 !== null && img2 !== null ? img1 + img2 : null;
-const build = phaseSeconds("build");
-const release = phaseSeconds("release") ?? phaseSeconds("preview");
-const buildPlusRelease = build !== null && release !== null ? build + release : null;
-
-const perfLine = `Built in ${fmtTotal(run.totalSeconds)} — design-system ${fmtSeconds(designSystem)} · images (phase 1 + phase 2) ${fmtSeconds(imgTotal)} · build+release ${fmtSeconds(buildPlusRelease)}`;
-
-console.log(JSON.stringify({
-  status: missingTiming.length > 0 ? "partial" : "ok",
-  path: runJsonPath,
-  totalSeconds: run.totalSeconds ?? null,
-  missingTiming,
-  perfLine,
-}, null, 2));