@wix/agent-skills 1.7.0 → 1.8.0

package/README.md

@@ -17,15 +17,11 @@ In [Claude Code](https://docs.anthropic.com/en/docs/claude-code), run:
 /plugin install wix@wix
 ```
 
-### Codex Plugin
+### Codex
 
-In a terminal, register the marketplace:
+**Codex App** — [Install the Wix plugin](https://chatgpt.com/plugins/share/b15215ad8e954c96a1108d176d53f572).
 
-```bash
-codex plugin marketplace add wix/skills
-```
-
-Then in Codex CLI, run `/plugins`, select **Wix**, and choose **Install Plugin**.
+**Codex CLI** — run `/plugins`, select **Wix**, and choose **Install Plugin**.
 
 ### VS Code Plugin
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/SKILL.md

@@ -25,6 +25,7 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
 - [ ] **Step 4a:** Scaffolded each CLI-supported extension via `wix generate --params`
 - [ ] **Step 4b:** Filled in business logic in the generated files
   - [ ] Invoked `wix-design-system` skill ONLY before editing the first `.tsx`/`.jsx` file that imports `@wix/design-system`. Skip for backend-only or data-only extensions.
+  - [ ] WDS: imported `@wix/design-system/styles.global.css` in the main component entry file (`page.tsx`, modal `.tsx`, etc.) — not child/tab/helper files.
 - [ ] **Step 5:** Ran validation (see [Validation](#validation))
   - [ ] Dependencies installed
   - [ ] TypeScript compiled
@@ -257,6 +258,7 @@ If the command fails because of unknown or invalid params, run `npx wix schema g
 Open every path returned in `newFiles` and replace stubbed handler bodies / UI / queries with the user's actual logic, guided by the extension reference file's API and configuration sections.
 
 - ⚠️ MANDATORY when using WDS: Invoke the `wix-design-system` skill **before editing your first `.tsx`/`.jsx` file that imports `@wix/design-system`**. Do NOT invoke it preemptively for backend-only or data-only jobs — it adds large content to context that you won't use.
+- ⚠️ MANDATORY when using WDS: Add `import "@wix/design-system/styles.global.css";` in the **main component** entry file (`page.tsx`, modal `.tsx`, etc.) — not in child/tab/helper files.
 - ⚠️ MANDATORY when using Data Collections: Use the EXACT collection ID from `idSuffix` (case-sensitive). If `idSuffix` is `"product-recommendations"`, use `<app-namespace>/product-recommendations` NOT `productRecommendations`.
 
 ### Step 5: Run Validation

package/skills/wix-app/references/STORES_VERSIONING.md

@@ -310,6 +310,7 @@ For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.co
 | `manageVariants: false` (customizations) | `modifiers[i]` |
 | `collectionIds[i]` | `directCategories[i].id` |
 | `ribbon`, `brand` (string) | `ribbon.name`, `brand.name` (managed via `ribbonsV3` / `brandsV3`) |
+| `media.mainMedia.image.url` (main image URL) | `media.main.image ?? media.main.url` — in V3, `ProductMedia.image` is a `string` (Wix-hosted URL), `url` is a `string` (external URL); check both |
 
 **Pricing model** — V1 had a `discount` object; V3 removed it. Discounts are now expressed by the relationship between two fields on the variant: `actualPrice` (required, what the customer pays) vs `compareAtPrice` (optional, original price shown struck through). With discount: V1 `price`/`discountedPrice` → V3 `compareAtPrice`/`actualPrice`. Without discount: V1 `price` → V3 `actualPrice`, leave `compareAtPrice` empty.
 

package/skills/wix-design-system/SKILL.md

@@ -127,3 +127,7 @@ Only use SP tokens for `gap`, `padding`, `margin` — not for width/height.
 import { Button, Card, Image } from "@wix/design-system";
 import { Add, Edit, Delete } from "@wix/wix-ui-icons-common";
 ```
+
+### Troubleshooting
+
+- **Components render unstyled** (plain HTML look, missing WDS spacing/typography): add `import "@wix/design-system/styles.global.css";` once to the root/main component (e.g. `page.tsx`, modal entry) — not child/tab/helper files.

package/skills/wix-headless/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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, take bookings, book appointments, appointment scheduling, let clients book online, site for my salon/spa/clinic/studio, sign up for classes or sessions, 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 *)
@@ -28,41 +28,53 @@ allowed-tools:
 
 # Wix Headless
 
-**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.
+**Run flow is owned by the conductor, split at the approval gate: `references/PLAN.md`** (pre-approval — routes on **operation** (create/connect), the Discovery questions, the plan + approval gate, the latency-hiding background dispatches) **then `references/BUILD.md`** (post-approval — routes on **framework** (`frontendBuild`); Setup → Seed → the build wave (merged Components + Pages per vertical) → Build → Release). The domain/step files (`DISCOVERY.md`, `SETUP.md`, `SEED.md`, `DESIGN_SYSTEM.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.
 
 > **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** (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.
+Your CWD at runtime is the **project directory, which is also the site-root** — `scaffold.sh` flattens the scaffolded project into the current directory, so the run is a **single folder with a single `.wix/`** (no nested project, no parent/child split). `<site-root>` and `<project-dir>` are the **same path**: the run's CWD. The end-of-run `AGENTS.md` (project root) and the project's own files (`package.json`, `src/`, `wix.config.json`, `.wix/design-tokens.css`, …) all live there — **never `cd` into a subdir, never look in a parent for `.wix`**. Compute `<SKILL_ROOT>` from this file: `<SKILL_ROOT>/SKILL.md` — strip `/SKILL.md`; hold the absolute path in session scratch. (Hold `<site-root>` from `SETUP.md` Step 1; the connect/`init` path is likewise single-folder in CWD.)
 
 | What | Absolute path |
 |---|---|
-| Discovery flow | `<SKILL_ROOT>/references/DISCOVERY.md` |
+| Discovery flow (router on OPERATION → operation files) | `<SKILL_ROOT>/references/DISCOVERY.md` → `DISCOVERY-create.md` (create) / `DISCOVERY-connect.md` (connect) |
 | 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` |
+| Pre-approval funnel (plan; router on OPERATION → operation files) | `<SKILL_ROOT>/references/PLAN.md` → `PLAN-create.md` (create) / `PLAN-connect.md` (connect) |
+| Post-approval build (router on FRAMEWORK → framework files) | `<SKILL_ROOT>/references/BUILD.md` → `BUILD-astro.md` (`frontendBuild: wix`) / `BUILD-own-build.md` (`frontendBuild: none`/`own`) |
 | 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` |
+| Design-system Designer (authors the DESIGN.md) | `<SKILL_ROOT>/references/DESIGN_SYSTEM.md` |
+| DESIGN.md format spec (vendored; Designer self-loads) | `<SKILL_ROOT>/references/shared/DESIGN_MD.md` |
+| Design-system Composer — deterministic script (writes the 6 files) | `<SKILL_ROOT>/scripts/compose.mjs` (self-documenting — its header is the spec) |
 | 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` |
+| Per-vertical instructions | `<SKILL_ROOT>/references/{stores,ecom,cms,blog,forms,gift-cards,bookings,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`.
+**Do NOT Read subagent role/instruction docs in the orchestrator** — pass the absolute path; the subagent opens it. 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 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.
 
-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.
+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/designer/INSTRUCTIONS.md` (page designers), the per-vertical `INSTRUCTIONS.md` routers, and the per-vertical guides under `references/astro/`. (There is no Composer doc — the Composer is the deterministic script `scripts/compose.mjs`, self-documenting in its header; the orchestrator never reads compose internals.)
+
+The orchestrator's own reading set is the conductor/domain docs only:
+
+- `PLAN.md` (+ the one operation funnel it routes to — `PLAN-create.md` *or* `PLAN-connect.md`)
+- `BUILD.md` (+ the one framework build file — `BUILD-astro.md` *or* `BUILD-own-build.md`)
+- `DISCOVERY.md` (+ the one operation discovery file — `DISCOVERY-create.md` *or* `DISCOVERY-connect.md`)
+- `SETUP.md`
+- `SEED.md`
+- `references/verticals/*.md`
+
+When and how each subagent is dispatched (Designer, seeders, image phases, vertical Components/Pages) — and the deterministic scripts in between (`emit-design-tokens.mjs`, `compose.mjs`) — is owned by the conductor (`references/PLAN.md` pre-approval, `references/BUILD.md` post-approval), not listed here.
 
 ## Authentication
 
@@ -102,35 +114,46 @@ the run.
 
 Explicit invocation only. **Two entry paths — decide before doing anything else.**
 
+**Decide by intent first, directory second.** An empty directory does **not** by itself mean Path A — read what the prompt is asking for. (See `DISCOVERY.md` § "Wave 0" for the authoritative rule.)
+
 ### Path A — New site from a prompt (default)
 
-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?"*
+The user asks to **create a new site from scratch** ("build me a store", "I want to sell tables online", "make a blog") with **no design to connect**, in an empty directory. 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; bookings → bookings+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?"*
+
+> **Framework keyword → scaffold that framework, not astro.** A create prompt that **explicitly names a client-build framework** (*"create a bakery site using vite and wix"*, react/vue/svelte/SPA) stays Path A (`operation: create`) but resolves `frontendBuild: own` — the skill scaffolds *that* framework and connects it via the SPA spine (companion case). A **bare** "create a bakery site" with no framework named stays **astro** (the default). Only an explicit keyword flips it — never infer a framework the user didn't ask for. (`DISCOVERY.md` § "Wave 0".)
 
 > **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.
 
-### Path B — Existing project → custom frontend (not available yet)
+### Path B — Connect an existing/brought design to Wix (`operation: connect`)
 
-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:
+Triggers: *"connect this to Wix Headless"*, *"implement this design … connecting to wix"*, *"add Wix Headless to this project"*, *"host this on Wix"*, *"deploy this to Wix"*, *"implement the features … using Wix Headless"*, or a **design-file URL to fetch + implement** (Claude Design / v0 / Lovable / any tool). **These route to B even when the working directory is empty** — the design arrives by fetch, so emptiness at trigger time does not make it Path A.
 
-| Working directory contents | Path |
+| Signal | 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** |
+| Prompt asks to **connect / implement / host an existing or fetched design** (incl. a design-file URL), **even if the CWD is empty** | **B (`operation: connect`)** |
+| A working frontend already on disk (`index.html`, `*.html`/`*.jsx`/`*.tsx`/`*.vue`, a design bundle) | **B (`operation: connect`)** |
+| Empty CWD **and** a create-a-new-site prompt, nothing to connect | A (`operation: create`) |
+| `wix.config.json` present (an existing wix-headless project) | resume/extend |
 
-**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.
+**The connect operation wires a brought-in design to Wix.** When the working directory holds a brought-in site, the run **connects it to a live Wix backend** — parse the site (`DISCOVERY-connect.md`), init + shared Setup/Seed, wire existing dynamic regions to `@wix/sdk` and augment static designs with the connected feature their purpose implies, then no-build release. The frontend-track playbook is `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md`; routing is owned by `PLAN-connect.md`.
 
-### Frontend modes (the `.wix/site.json.frontend` axis)
+### Two routing axes: operation (Discovery/Plan) + framework (Build)
 
-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:
+The skill routes each phase on its own axis — they only *happen* to coincide while there are exactly two modes:
 
-| `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 |
+- **Operation** (Discovery + Plan route on this) — *create* (scaffold a new site from a prompt) vs *connect* (integrate a brought-in design).
+- **Framework-build-class** (Build routes on this) — `frontendBuild`: `wix` (astro-native, `wix build`) vs `none` (static HTML, no build) vs `own` (own-build SPA, the project's own `npm run build`).
+
+These plus `frontend`, `verticals[]`, `designSource`, and `brand` form the **Plan→Build contract** (`PLAN.md` § "The Plan→Build contract"), held in orchestrator scratch and threaded into dispatch prompts. The axes are **orthogonal** — `frontendBuild` is derived inside the operation, not implied by it:
+
+| `operation` | `frontend` | `frontendBuild` | What runs |
+|---|---|---|---|
+| `create` (default) | `astro` | `wix` | the skill writes the site, then `wix build` + release (`references/astro/`) |
+| `create` + explicit framework keyword (*"…using vite"*) | `custom` | `own` | scaffold the named framework (vite/vue/svelte) → minimal app → connect via the SPA spine → the project's own `npm run build` + release (companion case) |
+| `connect` (brought static HTML) | `custom` | `none` | connect a brought-in HTML+CSS/JS site; init + Setup/Seed + connect/augment + **no-build** release (`references/custom/`) |
+| `connect` (brought framework SPA) | `custom` | `own` | connect a brought-in Vite/React/Vue/Svelte SPA; bundled `@wix/sdk` + source-edit wiring (persistence swap) + the project's own build + release |
 
-`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".**
+`DISCOVERY.md` § "Wave 0" resolves `operation` first, then derives `frontend`/`frontendBuild` (connect's build-class from disk — `DISCOVERY-connect.md` § 1.5; create's from an explicit framework keyword). `frontend`/`operation`/`frontendBuild` all live in **orchestrator scratch** and are **not** written to disk (on scratch loss, recover them from `package.json`: `@wix/astro` present ⇒ `frontend: astro`/`frontendBuild: wix`, else `frontend: custom` with `frontendBuild` re-derived from `scripts.build` + a bundler dep). **Operation routing is owned by `PLAN.md` § "Operation routing"; framework routing by `BUILD.md`.** Framework SPAs carry **no per-framework instruction files** — one agnostic playbook; only SSR frameworks (Next.js/Nuxt) are deferred.
 
 ### Two tracks (business vs frontend)
 
@@ -140,16 +163,16 @@ The skill runs two semi-independent tracks (business = frontend-blind site/app/s
 
 | 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` |
+| Scaffold-only with no further design/wiring | `bash <SKILL_ROOT>/scripts/scaffold.sh <folder-name> "<Brand>"` |
+| Release an existing wix-headless project | from the project dir: `npx @wix/cli@latest build` then `release` (astro); `release` only (custom — no build) |
+| Install a Wix app onto an existing site | Follow `SETUP.md` Step 3 (delegates to the `wix-manage` skill) |
 | Add a feature / restyle a prior wix-headless run | Resume on disk; ask whether to start fresh |
 
 > Read individual `.md` files under `references/verticals/`; `Read` on the directory returns `EISDIR`.
 
 ## The run
 
-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.
+The whole run — Discovery → Setup → design-system bridge → Seed → the build wave (merged Components + Pages per vertical) → 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.
 
@@ -159,4 +182,4 @@ Pack frontmatter in `references/verticals/` is **discovery-only**. Post-seed wor
 
 Upstream: `@skills/wix-manage` (seed + app install recipes).
 
-Current packs: `stores`, `ecom`, `gift-cards`, `cms`, `blog`, `forms`. Schema: `references/verticals/_schema.md` + `_schema.json`.
+Current packs: `stores`, `ecom`, `gift-cards`, `cms`, `blog`, `forms`, `bookings`. Schema: `references/verticals/_schema.md` + `_schema.json`.

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

@@ -0,0 +1,246 @@
+# Build — astro framework class (`frontendBuild === "wix"`)
+
+The post-approval conductor for the **astro-native** class (`create × astro` — the skill scaffolds and writes the site). Opened from `BUILD.md` when the run routes on `frontendBuild === "wix"`. Owns the astro flow: Setup → design-system bridge → Seed → build wave → Build → Release. Read top to bottom from approval.
+
+This file hosts the astro-create **bootstrap cell** (run-step 0: `scaffold.sh` → `npm create @wix/new@latest headless`) and **wiring cell** (the build wave). Shared with the own-build class via `BUILD.md`: **Subagent rate / credit limits**, the **parallel-batch diagnostic**, the **Final Message** (summary + `AGENTS.md`), and the **Shared release tail**. Pre-approval flow + the **Two tracks** / **Batching discipline** / **User-facing output** rules live in `PLAN.md`.
+
+## Phase axis
+
+Each phase is one of the two tracks (`PLAN.md` § "Two tracks"); all are background.
+
+| Phase | Track | Tier | What | When |
+|---|---|---|---|---|
+| **1 — Seed** | business | Fast | Per-pack seeders → orchestrator collects `seeded` map in scratch | Seed wave |
+| **2 — Design System** | frontend | Default (Designer) | **Designer** returns tokens + brand-voice JSON (authors `DESIGN.md`, no other files); **`compose.mjs`** (script, no subagent) writes the 6 files from it | Designer: run-step 0 · compose.mjs: Setup-window bridge |
+| **Image 1 — Decorative** | frontend | Fast | Hero/about/page-header decoratives | Seed wave (imagery-gated) |
+| **3 + 4 — Components + Pages (merged)** | frontend | Default | One merged "build" agent per vertical writes its islands **then** the routes that mount them | Build wave (§ "Step 4.5") |
+| **Image 2 — Entity** | business | Fast | Product/blog/CMS images PATCHed onto Wix entities | Build wave (imagery-gated) |
+
+> **Set the model tier on every dispatch** (`SKILL.md` § "Subagent model tier", by table lookup). Tier is the dispatch primitive's model parameter, not the prompt — omit it and Default-tier roles silently run under-powered.
+
+## The run from approval (Setup → Release)
+
+The contract lives in scratch — no disk snapshot. Nothing is dispatched yet (the funnel presented the plan fast).
+
+### 0. Dispatch scaffold + Designer (background, one concurrent batch on entry)
+
+Independent — fire together (`PLAN.md` § "Batching discipline"):
+- **Scaffold** — `scaffold.sh <folder-name> "<brand>" --frontend <value>` (background; capture `scaffold_handle` + its stderr tempfile). Folder-name + command shape: `DISCOVERY-create.md` § "After Q1". It **flattens the project into CWD** — one folder, one `.wix/`, no subdir to `cd` into (`SKILL.md` § "Path resolution"). `npm install` is **not** chained here (Setup Step 4c). The stderr tempfile is for post-hoc error inspection only — not a progress file to poll.
+- **Designer** — background; capture `designer_handle`. Instruction file = `<SKILL_ROOT>/references/DESIGN_SYSTEM.md` (the subagent opens it — do **not** Read it in the orchestrator). Inline Discovery's aesthetic craft from scratch (brand, aesthetic direction, palette, type, mood, page color strategy). Pass `designMdPath` = `<cwd>/DESIGN.md`. The Designer **authors `DESIGN.md`** (frontmatter = the tokens) and returns only `data.shell` + `designMdPath` — tokens never round-trip through your output. Judgment-only (~10–15 s). Do **not** pass application inputs (packs, nav links) — those go to `compose.mjs`.
+
+### 1. Setup Step 1 (foreground)
+
+`SETUP.md` Step 1 only: wait `scaffold_handle` (load `wix-manage` in the same batch), then hold `siteId`/`appId` (from `wix.config.json`) in scratch. Do **not** run Setup Step 4 yet — it goes in run-step 2. **Wait = await the harness completion notification; never sleep-poll a handle**.
+
+### 2. Setup window — bridge + platform batch as ONE concurrent message
+
+The whole Setup window is a single message of sibling `Bash` calls — **emit them, don't plan them.** It is order-free; the only failure mode is spending a turn deciding an order it doesn't have. The moment Setup Step 1 returns and the Designer has returned, fire the bridge **and** the platform batch together. `designer_handle` authored `DESIGN.md`; the bridge scripts read it directly — never re-emit tokens in your output.
+
+**Frontend bridge — one `Bash` call, two deterministic scripts (both read `DESIGN.md`):**
+
+1. `emit-design-tokens.mjs <project-dir>` — projects `.wix/design-tokens.css` + `.wix/site.d.ts` from `DESIGN.md` frontmatter (format: `references/shared/DESIGN_MD.md`). Does not write `DESIGN.md`.
+2. `compose.mjs` — app inputs on **stdin**, project dir as `argv[2]`. Reads `DESIGN.md` frontmatter (the single token source; roles map to the wix `--color-*` vocabulary) and substitutes into the six pinned skeletons — `global.css`, `astro.config.mjs` (anchored **merge**, not clobber), `Layout.astro`, `Navigation.astro`, `Footer.astro`, `index.astro`. Prints a `{status, phase:"compose", data, files}` manifest to **stdout** — parse it there. **astro-only** (defensive — non-astro classes never reach here); else record `{phase:"compose", status:"skipped"}`. Idempotent; derives any role the Designer omitted as a fail-safe.
+
+   ```bash
+   node <SKILL_ROOT>/scripts/emit-design-tokens.mjs "<project-dir>"
+
+   node <SKILL_ROOT>/scripts/compose.mjs "<project-dir>" <<'COMPOSE'
+   {
+     "shell": { ...the Designer's data.shell... },
+     "brand": { "name": "<brand>", "description": "<one-line context>" },
+     "navLinks": [ { "href": "/", "label": "Home" }, ... ],
+     "loadedPacks": ["stores", "cms", ...],
+     "packsWithComponents": ["stores", "ecom", ...],
+     "disabledPacks": ["gift-cards", ...]
+   }
+   COMPOSE
+   ```
+
+   The compose-input shape is documented in `scripts/compose.mjs`'s header.
+
+**In the SAME message — the business Setup Step 4 batch** (frontend-blind; `SETUP.md` owns recipes/package set). These overlap the bridge's `compose.mjs` (~20 s) so it adds no serial wall:
+
+3. `Bash` × N — app installs, one curl per `pack.apps[*]` → `SETUP.md` § Step 4a. Packs with no `apps[*]` (`cms`, `ecom`, `gift-cards`) install nothing — skip them.
+4. `Bash` — `npx @wix/cli@latest env pull --json` → `SETUP.md` § Step 4b (`--json` suppresses the spinner that bloats context).
+5. `Bash` (background) — `npm install …`, capture `npm_handle` + stderr tempfile → package set in `SETUP.md` § Step 4c. Trust the exit code at the seed gate — do not probe `node_modules`.
+
+### 3. Seed wave + 4. Seed gate
+
+See § "Wave 3" below for the dispatch. The **seed gate**: wait on the seeders + `npm_handle`; aggregate seeder returns into the `seeded` scratch map. Run `patch-decorative-slots.mjs` only when `imagery === "ai-generated"` and Image Phase 1 returned; else skip + record `{phase:"decorative-slot-patch", status:"skipped"}`.
+
+**Write `.wix/seeded.json` here — once, at the gate, before any reader dispatches** (one `Write`, conductor is sole writer). It is the producer→consumer handoff the build-wave readers pull from (§ "The `.wix/seeded.json` handoff"). The gate barriers all seeders before this write and the build wave dispatches only after it, so no reader sees a missing/partial file. Skipped packs → `{"<pack>": {"status":"skipped"}}` so a reader can tell "seeded nothing" from "not written yet" (the latter must never happen).
+
+### 5. Continue → the build wave (§ "Step 4.5") → Build & Release → Final message.
+
+## Imagery gates
+
+`imagery` (`"ai-generated"` | `"themed-blocks"`, captured `DISCOVERY.md` Q2.5, default `"themed-blocks"`) gates **both** image phases. The conductor owns the gate.
+
+- **Image Phase 1 — Decorative** (Wave-3 batch): dispatch the `image-phase-1-decorative` subagent (`<SKILL_ROOT>/references/images/INSTRUCTIONS.md`) **only on `ai-generated`**. On `themed-blocks`: don't dispatch (slots render as tokenised color blocks via compose-emitted CSS), record `{phase:"image-phase-1-decorative", status:"skipped", notes:"themed-blocks mode"}`, and skip `patch-decorative-slots.mjs`. Dispatching regardless wastes ~140–175 s + ~0.3–0.5 Wix AI credits.
+- **Image Phase 2 — Entity** (build-wave batch): same gate — dispatch only on `ai-generated`; on `themed-blocks` skip + record `{phase:"image-phase-2-entity", status:"skipped"}`. Dispatch + build gate: § "Step 4.5" and § "Wait: build wave → Build".
+
+---
+
+## Wave 3 — Seed + frontend prep + Image Phase 1
+
+One concurrent batch (`PLAN.md` § "Batching discipline"). No design-system work here — `compose.mjs` already wrote the six files in the bridge.
+
+- `seed-utilities.sh --template astro` — frontend project prep (idempotent), from the project dir. `SEED.md` § "Pre-batch".
+- Per-pack seed subagents (background) — `SEED.md` recipe map + seeder prompt template.
+- Image Phase 1 Decorative (background) — only on `ai-generated` (§ "Imagery gates").
+
+### Subagent dispatch
+
+Base prompt fields: `SEED.md` § "Subagent prompt template". Each merged build agent is dispatched with *"read your `<vertical>` slice from `.wix/seeded.json`"* — the page side reads its slice itself (§ "The `.wix/seeded.json` handoff") — and *"read `.wix/design-tokens.css` for the token vocabulary"*; the orchestrator does **not** inline the token block (§ "Styling contract coordination"). (Image Phase 2's single slice stays inlined.) Subagents read no shared state except their own `.wix/seeded.json` slice and the on-disk design-token artifacts (read-only).
+
+**`Instruction file` per loaded vertical** (one merged build agent each, writes components then pages in one dispatch):
+- `stores/INSTRUCTIONS.md` — components + pages (private pages merge; `pages-home-and-nav` is the serialized shell agent)
+- `ecom/INSTRUCTIONS.md` — components + cart/thank-you pages + CartBadge nav mount (shell chain; passive, required by stores)
+- `cms/INSTRUCTIONS.md` — CMS pages (no components scope)
+- `blog/INSTRUCTIONS.md` — components + pages (private — own `src/pages/blog/*`)
+- `forms/INSTRUCTIONS.md` — components + pages (private)
+- `bookings/INSTRUCTIONS.md` — components + pages (shell chain — patches `Navigation.astro` `<!-- nav:links -->` + `index.astro` `<!-- home:bookings -->`)
+- `gift-cards/INSTRUCTIONS.md` — components + pages (shell chain; passive/dashboard-gated)
+- `images/INSTRUCTIONS.md` — `image-phase-1-decorative` + `image-phase-2-entity` (image subagents also get: page list, entity types to cover)
+- `DESIGN_SYSTEM.md` — Phase 2 Designer (no Composer subagent — `compose.mjs` writes the six files)
+- `astro/designer/INSTRUCTIONS.md` — page-design spec applied by the merged build agents while writing routes (not a separate dispatch)
+
+Merged build agents **read `.wix/design-tokens.css` from disk** for the token vocabulary (gate-verified present at § "Step 4.5") — the orchestrator does **not** inline the styling-contract block (§ "Styling contract coordination").
+
+**Every subagent ends with the return contract** (`references/shared/RETURN_CONTRACT.md`); the orchestrator parses each return as it arrives. Put the closing line in the dispatch prompt **verbatim** — it's the only copy a leaf agent is guaranteed to see:
+
+```
+Return contract (your sole output channel — end your message with this fenced JSON block; it MUST be the last content, no trailing prose, no "**What was done:**" recap after it):
+{ ...the data shape for your scope, per references/shared/IMPLEMENTER.md § "Return contract"... }
+```
+
+---
+
+## The `.wix/seeded.json` handoff
+
+Seeded entity IDs reach the build-wave Page readers through a **write-once, read-only shared artifact** — not by re-inlining a slice into every prompt. The conductor writes it once at the seed gate; each reader reads its own `<vertical>` slice. (Image Phase 2 keeps its inlined slice; Phase 3 Components need no seeded IDs.) It is a safe exception to the "inputs inlined / don't read shared state" rule.
+
+**Scope of the exception (all three must hold):**
+- exactly one writer — the conductor at the seed gate, before any reader dispatch;
+- readers read only their own `<vertical>` slice; no reader writes the file;
+- it carries seeded entity IDs only, never observability fields.
+
+**Location:** `.wix/` (outside the Astro/Vite bundler root, so it never ships to `dist/` — same as `.wix/design-tokens.css`). Readers `Read` it to author code (slugs, `getStaticPaths`, demo content); pages query the live SDK at request time and **must not `import` it** into route files.
+
+**Schema** — one top-level key per loaded pack, mirroring the `seeded` scratch map:
+
+```json
+{
+  "stores": { "products": [{ "id": "...", "name": "...", "slug": "...", "variantId": "...", "price": 0 }], "productIds": ["..."], "categoryIds": ["..."] },
+  "cms":    { "collectionIds": { "about": "...", "faq": "..." }, "itemIds": { "about": ["..."], "faq": ["..."] } },
+  "blog":   { "postIds": ["..."], "categoryIds": ["..."] },
+  "forms":  { "formIds": ["..."] }
+}
+```
+
+Packs that seeded nothing → `{"<pack>": {"status":"skipped"}}`. Exact per-pack keys = the seeders' `Returns` column in `SEED.md` § "Recipe map".
+
+**Reader failure mode (fail loud):** a reader asserts its slice is present before using it. If the file or slice is absent → `status:"partial"`, `errors:[{code:"SEEDED_JSON_SLICE_MISSING", missing:"seeded.<vertical>"}]`. Do **not** render an empty page or fall back to re-querying via curl — a missing slice means an upstream phase didn't complete.
+
+---
+
+## Step 4.5 — the build wave (Components + Pages merged per vertical) + Image Phase 2
+
+ONE wave of per-vertical "build" agents, each writing its **components first, then the pages that mount them** — the within-agent write-order replaces the old cross-agent barrier, so the orchestrator never re-enters between components and pages. Image Phase 2 rides this wave. All background.
+
+**Gate (from the seed gate):** `seeded` populated, `.wix/seeded.json` written, bridge run. Verify **both** `.wix/design-tokens.css` **and** `.wix/site.d.ts` exist on disk, and `compose.mjs` wrote `src/layouts/Layout.astro` + `src/styles/global.css`. If a design-tokens file is missing, do not dispatch — surface the path and stop. (Each merged build agent reads `.wix/design-tokens.css` itself for the token vocabulary — the orchestrator does **not** read it or inline it into dispatch prompts, which would re-emit the full token block once per agent for no benefit; the cascade reaches components through `global.css`, not the prompt.)
+
+### Pre-batch (same message, before dispatches) — ALL pre-copies up front
+
+**1 · Per-pack component-CSS templates** (deterministic `cp`; static `var(--token)` CSS, no subagent). `compose.mjs`'s Layout imports `src/styles/components-<pack>.css` for every pack with `components`; **skip this and `astro build` fails with `Could not resolve "../styles/components-<pack>.css"`.** For each loaded pack with a `components` scope (today: `stores`, `ecom`, `blog`, `forms`, `gift-cards`, `bookings`):
+
+```bash
+for pack in <loaded packs with components>; do
+  cp "<SKILL_ROOT>/references/astro/templates/$pack/components-$pack.css" \
+     "src/styles/components-$pack.css"
+done
+```
+
+Idempotent. Packs without a template (`cms` — SSR inline) are skipped silently.
+
+**2 · Pre-copied utility templates** (both components- and pages-phase utils, since one agent imports both). Each vertical's INSTRUCTIONS lists files under "Pre-copied by the orchestrator (do NOT write these yourself)":
+
+```bash
+# stores (loaded)
+cp "<SKILL_ROOT>/references/astro/templates/stores/back-in-stock.ts" "src/utils/back-in-stock.ts"
+cp "<SKILL_ROOT>/references/astro/templates/stores/categories.ts"     "src/utils/categories.ts"
+# ecom (loaded)
+cp "<SKILL_ROOT>/references/astro/templates/ecom/discounts.ts"        "src/utils/discounts.ts"
+# bookings (loaded) — elevated SSR API endpoints + SeoTags
+mkdir -p src/pages/api
+cp "<SKILL_ROOT>/references/astro/templates/bookings/api/confirm-booking.ts" "src/pages/api/confirm-booking.ts"
+cp "<SKILL_ROOT>/references/astro/templates/bookings/api/waitlist.ts"        "src/pages/api/waitlist.ts"
+cp "<SKILL_ROOT>/references/astro/templates/bookings/SeoTags.astro"          "src/components/SeoTags.astro"
+```
+
+`categories.ts` is imported by `pages-categories`/`pages-products`/`pages-home-and-nav`; `back-in-stock.ts` by stores components; `discounts.ts` by ecom components + stores product pages; the bookings API endpoints (elevated `confirmBooking` seat-hold + native v1 waitlist register) by `BookingForm.tsx`, and `SeoTags.astro` by `services/[slug].astro`. Static, brand-agnostic SDK wrappers — if not pre-copied, multiple scopes race to author them.
+
+### Dispatch the wave — one concurrent batch (private agents) + a serialized shell chain alongside it
+
+One merged "build" agent per loaded vertical (Instruction file = that vertical's `INSTRUCTIONS.md`), owning its `components` scope **and** its private `pages` scopes, written islands-first then pages. Split by whether the agent's scopes touch a **shared shell** (`src/components/Navigation.astro` or `src/pages/index.astro`):
+
+**A · Concurrent batch — agents that own only private files:**
+- **stores-build** — `components` (AddToCartButton, ProductPurchase, BackInStockForm, SeoTags) → `pages-categories` (`category/[slug].astro`, `CategoryRail.astro`) → `pages-products` (`products/index.astro`, `products/[slug].astro`, `ProductCard.astro`). **Write order matters: islands → `pages-categories` (writes `CategoryRail.astro`) → `pages-products` (mounts it)** — every import a later scope mounts is already on disk.
+- **blog-build** — `components` (blog service module, RicosViewer, consts) → `pages` (listing, detail, RSS, BlogPost layout, all under `src/pages/blog/*`). No `home:` marker → no shared-shell patch, stays concurrent.
+- **cms-build** — `pages` (About + FAQ wired to live `@wix/data`). No `components` scope.
+- **forms-build** — `components` (ContactForm island) + `pages` (`contact.astro`, private).
+
+**B · Serialized shell chain — agents that patch `Navigation.astro` / `index.astro`** (read-modify-write a shared file → concurrent dispatch trips the staleness guard `File has been modified since read`, **per-file, not per-marker**). **Launch one, wait for its return, launch the next** — each sees the previous one's insertion. Runs **alongside** batch A, not after it. The shell-patchers (today): **ecom, stores `pages-home-and-nav`, bookings, gift-cards** — exactly the packs with `nav:`/`home:` markers:
+- **ecom-build** — `components` (CartView, CartBadge) → `pages` (`cart.astro`, `thank-you.astro` private, **+ CartBadge mount in `Navigation.astro` at `<!-- nav:actions -->`**).
+- **stores-home-and-nav** — patch `index.astro` product grid at `<!-- home:stores -->` + `Navigation.astro` Shop submenu at `<!-- nav:links -->`. Writes no islands; pure shell-patcher.
+- **bookings-build** — `components` (ServiceCard, AvailabilityCalendar, BookingForm, ServiceBookingFlow, ManageBooking) → `pages` (`services/index.astro`, `services/[slug].astro`, `booking-confirmation.astro`, `manage-booking.astro` private, **+ Services link in `Navigation.astro` at `<!-- nav:links -->` / services teaser in `index.astro` at `<!-- home:bookings -->`**).
+- **gift-cards-build** — `components` (probe util, GiftCardPurchase island) → `pages` (gift-cards landing + `Navigation.astro` `<!-- nav:links -->` / `index.astro` `<!-- home:gift-cards -->`).
+
+Cross-vertical imports (`stores-home-and-nav` importing `CategoryRail`/`ProductCard`/`utils/categories.ts`) resolve at **build time**, not write time, so they impose no write-ordering between the chain and batch A. The only ordering: (i) shell-patchers serialize against each other (per-file), (ii) everything is on disk before Build.
+
+**C · Image Phase 2 Entity** (imagery-gated) — same batch, background. Not dispatched on `themed-blocks`. On `ai-generated` with entities in `seeded`, dispatch it; the prompt **inlines** the `seeded.<pack>` slice (entity IDs + names + descriptions) + brand context (`images/INSTRUCTIONS.md` § "Scope: image-phase-2-entity"). It overlaps the whole wave, gated only at Build.
+
+### Merged-agent prompt additions (per vertical)
+
+```
+Scopes (write in this order — islands/components FIRST, then pages, and a page-scope that writes a shared component before the page-scope that mounts it): <e.g. components, pages-categories, pages-products>
+Files to own (absolute paths): <union of the scopes' files from the vertical's pack frontmatter>
+Phase 1 Seed data: read your `seeded.<vertical>` slice from `.wix/seeded.json` (written once at the seed gate; do NOT import it into route files — use it to resolve slugs / getStaticPaths / demo content, then query the live SDK at request time). Fail loud (status: "partial", errors:[{code:"SEEDED_JSON_SLICE_MISSING", missing:"seeded.<vertical>"}]) if your slice is absent — do not render an empty page.
+Styling contract: read .wix/design-tokens.css (on disk, gate-verified) for the token vocabulary — it is NOT inlined. Components do not write CSS (components-<pack>.css is already on disk, and global.css supplies the tokens to the build); use the token names only as the var(--token) / Tailwind utility vocabulary your markup references.
+```
+
+Merged agents MUST NOT:
+- Modify files outside their declared scopes (the union in their prompt)
+- Modify CSS (`global.css` owned by `compose.mjs`; `components-<pack>.css` is pre-copied — never authored)
+- Patch a shared shell unless they are the chain agent assigned to it
+
+---
+
+## Wait: build wave → Build
+
+Wait on **all** build-wave agents — batch A and the full serialized chain B — then:
+- **`ai-generated`** (wave dispatched `image-phase-2-entity`): wait that handle, hard **120 s timeout** from when build agents finish; on timeout, note it and proceed. (It's been running since the wave opened, so the timeout rarely fires.) Skipping this ships previews with entity images still attaching.
+- **`themed-blocks`**: no wait — proceed immediately.
+
+Ensure the background `npm install` (`npm_handle`, waited at the seed gate) exited 0 before Build. On non-zero, follow `SETUP.md` § "npm install recovery".
+
+## Build & Release
+
+1. `npx @wix/cli@latest build` — on failure, inspect `.wix/debug.log`, fix, retry (§ "Build failure modes"; Astro/React build-blockers in `IMPLEMENTER.md`).
+2. `npx @wix/cli@latest release` — extract the published URL from `Site published on <url>`. Also populates the **Frontend link** in headless settings natively. Transient errors (`ECONNRESET`, `ETIMEDOUT`, `EAI_AGAIN`, `STATE_MISMATCH`, `temporarily unavailable`, `try again shortly`) — retry serially up to 3× with `attempt * 5`s backoff. Do **not** retry build failures — those are code bugs.
+
+Then **Final Message** (`BUILD.md` § "Final Message" — summary + `AGENTS.md` turn).
+
+## Styling contract coordination
+
+`.wix/design-tokens.css` + `.wix/site.d.ts` are the coordination artifacts. **`DESIGN.md` is the single source of truth:** the Designer authors it (run-step 0); `emit-design-tokens.mjs` projects the `.wix` artifacts from it; `compose.mjs` reads it to write `global.css` + the other 5 files (run-step 2 bridge). The contract exists before the build wave launches; each merged build agent **reads `.wix/design-tokens.css` from disk** for the token vocabulary (gate-verified present at § "Step 4.5"). The orchestrator does **not** read it or inline it — inlining re-emits the full token block into every dispatch prompt (~one block per vertical per run) for no benefit, since the token cascade reaches components through `global.css`/`@theme`, not the prompt. The on-disk file is the single read source for the agent's token vocabulary.
+
+## Build failure modes
+
+Inspect `.wix/debug.log` after a failed build:
+
+| Failure | Detect | Fix |
+|---------|--------|-----|
+| `Legacy HTML single-line comments` | build stderr | An agent emitted HTML comments in `.astro` frontmatter — replace with `//` or `/* */` |
+| `Missing environment variable WIX_CLIENT_ID` | build stderr | `npx @wix/cli@latest env pull --json` then retry |
+| `Cannot find module '@wix/…'` | build stderr | npm install missed it; check the pack's `packages` list |