@wix/agent-skills 1.6.0 → 1.8.0

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

@@ -0,0 +1,354 @@
+---
+name: page-designer
+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-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 (`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 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.
+
+**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` | 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 `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.
+
+**Disabled-pack route discipline.** Loaded packs with `disabled: true` (today: only `gift-cards`) ship dormant — their surfaces are runtime-gated and only appear once the user enables the matching app. Do NOT add hero CTAs, footer links, brand-story callouts, closing-CTA buttons, or ANY entry point pointing at a `disabled: true` pack's route in your page output. Users click through and the feature doesn't exist. The pack's own markers are the only acceptable touchpoint, and those get gated by the pack's runtime probe in Phase 4, not by you.
+
+---
+
+## 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 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.
+
+### Common rules for all page scopes
+
+1. **Use contract classes.** Every component that corresponds to a contract key uses that class name. Do not invent replacements.
+2. **Use the Layout.** Every page wraps content in `<Layout>`:
+   ```astro
+   ---
+   import Layout from '../layouts/Layout.astro';
+   ---
+   <Layout title="Page Title">
+     <!-- page content -->
+   </Layout>
+   ```
+3. **Never empty — render real data, fall back gracefully.** Bind the live SDK query into the designed structure. When a query legitimately returns empty (collection not seeded, OOS, etc.), render a brand-contextual fallback (plausible copy / a tasteful empty state) so the page still looks complete and reviewable — never a blank section.
+4. **SDK queries belong in the route frontmatter.** The merged `pages` scope imports the relevant SDK (`@wix/stores`, `@wix/data`, `@wix/blog`, …) in the route's frontmatter and queries live data — see the per-vertical reference under `references/astro/<vertical>/` for the exact queries. Wrap every SSR `await` in try/catch with a safe fallback (an unguarded SSR throw truncates Astro's response stream mid-body). Do **not** ship hardcoded arrays as the final page output.
+5. **No React islands authored here.** Do not write `.tsx` components — Phase 3 Components writes the islands. Phase 4 routes **mount** the already-written islands (`client:load`, etc.) but never author them.
+6. **Scoped page styles allowed.** Pages may add `<style>` blocks for page-specific ornamental styling (section backgrounds, decorative elements, page-specific spacing adjustments). These are local to the page — do not override contract class rules from `global.css`.
+7. **Image placeholders — decorative slot convention.** Every decorative image (hero, about visual, page-header art) MUST be emitted as a `<div>` placeholder carrying a `data-decorative-slot="<key>"` attribute. **Use ONLY canonical slot keys from this fixed vocabulary:**
+
+    | Key | Where it lives | Required when |
+    |---|---|---|
+    | `hero` | Homepage hero image | Always |
+    | `about` | About-page (or home brand-story) editorial visual | Always |
+    | `productsHeader` | `/products` listing header decorative | Stores pack loaded |
+    | `cmsHeader` | `/about` or `/faq` page header decorative | CMS pack loaded (optional) |
+
+    Do NOT invent keys like `aboutFeature`, `background`, `heroAlt`, etc. The image agent receives this canonical list as its `decorativeSlots` input and generates exactly those keys — invented keys will not have images, and orphan generated images go unused. If a page needs more visual interest, use scoped CSS / SVG / brand-color blocks instead of additional generated images. The orchestrator runs a post-Phase-2 Edit pass that injects the actual `<img>` for each slot once Image Phase 1 finishes; your job is to make the slot visible. Rules:
+    - Use aspect-ratio + background-color on the placeholder so the page looks complete even if Image Phase 1 never completes.
+    - Keep decorative overlays (stamps, rules, frames) as siblings of the slot `<div>` — the orchestrator injects the `<img>` as the FIRST child of the slot, so anything you want to layer over it must stay outside the slot `<div>` (or inside with explicit z-index).
+    - Do NOT conditionally read any image-coordination file — Image Phase 1's slot→URL map flows to the orchestrator via its JSON return, and the orchestrator injects URLs into your slot placeholders. The slot mechanism is the contract; no file lookup is needed or correct.
+    - Do not use external placeholder services (picsum, unsplash, etc.).
+
+    Example:
+    ```astro
+    <section class="hero-section relative">
+      <div
+        class="hero-image"
+        data-decorative-slot="hero"
+        style="aspect-ratio: 4/5; background-color: var(--color-paper-warm);"
+      >
+        <!-- orchestrator injects <img src={decorativeImages.hero} …> here -->
+      </div>
+      <div class="hero-stamp">{/* decorative overlay, stays outside the slot */}</div>
+    </section>
+    ```
+8. **Comments in frontmatter.** Use `//` or `/* */` — never HTML `<!-- -->` comments in `.astro` frontmatter (it's TypeScript, not HTML). HTML comments in the template section are fine.
+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 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`
+
+Composes the home page from every loaded pack's `homeSection` snippet plus brand-specific hero and CTA sections.
+
+**Inputs (additional):**
+- `Pack home-section snippets` — one per loaded pack. Each names a section (e.g., "Featured products", "Brand story", "Latest posts", "Contact CTA") with a description and contract classes.
+
+**Structure:**
+1. **Hero section** — full-width, impactful brand moment. Uses `hero-section` contract class. Emit a `data-decorative-slot="hero"` placeholder per Common rule #7 — do not inline an Image Phase 1 URL; the orchestrator injects the `<img>` after Image Phase 1 completes.
+2. **Pack sections** — one section per loaded pack's `homeSection`, in a sensible order (typically: featured content first, then story, then CTA).
+3. **Optional closing CTA** — if no pack contributes a CTA section, add a minimal brand-appropriate closing.
+
+**Files:** `src/pages/index.astro`
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-home",
+  "scope": "home",
+  "data": {
+    "pagesDesigned": ["src/pages/index.astro"],
+    "contractClassesHonored": ["hero-section", "product-grid", "product-card", "brand-story", ...]
+  },
+  "files": ["src/pages/index.astro"]
+}
+```
+
+### Scope: `static`
+
+About and FAQ pages — content pages with similar layout demands.
+
+**Files:** `src/pages/about.astro`, `src/pages/faq.astro`
+
+**About page:**
+- Hero/header section with `about-hero` class
+- Body content with `about-body` class
+- Placeholder brand story text (2-3 paragraphs, brand-contextual)
+- Image placeholder for brand/team visual
+
+**FAQ page:**
+- Section wrapper with `faq-section` class
+- Individual Q&A items with `faq-item`, `faq-question`, `faq-answer` classes
+- 4-6 placeholder FAQ items contextual to the business type
+- Accordion or expandable pattern (CSS-only, using `<details>`/`<summary>` or checkbox hack)
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-static",
+  "scope": "static",
+  "data": {
+    "pagesDesigned": ["about", "faq"],
+    "contractClassesHonored": ["about-hero", "about-body", "faq-section", "faq-item", "faq-question", "faq-answer"]
+  },
+  "files": ["src/pages/about.astro", "src/pages/faq.astro"]
+}
+```
+
+### Scope: `store-pages`
+
+All store-facing pages designed together for visual coherence.
+
+**Files:** `src/pages/products/index.astro`, `src/pages/products/[slug].astro`, `src/components/ProductCard.astro`, `src/pages/cart.astro`, `src/pages/thank-you.astro`
+
+**Products listing (`/products`):**
+- Page heading
+- Product grid using `product-grid` class
+- 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) resolved from the live product record
+- Product info section with `product-detail` 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 — the full Wix product object from `productsV3`
+- Uses `product-card` class
+- Image, name, price, link to `/products/${product.slug}`
+- 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
+- Items column with `.cart-items`, `.cart-item`, `.cart-item.unavailable` (reduced opacity), `.cart-item-image`, `.cart-item-info`, `.cart-item-name`, `.cart-item-option`, `.cart-item-modifiers` classes
+- Quantity selector with `.cart-item-qty`, `.qty-btn`, `.qty-value` classes — include `:disabled` states (reduced opacity + `cursor: not-allowed`)
+- Price display with `.cart-item-actions`, `.cart-item-prices`, `.cart-item-full-price` (strikethrough for discounts), `.cart-item-unit-price`, `.cart-item-line-total` classes
+- Remove button with `.cart-item-remove` class (muted color, underline on hover)
+- Summary column with `.cart-summary` (sticky on desktop), `.cart-subtotal`, `.checkout-btn` (with `:disabled` state), `.cart-empty` classes
+- 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
+- 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
+- Order details bound to the live order data (per the ecom cart/checkout reference)
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-store-pages",
+  "scope": "store-pages",
+  "data": {
+    "pagesDesigned": ["products/index.astro", "products/[slug].astro", "ProductCard.astro", "cart.astro", "thank-you.astro"],
+    "contractClassesHonored": <count>
+  },
+  "files": [
+    "src/pages/products/index.astro",
+    "src/pages/products/[slug].astro",
+    "src/components/ProductCard.astro",
+    "src/pages/cart.astro",
+    "src/pages/thank-you.astro"
+  ]
+}
+```
+
+### 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.
+
+**Files:** `src/pages/blog/index.astro`, `src/pages/blog/[slug].astro`
+
+**Blog listing (`/blog`):**
+- Page heading
+- Post grid/list using `blog-feed` class
+- 3 placeholder post cards using `blog-post-card` class (title, date, excerpt, cover image placeholder)
+
+**Blog post detail (`/blog/[slug]`):**
+- Post header with title, date, author, cover image placeholder
+- Body area with `blog-post` and `blog-post-body` classes
+- Meta section with `blog-post-meta` class (tags, share links)
+- Good reading typography (max-width prose container, comfortable line height)
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-blog-pages",
+  "scope": "blog-pages",
+  "data": {
+    "pagesDesigned": ["blog/index.astro", "blog/[slug].astro"],
+    "contractClassesHonored": ["blog-feed", "blog-post-card", "blog-post", "blog-post-body", "blog-post-meta"]
+  },
+  "files": ["src/pages/blog/index.astro", "src/pages/blog/[slug].astro"]
+}
+```
+
+### Scope: `contact-page`
+
+Contact page with form placeholder.
+
+**Files:** `src/pages/contact.astro`
+
+**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 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:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-contact-page",
+  "scope": "contact-page",
+  "data": {
+    "pagesDesigned": ["contact.astro"],
+    "contractClassesHonored": ["contact-cta"]
+  },
+  "files": ["src/pages/contact.astro"]
+}
+```
+
+---
+
+## Return Contract
+
+At the end of your work, emit a structured JSON block per `../../shared/RETURN_CONTRACT.md`. Do **not** write sidecar files to `.wix/logs/*`.
+
+The JSON block MUST be the **last** content in your message — the parent parses it as the last fenced JSON. No trailing prose after the closing ` ``` `.
+
+## Anti-Patterns (apply to all page scopes)
+
+| WRONG | CORRECT |
+|-------|---------|
+| Author a `.tsx` React island in a page scope | Phase 3 Components writes the islands; the route only **mounts** them (`client:load`) |
+| Ship hardcoded data arrays as the final page | Query live SDK data in frontmatter (per the vertical reference) and bind it; hardcoded shapes are only a fallback for empty queries |
+| Write `global.css` or `@theme` tokens | The Composer owns `global.css`; you consume the published token contract |
+| Invent global semantic classes for layout/spacing/typography (`.featured-section`, `.page-header`) | Use Tailwind utilities derived from `@theme` tokens at the call site (`<section class="py-4xl">`); see `../../shared/STYLING.md` |
+| Override `global.css` rules from page `<style>` blocks | Pages can add co-located styles for one-off decoration; never override Composer-owned global classes |
+| HTML `<!-- comment -->` in `.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript |
+| Use external placeholder image services (picsum, unsplash) | Use colored `<div>` placeholders with `data-decorative-slot` — the orchestrator injects Image Phase 1 URLs later |
+| Write `components-<pack>.css` | Phase 3 Components creates that file — page scopes must not write it |
+| Leave a section empty when a query returns nothing | Render a brand-contextual fallback / empty state so the page is always reviewable |
+| Use default Tailwind colors (`bg-blue-500`, `text-gray-200`) | Use brand `@theme` tokens (`bg-bark`, `text-cream`) — defaults expose that it's AI-generated |
+| 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 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 |
+| ProductCard with flat props (`name`, `price`, `slug` as separate props) | Single `product` object prop: `{ product }` — Phase 4 passes the full Wix product object |
+| Wrap CartBadge in `<a>` or add cart SVG icons in `nav-actions` | Leave `nav-actions` empty — CartBadge renders its own `<a>` link; nesting `<a>` tags produces duplicate icons |
+
+## Coordination with other agents
+
+| 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/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 |
+
+## File ownership
+
+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`, `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/{ecom → 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,
@@ -117,4 +116,4 @@ Cart page → "Proceed to Checkout"
   ],
   "errors": []
 }
-```
+```

package/skills/wix-headless/references/{ecom → 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
 
@@ -100,4 +100,4 @@ Contract keys: `cartBadge`, `cartBadgeCount`
   ],
   "errors": []
 }
-```
+```

package/skills/wix-headless/references/{ecom → 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
 
@@ -19,11 +19,11 @@ Exactly one file:
 
 You only need:
 
-1. **`<SKILL_ROOT>/templates/ecom/components-ecom.css`** — the canonical template. Read it once.
+1. **`<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css`** — the canonical template. Read it once.
 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.
 
@@ -32,7 +32,7 @@ You do NOT need to read `INSTRUCTIONS.md`, `CART_WIRING.md`, the TSX templates,
 ### 1. Read the template
 
 ```
-<SKILL_ROOT>/templates/ecom/components-ecom.css
+<SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css
 ```
 
 This is the canonical scoped CSS for the ecom pack. Adapt sizing/spacing to the brand's aesthetic — use the design tokens from your prompt (`--color-bark`, `--color-cream`, `--spacing-md`, `--font-display`, etc.). **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
@@ -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
 
@@ -129,4 +129,4 @@ If a leak was found and overridden, include `errors: [{code: "GLOBAL_CSS_LEAK",
 | `@apply btn-primary` on `.checkout-btn` | Tailwind v4 only `@apply`s `@utility` declarations, not plain CSS rules — build fails. Either repeat the properties manually or compose via `composes` |
 | Rename a class because the brand is "more elegant" with kebab variants | Class names are contract keys; renaming breaks every TSX import that references them |
 | Skip the leak audit | Skipping ships double-defined rules; the audit is < 5 s and prevents downstream visual regressions |
-| Drop the `@reference` directives | Tailwind v4 needs both — without them, `@apply size-6` and similar fail at build |
+| Drop the `@reference` directives | Tailwind v4 needs both — without them, `@apply size-6` and similar fail at build |

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

@@ -12,31 +12,28 @@ Build a complete form feature using `@wix/forms` — server-side schema fetching
 
 ## Prerequisites
 
-- Wix Forms app must be installed on the site (via MCP after scaffolding, or manually in Wix dashboard)
+- Wix Forms app must be installed on the site (installed via the apps-installer REST endpoint after scaffolding, or manually in the Wix dashboard)
 - `@wix/forms` package installed: `npm install @wix/forms`
 
-> **Forms are auto-created during scaffolding.** When scaffolding with a forms template (e.g., the Registration template `e5d63bf1-cd06-48eb-ad77-0da9235adcf1`), a form is automatically created on the site with server-side privileges. Use `forms.listForms("wix.form_app.form")` with `auth.elevate` to discover it — no manual form ID needed. If no forms exist, use the MCP-assisted Form Setup below to create one (the Create Form API is not available to headless SDK calls, but MCP credentials can create forms).
+> **Forms are auto-created during scaffolding.** When scaffolding with a forms template (e.g., the Registration template `e5d63bf1-cd06-48eb-ad77-0da9235adcf1`), a form is automatically created on the site with server-side privileges. Use `forms.listForms("wix.form_app.form")` with `auth.elevate` to discover it — no manual form ID needed. If no forms exist, use the REST API Form Setup below to create one (the Create Form API is not available to headless SDK calls, but the CLI-minted REST token can create forms).
 
-## Form Setup (MCP-Assisted)
+## Form Setup (REST)
 
-Before writing any form code, ensure a contact form exists on the site via MCP:
+Before writing any form code, ensure a contact form exists on the site via the form-schema REST API:
 
-1. **List forms** — `CallWixSiteAPI: GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form`
+1. **List forms** — `REST: GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form`
 2. **If the API returns a "missing installed app" error** → install the Wix Forms app:
    ```
-   CallWixSiteAPI: POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
+   REST: POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
    body: {
      "tenant": { "tenantType": "SITE", "id": "<siteId>" },
      "appInstance": { "appDefId": "225dd912-7dea-4738-8688-4b8c6955ffc2", "enabled": true }
    }
    ```
-   > Translate this prose-HTTP form into the full `CallWixSiteAPI` tool-call shape — include `siteId`, `reason`, `sourceDocUrl` wrapper fields and pass `body` as a real object (NOT a stringified JSON). See `../../shared/MCP_PREFIX.md` § "CallWixSiteAPI call conventions".
+   > 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.
 
@@ -125,9 +122,9 @@ Before writing any form code, ensure a contact form exists on the site via MCP:
    }
    ```
 
-   Full MCP call structure:
+   Full REST call structure:
    ```
-   CallWixSiteAPI: POST https://www.wixapis.com/form-schema-service/v4/forms
+   REST: POST https://www.wixapis.com/form-schema-service/v4/forms
    body: {
      "form": {
        "formFields": [ <selected fields from above> ],
@@ -162,7 +159,7 @@ Before writing any form code, ensure a contact form exists on the site via MCP:
    - PATCH using the procedure in step 5 below
 5. **If forms already exist** → verify the form has `postSubmissionTriggers.upsertContact`. This field is **critical** — without it, submissions are recorded but no Contact is created in the CRM. If missing, patch the form to add it:
    ```
-   CallWixSiteAPI: PATCH https://www.wixapis.com/form-schema-service/v4/forms/<formId>
+   REST: PATCH https://www.wixapis.com/form-schema-service/v4/forms/<formId>
    body: {
      "form": {
        "revision": "<current revision from GET>",
@@ -194,7 +191,7 @@ Before writing any form code, ensure a contact form exists on the site via MCP:
 
 ### 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
 
@@ -427,7 +424,7 @@ const wixForm = listResult.forms?.[0];
 const formId = wixForm?._id;
 ```
 
-If no forms exist, use the MCP-assisted Form Setup section above to create one via `CallWixSiteAPI`. If MCP is not available, create one in the Wix dashboard (Forms section → Add New Form).
+If no forms exist, use the REST API Form Setup section above to create one via `curl`. If curl auth is not available, create one in the Wix dashboard (Forms section → Add New Form).
 
 ## Form Field Schema (SDK Types)
 
@@ -458,20 +455,9 @@ 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 dev`
+1. Run `npx @wix/cli@latest dev`
 2. Navigate to `/contact`
 3. Fill in the form and submit
-4. Check the Wix dashboard → Forms → Submissions to verify the data arrived
+4. Check the Wix dashboard → Forms → Submissions to verify the data arrived