@wix/agent-skills 1.7.0 → 1.9.0

package/skills/wix-headless/references/astro/cms/PORTFOLIO.md

@@ -6,7 +6,7 @@ Build a visual portfolio using `@wix/data` — project grid with category filter
 
 ## Collection Schema
 
-Create a collection in the Wix dashboard → CMS with these fields:
+The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
 
 | Field | Type | Purpose |
 |-------|------|---------|
@@ -38,7 +38,7 @@ Create a collection in the Wix dashboard → CMS with these fields:
 ### 1. Portfolio Service Module (`src/lib/portfolio.ts`)
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { media } from "@wix/sdk";
 
@@ -150,7 +150,7 @@ const { categories, activeCategory, basePath } = Astro.props;
 </nav>
 ```
 
-> **Styling note:** CategoryFilter styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Category Filter.
+> **Styling note:** CategoryFilter styling is created by the design skill. See `references/shared/STYLING.md` (Category Filter).
 
 > Server-rendered, no JavaScript. Category is read from `Astro.url.searchParams` in the page.
 
@@ -189,7 +189,7 @@ const { project } = Astro.props;
 </a>
 ```
 
-> **Styling note:** ProjectCard styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Project Card.
+> **Styling note:** ProjectCard styling is created by the design skill. See `references/shared/STYLING.md` (Project Card).
 
 ### 4. Project Grid Page (`src/pages/work/index.astro`)
 
@@ -376,7 +376,7 @@ export default function ImageGallery({ images, alt }: Props) {
 }
 ```
 
-> **Styling note:** Uses `.gallery-grid`, `.gallery-item`, `.lightbox-overlay`, `.lightbox-image`, `.lightbox-nav`, `.lightbox-close` from the designed component's `<style is:global>` block. See `COMPONENT_PATTERNS.md` → Image Gallery / Lightbox.
+> **Styling note:** Uses `.gallery-grid`, `.gallery-item`, `.lightbox-overlay`, `.lightbox-image`, `.lightbox-nav`, `.lightbox-close` from the designed component's `<style is:global>` block. See `references/shared/STYLING.md` (Image Gallery / Lightbox).
 
 Key details:
 - Renders as a grid; clicking opens a lightbox overlay
@@ -426,7 +426,7 @@ Project showcase image for [TITLE]. [BRAND AESTHETIC]. Color palette: [BRAND COL
 Gallery image [N] for [TITLE]: [describe a specific aspect/angle of the project]. [BRAND AESTHETIC]. [BRAND COLORS]. No text, no watermarks
 ```
 
-**Patch fields:** `coverImage`, optionally `galleryImages` (as an array of wixstatic URLs)
+**Patch field:** `galleryImages` (as an array of wixstatic URLs)
 
 Example patch:
 
@@ -445,10 +445,9 @@ body: {
 
 ## Testing
 
-1. Create a "Projects" collection in the Wix dashboard → CMS with the schema above
-2. Add 3+ projects with cover images, categories, and at least one with gallery images
-3. Mark 1–2 as `featured: true`
-4. Run `npx @wix/cli@latest dev`
-5. `/work` — grid with category filter tabs
-6. Click a category — filters projects
-7. Click a project — detail page with gallery lightbox
+Assumes the `seed` scope has already created the "Projects" collection and inserted items via REST (see `../../cms/CMS_FOUNDATIONS.md`) — 3+ projects with categories (and, after the image pass, cover/gallery images), 1–2 marked `featured: true`.
+
+1. Run `npx @wix/cli@latest dev`
+2. `/work` — grid with category filter tabs
+3. Click a category — filters projects
+4. Click a project — detail page with gallery lightbox

package/skills/wix-headless/references/astro/cms/RESOURCE_LIBRARY.md

@@ -6,7 +6,7 @@ Build a downloadable resource library using `@wix/data` — file listings with c
 
 ## Collection Schema
 
-Create a collection in the Wix dashboard → CMS with these fields:
+The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
 
 | Field | Type | Purpose |
 |-------|------|---------|
@@ -36,7 +36,7 @@ Create a collection in the Wix dashboard → CMS with these fields:
 ### 1. Resources Service Module (`src/lib/resources.ts`)
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { media } from "@wix/sdk";
 
@@ -146,8 +146,7 @@ const fileType = type.toUpperCase();
 ```
 
 Key details:
-- Color-coded by file type — red for PDF, blue for DOC, green for XLS, yellow for ZIP
-- Falls back to neutral gray for unknown types
+- The SVG uses `stroke="currentColor"` — any per-file-type coloring is purely CSS-driven (e.g. a `.file-type-pdf` class on the wrapper), not set here
 - File type label rendered inside the document icon SVG
 
 ### 3. Resource Card (`src/components/ResourceCard.astro`)
@@ -187,7 +186,7 @@ const { resource } = Astro.props;
 </a>
 ```
 
-> **Styling note:** ResourceCard styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Resource Card.
+> **Styling note:** ResourceCard styling is created by the design skill. See `references/shared/STYLING.md` (Resource Card).
 
 ### 4. Resource Listing Page (`src/pages/resources/index.astro`)
 
@@ -347,10 +346,9 @@ body: {
 
 ## Testing
 
-1. Create a "Resources" collection in the Wix dashboard → CMS with the schema above
-2. Add 4+ resources across 2+ categories with different file types (PDF, DOC, ZIP)
-3. Include `fileUrl` links (can be any downloadable URL for testing)
-4. Run `npx @wix/cli@latest dev`
-5. `/resources` — shows all resources with category filters and file type badges
-6. Click a category — filters resources
-7. Click a resource — detail page with download button and related resources
+Assumes the `seed` scope has already created the "Resources" collection and inserted items via REST (see `../../cms/CMS_FOUNDATIONS.md`) — 4+ resources across 2+ categories with different file types (PDF, DOC, ZIP) and `fileUrl` links (any downloadable URL for testing).
+
+1. Run `npx @wix/cli@latest dev`
+2. `/resources` — shows all resources with category filters and file type badges
+3. Click a category — filters resources
+4. Click a resource — detail page with download button and related resources

package/skills/wix-headless/references/astro/cms/TEAM_DIRECTORY.md

@@ -6,7 +6,7 @@ Build a team directory using `@wix/data` — staff cards grouped by department w
 
 ## Collection Schema
 
-Create a collection in the Wix dashboard → CMS with these fields:
+The schema the `seed` scope creates via REST (see `../../cms/CMS_FOUNDATIONS.md`) — fields:
 
 | Field | Type | Purpose |
 |-------|------|---------|
@@ -35,7 +35,7 @@ Create a collection in the Wix dashboard → CMS with these fields:
 ### 1. Team Service Module (`src/lib/team.ts`)
 
 ```typescript
-import * as items from "@wix/wix-data-items-sdk";
+import { items } from "@wix/data";
 import { auth } from "@wix/essentials";
 import { media } from "@wix/sdk";
 
@@ -156,7 +156,7 @@ const { member } = Astro.props;
 </a>
 ```
 
-> **Styling note:** TeamMemberCard styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Team Member Card.
+> **Styling note:** TeamMemberCard styling is created by the design skill. See `references/shared/STYLING.md` (Team Member Card).
 
 Key details:
 - Inline SVG icons — no icon library dependency
@@ -292,8 +292,8 @@ body: {
 
 ## Testing
 
-1. Create a "Team" collection in the Wix dashboard → CMS with the schema above
-2. Add 4+ members across 2+ departments, with photos and social links
-3. Run `npx @wix/cli@latest dev`
-4. `/team` — shows members grouped by department
-5. Click a member — profile page with photo, bio, and social links
+Assumes the `seed` scope has already created the "Team" collection and inserted items via REST (see `../../cms/CMS_FOUNDATIONS.md`) — 4+ members across 2+ departments, with social links (and headshots after the image pass).
+
+1. Run `npx @wix/cli@latest dev`
+2. `/team` — shows members grouped by department
+3. Click a member — profile page with photo, bio, and social links

package/skills/wix-headless/references/astro/designer/INSTRUCTIONS.md

@@ -1,42 +1,43 @@
 ---
 name: page-designer
-description: "The page-design specification for Wix Managed Headless Phase 4 routes: home, static (about/faq), store-pages, blog-pages, contact-page. This is the visual-design guidance the merged Phase 4 `pages` scopes (vertical packs, BUILD.md Step 7) apply when they write each route ONCE with both visual design and live SDK data. It defines layout, contract classes, decorative-slot conventions, responsive rules, and anti-patterns — not a separate placeholder-writing pass. The design-system phase (tokens + global.css + Layout/Nav/Footer shells) is NOT here — it is split across DESIGN_SYSTEM.md (Designer) and astro/COMPOSE.md (Composer)."
+description: "The page-design specification for Wix Managed Headless page routes: home, static (about/faq), store-pages, services-pages, blog-pages, contact-page. This is the visual-design guidance the merged build agents' `pages` scopes (vertical packs, BUILD-astro.md § 'Step 4.5' — the build wave) apply when they write each route ONCE with both visual design and live SDK data. It defines layout, contract classes, decorative-slot conventions, responsive rules, and anti-patterns — not a separate placeholder-writing pass. The design-system phase (tokens + global.css + Layout/Nav/Footer shells) is NOT here — it is split across DESIGN_SYSTEM.md (Designer) and scripts/compose.mjs (Composer)."
 ---
 
 # Page Designer — Scope-Based Page Design
 
-> **Single-write merged model (BUILD.md Step 7 is authoritative).** Phase 4 routes are written **once**, by the per-vertical `pages` scopes, with both visual design **and** live SDK queries in the same pass — there is no separate "write a design placeholder, then rewrite it with data" dispatch (that double-write was eliminated). This doc is the **visual-design specification** the merged author applies: the layout, typography, color, spacing, contract classes, decorative slots, and component composition each route should have. Where a section below says "placeholder data," read it as *the data shape* the live query maps onto — and the safe fallback to render if a query returns empty. The merged scope binds real SDK data into this structure; it does not ship hardcoded arrays as the final output.
+> **Single-write merged model (BUILD-astro.md § "Step 4.5" — the build wave — is authoritative).** Routes are written **once**, by the per-vertical merged build agents' `pages` scopes (after that agent writes its islands), with both visual design **and** live SDK queries in the same pass — there is no separate "write a design placeholder, then rewrite it with data" dispatch (that double-write was eliminated), and no separate Components→Pages wave (those are merged into one per-vertical agent). This doc is the **visual-design specification** the merged author applies: the layout, typography, color, spacing, contract classes, decorative slots, and component composition each route should have. Where a section below says "placeholder data," read it as *the data shape* the live query maps onto — and the safe fallback to render if a query returns empty. The merged scope binds real SDK data into this structure; it does not ship hardcoded arrays as the final output.
 
 Your prompt will contain a `Scope:` line naming exactly one of the page scopes below. **Read only the section for your scope. Do not read sections for other scopes — wastes context and blurs ownership.**
 
 You own **page-level visual output**: the layout, typography, color, spacing, and component composition of one route group. The same merged scope also binds the live SDK data into that structure (the per-vertical reference under `references/astro/<vertical>/` supplies the exact queries).
 
-> **The design-system phase is not in this doc.** Tokens (`data.designTokens`), `global.css`, `astro.config.mjs`, `Layout.astro`, `Navigation.astro`, and `Footer.astro` are produced earlier in the run by a two-role split:
-> - **Designer** (`<SKILL_ROOT>/references/DESIGN_SYSTEM.md`) — returns the framework-agnostic design spec (tokens + brand-voice strings) as JSON only.
-> - **Composer** (`<SKILL_ROOT>/references/astro/COMPOSE.md`) — applies that spec to the astro skeletons and writes the 6 design-system files.
+> **The design-system phase is not in this doc.** Tokens (`DESIGN.md` / `data.design`), `global.css`, `astro.config.mjs`, `Layout.astro`, `Navigation.astro`, and `Footer.astro` are produced earlier in the run by a two-role split:
+> - **Designer** (`<SKILL_ROOT>/references/DESIGN_SYSTEM.md`) — authors `DESIGN.md` (the framework-agnostic token spec) and returns the brand-voice strings.
+> - **Composer** (`<SKILL_ROOT>/scripts/compose.mjs`, a deterministic script — self-documenting) — applies `DESIGN.md` to the astro skeletons and writes the 6 design-system files.
 >
 > By the time the Phase 4 routes are written, the `@theme` token contract, the `.astro` shells, and `.wix/design-tokens.css` already exist. You consume them; you do not write them.
 
 ## Self-Loading
 
 1. Read `../../shared/RETURN_CONTRACT.md` — structured return format.
-2. Read `../../shared/STYLING.md` — three styling categories (tokens-as-utilities, global semantic classes, co-located styles). Pages compose `@theme` tokens at call sites as Tailwind utilities; the inlined `designTokens` contract in your prompt tells you which tokens this run published.
+2. Read `../../shared/STYLING.md` — three styling categories (tokens-as-utilities, global semantic classes, co-located styles). Pages compose `@theme` tokens at call sites as Tailwind utilities; the design-token vocabulary on disk at `.wix/design-tokens.css` tells you which tokens this run published.
 
 No REST calls required. Page-design scopes are frontend-only — no `curl`, no MCP tool-discovery.
 
-**Do NOT `Read .wix/site.json`.** Every input you need (brand, the published `designTokens` contract, pages to design, pack home-section snippets) is inlined in your prompt.
+**Every input you need (brand, the published design-token vocabulary, pages to design, pack home-section snippets) is inlined in your prompt.** Don't depend on mutable shared state.
 
 ## Scope Routing
 
 | Scope | Phase | Output (files) |
 |-------|-------|----------------|
-| `home` | Phase 4 — Step 7 | `src/pages/index.astro` (composes pack home-sections + brand hero/CTA into the Composer-written shell) |
-| `static` | Phase 4 — Step 7 | `src/pages/about.astro`, `src/pages/faq.astro` |
-| `store-pages` | Phase 4 — Step 7 | `src/pages/products/index.astro`, `src/pages/products/[slug].astro`, `src/components/ProductCard.astro`, `src/pages/cart.astro`, `src/pages/thank-you.astro` |
-| `blog-pages` | Phase 4 — Step 7 | `src/pages/blog/index.astro`, `src/pages/blog/[slug].astro` |
-| `contact-page` | Phase 4 — Step 7 | `src/pages/contact.astro` |
+| `home` | build wave | `src/pages/index.astro` (composes pack home-sections + brand hero/CTA into the Composer-written shell) |
+| `static` | build wave | `src/pages/about.astro`, `src/pages/faq.astro` |
+| `store-pages` | build wave | `src/pages/products/index.astro`, `src/pages/products/[slug].astro`, `src/components/ProductCard.astro`, `src/pages/cart.astro`, `src/pages/thank-you.astro` |
+| `services-pages` | build wave | `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro` |
+| `blog-pages` | build wave | `src/pages/blog/index.astro`, `src/pages/blog/[slug].astro` |
+| `contact-page` | build wave | `src/pages/contact.astro` |
 
-If your prompt's `Scope:` line names `design-system`, you have the wrong doc — that work lives in `DESIGN_SYSTEM.md` (Designer) and `astro/COMPOSE.md` (Composer). Stop and tell the parent.
+If your prompt's `Scope:` line names `design-system`, you have the wrong doc — that work lives in `DESIGN_SYSTEM.md` (Designer) and `scripts/compose.mjs` (Composer). Stop and tell the parent.
 
 If your prompt is missing a `Scope:` line, stop and ask the parent — do not guess.
 
@@ -44,14 +45,14 @@ If your prompt is missing a `Scope:` line, stop and ask the parent — do not gu
 
 ---
 
-## Page Designer Scopes (Phase 4 — Step 7, background)
+## Page Designer Scopes (build wave, background)
 
 All page scopes share common inputs and rules. Scope-specific details follow.
 
 ### Common inputs (from your prompt)
 
 - **Brand context** — name, vibe, aesthetic direction, colors, fonts, mood.
-- **Published token contract** — the `designTokens` JSON (same shape the Designer returned, written into `@theme` by the Composer). Compose these tokens as Tailwind utilities; if a token you need is absent, flag it in your return (`MISSING_TOKEN`) — do not invent a class.
+- **Published token contract** — the design-token vocabulary (the DESIGN.md tokens, written into `@theme` by `compose.mjs`). Compose these tokens as Tailwind utilities; if a token you need is absent, flag it in your return (`MISSING_TOKEN`) — do not invent a class.
 - **Pages to design** — list of routes and their contract class associations.
 - **Pack home-section snippet** (home scope only) — section stubs from every loaded pack.
 - **Placeholder data instruction** — use plausible brand-contextual placeholder text, prices, images where live data is not yet available.
@@ -104,7 +105,7 @@ All page scopes share common inputs and rules. Scope-specific details follow.
 9. **Responsive.** All pages must work at mobile (320px), tablet (768px), and desktop (1024px+). Use Tailwind responsive prefixes (`md:`, `lg:`) and the spacing scale from `@theme`.
 10. **Use Tailwind utility classes in templates.** For layout, spacing, typography, and responsive design — use utility classes directly in the markup. Contract classes are still required for components referenced by Phase 3/4 agents. Mix both: `<div class="product-grid grid grid-cols-1 md:grid-cols-3 gap-lg">`. Always use brand `@theme` tokens (e.g., `bg-bark`, `text-cream`) — never default Tailwind colors.
 11. **No duplicate files.** If two scopes list the same file (rare), the scope whose prompt explicitly names it as "owned" takes precedence. If unclear, write it and note the overlap in your return.
-12. **Do NOT write to `src/styles/components-<pack>.css` or `src/styles/global.css`** — `components-<pack>.css` is owned by Phase 3 Components agents; `global.css` is owned by the Composer. Writing to either causes double-write conflicts.
+12. **Do NOT write to `src/styles/components-<pack>.css` or `src/styles/global.css`** — `components-<pack>.css` is pre-copied from the skill template by the orchestrator (build-wave pre-batch); `global.css` is owned by the Composer. Writing to either causes double-write conflicts.
 
 ### Scope: `home`
 
@@ -175,19 +176,19 @@ All store-facing pages designed together for visual coherence.
 **Products listing (`/products`):**
 - Page heading
 - Product grid using `product-grid` class
-- 3-6 placeholder product cards using `ProductCard` component
+- Bind the live `productsV3` query (per `references/astro/stores/PRODUCT_PAGES.md`) into a grid of `ProductCard` components; render a brand-contextual empty state if the query returns nothing
 
 **Product detail (`/products/[slug]`):**
-- Product image (large, placeholder)
+- Product image (large) resolved from the live product record
 - Product info section with `product-detail` class
-- Purchase area with `product-purchase` class — placeholder price, placeholder variant selector, Add to Cart button with `add-to-cart-btn` class
+- Purchase area with `product-purchase` class — price, variant selector, and Add to Cart button (`add-to-cart-btn` class) bound to the live product/variant data
 - Product description area
 
 **ProductCard component:**
-- Accepts a single `product` prop (object with name, price, slug, image fields)
+- Accepts a single `product` prop — the full Wix product object from `productsV3`
 - Uses `product-card` class
 - Image, name, price, link to `/products/${product.slug}`
-- **Important:** Phase 2 `product-pages` rewrites this to accept the full Wix product object. Design with a simple prop interface: `{ product: { name: string; slug: string; price: number; image?: string } }`
+- Design the prop interface around the full product object: `{ product }` (the canonical `productsV3` shape — see `references/astro/stores/PRODUCT_PAGES.md`)
 
 **Cart (`/cart`):**
 - Two-column grid layout: `.cart-grid` — items column left, order summary right. Stacks vertically on mobile
@@ -199,11 +200,11 @@ All store-facing pages designed together for visual coherence.
 - Unavailable item warning with `.cart-item-unavailable` class (red text)
 - Empty state with `.cart-empty` class (centered, muted text + "Browse Products" link)
 - **All cart CSS must be in `<style is:global>`** — `CartView` is a React island; scoped Astro styles do not reach its children
-- Placeholder cart items (2-3)
+- The live `CartView` island renders the items/summary at runtime; design the surrounding structure and an empty-cart fallback
 
 **Thank you (`/thank-you`):**
 - Confirmation message with `order-summary` class
-- Placeholder order details
+- Order details bound to the live order data (per the ecom cart/checkout reference)
 
 **Return:**
 ```json
@@ -225,6 +226,25 @@ All store-facing pages designed together for visual coherence.
 }
 ```
 
+### Scope: `services-pages`
+
+All bookings-facing pages designed together for visual coherence. **Canonical templates exist** at `<SKILL_ROOT>/references/astro/templates/bookings/` — adapt them (copy, headings, styling); do not re-author the SDK/booking-flow wiring (`references/astro/bookings/SERVICES_PAGES.md` is the wiring spec).
+
+**Files:** `src/pages/services/index.astro`, `src/pages/services/[slug].astro`, `src/pages/booking-confirmation.astro`
+
+**Services listing (`/services`):**
+- Page heading + optional brand tagline
+- Service grid using the `service-grid` class, one `ServiceCard` per service (`service-card` class — image/placeholder, name, tagline, duration + price row)
+- Bind the live `services.queryServices` query (per `references/astro/bookings/SERVICES_PAGES.md`); brand-contextual empty state if it returns nothing
+
+**Service detail (`/services/[slug]`):**
+- `container-reading` width (never a bare `max-w-<size>`); optional banner image **only when the service has media** (image-less is the common seed case — no fixed-ratio placeholder)
+- Title, tagline, duration + price row, description
+- "Book this service" section mounting the `ServiceBookingFlow` island (`client:only="react"`, threads `serviceType`) — the week calendar uses the `availability-*` classes (week strip + `availability-day`), slots use `time-slot` classes (`--available`/`--selected`), and the form uses the `booking-*` family
+
+**Booking confirmation (`/booking-confirmation`):**
+- `max-w-prose`, centered; "Thank you for booking" headline + the service name and time (read from the `service`/`startDate` query params) + a link back to `/services`. No re-fetch, no cancel UI (manage/cancel is out of scope).
+
 ### Scope: `blog-pages`
 
 Blog feed listing and post detail designed together.
@@ -265,7 +285,7 @@ Contact page with form placeholder.
 **Contact page:**
 - Page heading and descriptive text
 - Contact CTA section using `contact-cta` class (if on home, this mirrors the home CTA's visual language)
-- Form placeholder area — a styled `<div>` where Phase 2 mounts the `ContactForm.tsx` island. Use a placeholder form layout (name, email, message fields, submit button) so the page looks complete, but Phase 2 replaces this with the real React island.
+- Form area — mount the `ContactForm.tsx` island (written by Phase 3 Components) styled to the brand, per `references/astro/forms/CONTACT_FORM.md`. Style a complete form layout (name, email, message fields, submit button) so the page reads as finished even before submissions wire up.
 - Optional: map embed placeholder, business hours, address (if brand context suggests it)
 
 **Return:**
@@ -307,7 +327,7 @@ The JSON block MUST be the **last** content in your message — the parent parse
 | Generic unstyled HTML | Brand-first design — every element reflects the aesthetic direction |
 | Fixed-width layouts | Responsive: mobile-first, breakpoints at 320/768/1024px |
 | `ls src/`, `Glob src/**` to discover files | Your prompt lists every file and class contract. Write directly. |
-| `Read .wix/site.json` to get brand or verticals | Every field is in your prompt |
+| Read a shared file to get brand or verticals | Every field is in your prompt |
 | Hardcode an external `<img src="https://...">` for product/content images | Resolve entity images from the live record (`media.getScaledToFillImageUrl(...)`) in this same scope; **decorative** images use the `data-decorative-slot` mechanism |
 | Omit `data-decorative-slot` on hero/about/background placeholders | Every decorative image placeholder MUST carry a slot attribute — the orchestrator's injection pass depends on it (common rule #7) |
 | Add a hero CTA / footer link to a disabled-pack route | Disabled packs (gift-cards) are dormant — no entry points to their routes |
@@ -319,7 +339,7 @@ The JSON block MUST be the **last** content in your message — the parent parse
 | Agent | Relationship | Rule |
 |-------|-------------|------|
 | Composer (design-system) | Wrote `global.css`, `Layout.astro`, `Navigation.astro`, `Footer.astro`, the `@theme` tokens | You consume the token contract and wrap pages in its `Layout`; you never rewrite those files |
-| Phase 3 Components (stores/blog/forms) | Writes React islands referencing contract classes + `components-<pack>.css` | They own islands + scoped CSS; the route references contract classes in markup and mounts the islands, no overlap |
+| Phase 3 Components (stores/bookings/blog/forms) | Writes React islands referencing contract classes + `components-<pack>.css` | They own islands + scoped CSS; the route references contract classes in markup and mounts the islands, no overlap |
 | Per-vertical reference (`references/astro/<vertical>/`) | Supplies the exact SDK queries + wiring the merged route binds | Apply this design spec **and** that vertical's queries together in one write — there is no second pass |
 | Image agent (Image Phase 1) | Returns decorative URLs in `data.slots` | Emit `data-decorative-slot="<key>"` placeholders; the orchestrator injects the `<img>` once Image Phase 1 returns |
 | Image agent (Image Phase 2) | PATCHes entity images onto products/posts via REST | No direct interaction — images flow through product/post records that Phase 4 queries |
@@ -328,4 +348,4 @@ The JSON block MUST be the **last** content in your message — the parent parse
 
 The merged Phase 4 `pages` scope owns each route file **end to end** — visual structure **and** data wiring, written in a single pass. There is no separate page-designer agent that writes a file for a later scope to rewrite; this doc is the visual-design spec the merged author applies alongside its vertical's SDK queries (`references/astro/<vertical>/`). Each route file therefore has exactly **one** writer (its `pages` scope), which removes the cross-phase double-write the older placeholder-then-rewrite model carried.
 
-The shared shells the route composes into — `Layout.astro`, `Navigation.astro`, `index.astro`, `global.css`, `components-<pack>.css` — are owned by the Composer / Phase 3 Components, not by the route scope (see "Coordination" above and BUILD.md Step 7's shared-shell-patcher serialization rule).
+The shared shells the route composes into — `Layout.astro`, `global.css` (Composer), and the marker-patched `Navigation.astro` / `index.astro` / `components-<pack>.css` (pre-copied or patched by the serialized shell-patcher agents) — are NOT owned by a private-file route scope (see "Coordination" above and BUILD-astro.md § "Step 4.5", the serialized shell chain).

package/skills/wix-headless/references/astro/ecom/CART_PAGES.md

@@ -1,21 +1,20 @@
 # Phase 4 Cart Pages — Ecom
 
-Scope: `ecom-pages`. Launched in **Step 7**. Mounts `CartView` island on the cart page, wires the thank-you page, and mounts `CartBadge` in Navigation.
+Scope: `cart-checkout` (the ecom `pages` scope) — the **pages** portion of the ecom **merged build agent** (the build wave), written *after* its `components`. Mounts `CartView` island on the cart page, wires the thank-you page, and mounts `CartBadge` in `Navigation.astro` (at the `<!-- nav:actions -->` marker). **Because it patches the shared `Navigation.astro` shell, the ecom build agent runs in the build wave's serialized shell chain** — never concurrent with the other Navigation/index patchers (stores `pages-home-and-nav`, gift-cards, blog), so concurrent marker edits can't collide (`BUILD-astro.md` § "Step 4.5").
 
 ## Scope
 
-Files this agent OWNS (rewrites from designer output):
+Files this agent OWNS (each written once — designer visual spec + live wiring together):
 
 - `src/pages/cart.astro` — mount `CartView.tsx` (client-only, no server-side cart fetch)
 - `src/pages/thank-you.astro` — read `orderId` from URL, fire `Purchase` event
 
-Files this agent PATCHES (does NOT rewrite):
+Files this agent PATCHES (does NOT rewrite) — only at its own marker:
 
-- `src/components/Navigation.astro` — mount `CartBadge` in the `nav-actions` area
+- `src/components/Navigation.astro` — mount `CartBadge` in the `nav-actions` area (`<!-- nav:actions -->`). Stores `pages-home-and-nav` patches the same file at `<!-- nav:links -->`; the serialized shell chain keeps these from colliding.
 
 Files this agent MUST NOT touch:
-- `src/components/CartView.tsx` — owned by `ecom-shared` (already written)
-- `src/components/CartBadge.tsx` — owned by `ecom-shared`
+- `src/components/CartView.tsx`, `src/components/CartBadge.tsx` — the ecom islands; written earlier in this same merged agent (the `components` scope)
 - Any product page, home page, or stores-specific component
 - `global.css`, any designed component
 
@@ -100,8 +99,8 @@ Cart page → "Proceed to Checkout"
 ```json
 {
   "status": "complete",
-  "phase": "ecom-pages",
-  "scope": "ecom-pages",
+  "phase": "cart-checkout",
+  "scope": "cart-checkout",
   "summary": "Mounted CartView (client-only fetch); wired Purchase event; mounted CartBadge in Navigation",
   "data": {
     "pagesWired": 2,

package/skills/wix-headless/references/astro/ecom/CART_WIRING.md

@@ -1,8 +1,8 @@
 # Phase 3 Components — Ecom (TSX)
 
-Scope: `components`. Launched in **Step 4.5** (after Phase 2 Design System completes, parallel to stores components and the `components-css` sibling). Writes code that depends on the **design tokens** but NOT on Phase 4 page markup.
+This is the **components** portion of the ecom **merged build agent** (the build wave — `BUILD-astro.md` § "Step 4.5"). Your agent writes these islands **first**, then the ecom pages (`cart.astro`, `thank-you.astro`) that mount them. The code here depends on the **design tokens** (read from `.wix/design-tokens.css` on disk) but NOT on page markup.
 
-> **CSS lives in a sibling scope.** `src/styles/components-ecom.css` is owned by the `components-css` scope (see `./COMPONENTS_CSS.md`), which runs concurrently with this one in the same Step 4.5 batch. This scope does NOT write the CSS file. Reference contract class names from the design tokens here; the CSS sibling defines the rules.
+> **CSS is pre-copied, not authored.** `src/styles/components-ecom.css` ships from the skill template, copied by the orchestrator in the build-wave pre-batch (see `./COMPONENTS_CSS.md`). This scope does NOT write the CSS file. Reference its contract class names from the design tokens here; the pre-copied stylesheet defines the rules.
 
 ## Scope
 
@@ -20,7 +20,7 @@ Files this agent MUST NOT touch:
 
 ## Coordination: design tokens
 
-Your parent prompt includes the design tokens inline. Use it directly — do not read `.wix/design-tokens.css` + `.wix/site.d.ts` from disk.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave).
 
 For layout/spacing/typography, compose Tailwind utilities derived from `@theme` tokens at the call site (`<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-2xl">`). For published global semantic classes (`cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — the compound + interactive-state patterns), use the ACTUAL class name verbatim. Row-internal class names (`cart-item-qty`, `qty-btn`, etc.) come from the template — keep them as-is and live in `components-ecom.css`. See `references/shared/STYLING.md` and `references/shared/IMPLEMENTER.md` § "Styling: tokens-first, classes as exception".
 
@@ -67,7 +67,7 @@ Class names used (template provides them — do not invent):
 
 Use template `templates/CartBadge.tsx`.
 
-Mounted once in `Navigation.astro` (by `ecom-pages` scope). Shows cart item count; listens for `cart-updated` custom event.
+Mounted once in `Navigation.astro` (by the `cart-checkout` scope). Shows cart item count; listens for `cart-updated` custom event.
 
 **No `initialCount` prop.** Cart is per-visitor — server-rendering the count breaks SSR caching. On mount, CartBadge reads the sessionStorage snapshot that CartView maintains (same `CART_CACHE_KEY`) to seed the initial count without a visible zero-flash between page navigations, then fetches fresh from the SDK and reconciles. If no snapshot exists (first-ever page load), count starts at 0 like before.
 
@@ -77,7 +77,7 @@ Contract keys: `cartBadge`, `cartBadgeCount`
 
 ### 3. `src/utils/analytics.ts` — not owned by this scope
 
-> `analytics.ts` is a shared utility (see `references/shared/analytics.ts`). Import from it (`import { trackEvent } from "../utils/analytics"`) but do not write it.
+> `analytics.ts` is a shared utility (canonical source `shared-utilities/analytics.ts`, seeded to `src/utils/analytics.ts`). Import from it (`import { trackEvent } from "../utils/analytics"`) but do not write it.
 
 ### 4. `src/styles/components-ecom.css` — not owned by this scope
 

package/skills/wix-headless/references/astro/ecom/COMPONENTS_CSS.md

@@ -1,6 +1,6 @@
 # Phase 3 Components-CSS — Ecom
 
-Sibling of the `components` scope. Launched in **Step 4.5** in the same concurrent batch — runs in parallel with the TSX work, stores components, gift-cards components, and Image Phase 2.
+**This stylesheet is pre-copied from the skill template by the orchestrator** (build-wave pre-batch, BUILD-astro.md § "Step 4.5") — there is no `components-css` subagent to dispatch. This file documents the CSS for reference so the ecom `components` scope (in the merged build agent) knows the class-name surface it targets.
 
 ## What this scope owns
 
@@ -23,7 +23,7 @@ You only need:
 2. **`<SKILL_ROOT>/references/shared/STYLING.md`** — the styling-contract conventions (how to use `@apply`, the `@theme` token utilities, the no-default-Tailwind-colors rule, and the global-vs-scoped CSS ownership boundary).
 3. **`<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`** — the return JSON shape.
 4. **`src/styles/global.css`** in the project — read to audit for ecom-class leaks (see § "Global-CSS leak audit" below).
-5. **Design tokens (inline in your prompt)** — the parent skill pastes the full `designTokens` JSON into your dispatch prompt. Use it directly; do NOT read `.wix/design-tokens.css` or `.wix/site.d.ts` from disk.
+5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) from `.wix/design-tokens.css` (gate-verified present before the wave). They are NOT inlined in your prompt.
 
 You do NOT need to read `INSTRUCTIONS.md`, `CART_WIRING.md`, the TSX templates, the `discounts.ts` util, or any other reference. Skipping those reads is the point of the split.
 
@@ -85,7 +85,7 @@ Write the adapted CSS to `src/styles/components-ecom.css`. The orchestrator's po
 
 ## Coordination: design tokens
 
-Your parent prompt includes the design tokens JSON inline. Use it directly — do **not** read `.wix/design-tokens.css` or `.wix/site.d.ts` from disk and do not poll for them.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave) — they are NOT inlined in your prompt.
 
 ## Return format
 

package/skills/wix-headless/references/astro/forms/CONTACT_FORM.md

@@ -33,10 +33,7 @@ Before writing any form code, ensure a contact form exists on the site via the f
    > Translate this prose-HTTP form into the full `curl` tool-call shape — pass `body` as JSON in `-d` (NOT a stringified JSON). See `../../shared/AUTHENTICATION.md` for the standard REST headers.
 
    Then retry listing forms.
-3. **If forms list is empty** → create a form (two-step atomic operation):
-   - **Step 3a:** POST to create the form (fields, layout, submit settings)
-   - **Step 3b:** Immediately PATCH to add `postSubmissionTriggers` (the POST silently drops this field — see step 4)
-   - Both steps must succeed. If 3a succeeds but 3b fails, log Status as `partial`.
+3. **If forms list is empty** → create a form. This is a two-step atomic operation (POST to create, then PATCH to add `postSubmissionTriggers`) — see step 4 for the full procedure and rationale.
 
    > **Namespace propagation:** If form creation fails with `UNSUPPORTED_FORM_NAMESPACE` immediately after installing the Forms app, the namespace hasn't propagated yet. Wait 10 seconds and retry up to 3 times. Do NOT silently fall back to static field definitions — forms without a `formId` cannot submit to Wix.
 
@@ -194,7 +191,7 @@ Before writing any form code, ensure a contact form exists on the site via the f
 
 ### 1. Modify the Existing Designed Page
 
-**Do NOT create a new page from scratch.** The design skill already created this page with branded styling, layout, and a `<style>` block. Modify it in place:
+**Do NOT create a new page from scratch.** The merged `contact-page` scope writes this page once — branded styling, layout, and `<style>` block alongside the form wiring (per `references/astro/designer/INSTRUCTIONS.md` → `contact-page`). When wiring an existing designed page, modify it in place:
 
 1. **Add SDK imports** to the frontmatter:
    ```astro
@@ -262,7 +259,7 @@ The React island must match the designed component's class names and use CSS var
 
 **Approach B: Component owns its styles using CSS variables.** If the page doesn't have a `<style>` block for the form, the component includes a `<style>` JSX element using only CSS custom properties.
 
-> **Styling note:** The React island uses the styling contract class names (`.form-container`, `.form-field`, `.form-label`, `.form-input`, `.form-textarea`, `.form-button`, `.form-success`, `.form-error`, `.form-field-error`, `.form-input-error`) from the designed ContactForm component's `<style is:global>` block. See the design skill's `COMPONENT_PATTERNS.md` → Contact Form.
+> **Styling note:** The React island uses the styling contract class names (`.form-container`, `.form-field`, `.form-label`, `.form-input`, `.form-textarea`, `.form-button`, `.form-success`, `.form-error`, `.form-field-error`, `.form-input-error`) from the designed ContactForm component's `<style is:global>` block. See `references/shared/STYLING.md` (Contact Form).
 
 ```tsx
 import { useState } from "react";
@@ -342,7 +339,7 @@ export default function ContactForm({ formId, fields }: ContactFormProps) {
           Uses styling contract classes: .form-container, .form-field, .form-label,
           .form-input, .form-select, .form-textarea, .form-button, .form-error,
           .form-field-error, .form-input-error.
-          See design skill's COMPONENT_PATTERNS.md → Contact Form. */}
+          See references/shared/STYLING.md (Contact Form). */}
 
       {fields.map((field) => (
         <div key={field.target} className="form-field">
@@ -411,7 +408,7 @@ export default function ContactForm({ formId, fields }: ContactFormProps) {
 }
 ```
 
-> **Adapting class names:** The class names above (`form-container`, `form-field`, `form-label`, `form-input`, `form-button`, `form-success`, `form-error`, `form-field-error`, `form-input-error`) are defaults. If the designed component uses different class names, use those instead — the styling contract from the design skill takes precedence.
+> **Adapting class names:** The class names above (`form-container`, `form-field`, `form-label`, `form-input`, `form-button`, `form-success`, `form-error`, `form-field-error`, `form-input-error`) are defaults. If the designed component uses different class names, use those instead — the styling contract from the page's own design takes precedence.
 
 ## Discovering Forms
 
@@ -458,17 +455,6 @@ field.inputOptions.stringOptions.phoneInputOptions?.label    // label for phone
 
 Custom fields use UUID-based targets from the form schema.
 
-## Log Results
-
-After form verification, write a sidecar file at `.wix/logs/forms-data.md` (form schema setup) or `.wix/logs/forms-implementer.md` (Phase 2 wiring) — see `../../shared/LIFECYCLE_LOG.md` for the sidecar contract. Do **not** append to `.wix/lifecycle.log.md` directly — the orchestrator concatenates all sidecars at the end. Use a `####` heading so the entry nests under `### features-orchestrator` in the assembled log:
-
-```markdown
-## forms
-- Status: complete
-- Content: "{form name}" form created (fields: {field list})
-- Images: not applicable
-```
-
 ## Testing
 
 1. Run `npx @wix/cli@latest dev`

package/skills/wix-headless/references/astro/gift-cards/COMPONENTS.md

@@ -1,6 +1,6 @@
 # Phase 3 Components — Gift Cards
 
-Launched in **Step 4.5** alongside other verticals' `components` scopes (after Phase 2 Design System). Writes the runtime probe utility, the buy-flow React island, and scoped CSS. Finishes before the Phase 4 Pages scopes run in Step 7.
+This is the **components** portion of the gift-cards **merged build agent** (the build wave). Your agent writes the runtime probe utility, the buy-flow React island, and scoped CSS **first**, then its pages (`/gift-cards` route + Navigation/index patches) — so the island is on disk before the page mounts it. Because the page side patches the shared shells, the whole gift-cards agent runs in the build wave's **serialized shell chain** (`BUILD-astro.md` § "Step 4.5").
 
 ## Scope
 
@@ -18,7 +18,7 @@ Files this agent MUST NOT touch:
 
 ## Coordination: design tokens
 
-Your parent prompt includes the design tokens inline. Reference token CSS variables (`var(--color-cream)`, `var(--spacing-lg)`, etc.) from `components-gift-cards.css`. Do NOT read `.wix/design-tokens.css` from disk.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). Reference token CSS variables (`var(--color-cream)`, `var(--spacing-lg)`, etc.) from `components-gift-cards.css`.
 
 ## Critical rules
 

package/skills/wix-headless/references/astro/gift-cards/PAGES.md

@@ -1,6 +1,6 @@
 # Phase 4 Pages — Gift Cards
 
-Launched in **Step 7** alongside other verticals' `pages` scopes. Writes the `/gift-cards` route and patches `Navigation.astro` + `index.astro` at their declared markers. The Components scope's outputs (`src/utils/gift-cards.ts`, `src/components/GiftCardPurchase.tsx`, `src/styles/components-gift-cards.css`) must already exist before this scope runs.
+The **pages** portion of the gift-cards **merged build agent** (the build wave) — written *after* its `components`. Writes the `/gift-cards` route and patches `Navigation.astro` + `index.astro` at their declared markers. Because it patches the shared shells, the gift-cards agent runs in the build wave's **serialized shell chain** (one shell-patcher at a time — `BUILD-astro.md` § "Step 4.5"). The components outputs (`src/utils/gift-cards.ts`, `src/components/GiftCardPurchase.tsx`, `src/styles/components-gift-cards.css`) were written earlier in this same agent, so they're already on disk.
 
 ## Scope