@wix/agent-skills 1.6.0 → 1.7.0

package/skills/wix-headless/SKILL.md

@@ -1,440 +1,162 @@
 ---
 name: wix-headless
 description: "Build a complete Wix Managed Headless site from a single prompt, OR connect an existing project (HTML/JSX/Vite app, Claude Design output, etc.) to Wix Headless for hosting + Business Solutions. Entry point for both: (1) new-site requests — runs discovery, design, feature wiring, and preview; and (2) existing-project requests — runs `npm create @wix/new@latest init`, analyzes the project for needed Business Solutions, installs apps, **wires the Wix SDK into the existing source files so each installed app actually powers its corresponding feature**, and releases. Triggers: build me a site, create a website, make me a website, new website, online store, I want to sell X, start a business online, launch a site, ecommerce, portfolio, business website, sell online, online shop, connect this to Wix Headless, add Wix Headless to this project, host this on Wix, deploy this to Wix, implement the features of this project using Wix Headless. Use this skill instead of the WixSiteBuilder MCP tool for new-site requests."
+allowed-tools:
+  - Bash(cd *)
+  - Bash(npx @wix/cli@latest *)
+  - Bash(npx @wix/cli *)
+  - Bash(npm create @wix/new@latest *)
+  - Bash(npm install *)
+  - Bash(npm run *)
+  - Bash(node *)
+  - Bash(bash *)
+  - Bash(curl *)
+  - Bash(ls *)
+  - Bash(grep *)
+  - Bash(find *)
+  - Bash(cat *)
+  - Bash(head *)
+  - Bash(wc *)
+  - Bash(mkdir *)
+  - Bash(cp *)
+  - Read
+  - Write
+  - Edit
+  - Skill
+  - Agent
 ---
 
-# Wix Headless — One Skill, One Flow
+# Wix Headless
 
-Single orchestrator for the full site build. Linear flow with parallel subagent workers coordinated through design tokens and structured agent returns.
+**Run flow is owned by the conductor, split at the approval gate: `references/PLAN.md`** (pre-approval — mode routing, the Discovery questions, the plan + approval gate, the latency-hiding background dispatches) **then `references/BUILD.md`** (post-approval — Setup → Seed → Components → Pages → Build → Release). The domain/step files (`DISCOVERY.md`, `SETUP.md`, `SEED.md`, `DESIGN_SYSTEM.md`, `COMPOSE.md`, the per-vertical references) describe only *what* each step does; they do not name the sequence. **Start a run by opening `PLAN.md`**; open `BUILD.md` when the user approves the plan. All site operations use `npx @wix/cli@latest token` + `curl` — no MCP.
 
-## Prerequisites
-
-Before running this skill, the user's environment must have a working, authenticated Wix CLI and a Wix MCP server registered with their agent client:
-
-| Requirement | Why | How to verify | How to fix if missing |
-|---|---|---|---|
-| **`@wix/cli` available** | Wave 2 runs `npx @wix/cli env pull` to write `.env.local`; Wave 6 runs `npx @wix/cli build` + `release` to publish. `npx` will fetch the CLI on demand, but a locally installed CLI is faster and surfaces version issues earlier. | `which wix` or `npx @wix/cli --version`. | `npm i -g @wix/cli` (or rely on `npx` to fetch per-invocation). |
-| **Wix CLI authenticated** | `env pull` and `release` both require a logged-in session; tokens live in `~/.wix/auth/`. On auth error the skill surfaces `"Run \`npx @wix/cli login\` and retry."` and stops. | `ls ~/.wix/auth/account.json` exists and is non-empty. | `npx @wix/cli login` — opens a browser to auth. |
-| **Wix MCP exposing admin tools** | Admin tools (`CallWixSiteAPI`, `ListWixSites`, `ManageWixSite`, image upload, etc.) are called at Wave 0 and across every downstream subagent. Any authenticated Wix MCP that exposes them satisfies this prereq — a pre-installed remote connector (claude.ai, ChatGPT, etc.) and a locally-registered stdio `@wix/mcp --wixCliAuth` are equivalent for the skill's purposes. | Tool discovery from your agent client finds `WixREADME` and `CallWixSiteAPI` from any authenticated Wix MCP. If only `Search*Documentation` tools appear, no admin-capable Wix MCP is connected. | If no authenticated Wix MCP exposes admin tools, register a stdio MCP server running `npx -y @wix/mcp --wixCliAuth` in your agent client, then restart the session so the new tools load. `--wixCliAuth` reuses the `wix login` token from the row above, so this is one command and no extra auth UI. Do **not** prompt the user to OAuth into a remote connector when this command-driven path is available. |
-
-If any prerequisite is missing, surface the specific gap to the user and stop **before** any subagent dispatches — failing mid-flow leaves a partially scaffolded project.
-
-### Authentication
-
-`wix login` (and `npx @wix/cli login`) are **safe to run from a non-interactive AI-agent
-environment**. When the CLI detects an AI agent it skips the interactive UI and emits
-JSON events on stdout, one per line:
-
-- `{"event":"awaiting_user","verificationUri":"...","userCode":"...","expiresInSeconds":...}`
-   — surface the URL and code to the user; wait for them to complete login in their browser.
-- `{"event":"success","email":"...","userId":"..."}` — login complete; resume the
-   step that failed.
-- `{"event":"logged_in","email":"...","userId":"..."}` — there was already a valid
-   session, nothing to do.
-
-### How to run it
-
-Run `wix login` (or `npx @wix/cli login`) with `run_in_background: true` since it
-blocks until the human finishes the browser step. Tail the output file to read the
-`awaiting_user` event as soon as it appears; you'll be notified when the process
-exits with the terminal event.
+> **Explicit invocation only.** Do not auto-route on generic "build me a site" prompts; production `wix-headless` should win those unless the user names this skill.
 
 ## Path resolution — read this first
 
-Your CWD at runtime is the **project directory**, not the skill root. How you resolve `<SKILL_ROOT>/...` references depends on how you loaded the skill:
-
-- **On-disk install** (`curl -O https://dev.wix.com/skills/wix-headless.tgz && tar xzf wix-headless.tgz`): this file is at `<SKILL_ROOT>/SKILL.md` on disk — strip the trailing `/SKILL.md` for the absolute path. Hold it in session scratch for the whole run. Run scripts as written: `bash <SKILL_ROOT>/scripts/X.sh` and `node "<SKILL_ROOT>/scripts/X.mjs" <args>`.
-- **URL stream** (you see the agent-note preamble at the top of this file): `<SKILL_ROOT>` is `https://dev.wix.com/skills/wix-headless`. Execute scripts via process substitution:
-  - `bash <SKILL_ROOT>/scripts/X.sh <args>` → `bash <(curl -s <SKILL_ROOT>/scripts/X.sh) <args>`
-  - `node "<SKILL_ROOT>/scripts/X.mjs" <args>` → `curl -s <SKILL_ROOT>/scripts/X.mjs | node --input-type=module - <args>`
-
-  Process substitution (`node <(curl ...)`) does **not** work for `.mjs` — Node sees the script as `/dev/fd/N` with no extension and refuses ESM syntax. Pipe via stdin with `--input-type=module` instead.
+Your CWD at runtime is the **project directory** (scaffold subdir after setup), not the skill root. Compute `<SKILL_ROOT>` from this file: `<SKILL_ROOT>/SKILL.md` — strip `/SKILL.md`. Hold the absolute path in session scratch. Also hold `<site-root>` (eval run dir where `.wix/site.json` lives — parent of scaffold) from `SETUP.md` Step 1.
 
 | What | Absolute path |
 |---|---|
-| Shared return contract | `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` |
-| Shared MCP prefix guide | `<SKILL_ROOT>/references/shared/MCP_PREFIX.md` |
-| Production release / reserved root path sharp edges | `<SKILL_ROOT>/references/shared/PRODUCTION_SHARP_EDGES.md` |
-| Per-vertical / per-scope subagent instructions | `<SKILL_ROOT>/references/<scope>/INSTRUCTIONS.md` (scopes: `stores`, `ecom`, `cms`, `blog`, `forms`, `gift-cards`, `images`, `designer`). Subagent-only — orchestrator never reads. |
-| Vertical packs directory | `<SKILL_ROOT>/references/verticals/` |
-| Templates directory | `<SKILL_ROOT>/templates/` |
-| Scripts directory | `<SKILL_ROOT>/scripts/` |
-| Shared utilities | `<SKILL_ROOT>/shared-utilities/` — copied into `src/utils/` by `seed-utilities.sh` |
-| Frozen MCP-call references | `<SKILL_ROOT>/references/commands/` — `install-app.md`, `mcp-bootstrap.md`, `known-apps.json` |
-
-**Do NOT Read subagent INSTRUCTIONS files in the orchestrator.** Pre-reading wastes ~25k tokens on a typical dispatch and pushes the orchestrator past its autocompact threshold mid-pipeline. Pass the absolute path; the subagent opens the file.
-
-## Subagent dispatch discipline
-
-Every subagent is a **general-purpose worker** that loads its behavior from a specific `INSTRUCTIONS.md`. There are no specialized subagent types — the instruction file makes it specialized for that scope. Do NOT delegate to specialized agent types your runtime offers (research, code-review, planning) — they have mismatched tooling and will break the flow.
-
-**Every dispatch prompt must include `Instruction file (absolute path)`** pointing at one of:
-`<SKILL_ROOT>/references/{stores,ecom,cms,blog,forms,gift-cards,images,designer}/INSTRUCTIONS.md`.
-
-Subagents run with the project as CWD and cannot resolve `<SKILL_ROOT>` themselves — pass absolute paths.
-
-## When This Skill Triggers
-
-Two entry paths. **Decide which one before doing anything else** — they branch immediately after Wave 0.
-
-### Path A — New site from a prompt (default flow)
-
-Any user request to build a new site. Infer vertical(s) from the prompt:
-
-| Signal | Load packs |
-|---|---|
-| "sell X online", "store", "shop", "ecommerce", product-related | `stores` + `cms` |
-| "blog", "publish articles", "editorial", "journal" | `blog` + `cms` |
-| "contact form", "lead form", "signup", "get in touch" | `forms` + `cms` |
-
-`cms` is **always** loaded (provides About/FAQ content pages). If the prompt is too vague, ask one conversational clarifier (NOT `AskUserQuestion`): *"What do you want your site to do — sell things, publish content, take bookings?"*
-
-**Do NOT call the `WixSiteBuilder` MCP tool for new-site requests.** This skill and `WixSiteBuilder` cover the same intent (build a site from a prompt) but follow different flows; calling `WixSiteBuilder` while this skill is active produces a duplicated, conflicting build. This skill is the sole entry point — proceed with the wave flow below.
-
-### Path B — Connect an existing project to Wix Headless
-
-The user already has a working frontend on disk (e.g. a Claude Design output, a hand-coded `index.html`, a Vite/React/Vue app) and wants to **connect it** to Wix Headless for hosting + Business Solutions. Triggers: *"connect this to Wix Headless"*, *"add Wix Headless to this project"*, *"host this on Wix"*, *"deploy this to Wix"*, or a prompt referencing "Wix Headless" against a non-empty working directory.
-
-**Detection (apply immediately after Wave 0, before any vertical inference):**
-
-| Working directory contents | Path |
-|---|---|
-| Empty, or freshly scaffolded by `scaffold.sh` | A (new site) |
-| Has source files (`index.html`, `*.jsx`, `*.tsx`, etc.) **and no `wix.config.json`** | B (connect existing) |
-| Has `wix.config.json` AND Astro structure (`src/`, `astro.config.mjs`) | resume a prior wix-headless run — see "When NOT to Use" below |
-| Has `wix.config.json` AND non-Astro frontend | B, but skip the `init` step — proceed from "Step E2" |
-
-**Do NOT run vertical-pack inference from the user's prompt in Path B.** Vertical packs (`stores`, `blog`, `forms`, …) are inferred from the user's described business in Path A. In Path B, the project ALREADY exists — packs are decided by **reading the project files** (see `SETUP.md` § "Step E2"), not by re-asking the user what they're building.
-
-**Path B skips most of the wave flow.** Run only: Wave 0 (MCP bootstrap) → `SETUP.md` § "Existing project flow" (E1 init → E2 analyze → E3 install apps → **E4 SDK wiring (required)** → E5 release → E6 final message). Do **not** run Discovery (Wave 1), Setup Dispatch (Wave 2), Seed/Design (Wave 3), Components (Wave 4), Pages (Wave 5), or the Wave 6 manifest checks. The existing project supplies its own frontend, so there is nothing for the designer / seeders / pages subagents to do — but **E4 still runs**: installed apps without SDK wiring would leave the project's features static, which defeats the purpose of "implement the features … using Wix Headless".
-
-## When NOT to Use This Skill
-
-| Scenario | Use Instead |
-|---|---|
-| Scaffold-only with no further design/wiring | `bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<Brand>"` |
-| Build + preview an existing wix-headless project | `bash <SKILL_ROOT>/scripts/preview.sh` (from project dir) |
-| Release / ship / go-live an existing wix-headless project | `bash <SKILL_ROOT>/scripts/release.sh` (from project dir) |
-| Install a Wix app onto an existing site | Follow `<SKILL_ROOT>/references/commands/install-app.md` |
-| Connect a non-Wix project (HTML/JSX/Vite/etc.) to Wix Headless | **Path B above — this skill, existing-project flow** |
-| Add a feature to / restyle a prior wix-headless run | Resume on disk; tell user, ask whether to start fresh |
-
-If `wix.config.json` is present in the working directory alongside an Astro project structure, offer: *"I found an existing wix-headless project. Continue it or start fresh?"* via `AskUserQuestion`. "Continue" jumps to the appropriate phase based on what's on disk; "fresh" proceeds with full flow. If `wix.config.json` is present alongside a non-Astro frontend, that's Path B mid-flow — skip `init` and continue from `SETUP.md` § "Step E2".
-
----
-
-## The Flow at a Glance
+| Discovery flow | `<SKILL_ROOT>/references/DISCOVERY.md` |
+| Setup flow | `<SKILL_ROOT>/references/SETUP.md` |
+| Seed flow | `<SKILL_ROOT>/references/SEED.md` |
+| Pre-approval funnel (plan) | `<SKILL_ROOT>/references/PLAN.md` |
+| Post-approval build | `<SKILL_ROOT>/references/BUILD.md` |
+| Seed recipe map (human ref) | `<SKILL_ROOT>/references/seed-recipes.md` |
+| Auth + REST headers | `<SKILL_ROOT>/references/shared/AUTHENTICATION.md` |
+| Public doc endpoints | `<SKILL_ROOT>/references/shared/DOCS_SEARCH.md` |
+| Return contract | `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md` |
+| Implementer shared behavior | `<SKILL_ROOT>/references/shared/IMPLEMENTER.md` |
+| Image generation | `<SKILL_ROOT>/references/shared/IMAGE_GENERATION.md` |
+| Design-system Designer (design spec, JSON only) | `<SKILL_ROOT>/references/DESIGN_SYSTEM.md` |
+| Design-system Composer (writes the 6 files) | `<SKILL_ROOT>/references/astro/COMPOSE.md` |
+| Composer astro skeletons | `<SKILL_ROOT>/references/astro/templates/` |
+| Vertical packs (discovery) | `<SKILL_ROOT>/references/verticals/` |
+| Per-vertical instructions | `<SKILL_ROOT>/references/{stores,ecom,cms,blog,forms,gift-cards,images}/INSTRUCTIONS.md` |
+| Phase 4 page-designer scopes | `<SKILL_ROOT>/references/astro/designer/INSTRUCTIONS.md` |
+| Templates | `<SKILL_ROOT>/references/astro/templates/` |
+| Shared utilities (copied by seed-utilities) | `<SKILL_ROOT>/shared-utilities/` |
+| Known app IDs | `<SKILL_ROOT>/references/commands/known-apps.json` |
+| Scripts | `<SKILL_ROOT>/scripts/` |
+
+**Do NOT Read subagent role/instruction docs in the orchestrator** — pass the absolute path; the subagent opens it. This covers **every** doc whose body is written *for a subagent to follow*, not just files literally named `INSTRUCTIONS.md`: `DESIGN_SYSTEM.md` (Designer), `astro/COMPOSE.md` (Composer), `astro/designer/INSTRUCTIONS.md` (page designers), the per-vertical `INSTRUCTIONS.md` routers, and the per-vertical guides under `references/astro/`. The orchestrator only needs to know **which inputs to inline** for each dispatch — and that list lives in `BUILD.md`'s dispatch steps, not in the role doc. Reading a role doc to "prepare a dispatch" pulls 5–14 KB of subagent-only how-to into the orchestrator's context, which it then has to reason over on the dispatch turn — measurably inflating bridge turns. The orchestrator's own reading set is the conductor/domain docs only: `PLAN.md`, `BUILD.md`, `DISCOVERY.md`, `SETUP.md`, `SEED.md`, and `references/verticals/*.md`.
+
+When and how each subagent is dispatched (Designer, Composer, seeders, image phases, vertical Components/Pages) is owned by the conductor (`references/PLAN.md` pre-approval, `references/BUILD.md` post-approval), not listed here.
+
+## Authentication
+
+Every Wix API call uses `@wix/cli` + `curl`:
 
 ```
-[Discovery] → [Setup] → [Phase 1 Seed + Phase 2 Design System + Image Phase 1 in parallel]
-                                   ↓ (Phase 2 done)
-                        [Phase 3 Components + Image Phase 2 dispatched; decorative slots patched once Image Phase 1 returns]
-                                   ↓ (Phase 3 + Phase 1 Seeders done)
-                        [Phase 4 Pages]
-                                   ↓ (Phase 4 done + Image Phase 2 done)
-                        [Manifest check] → [Build + Release] → [Final message + run.json]
+Authorization: Bearer $(npx @wix/cli@latest token --site "$SITE_ID")
+wix-site-id: $SITE_ID
 ```
 
-| Wave | Dispatches | Waits for | Bridge work |
-|---|---|---|---|
-| 0 | (bash) | — | MCP prefix discovery, schema bootstrap, capture `runStartedAt` |
-| 1 | (Q&A) | user | brand/vibe/aesthetic; scaffold launches in background after Q1 |
-| 2 | apps install + env-pull + npm-install (bg) + seed-utilities | — | `init-site-json.mjs` |
-| 3 | seeders + design-system + image-phase-1 | design-system (fg) | merge `designTokens` into site.json; `emit-design-tokens.mjs`; grep Layout.astro CSS imports |
-| 4 | components + components-css + image-phase-2 (all bg) | (none — all backgrounded) | `copy-utility-templates.mjs components`; on Image Phase 1 return: `patch-decorative-slots.mjs`; on Phase 3 return: `check-manifest.mjs components` |
-| 5 | pages | components done + Phase 1 seeders done | `copy-utility-templates.mjs pages` |
-| 6 | (bash) | pages done + image-phase-2 done | `check-manifest.mjs pages`; `release.sh`; `finalize-run-json.mjs` |
-
-**Phase axis.** Core pipeline: `Phase 1 (Seed) → Phase 2 (Design System) → Phase 3 (Components) → Phase 4 (Pages)`. Image pipeline runs in parallel: Image Phase 1 (Decorative) alongside Phases 1–2; Image Phase 2 (Entity) alongside Phase 3 (depends only on Phase 1 Seed entity IDs + brand). Each Phase 4 agent writes its routes ONCE with both visual design and data queries — no placeholder-then-rewrite split.
-
-**The orchestrator is the only writer of `.wix/site.json`** — it merges each Seeder's `data` block into `seeded.<vertical>` and the Designer's `data.designTokens` block into `designTokens` as subagent results arrive. Subagents never write `site.json` themselves.
-
-### Batching compliance
-
-Each parallel-dispatch step is **one concurrent batch** with **no narration between dispatches**. Interleaved status updates, file writes, or text like "Launching agents…" splits the batch into separate turns and adds 12–39s of inter-dispatch latency per gap. Make every subagent that doesn't block downstream work a **background subagent** (only Phase 2 Design System is foreground) — background dispatch alone gives ~2× compression by overlapping execution.
-
-### Standard subagent prompt fields
-
-Every dispatch prompt includes:
-- `Instruction file (absolute path)` — `<SKILL_ROOT>/references/<scope>/INSTRUCTIONS.md`
-- `Phase instruction` / `Scope` — exact scope string
-- `MCP tool prefix` — from Wave 0, verbatim
-- `Project directory (absolute path)` — project CWD
-- `siteId` — from `wix.config.json`
-- `Brand context` — name, vibe, aesthetic direction, colors, fonts
-
----
-
-## Wave 0 — MCP bootstrap & run start
-
-See `references/SETUP.md` § "MCP Prefix Discovery + Schema Bootstrap".
-
-1. **Capture `runStartedAt`** via `date -u +%Y-%m-%dT%H:%M:%SZ` and hold in scratch (used at end-of-run for `run.totalSeconds`).
-2. **Discover the MCP prefix** via your runtime's tool-discovery primitive: look up `WixREADME`, strip the trailing suffix from the returned name. Call `<prefix>WixREADME` to verify connectivity. On failure, stop and tell the user the Wix MCP server isn't connected.
-3. **Pre-load Wix MCP tool schemas** — read `<SKILL_ROOT>/references/commands/mcp-bootstrap.md` and follow its single `ToolSearch` invocation. Capture `{ phase: "mcp-bootstrap", seconds: <duration> }` in `run.json.phases[]`.
-4. Hold the prefix for the whole session. Pass it verbatim into every subagent prompt.
-
-## Wave 1 — Discovery
-
-See `references/DISCOVERY.md` for full mechanics.
-
-- Infer vertical(s) from the user's opening message; if too vague, one conversational clarifier.
-- **Q1** (`AskUserQuestion`): brand name. On answer, launch scaffold in background: `bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<Brand>"`. Slug-derivation + timing capture rules in `references/DISCOVERY.md` § "Scaffold dispatch".
-- **Q2** (`AskUserQuestion`): vibe.
-- Craft a 2–3 sentence aesthetic direction in scratch (do not print standalone).
-- Present the plan as markdown (Design Direction → Features → Pages → CMS Collections → Apps & SDK). **Pages, CMS Collections, and Apps & SDK MUST be markdown tables.**
-
-  > **Before typing any table, open `references/DISCOVERY.md` § "Plan structure" and copy each section's header skeleton verbatim.** Do NOT type column headers from memory — root cause of every plan-format regression. DISCOVERY.md leads with the exact `| ... |` header to copy and a STOP cue listing wrong shapes.
-
-- `AskUserQuestion` for approval.
-
-## Wave 2 — Setup (one concurrent batch)
-
-See `references/SETUP.md`. After approval, run **one concurrent batch** with no narration between operations.
-
-1. **App install** for every entry in `apps[*]` of every loaded vertical. Follow `<SKILL_ROOT>/references/commands/install-app.md` — owns the `CallWixSiteAPI` body shape, `appName → appDefId` lookup, and recovery ladder. **An empty `apps: []` array means install nothing for that pack** — gift-cards, ecom, cms all ship `apps: []`. Do not invent an `appName` from the pack name or SDK packages. Capture `APP_INSTALL_START`/`END` via `date -u +%s` around the `CallWixSiteAPI` invocation; record `{ phase: "app-install-<appName>", seconds }`.
-2. **`npx @wix/cli env pull`** (foreground, fast). Produces `.env.local` with `WIX_CLIENT_ID`. On auth error: surface `"Run \`npx @wix/cli login\` and retry."` and stop. Record `{ phase: "env-pull", seconds }`.
-3. **`rm -f package-lock.json && npm install …`** as a **background shell** with the union of all loaded verticals' `packages` arrays plus the always-packages (`@wix/sdk tailwindcss @tailwindcss/vite`). Flags: `--no-fund --no-audit --legacy-peer-deps`. Bake `NPM_INSTALL_START=$(date -u +%s)` and `NPM_INSTALL_END=$(date -u +%s)` into the SAME background bash command so the values land in its output. Record `{ phase: "npm-install", seconds }` when the install finishes. **Do not add packages beyond this set** — see `SETUP.md` § anti-hallucination rule.
-4. **`bash <SKILL_ROOT>/scripts/seed-utilities.sh`** — copies `<SKILL_ROOT>/shared-utilities/*.ts` (`wix-image.ts`, `analytics.ts`, `ricos.ts`) into `src/utils/` with `cp -n` and strips the Astro starter cruft. Record `{ phase: "seed-utilities", seconds }`.
-5. **Memory writes** — `project` memory with brand/apps/pages/phase.
-6. **User-facing roadmap × N** — emit a tracker entry per phase boundary. Target **6–8 entries**: "Install apps", "Seed data", "Design site", "Wire features", "Generate images", "Install dependencies", "Build and preview".
+`wix login` is safe from non-interactive agents (URL + user code written to stderr, exits non-zero once the browser flow concludes). Full recovery ladder: `<SKILL_ROOT>/references/shared/AUTHENTICATION.md`.
 
-   > **No ampersands in roadmap titles.** Some progress trackers HTML-escape input — `"Build & preview"` renders as literal `Build &amp; preview`. Spell out "and"; same for `<`, `>`, `"`.
+## Subagent model tier
 
-7. **`mkdir -p .wix`** — minimal. No `.wix/logs/`.
-8. **`node "<SKILL_ROOT>/scripts/init-site-json.mjs" "$(pwd)" "<brand>" "<one-line aesthetic from Q2>" "<verticals-csv>"`** — wraps in `PHASE_START`/`PHASE_END`; record `{ phase: "init-site-json", seconds }`. Writes the canonical initial `.wix/site.json`:
+Match each subagent's task to one of two tiers; dispatch with the model
+your environment provides for that tier. Apply by lookup, not deliberation.
 
-   ```json
-   {"brand": {"name": "...", "description": "..."}, "seeded": {}, "designTokens": {}, "verticals": ["..."]}
-   ```
+**Fast tier** — recipe-following work whose return is JSON of IDs/URLs.
+No source-code authoring, no creative judgment.
 
-   `.wix/site.json` is the single source of truth that every downstream phase reads. Only the orchestrator writes — it merges Seeder `data` into `seeded.<vertical>` and Designer `data.designTokens` into `designTokens` as returns arrive.
+- All Seeder subagents (stores, cms, blog, forms, future verticals)
+- Image-generation subagents (while still dispatched as subagents)
 
-## Wave 3 — Seed + Design System + Image Phase 1 (one concurrent batch)
+**Default tier** — everything else.
 
-Per loaded vertical:
-- **Phase 1 Seeder subagent (background)**, per vertical's `seed` config. Returns its data via the standard return JSON; orchestrator merges into `.wix/site.json.seeded.<vertical>`.
+- Design System / Designer (brand-voice CSS, type, layout)
+- Phase 3 Components (SDK composition, hooks, JSX)
+- Phase 4 Pages (cross-file dependencies, brand-voice content)
+- Any subagent that authors files the build will consume
 
-Always:
-- **Image Phase 1 Decorative subagent (background)**. Generates decorative images from brand context only — no Phase 1 Seed dependency. Prompt adds `Scope: image-phase-1-decorative` + page list + **`decorativeSlots: string[]`** (REQUIRED). Compose `decorativeSlots` from the canonical vocabulary in `references/designer/INSTRUCTIONS.md` § common rule #7: always `["hero", "about"]`, plus `"productsHeader"` if stores loaded, plus `"cmsHeader"` if you want a CMS page-header decorative. Designer is restricted to the same vocabulary; the two MUST match exactly.
-- **Phase 2 Design System subagent (foreground)**, scope `design-system`, instruction file `<SKILL_ROOT>/references/designer/INSTRUCTIONS.md`. Writes `global.css`, `Layout.astro`, `Navigation.astro`, `Footer.astro`, `astro.config.mjs`, `index.astro` shell, returns `designTokens` JSON.
+If unsure, pick default. Do not weigh alternatives per dispatch — the
+choice is determined by the task type, not by the subject matter of
+the run.
 
-The Designer prompt additionally requires:
-- **`Navigation links: [...]`** — JSON array of `{href, label}` for top-level nav links the designer hardcodes. Compose by filtering loaded packs: include a route ONLY if its pack does not declare a `<!-- nav:links -->` entry in `contributes:`. With today's packs:
-  - cms → `/about`, `/faq` are designer-owned.
-  - stores → `/products` is NOT designer-owned (stores splices a Shop submenu at `<!-- nav:links -->` in Phase 4 `pages-home-and-nav`).
-  - gift-cards → `/gift-cards` is NOT designer-owned (gift-cards splices a probe-gated link, AND it's `disabled: true`).
-  - ecom → no nav-link routes; only `<!-- nav:actions -->` (CartBadge mount).
-  - For a stores+cms+ecom+gift-cards run the list is `[{href:"/about",label:"About"},{href:"/faq",label:"FAQ"}]`. Including `/products` or `/gift-cards` produces duplicate Products+Shop links.
-- **`Disabled packs: [...]`** — names of loaded packs with `disabled: true`. The designer must not add hero CTAs, footer links, or any other surfaces pointing at their routes. Without this, the designer composes a "Send a gift card" CTA pointing at `/gift-cards` even when the user hasn't enabled gift-cards.
 
-### Bridge: post-Design System (foreground returns)
+## When this skill triggers
 
-Phase 2 completes (~2–3 min). Inline orchestrator work, in this exact order:
+Explicit invocation only. **Two entry paths — decide before doing anything else.**
 
-1. **Merge `data.designTokens` into `.wix/site.json.designTokens`.**
-2. **`node "<SKILL_ROOT>/scripts/emit-design-tokens.mjs" "$(pwd)"`** — deterministically projects `.wix/site.json.designTokens` → `.wix/design-tokens.css` + `.wix/site.d.ts`. Wrap in `PHASE_START`/`PHASE_END`; record `{ phase: "emit-design-tokens", seconds }`.
-3. **Layout.astro CSS-import verification (mandatory).** Grep the generated `src/layouts/Layout.astro`. For every loaded vertical whose pack declares a `components` entry (stores, ecom, blog, forms), there MUST be a matching `import '../styles/components-<pack>.css'` in the frontmatter. If any is missing, **inline-patch Layout.astro now** — Phase 3 agents write `components-<pack>.css` expecting the designer to have imported it; if forgotten, every React island that uses scoped contract classes renders unstyled.
+### Path A — New site from a prompt (default)
 
-Phase 1 seeders are still running. Image Phase 1 is still running. Do not block on either — proceed to Wave 4.
+Infer vertical(s) from the opening message and load the **full resolved pack set** (top-level + `requires:` transitives + always-on `cms`) in one read batch — routing examples: stores → stores+cms+ecom+gift-cards; blog → blog+cms; etc. If the prompt is too vague, ask one conversational clarifier (NOT `AskUserQuestion`): *"What do you want your site to do — sell things, publish content, take bookings?"*
 
-## Wave 4 — Components + Image Phase 2 (one concurrent batch, all background)
+> **Do NOT call `WixSiteBuilder` MCP** for new-site requests — same intent, different flow; calling both produces a duplicated, conflicting build. This skill is the sole entry point.
 
-Read `.wix/design-tokens.css` + `.wix/site.d.ts` once (orchestrator pastes them inline into Phase 3 prompts).
+### Path B — Existing project → custom frontend (not available yet)
 
-**Pre-dispatch bridge:** `node "<SKILL_ROOT>/scripts/copy-utility-templates.mjs" "$(pwd)" components` (sibling of the dispatch in the same orchestration step). Deterministically copies templated SDK-wrapper utility files for the `components` phase into `src/utils/` (today: `back-in-stock.ts` if stores loaded; `discounts.ts` if ecom loaded). Reads `.wix/site.json.verticals` to know which packs are loaded; uses `cp -n`. Wrap in `PHASE_START`/`PHASE_END`; record `{ phase: "copy-utility-templates-components", seconds }`. The hardcoded mapping (template → destination, per pack + phase) lives at the top of the script — single source of truth.
+Triggers: *"connect this to Wix Headless"*, *"add Wix Headless to this project"*, *"host this on Wix"*, *"deploy this to Wix"*, *"implement the features … using Wix Headless"*, or any "Wix Headless" prompt against a non-empty working directory. Decide by working-directory contents:
 
-### Subagent batch
-
-Per loaded vertical with a `components` entry:
-- **Phase 3 Components subagent (background)**. Prompt includes the standard fields PLUS the **inline styling-contract JSON** (Phase 3 agents do NOT read the design-tokens contract from disk).
-
-Per loaded vertical with a `componentsCss` entry (today: stores, ecom):
-- **Phase 3 Components-CSS subagent (background)**. Same concurrent batch as the `components` sibling — TSX→CSS link is build-time via class names. Reading set is much smaller (see `<SKILL_ROOT>/references/<vertical>/COMPONENTS_CSS.md`). Skip silently for packs without this entry.
-
-If any pack produces entities (stores products, CMS items, blog posts) AND the relevant Phase 1 Seeder has returned:
-- **Image Phase 2 Entity subagent (background)**. Generates + PATCHes entity images. Prompt adds `Scope: image-phase-2-entity` + `Phase 1 Seed return data` (products, collections, blogPosts — same inline format used for Phase 4 scopes) + brand context.
-
-  > **Gate.** If a Phase 1 Seeder is still running, hold Image Phase 2 until that seeder returns and merges. Phase 3 dispatch does not wait — Phase 3 agents don't need entity data.
-  >
-  > **Credit-exhaustion skip.** If Image Phase 1 returned `status: "failed"` AND any `errors[].code` matches `REQUEST_NOT_ELIGIBLE` / `INSUFFICIENT_CREDITS` / quota-exhaustion patterns (messages containing `not eligible for credits`, `quota exceeded`, `resets at`), DO NOT dispatch Image Phase 2 — both phases hit the same Wix AI credit pool. Record `{phase: "image-phase-2-entity", status: "skipped", seconds: 0, notes: "Phase 1 confirmed credit exhaustion via <code>"}` and surface in the final message ("No imagery shipped — you can upload images from the Wix dashboard"). Per-request transient errors (5xx, timeout) do NOT trigger this skip.
-
-> **Do not enumerate files in the Phase 3 Components prompt.** The agent's INSTRUCTIONS.md and the vertical pack's `creates:` list (filtered by `phase: components`) own which files the agent writes. A hand-typed file list omits a file the pack declares, the agent skips it, downstream pages import it, build breaks.
-
-### Bridge: post-Image-Phase-1 decorative slot patch
-
-Phase 2 designer wrote `index.astro` with `data-decorative-slot="<key>"` placeholder `<div>`s. Once Image Phase 1 returns:
-
-1. If Image Phase 1 returned `status: "failed"` or timed out, skip — placeholders look complete on their own. (You can also unconditionally invoke the script — it self-skips when `.wix/image-urls.md` is missing.)
-2. **`node "<SKILL_ROOT>/scripts/patch-decorative-slots.mjs" "$(pwd)"`** — reads `.wix/image-urls.md`, walks `src/pages/**/*.astro`, injects `<img …class="decorative-slot-img" />` as the first child of each matching slot div. Idempotent + safe (won't clobber a div with non-`<img>` child content). JSON return: `{ status, imageUrls, filesScanned, patched, skipped, warnings }`.
-3. If `warnings[]` is non-empty, append `{code: "DECORATIVE_SLOT_DIV_OCCUPIED", file, slot}` per warning to the Phase 2 Design System entry's `errors` in `run.json`. If `imageUrls[]` is non-empty but `patched[]` is empty AND `warnings[]` is empty, the designer emitted no `data-decorative-slot=` attributes at all — append `{code: "NO_DECORATIVE_SLOTS_FOUND"}`. Both non-fatal.
-
-Wrap in `PHASE_START`/`PHASE_END`; record `{ phase: "decorative-slot-patch", seconds }`.
-
-### Bridge: post-Phase-3 manifest check
-
-When all Phase 3 sub-agents return: **`node "<SKILL_ROOT>/scripts/check-manifest.mjs" "$(pwd)" components "<packs-csv>"`**. Verifies every `creates:` entry tagged `phase: components` exists on disk and recovers missing files from canonical templates. JSON output: `present`, `recovered`, `missing` arrays. Exit 0 = happy or fully recoverable; exit 1 = unrecoverably missing.
-
-For each `recovered` entry, append to `run.json.recoveries[]`. For each `missing` entry, surface the remediation hint to the user before Wave 5 dispatches — Phase 3 React islands that Phase 4 imports are critical-path; if any are unrecoverable, do NOT continue. Record `{ phase: "manifest-check-components", seconds }`.
-
-## Wave 5 — Pages (one concurrent batch)
-
-**Wait gate:** before dispatching, confirm:
-- All Phase 1 Seeders done — data merged into `.wix/site.json.seeded.<vertical>`.
-- All Phase 3 Components agents done — they've written `src/components/*` and `src/styles/components-<vertical>.css`.
-- Phase 2 Design System done — `.wix/site.json.designTokens`, `.wix/design-tokens.css`, `.wix/site.d.ts` all exist.
-
-If a Phase 1 Seeder returned without a parseable JSON block, re-request it (see `<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`) — do NOT dispatch with empty data and rely on subagents to re-query.
-
-**Pre-dispatch bridge:** `node "<SKILL_ROOT>/scripts/copy-utility-templates.mjs" "$(pwd)" pages` — same script as Wave 4, invoked with `pages`. Today copies `templates/stores/categories.ts` → `src/utils/categories.ts` when stores loaded. Without it, `pages-products` and `pages-home-and-nav` start before `pages-categories` writes `categories.ts` and trigger spurious "missing import" recovery paths. Record `{ phase: "copy-utility-templates-pages", seconds }`.
-
-### Subagent batch
-
-Per loaded vertical's `pages`:
-- Per-scope **Page subagent (background)**.
-
-Example for stores + cms run:
-- `product-pages` — `products/index.astro`, `products/[slug].astro`, `ProductCard.astro`
-- `category-pages` — `category/[slug].astro`, `CategoryRail.astro`, `utils/categories.ts`
-- `cart-checkout` — `cart.astro`, `thank-you.astro`
-- `home-and-nav` — patch `index.astro` home product grid; patch `Navigation.astro` (CartBadge mount + Shop submenu insert)
-- `cms-pages` — wire about + FAQ
-
-Each prompt includes the standard fields PLUS:
-- Scope string (names the files it owns)
-- **`.wix/site.json` path reference (MANDATORY).** Agents read seeded data from `.wix/site.json.seeded.<vertical>`:
-  - stores scopes → `.wix/site.json.seeded.stores.products` (id, name, slug, variantId, price, sku, inventory). `.wix/site.json.seeded.stores.categories` is always `[]` — categories are merchant-driven, live-queried by the frontend.
-  - CMS scopes → `.wix/site.json.seeded.cms.collections`.
-  - blog scopes → `.wix/site.json.seeded.blog.posts`.
-  - Agents DO NOT re-query MCP — if `site.json` is missing a required key, return `status: "failed", errors: [{code: "SITE_JSON_INCOMPLETE", missing: "..."}]` rather than re-fetching. Re-querying would mask a seeder bug and adds 5–15 s per agent.
-- Styling contract (full JSON inline — same pattern as Phase 3 Components).
-- **ProductCard interface (for `product-pages` and `home-and-nav` only).** Both subagents touch `ProductCard.astro` — `product-pages` owns and rewrites it, `home-and-nav` reads it to wire the home grid. Tell both subagents the interface up front to eliminate the read-timing race:
-  > `ProductCard.astro accepts a single prop: { product } where product is the full Wix product object from productsV3. Usage: <ProductCard product={p} />`
-
-  Include verbatim in both prompts. Without this, `home-and-nav` reads the designer's placeholder ProductCard (which may have flat props) before `product-pages` rewrites it.
-
-> **Image Phase 2 is NOT dispatched here.** It was launched in Wave 4; the Wave 6 hard gate waits for it before release.
-
-## Wave 6 — Manifest check, build, release
-
-> **HARD GATE: Do NOT invoke `release.sh` until `image-phase-2-entity` has completed or timed out (120s).** Skipping has shipped sites with no product images and `run.json` recording `image-phase-2-entity` as `"in_progress"`.
-
-1. **Wait for ALL Phase 4 subagents AND `image-phase-2-entity`.** If Phase 4 finishes before Image Phase 2, wait up to 120s. With Image Phase 2 dispatched in Wave 4 this is usually a no-op.
-
-   **Observability fallback.** Subagent return signals are not always reliable — silent gaps happen. If 3 minutes pass past the expected completion window with no signal, do NOT keep waiting indefinitely. Trigger the post-Phase-4 manifest check directly — if files exist, the subagents finished; if not, treat the gap as a failure and surface to the user.
-
-   **Rate-limit recovery for `image-phase-2-entity`.** If the subagent returns `status: "failed"` with an error matching `/limit|quota|resets/i`, do NOT stall or retry the subagent. Run the inline recovery in the orchestrator: batched generate (one call) → concurrent imports (one batch) → concurrent product/CMS PATCHes (one batch). Procedure encoded in `references/shared/IMAGE_GENERATION.md`.
-
-2. **Post-Phase-4 manifest check.** `node "<SKILL_ROOT>/scripts/check-manifest.mjs" "$(pwd)" pages "<packs-csv>"`. Same recovery rules as Phase 3 check. Surface any unrecoverable `missing[]` entries (exit code 1) before invoking release — those are page files Phase 4 didn't write that have no template fallback. Record `{ phase: "manifest-check-pages", seconds }`.
-
-3. **Wait for npm install** — the background install from Wave 2. Wait on its handle; do not `sleep`-poll. On non-zero exit follow the recovery ladder in `references/SETUP.md` § "npm install recovery" (foreground retry with timeout, never delete the lockfile).
-
-4. **`bash <SKILL_ROOT>/scripts/release.sh`** — runs `npx @wix/cli build` + `release`, extracts the URL from `Site published on <url>`, prints the URL on stdout. Capture build / release timings via `date -u` wrappers and record `{ phase: "build", seconds }` and `{ phase: "release", seconds }`. The script's stdout becomes `outcome.releaseUrl` in `run.json`. This populates the **Frontend link** in headless settings so transactional emails link to the deployed frontend. On build failure, surface the compiler error and stop — do NOT deploy a broken site. The script retries known transient release failures; see `<SKILL_ROOT>/references/shared/PRODUCTION_SHARP_EDGES.md` before adding custom release retry logic.
-
-   Use `bash <SKILL_ROOT>/scripts/preview.sh` (not this step) only when the user is iterating on an existing site and explicitly asks for a fast preview without touching production.
-
-   On non-fatal build warnings, see `<SKILL_ROOT>/references/shared/BUILD_NOISE.md` — read only if a warning surfaces.
-
-   If the user asks for SEO root files (`robots.txt`, `llms.txt`), favicons, custom-domain verification, or batch release behavior, read `<SKILL_ROOT>/references/shared/PRODUCTION_SHARP_EDGES.md` before implementing. Wix may own these root paths at the edge, so static files and Astro routes are not always effective.
-
-> **No standalone verify phase.** The post-phase manifest check catches missing files with auto-recovery; type/module/template errors surface from `astro build` a few seconds later.
-
-### Post-phase manifest check — recovery rules
-
-`<SKILL_ROOT>/scripts/check-manifest.mjs` is invoked from both Wave 4 (after Phase 3, with `phase: components`) and Wave 6 (after Phase 4, with `phase: pages`). Cost on the happy path: < 1 s per phase boundary. Recovery cost: ~10 ms per file copied from a template.
-
-For every loaded pack, for every `creates:` entry where `phase == <given>`:
-1. If the file exists → record as `present`.
-2. If missing AND a template exists at `<SKILL_ROOT>/templates/<pack>/<tail>` → copy it; record as `recovered` with `{source: "template-copy", template}`.
-3. Otherwise → record as `missing` with a `PHASE_FILE_MISSING` code and a remediation hint.
-
-The script outputs JSON; the orchestrator appends `recovered[]` to `run.json.recoveries[]`, `missing[]` to `run.json.errors[]`. On any unrecoverable miss (exit 1), critical-path files (Phase 3 React islands that Phase 4 imports) → stop; optional ancillary files → log and continue.
-
-The orchestrator never invents stub content for missing files — template-copy is the only recovery path. Stubs hide bugs (e.g. a no-op `discounts.ts` ships green builds with silently-broken discount rendering).
-
-**Backward compat.** `PHASE4_FILE_MISSING` (used historically) remains as an alias for `{code: "PHASE_FILE_MISSING", phase: "pages"}`.
-
-## Final message + run.json
-
-> **No visual or browser-based verification.** After the build succeeds, do NOT open the URL in Playwright, take screenshots, or run smoke tests on your own initiative. Visual verification is opt-in only when the user explicitly requests it.
-
-One concluding turn containing, in order:
-
-1. **Release URL text first** — bold heading / link at the top so the user sees it immediately.
-2. **Compose the draft `run.json` blob** in scratch. Aggregate every subagent return into `phases[]`, set `outcome.previewUrl`, fill `run.started` (from `runStartedAt`) / `run.ended` (capture now via `date -u`), compute `run.totalSeconds`, and compose `requiredPhases[]` — phases that MUST have a captured duration:
-   - Always: `mcp-bootstrap`, `init-site-json`, `scaffold`, `env-pull`, `seed-utilities`, `emit-design-tokens`, `manifest-check-components`, `manifest-check-pages`, `decorative-slot-patch`, `npm-install`, `build`, `release` (or `preview` if `preview.sh` was used).
-   - Per app installed in Wave 2: `app-install-<appName>`.
-   - When `copy-utility-templates` ran: `copy-utility-templates-components` and/or `copy-utility-templates-pages`.
-   - `image-phase-2-entity`'s duration arrives via its return; record from there if any pack produced entities.
-3. **`echo "$RUN_JSON_DRAFT" | node "<SKILL_ROOT>/scripts/finalize-run-json.mjs" "$(pwd)"`** — applies the timing-completeness gate (any `requiredPhases` entry without a captured duration becomes `seconds: null` + `{code: "MISSING_TIMING"}` in `errors[]`), writes the canonical `.wix/run.json`, prints `{perfLine, missingTiming[]}` on stdout.
-4. **Emit the perf one-liner** verbatim as the last line of the message body, from the script's `perfLine`:
-
-   > `Built in <Nm Ss> — design-system <n>s · images (phase 1 + phase 2) <n>s · build+release <n>s`
+| Working directory contents | Path |
+|---|---|
+| Empty, or freshly scaffolded by `scaffold.sh` | A (astro, supported) |
+| Source files (`index.html`, `*.jsx`, `*.tsx`, …) AND no `wix.config.json` | **custom — not available yet** |
+| `wix.config.json` + Astro structure (`src/`, `astro.config.mjs`) | resume a prior wix-headless run — ask "continue or start fresh?" via `AskUserQuestion` |
+| `wix.config.json` + non-Astro frontend | **custom — not available yet** |
 
-   Three buckets only — don't dump every phase. Missing buckets render as `–` rather than fabricated. If `missingTiming[]` is non-empty, surface those names on a separate line below the perf one-liner.
+**Custom (non-astro) frontends route to the stub.** When the working directory holds a non-astro project, the run does **not** author anything — it opens `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md`, surfaces the not-available message, and stops (`DISCOVERY.md` § "Custom (non-astro) — not available yet"; `PLAN.md` § "Custom (non-astro) frontends — not available yet"). The retired Integrate flow (`SETUP.md` § "Existing project flow" E1–E6, especially the E4 SDK-wiring recipe) is kept as a **historical reference** for the eventual custom authoring track — it is no longer dispatched.
 
-Do not re-read anything from disk to compose `run.json`. Use the agent return data already in session context.
+### Frontend modes (the `.wix/site.json.frontend` axis)
 
-### Timing capture — required pattern
+Path A vs Path B is the routing question. The `frontend` value is the **downstream branching axis** — the orchestrator holds it in session scratch and either branches on it directly or passes it to scripts as a `--frontend` flag. (It is also persisted to `.wix/site.json` as a resume fallback, but the live run reads scratch, not the file.) The axis is binary:
 
-For phases the skill runs directly (`scaffold`, `app-install-*`, `env-pull`, `seed-utilities`, `npm-install`, scripts, `build`, `preview`):
+| `frontend` | Mode |
+|---|---|
+| `astro` | Scaffold + full build (the only supported frontend; full playbook under `references/astro/`) |
+| `custom` (anything non-astro) | **Not available yet** — routed to `references/custom/INSTRUCTIONS.md`, surfaces the not-available message, no authoring |
 
-```bash
-PHASE_START=$(date -u +%s)
-# … invoke …
-PHASE_END=$(date -u +%s)
-# record: { "phase": "<name>", "seconds": $((PHASE_END - PHASE_START)) }
-```
+`DISCOVERY.md` § "Wave 0 — Mode detection" decides which value to set and records it via `init-site-json.mjs --frontend <value>` (on the astro path only). **Which flow each value runs is owned by `PLAN.md` § "Frontend-mode routing".**
 
-For background subagents / shells, capture `PHASE_START` at dispatch time and `PHASE_END` when the result arrives — not when you check output. A missed capture = `MISSING_TIMING` in `run.json`.
+### Two tracks (business vs frontend)
 
-For per-phase `seconds` from subagent returns: compute from the agent's `started`/`ended` fields (per `RETURN_CONTRACT.md`). If omitted, set `seconds: null` and add `{code: "MISSING_TIMING"}` rather than faking — null makes the omission visible.
+The skill runs two semi-independent tracks (business = frontend-blind site/app/seed work; frontend = scaffold/design/components/pages/build) that the orchestrator interleaves for wall-time. **The track model and interleaving are owned by `PLAN.md` § "Two tracks".**
 
-### URL discipline — do not invent URLs
+### When NOT to use this skill
 
-The final message emits **exactly two URLs**, copy-pasted verbatim:
+| Scenario | Use instead |
+|---|---|
+| Scaffold-only with no further design/wiring | `bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<Brand>"` |
+| Release an existing wix-headless project | `bash <SKILL_ROOT>/scripts/release.sh` (from project dir) |
+| Install a Wix app onto an existing site | Follow `<SKILL_ROOT>/references/commands/install-app.md` |
+| Add a feature / restyle a prior wix-headless run | Resume on disk; ask whether to start fresh |
 
-- **Release URL** — extracted from `npx @wix/cli release` stdout, on the line `Site published on <url>`. Copy the exact string; do not retype, modify, or fill in digits from memory.
-- **Dashboard URL** — `https://manage.wix.com/dashboard/<siteId>` where `<siteId>` comes from `wix.config.json`.
+> Read individual `.md` files under `references/verticals/`; `Read` on the directory returns `EISDIR`.
 
-Do NOT emit any URL constructed by modifying the release URL (swapping subdomains, changing digits, removing path segments) or any URL not present verbatim in tool output / config. Prior failure: a run emitted `...alexp575.wix-host.com` next to the real `...alexp775.wix-host.com` — the second was typo-constructed and 404'd.
+## The run
 
-**On "going live":** the flow deploys via `release.sh`, a real production release that populates the **Frontend link** so transactional emails link to the deployed frontend. Accepting real payments still requires a paid plan + payment provider — mention if asked.
+The whole run — Discovery → Setup → design-system bridge → Seed → Components → Pages → Build → Release, with every dispatch, handle, wait, and transition — is owned by the conductor: **`references/PLAN.md`** (pre-approval) then **`references/BUILD.md`** (post-approval). Open `PLAN.md` to start a run. This file does not duplicate the sequence.
 
----
+Wall-time targets: discovery ≤ 80 s (excl. user think-time); setup foreground ≤ 25 s; seed longest pole ≤ 120 s. Full-build target: ≤ 600 s prompt-to-live-URL when all phases run.
 
 ## Verticals
 
-Verticals live in `references/verticals/` and declare how a vertical plugs into the flow: app installs, SDK packages, `seed`/`components`/`pages` agent configs, `creates:` and `contributes:` file-ownership.
-
-Current verticals:
-- `stores.md` — product catalog (requires `ecom`, `gift-cards`)
-- `ecom.md` — vertical-agnostic cart/checkout (co-loaded via `requires`)
-- `gift-cards.md` — passive pack: ships in storefront sites; lights up only when the dashboard's Wix Gift Card app is enabled
-- `cms.md` — About/FAQ + use-case recipes (always loaded)
-- `blog.md` — blog posts with Ricos rich content, RSS/sitemap
-- `forms.md` — contact, lead, signup forms with CRM integration
-
-`requires:` resolution: when a pack is loaded via discovery, every name in its `requires:` is also loaded transitively. Current chain: `stores → [ecom, gift-cards]` and `gift-cards → [ecom]`.
-
-Schema: `references/verticals/_schema.md` (human-readable) and `_schema.json` (machine-validated at session start). Adding a vertical: create `references/verticals/<name>.md`, `references/<name>/INSTRUCTIONS.md`, and any per-vertical references / templates. No changes to this skill file are needed.
-
-## Agent Return Contract
-
-Agents return structured data in their completion message, not via sidecar files. The skill parses return JSON and merges seeders' `data` blocks into `.wix/site.json.seeded.<vertical>`. At end of run, the skill writes `.wix/run.json` — a single observability record. See `references/shared/RETURN_CONTRACT.md` for schema and aggregation rules.
-
-## References
+Pack frontmatter in `references/verticals/` is **discovery-only**. Post-seed work uses `INSTRUCTIONS.md` + templates under each vertical directory.
 
-Skill-level:
-- `references/DISCOVERY.md` — discovery flow, plan format, aesthetic direction crafting
-- `references/SETUP.md` — MCP prefix, app install, env pull, npm install recovery
-- `references/ORCHESTRATION.md` — phase-dispatch mechanics, wait conditions, data carry-forward
-- `references/verticals/_schema.md` — vertical pack schema
+Upstream: `@skills/wix-manage` (seed + app install recipes).
 
-Shared (with agents):
-- `references/shared/RETURN_CONTRACT.md` — agent return JSON schema, run.json aggregation
-- `references/shared/MCP_PREFIX.md` — prefix discovery + recovery
-- `references/shared/IMAGE_GENERATION.md` — image agent contract
-- `references/shared/STYLING.md` — three styling categories, ownership, decision rules
-- `references/shared/IMPLEMENTER.md` — shared implementer behavior
-- `references/shared/PRODUCTION_SHARP_EDGES.md` — release retries, reserved root paths, SEO files, favicons, verification
+Current packs: `stores`, `ecom`, `gift-cards`, `cms`, `blog`, `forms`. Schema: `references/verticals/_schema.md` + `_schema.json`.