@wix/agent-skills 1.7.0 → 1.9.0

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/create-product-from-image.md

@@ -183,6 +183,30 @@ Examine the images for visible product attributes that should become variant opt
 - If multiple images show the **same product from different angles**, treat them as additional product media — NOT as separate variants.
 - If only one image is provided and a distinctive color is visible, suggest that single color as a choice and ask the user if the product comes in other colors.
 
+### 4h. Subscription Eligibility Detection (silent — no user interaction)
+
+Based on the product name, description, and image analysis, determine whether this product is **subscription-eligible**. A product qualifies if it is a consumable that gets depleted at a predictable rate — something customers buy repeatedly on a regular schedule.
+
+**Eligible categories (examples):**
+- Food & beverage: coffee beans/pods, tea, protein powder, meal kits
+- Supplements & health: vitamins, probiotics, protein supplements
+- Pet: pet food, flea/tick treatments, cat litter
+- Personal care: skincare routine products, razor blades/cartridges, deodorant, shampoo/conditioner
+- Household: cleaning supplies, paper towels, toilet paper, laundry detergent
+- Baby: diapers, formula, wipes
+- Media: print/digital newspapers, magazines
+- Candles (daily-use scented candles with high burn frequency)
+
+**NOT eligible (do not suggest):**
+- Furniture, art, décor (one-time purchase)
+- Electronics, tools, appliances
+- Standard clothing, apparel, shoes (not subscription-typical)
+- Jewelry, watches
+- Books (single title), games, toys
+- Any unique or collectible item
+
+Store the result internally as `subscription_eligible: true/false`. If `true`, also note a brief reason (e.g., `"coffee beans — daily consumable"`). No user interaction at this step.
+
 ---
 
 ## V3 STEP 4: Present Review Card to User (INTERACTIVE)
@@ -207,6 +231,7 @@ Present a structured review card using the markdown format below. This provides
 | Images | [count] uploaded |
 | SEO | [first 60 chars of meta description]… |
 | Tone | [Matched from existing site products / Neutral e-commerce] |
+| Subscription | [e.g. Monthly · 10% off] or [Not applicable] |
 
 **Info Sections**
 - **[Title 1]:** [one-line summary]
@@ -221,7 +246,7 @@ After the card, present the action options:
 
 > 1. **Refine** — tell me what to change (e.g., "make the description shorter", "the price should be lower")
 > 2. **Regenerate** — I'll start the analysis over, optionally with additional context from you
-> 3. **Approve** — proceed to options and product creation
+> 3. **Approve** — lock in these details and continue to the next steps
 
 If the user provided a text note that **contradicts** what's visible in the image (e.g., image shows blue but note says "available in red"), ask the user to clarify before proceeding.
 
@@ -229,6 +254,68 @@ If the user provided a text note that **contradicts** what's visible in the imag
 
 ---
 
+## V3 STEP 4.5: Suggest Subscription (INTERACTIVE, conditional)
+
+> **Run this step ONLY if `subscription_eligible: true` was set in V3 STEP 3 section 4h.** Otherwise skip directly to V3 STEP 5.
+
+Present a short, non-pushy suggestion card:
+
+---
+
+**This product looks like a great candidate for a subscription plan.**
+Customers who subscribe to *[product name]* get auto-refills on a schedule they choose — boosting repeat revenue for you.
+
+Would you like to add a subscription option?
+- **Yes** — set it up now (takes ~30 seconds)
+- **No** — create as a one-time purchase only
+
+---
+
+If the user says **No**, proceed directly to V3 STEP 5.
+
+If the user says **Yes**, ask the following 4 questions (can be presented together as a single form):
+
+**Q1 — Billing frequency**
+> "How often should subscribers be charged and receive this product?"
+
+| Choice | `frequency` | `interval` |
+|--------|------------|-----------|
+| Every week | `WEEK` | `1` |
+| Every 2 weeks | `WEEK` | `2` |
+| Every month *(Recommended)* | `MONTH` | `1` |
+| Every 2 months | `MONTH` | `2` |
+| Every 3 months | `MONTH` | `3` |
+| Every 6 months | `MONTH` | `6` |
+| Every year | `YEAR` | `1` |
+
+**Q2 — Duration**
+> "How long should the subscription run?"
+
+- **Ongoing** — renews automatically until the customer cancels (omit `billingCycles`)
+- **Fixed** — ends after N cycles (ask: "How many cycles?") → set `billingCycles: N`
+
+**Q3 — Subscriber discount (optional incentive)**
+> "Would you like to offer a discount to customers who subscribe?"
+
+- No discount (omit `discount` block)
+- **10% off** *(Recommended)* → `type: "PERCENTAGE", amount: 10`
+- Custom percentage → ask for value → `type: "PERCENTAGE", amount: [value]`
+- Fixed amount off → ask for value → `type: "AMOUNT", amount: [value]`
+
+**Q4 — Allow one-time purchase alongside subscription**
+> "Can customers also buy this product as a one-time purchase (without subscribing)?"
+
+- **Yes — sell both ways** *(Recommended)* → `allowOneTimePurchases: true`
+- No — subscription only → `allowOneTimePurchases: false`
+
+After collecting the user's answers, show a brief confirmation line before moving on:
+
+> Subscription plan configured: [e.g. Monthly · Ongoing · 10% off · One-time purchases also allowed]
+
+Store the collected subscription data for use in V3 STEP 6.
+
+---
+
 ## V3 STEP 5: Suggest Options and Ask User (INTERACTIVE)
 
 **Present the detected options from V3 STEP 4g and ask the user if they want to add product options.**
@@ -255,10 +342,74 @@ If no options were detected:
 
 ## V3 STEP 6: Create the Product
 
+Before making the API call, ask the user one final time:
+
+> Everything is ready. Shall I create the product now?
+> - **Yes, create it** — I'll submit the product to your store now.
+> - **No, go back** — return to a previous step to make changes.
+
+**Wait for confirmation.** Only proceed with the API call if the user says Yes.
+
+---
+
 **API Endpoint:** `POST https://www.wixapis.com/stores/v3/products`
 
 Build the request body with all confirmed fields. The write must be **atomic** — either all fields save or none do.
 
+**If a subscription was configured in V3 STEP 4.5**, include a `subscriptionDetails` block in the product body (see rules below). Otherwise omit it entirely.
+
+**`subscriptionDetails` rules:**
+- `title`: auto-generate from frequency (e.g. `"Monthly Subscription"`, `"Weekly Subscription"`, `"Quarterly Subscription"`)
+- `description`: if a discount was set, write a short sentence referencing it (e.g. `"Subscribe and save 10% on every order."`). Omit if no discount.
+- `visible`: always `true`
+- `frequency` + `interval`: from user's Q1 answer
+- `billingCycles`: include only for fixed-duration subscriptions (from Q2). Omit for ongoing.
+- `discount`: include only if a discount was chosen (from Q3). Omit the entire block if no discount.
+- `allowOneTimePurchases`: from user's Q4 answer
+
+**Example `subscriptionDetails` block (monthly, ongoing, 10% off, one-time also allowed):**
+
+```json
+"subscriptionDetails": {
+    "subscriptions": [
+        {
+            "title": "Monthly Subscription",
+            "description": "Subscribe and save 10% on every order.",
+            "visible": true,
+            "frequency": "MONTH",
+            "interval": 1,
+            "discount": {
+                "type": "PERCENTAGE",
+                "amount": 10
+            }
+        }
+    ],
+    "allowOneTimePurchases": true
+}
+```
+
+**Example with fixed duration and flat amount discount (every 2 months, 6 cycles, $5 off, subscription only):**
+
+```json
+"subscriptionDetails": {
+    "subscriptions": [
+        {
+            "title": "Bi-Monthly Subscription",
+            "description": "Subscribe and save $5 on every order.",
+            "visible": true,
+            "frequency": "MONTH",
+            "interval": 2,
+            "billingCycles": 6,
+            "discount": {
+                "type": "AMOUNT",
+                "amount": 5
+            }
+        }
+    ],
+    "allowOneTimePurchases": false
+}
+```
+
 ---
 
 ### Path A: Simple Product (No Options)
@@ -650,8 +801,9 @@ Before reporting success to the user, verify ALL of the following:
 - [ ] V3 STEP 2 completed: User provided 1-3 images, all uploaded to Media Manager with wixstatic.com URLs.
 - [ ] V3 STEP 3 completed: Images analyzed from user's message, all product fields generated based on what's visible in the image(s).
 - [ ] V3 STEP 4 completed: User reviewed and approved the generated details.
+- [ ] V3 STEP 4.5 completed (if applicable): Subscription eligibility was evaluated. If eligible, user was asked and their choice (Yes/No) was applied before proceeding to STEP 5.
 - [ ] V3 STEP 5 completed: User confirmed, modified, or skipped product options.
-- [ ] V3 STEP 6 completed: Product was created via API and you received a product ID.
+- [ ] V3 STEP 6 completed: User confirmed "create now", product was created via API and you received a product ID.
 
 ---
 

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));

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

@@ -1,101 +0,0 @@
-#!/usr/bin/env node
-// 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.
-//
-// 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)
-//   }
-//
-// 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 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 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> --frontend <astro|custom> [--site-id <id>] [--app-id <id>]");
-  process.exit(2);
-}
-
-const verticals = verticalsCsv
-  .split(",")
-  .map((v) => v.trim())
-  .filter(Boolean);
-
-if (verticals.length === 0) {
-  console.error("init-site-json: <verticals-csv> resolved to zero verticals — cms is always loaded, so this is a bug");
-  process.exit(2);
-}
-
-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. Discovery should call this exactly once.`);
-  process.exit(2);
-}
-
-mkdirSync(wixDir, { recursive: true });
-
-const site = {
-  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, frontend, verticals, ...(siteId ? { siteId } : {}), ...(appId ? { appId } : {}) }, null, 2));

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

@@ -1,45 +0,0 @@
-#!/usr/bin/env bash
-# Build the project and deploy a rotating preview URL.
-#
-# Usage:
-#   bash <SKILL_ROOT>/scripts/preview.sh
-#
-# Run from the project directory (CWD = <project>/). Requires wix.config.json.
-#
-# 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.
-#
-# `preview` does NOT populate the Frontend link in headless settings — that's
-# what `release.sh` is for. Use preview for fast iteration on a rotating URL;
-# use release for production deploy + transactional-email URL stability.
-#
-# Exit codes:
-#   0 — ok; preview URL on stdout
-#   <other> — build or preview failed; stderr surfaces the underlying error
-#             (TypeScript / Astro errors are code bugs, not endpoint drift —
-#              the orchestrator's recovery ladder doesn't retry build).
-
-set -euo pipefail
-
-# Build first; surface compile errors verbatim if it fails.
-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@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
-# preview URL.
-PREVIEW_URL="$(grep -oE 'https://[A-Za-z0-9.-]+\.wix-host\.com[^[:space:]]*' "$PREVIEW_OUTPUT" | head -n 1 || true)"
-
-if [[ -z "$PREVIEW_URL" ]]; then
-  echo "preview.sh: could not extract a *.wix-host.com URL from preview output" >&2
-  exit 1
-fi
-
-echo "$PREVIEW_URL"