@wix/agent-skills 1.7.0 → 1.8.0

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`, `src/pages/manage-booking.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,28 @@ 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`, `src/pages/manage-booking.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`) — calendar slots use `time-slot` classes (`--available`/`--selected`/`--full`), form uses the `booking-form` family
+
+**Booking confirmation (`/booking-confirmation`):**
+- `max-w-prose`, centered; status-aware headline ("Thank you for booking" vs pending-approval) + embedded cancel (`ManageBooking` island, `showSummary={false}`)
+
+**Manage booking (`/manage-booking`):**
+- `container-reading`; booking summary + cancel via the `manage-booking` class family
+
 ### Scope: `blog-pages`
 
 Blog feed listing and post detail designed together.
@@ -265,7 +288,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 +330,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 +342,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 +351,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
 

package/skills/wix-headless/references/astro/stores/BACK_IN_STOCK.md

@@ -1,15 +1,17 @@
 # Phase 3 Components — Back in Stock (Stores)
 
-Split across the stores `components` scope (TSX/util files) and the `components-css` sibling (CSS rules). The matching Phase 4 wiring lives in `PRODUCT_PAGES.md` (SSR probe import + new props on `<ProductPurchase>`).
+The stores `components` scope writes the TSX/util files; the CSS rules ship in the **pre-copied** `components-stores.css` template (no agent authors them). The matching page wiring lives in `PRODUCT_PAGES.md` (SSR probe import + new props on `<ProductPurchase>`). Both the components and that page wiring run inside the **same stores merged build agent** (the build wave), components first.
 
 ## Scope
 
 Files written for back-in-stock, by scope:
 
 **`components` scope** (see `./SHARED_WIRING.md`):
-- `src/utils/back-in-stock.ts` — SSR-elevated probe of the Wix back-in-stock service, plus the canonical Stores app id constant
 - `src/components/BackInStockForm.tsx` — React island that posts via `@wix/ecom`'s `backInStockNotifications.createBackInStockNotificationRequest`
 
+**Pre-copied by the orchestrator** (do NOT author — same treatment as `categories.ts`):
+- `src/utils/back-in-stock.ts` — SSR-elevated probe of the Wix back-in-stock service, plus the canonical Stores app id constant. Pre-copied into the project in the build-wave pre-batch (BUILD-astro.md § "Step 4.5"). **Import** `getBackInStockEnabled`/the app-id constants from `../utils/back-in-stock`; never `Write` it yourself (racing the pre-copy trips the harness staleness guard).
+
 **`components-css` scope** (see `./COMPONENTS_CSS.md`):
 - `src/styles/components-stores.css` — appends the back-in-stock form CSS rules at the end of the file (see § 3 below)
 
@@ -45,9 +47,9 @@ This scope uses **template files** instead of inline code. For each file below:
 
 Do NOT modify logic, imports, the bare-fields request shape, or the app-id constants.
 
-### 1. `src/utils/back-in-stock.ts`
+### 1. `src/utils/back-in-stock.ts` — pre-copied, not owned by this scope
 
-Use template `templates/back-in-stock.ts`.
+> Pre-copied by the orchestrator in the build-wave pre-batch (BUILD-astro.md § "Step 4.5") — same treatment as `categories.ts`. **Import** from `../utils/back-in-stock`; do NOT write it yourself. The exports below are documented here so callers (the form island, the `[slug].astro` probe) know the surface.
 
 Exports:
 - `WIX_STORES_BACK_IN_STOCK_APP_ID` — string constant. Use this for the `catalogReference.appId` in the form.
@@ -150,7 +152,6 @@ The full components scope return must mention back-in-stock:
   "summary": "Wrote stores islands, scoped CSS, back-in-stock probe + form",
   "data": {
     "islands": ["ProductPurchase.tsx", "AddToCartButton.tsx", "BackInStockForm.tsx"],
-    "utils": ["back-in-stock.ts"],
     "scopedCssFile": "src/styles/components-stores.css",
     "backInStockWired": true
   },
@@ -159,7 +160,6 @@ The full components scope return must mention back-in-stock:
     "src/components/AddToCartButton.tsx",
     "src/components/ProductPurchase.tsx",
     "src/components/BackInStockForm.tsx",
-    "src/utils/back-in-stock.ts",
     "src/styles/components-stores.css"
   ],
   "errors": []

package/skills/wix-headless/references/astro/stores/CATEGORY_PAGES.md

@@ -1,8 +1,8 @@
 # Phase 4 Category Pages — Stores
 
-Scope: `pages-categories`. Launched in **Step 7** alongside `pages-products` and `pages-home-and-nav`. This scope writes the dedicated category landing route and the shared `<CategoryRail/>`. The `categories.ts` helper that all three scopes import is **pre-copied by the orchestrator before this phase** (BUILD.md Step 7 pre-batch) — do NOT write it here.
+Scope: `pages-categories` — written by the stores **merged build agent** (the build wave) *before* its `pages-products` scope, so `<CategoryRail/>` is on disk before that scope mounts it. This scope writes the dedicated category landing route and the shared `<CategoryRail/>`. The `categories.ts` helper is **pre-copied by the orchestrator in the build-wave pre-batch** (BUILD-astro.md § "Step 4.5") — do NOT write it here.
 
-**Dispatch:** all three stores Phase-4 scopes are dispatched in parallel — Astro resolves the cross-file imports at build time (Step 8). The orchestrator does not need to serialize them. Each scope only needs its own declared files to exist by the time `astro build` runs; `categories.ts` is already on disk from the pre-batch.
+**Within-agent order:** the merged stores agent writes `components` → `pages-categories` (this scope) → `pages-products`. `pages-home-and-nav` is a *separate* serialized agent (it patches the shared shells) and resolves `<CategoryRail/>` at build time (Step 8). Each scope only needs its own declared files to exist by the time `astro build` runs.
 
 ## Scope
 
@@ -23,7 +23,7 @@ Files this agent MUST NOT touch:
 ## Inputs (from parent prompt)
 
 - **Phase 1 return data** — `categories: []`. Phase 1 does not seed categories (they're merchant-driven). This scope still writes the helper + rail + route — they're harmless when no categories exist, and they light up automatically once the merchant creates visible categories with items in the dashboard. `listStoreCategories()` queries the API live at SSR time (5-min TTL cache), so no redeploy is needed when categories are added later.
-- **Design tokens** — the full `designTokens` JSON is inlined in your prompt (same shape Designer returned). Page header / breadcrumbs / pill / pagination styling should follow `references/shared/STYLING.md` (utilities derived from tokens, semantic classes only for primitives).
+- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk). Page header / breadcrumbs / pill / pagination styling should follow `references/shared/STYLING.md` (utilities derived from tokens, semantic classes only for primitives).
 - **Designer output summary** — confirm `Layout.astro` already includes `<ClientRouter />`, `transition:persist` markers on nav/footer, and the `[data-nav-progress]` element + after-swap hook. If any of those is missing, return `status: "partial"` with `errors: [{ code: "DESIGNER_LAYOUT_MISSING_TRANSITIONS", path: "src/layouts/Layout.astro" }]`.
 
 ## Critical rules (all must be honored)
@@ -40,7 +40,7 @@ Files this agent MUST NOT touch:
 
 ## Writing the templates
 
-Read each template at `templates/stores/` and write it verbatim to the corresponding `src/` path, with three small adjustments. (`categories.ts` is **not** in this list — the orchestrator pre-copies it; you only import its helpers.)
+Read each template at `references/astro/templates/stores/` and write it verbatim to the corresponding `src/` path, with three small adjustments. (`categories.ts` is **not** in this list — the orchestrator pre-copies it; you only import its helpers.)
 
 | Template path | Site path |
 |---|---|

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

@@ -1,6 +1,6 @@
 # Phase 3 Components-CSS — Stores
 
-Sibling of the `components` scope. Launched in **Step 4.5** in the same concurrent batch — runs in parallel with the TSX/Astro work, ecom and 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 stores `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 stores-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`, `SHARED_WIRING.md`, `BACK_IN_STOCK.md`, the TSX templates, the back-in-stock util, or any other reference. Skipping those reads is the point of the split — they would consume tokens for context this scope doesn't use.
 
@@ -86,7 +86,7 @@ Write the adapted CSS to `src/styles/components-stores.css`. The first line must
 
 ## 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/stores/HOME_AND_NAV.md

@@ -1,8 +1,8 @@
 # Phase 4 Home Page + Nav — Stores
 
-Scope: `pages-home-and-nav`. Launched in **Step 7**; imports the orchestrator-pre-copied `categories.ts` helper (and the rail `pages-categories` writes — resolved at build time). Patches the home page's stores-related placeholder data with live `productsV3` queries AND inserts the Shop submenu (categories list) into the persisted Navigation.
+Scope: `pages-home-and-nav` — dispatched as its **own serialized shell-patcher agent** in the build wave (NOT merged into the stores private-files agent, because it patches the shared shells). Imports the orchestrator-pre-copied `categories.ts` helper and the `CategoryRail`/`ProductCard` the stores private agent writes — **resolved at build time, so no write-ordering against that agent.** Patches the home page's stores-related placeholder data with live `productsV3` queries AND inserts the Shop submenu (categories list) into the persisted Navigation at the `<!-- nav:links -->` marker. (The `CartBadge` mount at `<!-- nav:actions -->` is ecom's; you own only `<!-- nav:links -->`.) Read your seeded slice from `.wix/seeded.json` (`seeded.stores`).
 
-> **You patch the shared `Navigation.astro` + `index.astro` shells**, which other packs (e.g. gift-cards) also patch at their own markers. **Touch only your markers and preserve every other scope's siblings — never rewrite either file.** (Flow is the conductor's job: it serializes shell-patching scopes so concurrent marker edits don't collide — BUILD.md Step 7.)
+> **You patch the shared `Navigation.astro` + `index.astro` shells**, which other packs (ecom at `nav:actions`, gift-cards, blog) also patch at their own markers. **Touch only your markers and preserve every other scope's siblings — never rewrite either file.** (Flow is the conductor's job: it serializes the shell-patching agents so concurrent marker edits don't collide — BUILD-astro.md § "Step 4.5", the serialized shell chain.)
 
 ## Scope
 
@@ -21,7 +21,7 @@ Files this agent MUST NOT touch:
 ## Inputs (from parent prompt)
 
 - **Phase 1 stores return** — `products: [{id, name, slug, ...}]`. Needed for live query on home page; also useful for deciding how many to feature.
-- **Design tokens** — the full `designTokens` JSON is inlined in your prompt for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens at the call site rather than inventing semantic classes. See `references/shared/STYLING.md` for the three styling categories.
+- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens at the call site rather than inventing semantic classes. See `references/shared/STYLING.md` for the three styling categories.
 - **Designer output summary** — path of `src/pages/index.astro` and `src/components/Navigation.astro`, with notes on what placeholder data exists.
 - **Categories (lookup)** — if the designer used category links with hardcoded slugs, call `categoriesV3` SDK to discover real category slugs and rewrite `href`s.