@wix/agent-skills 1.0.0

package/skills/wix-headless/references/verticals/cms.md

@@ -0,0 +1,121 @@
+---
+name: cms
+triggers: []                          # not trigger-based — always loaded
+description: "Content pages — About + FAQ managed via Wix CMS"
+
+features:
+  - name: "About (CMS-based)"
+    description: "Tell your brand story with images and rich text. Editable from the Wix dashboard's Content Manager."
+  - name: "FAQ (CMS-based)"
+    description: "Common questions and answers about your products. Managed from the dashboard's Content Manager."
+
+apps: []                              # CMS is built-in, no app install
+
+packages:
+  - "@wix/data"
+  - "@wix/wix-data-items-sdk"   # provides the `items` namespace (query/insert/etc.). @wix/data 1.0.448 stopped re-exporting it; pages import from here directly. See references/cms/CMS_FOUNDATIONS.md.
+  - "@wix/essentials"
+
+routes:
+  - route: "/"
+  - route: "/about"
+  - route: "/faq"
+
+cmsCollections:
+  - name: "about-content"
+    fields:
+      - { name: "heading", type: "string", required: true }
+      - { name: "body", type: "rich-text", required: true }
+      - { name: "image", type: "image", required: false }
+  - name: "faq"
+    fields:
+      - { name: "question", type: "string", required: true }
+      - { name: "answer", type: "rich-text", required: true }
+      - { name: "sortOrder", type: "number", required: true }
+
+seed:
+  agentLocation: "references/cms/"
+  scope: "seed"
+  description: "Create about-content + faq collections, seed 1 about-content item and 4–6 contextual FAQ items based on the business type"
+  references: ["references/cms/CMS_FOUNDATIONS.md"]
+
+# CMS has no "components" — page designers write CMS-reading pages directly using
+# @wix/data queries inline. So the only post-design work is the pages scope below.
+components: null
+
+pages:
+  - name: "cms-pages"
+    agentLocation: "references/cms/"
+    scope: "pages"
+    description: "Swap placeholder copy in About + FAQ pages for live @wix/data queries"
+    references: ["references/cms/CMS_FOUNDATIONS.md"]
+    files:
+      - "src/pages/about.astro"
+      - "src/pages/faq.astro"
+
+creates:
+  - { file: src/pages/about.astro, phase: pages }
+  - { file: src/pages/faq.astro,   phase: pages }
+
+# CMS does NOT contribute to the home page. The designer owns the brand-story
+# section directly (writes its own placeholder heading/paragraph). Historically
+# this pack declared a home:cms marker but no phase patched it, so the
+# designer's placeholder copy shipped as-is to preview. Dropping the marker
+# makes that behavior explicit.
+contributes: []
+
+include: true   # always loaded — every site gets About + FAQ content pages
+disabled: false
+---
+
+# CMS Pack
+
+Always loaded. Provides content pages (Home, About, FAQ) editable from the Wix dashboard's Content Manager.
+
+## Why always-include
+
+Every site needs About and FAQ content. The CMS collections give the user a dashboard-editable surface, so non-technical owners can update copy without touching code.
+
+## Pages
+
+- **Home** (`/`) — designed by `designer-home`. The designer writes the brand-story section directly (no CMS-driven home contribution; see `contributes: []` in frontmatter above for why).
+- **About** (`/about`) — content from `about-content` CMS collection
+- **FAQ** (`/faq`) — content from `faq` CMS collection
+
+## Phase 1
+
+One agent creates both collections and seeds them:
+- `about-content` — one item (heading, body, optional image) with placeholder copy based on business context
+- `faq` — 4–6 items tailored to the business type (e.g., shipping, returns, sizing, care instructions)
+
+The agent tailors FAQ content to the vertical. For stores: shipping/returns/sizing. For future verticals: different sets.
+
+## Phase 2 pattern
+
+About and FAQ pages read their CMS content inline via `@wix/data`:
+
+```astro
+---
+import * as items from "@wix/wix-data-items-sdk";
+const faqs = await items
+  .query("faq")
+  .ascending("sortOrder")
+  .find()
+  .then(r => r.items);
+---
+```
+
+> **Why not `import { items } from "@wix/data"`?** That's the documented Wix headless pattern but `@wix/data` 1.0.448 dropped the `items` re-export — only sub-namespaces (`backups`, `collections`, `permissions`, …) remain, and the documented form fails the build with `'items' is not exported by '@wix/data'`. The actual `items` API lives in `@wix/wix-data-items-sdk` (which `@wix/data` depends on transitively). Importing from there directly works on every current `@wix/data` version.
+
+No React islands required for static content pages — they SSR from data.
+
+## Contract
+
+This pack contributes contract keys for content-page class names. Other packs do not typically overlap with these keys.
+
+The home page's `heroSection` and `brandStory` keys are consumed by `designer-home`, which composes the home page from every loaded pack's `homeSection` snippet.
+
+## References
+
+- `references/cms/CMS_FOUNDATIONS.md` — existing CMS reference (data seeding + page wiring)
+- `references/cms/FAQ_KNOWLEDGE_BASE.md` — FAQ patterns

package/skills/wix-headless/references/verticals/ecom.md

@@ -0,0 +1,96 @@
+---
+name: ecom
+triggers: []  # Never triggered independently — co-loaded by packs that require it (stores, bookings, etc.)
+description: "Vertical-agnostic ecommerce: cart page, checkout redirect, order confirmation"
+
+features:
+  - name: "Cart & checkout"
+    description: "Add items to cart, review order, check out via Wix's secure hosted checkout. Order confirmation on thank-you page."
+
+apps: []  # No app to install — @wix/ecom works with any installed catalog app
+
+packages:
+  - "@wix/ecom"
+  - "@wix/redirects"
+  - "@wix/site"
+  - "@wix/essentials"  # auth.elevate() in src/utils/discounts.ts — ECOM.DISCOUNT_RULES_READ
+
+routes:
+  - route: "/cart"
+  - route: "/thank-you"
+  - route: "Hosted by Wix"   # Wix-hosted endpoint — no .astro file. Listed so the discovery plan's Section C table includes a Checkout row (omitting it created user anxiety in the 2026 dolls-store run; the cart appeared to "go nowhere"). The route cell renders the literal string "Hosted by Wix".
+    name: "Checkout"
+
+cmsCollections: []
+
+seed: null  # No data seeding — ecom has no data of its own
+
+components:
+  agentLocation: "references/ecom/"
+  scope: "components"
+  description: "Cart/checkout React islands. CSS is split into the sibling componentsCss scope."
+  references: ["references/ecom/CART_WIRING.md"]
+  files:
+    - "src/components/CartView.tsx"
+    - "src/components/CartBadge.tsx"
+    - "src/utils/discounts.ts"
+
+componentsCss:
+  agentLocation: "references/ecom/"
+  scope: "components-css"
+  description: "Scoped ecom CSS — components-ecom.css. Runs in parallel with the components scope; reads design tokens + global.css (for leak audit) but no SDK templates. Independent of TSX work because TSX/CSS link is build-time via class names."
+  references:
+    - "references/ecom/COMPONENTS_CSS.md"
+  files:
+    - "src/styles/components-ecom.css"
+
+pages:
+  - name: "ecom-pages"
+    agentLocation: "references/ecom/"
+    scope: "pages"
+    description: "Mount CartView on cart.astro, wire thank-you.astro, mount CartBadge in Navigation"
+    references: ["references/ecom/CART_PAGES.md"]
+    files:
+      - "src/pages/cart.astro"
+      - "src/pages/thank-you.astro"
+      - "src/components/Navigation.astro (patch — CartBadge mount only)"
+
+creates:
+  - { file: src/components/CartView.tsx,      phase: components }
+  - { file: src/components/CartBadge.tsx,     phase: components }
+  - { file: src/styles/components-ecom.css,   phase: components }
+  - { file: src/utils/discounts.ts,           phase: components }
+  - { file: src/pages/cart.astro,             phase: pages }
+  - { file: src/pages/thank-you.astro,        phase: pages }
+
+contributes:
+  - file: src/components/Navigation.astro
+    marker: "<!-- nav:actions -->"
+    description: "CartBadge mount point in the nav actions area"
+
+include: false
+disabled: false
+---
+
+# Ecom Pack
+
+Vertical-agnostic ecommerce cart, checkout, and order confirmation. Co-loaded by any pack that needs cart/checkout (stores, bookings, events) via the `requires` field.
+
+## Why separate from stores
+
+The cart page works with any catalog provider — `@wix/ecom`'s `currentCart` API returns line items with all the display data (name, image, options, availability, price) regardless of which app added the item. CartView, CartBadge, and the checkout flow have zero dependency on `@wix/stores`.
+
+Separating ecom from stores:
+- Enables future verticals (bookings, events) to reuse cart/checkout without pulling in the stores agent
+- Clarifies ownership boundaries — stores owns the catalog, ecom owns the purchase flow
+- Reduces the stores agent's scope and context window usage
+
+## Cross-agent event contract
+
+`cart-updated` CustomEvent on `window`:
+- **Dispatchers:** AddToCartButton (stores), CartView (ecom)
+- **Listener:** CartBadge (ecom)
+
+## Template files
+
+The `ecom-shared` scope uses real template files at `templates/ecom/` instead of inline markdown code. The agent reads each template, adapts CSS class names to the styling contract, and writes to the project. This reduces markdown size and ensures the agent copies proven code rather than improvising.

package/skills/wix-headless/references/verticals/forms.md

@@ -0,0 +1,106 @@
+---
+name: forms
+triggers: ["contact form", "lead form", "signup form", "waitlist", "registration", "get in touch", "inquiry", "feedback"]
+description: "Forms — contact, lead capture, or newsletter signup with CRM integration"
+
+features:
+  - name: "Contact form"
+    description: "Dynamic form powered by @wix/forms with server-side schema discovery and client-side submission. Submissions create CRM contacts automatically."
+
+apps:
+  - name: "Wix Forms"
+    appDefId: "225dd912-7dea-4738-8688-4b8c6955ffc2"
+
+packages:
+  - "@wix/forms"
+  - "@wix/essentials"
+
+routes:
+  - route: "/contact"
+
+cmsCollections: []
+
+seed:
+  agentLocation: "references/forms/"
+  scope: "seed"
+  description: "Install Forms app, create form with fields matching business purpose, PATCH postSubmissionTriggers for CRM contact creation"
+  references: ["references/forms/CONTACT_FORM.md"]
+
+components:
+  agentLocation: "references/forms/"
+  scope: "components"
+  description: "ContactForm.tsx React island for client-side form submission with dynamic field rendering and validation"
+  references: ["references/forms/CONTACT_FORM.md"]
+  files:
+    - "src/components/ContactForm.tsx"
+
+pages:
+  - name: "contact-page"
+    agentLocation: "references/forms/"
+    scope: "pages"
+    description: "Wire designed contact.astro page to @wix/forms SDK — add form discovery query, replace placeholder with ContactForm island, migrate styles"
+    references: ["references/forms/CONTACT_FORM.md"]
+    files:
+      - "src/pages/contact.astro"
+
+creates:
+  - { file: src/components/ContactForm.tsx, phase: components }
+  - { file: src/pages/contact.astro,        phase: pages }
+
+contributes:
+  - file: src/pages/index.astro
+    marker: "<!-- home:forms -->"
+    description: "Contact CTA (heading + one-liner + button linking to /contact)"
+  - file: src/components/Navigation.astro
+    marker: "<!-- nav:links -->"
+    description: "Contact menu link → /contact"
+
+include: false
+disabled: false
+---
+
+# Forms Pack
+
+Contact, lead capture, and signup forms with CRM integration. Loaded when the user's prompt mentions forms, contact pages, inquiries, or signups.
+
+## Phase decomposition
+
+| Scope | Phase | Files | Depends on |
+|-------|-------|-------|------------|
+| `seed` | Phase 1 — Step 3 (bg) | None (MCP only) | MCP connection |
+| `components` | Phase 3 — Step 4.5 (bg) | ContactForm.tsx | Styling contract |
+| `contact-page` | Phase 4 — Step 7 (bg) | contact.astro | Phase 2 Design System + Phase 1 Seed formId |
+
+All three scopes reference the same `CONTACT_FORM.md` file — it covers MCP form setup, React island implementation, and page wiring in one document. The agent's scope parameter guides it to the correct section.
+
+## Known failure modes (propagate to agent prompts)
+
+| Wrong | Right |
+|-------|-------|
+| Skip `postSubmissionTriggers` PATCH after form creation | Always PATCH — the POST silently drops triggers; without them, submissions are silently lost (no CRM Contact created) |
+| Include triggers in POST body and assume it worked | POST silently drops `postSubmissionTriggers` — always follow up with PATCH |
+| Fall back to hardcoded fields on `UNSUPPORTED_FORM_NAMESPACE` | Wait 10s and retry up to 3 times — namespace propagation delay after Forms app install |
+| Skip `auth.elevate` when listing forms | `listForms` requires elevated permissions |
+| Submit forms from server-side code | Form submission must happen client-side (React island with `client:load`) |
+| Replace `.astro` placeholder without migrating styles | Copy the placeholder's `<style is:global>` block to the page — styles vanish when the Astro import is replaced with React |
+| Detect textarea by `componentType === "TEXT_AREA"` | Check `identifier === "TEXT_AREA"` or `target === "message"` — the API rejects `TEXT_AREA` as a componentType value |
+| Hardcode form field IDs or form ID | Use `forms.listForms("wix.form_app.form")` with `auth.elevate` for runtime discovery |
+
+## Form purpose variants
+
+The forms agent adapts field selection based on the business purpose from the functional plan:
+
+| Purpose | Fields | Layout |
+|---------|--------|--------|
+| Waitlist / newsletter | EMAIL + SUBMIT | Single column |
+| Lead capture | FIRST_NAME + EMAIL + SUBMIT | Single column |
+| Contact (full) | FIRST_NAME + LAST_NAME + EMAIL + PHONE + MESSAGE + SUBMIT | First+last side-by-side, rest stacked |
+| Registration | FIRST_NAME + LAST_NAME + EMAIL + custom | Single column |
+
+## Images
+
+Forms has no entity images. The contact page gets decorative images via `image-phase-1-decorative` if the image agent is running.
+
+## References
+
+- `references/forms/CONTACT_FORM.md` — All phases: MCP form setup, field building blocks, React island, page wiring, form schema types

package/skills/wix-headless/references/verticals/gift-cards.md

@@ -0,0 +1,121 @@
+---
+name: gift-cards
+triggers: []  # Never triggered independently — co-loaded by packs that include a storefront (stores) via the `requires` field
+description: "Conditional gift-card buy page + nav/home contributions. Detects the Wix Gift Card app at runtime; renders only when installed."
+requires: ["ecom"]  # buy flow uses currentCart.addToCurrentCart
+
+features:
+  - name: "Gift cards (when enabled in dashboard)"
+    description: "Customers buy preset-amount gift cards on a dedicated page. Wix issues redeemable codes after payment and emails the recipient. The page, nav link, and home teaser only appear once the Wix Gift Card app is enabled in the dashboard — no rebuild needed."
+
+apps: []  # do NOT auto-install; the user opts in via Catalog → Gift Cards in the dashboard
+
+packages:
+  - "@wix/ecom"        # currentCart.addToCurrentCart
+  - "@wix/essentials"  # httpClient.fetchWithAuth (REST probe)
+
+routes:
+  - route: "/gift-cards"
+
+cmsCollections: []
+
+seed: null  # the dashboard's eGift Card template is the source of truth — never seed denominations from code
+
+components:
+  agentLocation: "references/gift-cards/"
+  scope: "components"
+  description: "Runtime probe util + GiftCardPurchase React island + scoped CSS"
+  references: ["references/gift-cards/COMPONENTS.md"]
+  files:
+    - "src/utils/gift-cards.ts"
+    - "src/components/GiftCardPurchase.tsx"
+    - "src/styles/components-gift-cards.css"
+
+pages:
+  - name: "gift-cards-pages"
+    agentLocation: "references/gift-cards/"
+    scope: "pages"
+    description: "Write /gift-cards landing page (redirects when app is disabled), patch nav link + home teaser via markers"
+    references: ["references/gift-cards/PAGES.md"]
+    files:
+      - "src/pages/gift-cards.astro"
+      - "src/components/Navigation.astro (patch — gift-cards link)"
+      - "src/pages/index.astro (patch — gift-cards teaser)"
+
+creates:
+  - { file: src/utils/gift-cards.ts,            phase: components }
+  - { file: src/components/GiftCardPurchase.tsx, phase: components }
+  - { file: src/styles/components-gift-cards.css, phase: components }
+  - { file: src/pages/gift-cards.astro,         phase: pages }
+
+contributes:
+  - file: src/components/Navigation.astro
+    marker: "<!-- nav:links -->"
+    description: "Gift Cards link → /gift-cards (rendered only when getGiftCardProduct() returns non-null)"
+  - file: src/pages/index.astro
+    marker: "<!-- home:gift-cards -->"
+    description: "Home teaser block (image + lede + CTA), gated on getGiftCardProduct() so it disappears when the app is disabled"
+
+include: false
+
+# disabled: true → the pack ships its code (page file, nav/home contributions),
+# but its surfaces are inactive by default. They light up only when the user
+# enables the matching app from the Wix dashboard, which the runtime probe in
+# `gift-cards.ts` detects per request. DISCOVERY.md plan composition (Sections
+# B + C) skips features and routes from disabled packs so the plan never
+# promises a surface the user did not opt into.
+disabled: true
+---
+
+# Gift Cards Pack
+
+Passive vertical: code ships in every site that has a storefront, but every gift-card surface (page, nav link, home teaser) only renders if the **Wix Gift Card app** is enabled in the site's dashboard. A runtime REST probe per request decides — no build-time install, no seeding, no rebuild needed when the app state flips.
+
+## Why passive
+
+The dashboard's Catalog → Gift Cards screen owns the eGift Card template (denominations, image, copy). We never seed it. We never install the app via MCP. Instead:
+
+1. The site owner enables the Wix Gift Card app from their dashboard whenever they want.
+2. On every request, `getGiftCardProduct()` probes `POST /gift-cards/v1/gift-card-products/query` and memoizes the result for the request.
+3. If the probe returns a product → page renders, nav link shows, home teaser shows. If the probe returns null (app uninstalled, revoked, or the dashboard template not configured) → all three surfaces hide. The page redirects to `/`.
+
+This keeps gift cards as a "lights-up-when-ready" feature rather than a build-time commitment.
+
+## Co-load semantics
+
+This pack is **never user-triggered**. It loads when another pack pulls it in via `requires`. Today the storefront-bearing pack (`stores`) is the only puller; future commerce packs (bookings, events) can opt in the same way.
+
+If a user builds a pure-blog or pure-forms site, this pack does not load — no gift-card code ships, no `/gift-cards` route, no markers requested from the designer.
+
+## Wix Gift Card app reference data
+
+- **App ID** (`WIX_GIFT_CARDS_APP_ID`): `d80111c5-a0f4-47a8-b63a-65b54d774a27`. Captured from a real paid Wix-Editor order line item — not in the public "Apps Created by Wix" registry. Treat as stable; if Wix rotates it, both the runtime probe and buy flow break together (failure mode is identical to "app uninstalled" — page hides gracefully).
+- **Probe endpoint**: `POST https://www.wixapis.com/gift-cards/v1/gift-card-products/query`. The auto-package `@wix/auto_sdk_ecom_gift-vouchers` exposes only redemption methods; the buy template is reachable only via REST.
+- **Buy-flow `catalogReference` shape** (passed to `currentCart.addToCurrentCart`):
+  ```ts
+  {
+    appId: WIX_GIFT_CARDS_APP_ID,
+    catalogItemId: <giftCardProduct.id>,
+    options: {
+      variantId: <selected preset variantId>,
+      quantity: 1,
+      giftingInfo: {
+        recipientInfo: { email, firstName, lastName },
+        greetingMessage,
+      },
+      wixGiftCardsAppNewCatalog: true,
+    },
+  }
+  ```
+- **Post-payment**: on `ORDER_PAID`, Wix's gift-card backend auto-issues a redeemable card with `source: "ORDER"` and emails the recipient. No webhook, no admin scope, no follow-up call required.
+
+## Stores-vertical interaction
+
+When the Wix Gift Card app is enabled, it auto-creates **5 mirror Stores products** (one per denomination, `productType: "DIGITAL"`, ribbon name `"Gift Card"`). They appear in standard product queries and would compete with our `/gift-cards` page (a customer buying the mirror gets a dud DIGITAL line item that does not trigger gift-card issuance).
+
+The `stores` pack drops them in its product queries via `productList.filter(p => p.ribbon?.name !== "Gift Card")`. That filter is owned by stores (not gift-cards) so it protects the listing regardless of whether the gift-cards pack is loaded — a future site that drops gift-cards but still has the dashboard app would still hide the mirrors. See `references/stores/PRODUCT_PAGES.md` § "Gift-card mirror filter".
+
+## References
+
+- `references/gift-cards/COMPONENTS.md` — runtime probe util + React island
+- `references/gift-cards/PAGES.md` — landing page + nav/home contributions

package/skills/wix-headless/references/verticals/stores.md

@@ -0,0 +1,167 @@
+---
+name: stores
+triggers: ["sell", "ecommerce", "store", "shop", "products", "merchandise", "catalog", "merch", "buy"]
+description: "Ecommerce — product catalog with add-to-cart. Requires ecom pack for cart/checkout."
+requires: ["ecom", "gift-cards"]  # ecom = vertical-agnostic cart/checkout; gift-cards = passive pack that lights up when the dashboard's Wix Gift Card app is enabled
+
+features:
+  - name: "Product catalog"
+    description: "Browse all products with images, prices, and variants. Click through to detailed product pages with add-to-cart."
+
+apps:
+  - name: "Wix Stores"
+    appDefId: "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+
+packages:
+  - "@wix/stores"
+  - "@wix/ecom"
+
+routes:
+  - route: "/products"
+  - route: "/products/[slug]"
+    name: "Product Detail"   # path-derivation would produce "Products [slug]" — override with the user-facing label
+  - route: "/category/[slug]"
+    name: "Category"         # SEO-friendly per-category landing — server-side filtered, cursor-paginated
+
+cmsCollections: []
+
+seed:
+  agentLocation: "references/stores/"
+  scope: "seed"
+  description: "Delete default sample products (Wix Stores ships 12) and create 3 on-brand products with variants/prices/inventory. Does NOT seed categories — those are merchant-driven; the storefront wires the rail/submenu/route in Phase 4 and lights up automatically when the merchant creates categories in the dashboard."
+  references: ["references/stores/PRODUCT_CATALOG_DATA.md"]
+
+components:
+  agentLocation: "references/stores/"
+  scope: "components"
+  description: "SDK wiring that depends only on the styling contract, not on designed page markup. Writes React/Astro islands and the back-in-stock util. CSS is split into the sibling componentsCss scope."
+  references:
+    - "references/stores/SHARED_WIRING.md"
+    - "references/stores/BACK_IN_STOCK.md"
+  files:
+    - "src/components/SeoTags.astro"
+    - "src/components/AddToCartButton.tsx"
+    - "src/components/ProductPurchase.tsx"
+    - "src/components/BackInStockForm.tsx"
+    - "src/utils/back-in-stock.ts"
+
+componentsCss:
+  agentLocation: "references/stores/"
+  scope: "components-css"
+  description: "Scoped stores CSS — components-stores.css. Runs in parallel with the components scope; reads design tokens + global.css (for leak audit) but no SDK templates. Independent of TSX work because TSX/CSS link is build-time via class names."
+  references:
+    - "references/stores/COMPONENTS_CSS.md"
+    - "references/stores/BACK_IN_STOCK.md"  # § 3 — back-in-stock form CSS rules to append
+  files:
+    - "src/styles/components-stores.css"
+
+pages:
+  - name: "product-pages"
+    agentLocation: "references/stores/"
+    scope: "pages-products"
+    description: "Swap placeholder data in products listing + detail for live productsV3 queries with cursor pagination; mount the shared <CategoryRail/>; register wixMetadata + SeoTags on detail page"
+    references: ["references/stores/PRODUCT_PAGES.md"]
+    files:
+      - "src/pages/products/index.astro"
+      - "src/pages/products/[slug].astro"
+      - "src/components/ProductCard.astro"
+
+  - name: "category-pages"
+    agentLocation: "references/stores/"
+    scope: "pages-categories"
+    description: "Server-side filtered /category/[slug] listing (cursor-paginated). Writes shared CategoryRail and the categories.ts helper; both are imported by pages-products as well."
+    references: ["references/stores/CATEGORY_PAGES.md"]
+    files:
+      - "src/pages/category/[slug].astro"
+      - "src/components/CategoryRail.astro"
+      - "src/utils/categories.ts"
+
+  - name: "home-and-nav"
+    agentLocation: "references/stores/"
+    scope: "pages-home-and-nav"
+    description: "Patch home page featured products to live query and contribute the Shop submenu (categories list) to Navigation"
+    references: ["references/stores/HOME_AND_NAV.md"]
+    files:
+      - "src/pages/index.astro (patch — home product grid only)"
+      - "src/components/Navigation.astro (patch — Shop submenu insert)"
+
+creates:
+  - { file: src/components/AddToCartButton.tsx,  phase: components }
+  - { file: src/components/ProductPurchase.tsx,  phase: components }
+  - { file: src/components/BackInStockForm.tsx,  phase: components }
+  - { file: src/components/SeoTags.astro,        phase: components }
+  - { file: src/utils/back-in-stock.ts,          phase: components }
+  - { file: src/styles/components-stores.css,    phase: components }
+  - { file: src/pages/products/index.astro,      phase: pages }
+  - { file: src/pages/products/[slug].astro,     phase: pages }
+  - { file: src/components/ProductCard.astro,    phase: pages }
+  - { file: src/pages/category/[slug].astro,     phase: pages }
+  - { file: src/components/CategoryRail.astro,   phase: pages }
+  - { file: src/utils/categories.ts,             phase: pages }
+
+# Files this vertical contributes to via named markers (Design System phase scaffolds; verticals insert).
+contributes:
+  - file: src/pages/index.astro
+    marker: "<!-- home:stores -->"
+    description: "Featured products grid (3–6 items from productsV3.queryProducts)"
+  - file: src/components/Navigation.astro
+    marker: "<!-- nav:links -->"
+    description: "Shop menu link → /products"
+
+include: false
+disabled: false
+---
+
+# Stores Pack
+
+Full ecommerce vertical. Loaded whenever the user's prompt implies selling products.
+
+## Phase decomposition
+
+Stores work is split across **Phase 3 Components** (shared React islands) and **4 Phase 4 Pages scopes** (per-route wiring):
+
+| Scope | When | Files | Notes |
+|-------|------|-------|-------|
+| `components` | Step 4.5 / Phase 3 (bg) | React islands, utils, SeoTags | Needs only the styling contract |
+| `pages-products` | Step 7 / Phase 4 (bg) | products/index.astro, [slug].astro, ProductCard.astro | Imports `<CategoryRail/>` and `listStoreCategories` from `pages-categories` outputs |
+| `pages-categories` | Step 7 / Phase 4 (bg) | category/[slug].astro, CategoryRail.astro, utils/categories.ts | Server-side filtered, cursor-paginated. Writes the shared rail + helper used by `pages-products` too |
+| `pages-home-and-nav` | Step 7 / Phase 4 (bg) | index.astro patch, Navigation patch (Shop submenu) | Needs Phase 2 Design System output + home contribution markers; live-queries categories for the Shop submenu (empty by default — categories are merchant-driven) |
+
+Historically stores was one monolithic agent taking ~6 minutes. The split turns it into a ~2-minute parallel dispatch (max of the 4 scopes). All four Phase-4 stores scopes dispatch in parallel — `pages-products` and `pages-home-and-nav` import files from `pages-categories`, but Astro resolves imports at build time (Step 8), not at write time. Each scope only needs its own files to exist by the time `astro build` runs.
+
+## Known failure modes (propagate to agent prompts)
+
+Listed here once so every scope's prompt can include them; they also live in `references/shared/RETURN_CONTRACT.md` § "Common failure modes".
+
+| Wrong | Right |
+|-------|-------|
+| `import { products }` | `import { productsV3 }` — V1 silently returns 0 on V3 catalogs |
+| Skip `variantId` on cart add | Always include — single-variant products have one |
+| HTML `<!-- comment -->` in `.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript |
+| Omit `wixMetadata` on `/products/[slug]` | Required for Wix sitemap/SEO/deep-link platform integration |
+| Hardcode `<title>` from `product.name` | Pipe `product.seoData.tags` through Layout head slot |
+| Mount CartBadge on a page component | Mount in `Navigation.astro` so it appears on all pages |
+| Render the Wix Gift Card app's 5 auto-mirror products in `/products` or the home grid | Filter them out with `p.ribbon?.name !== "Gift Card"` — they're DIGITAL stand-ins; real purchases happen via `/gift-cards` (gift-cards pack) |
+| Use the Stores install id `215238eb-…` for back-in-stock | Use sub-page id `1380b703-ce81-ff05-f115-39571d94dfcd`; install id is rejected on V3 with `NOT_SUPPORTED_APP_DEF_ID` / `REQUEST_COLLECTION_DISABLED` (see `references/stores/BACK_IN_STOCK.md`) |
+| Pass `itemUrl` or `image` to `createBackInStockNotificationRequest` | Send only `catalogReference`, `email`, `name`, numeric `price` — the SDK throws `Failed to construct 'URL': Invalid URL` on either optional field |
+
+## Images — this pack's contribution
+
+Entity images (product hero + lifestyle) are generated by the shared image agent (Image Phase 2), not by this pack's agents. The image agent watches for this pack's Phase 1 Seed return and generates `heroImage` + `lifestyleImage` per product, then PATCHes them onto product records.
+
+Phase 4 agents do NOT read the image agent's output. Image URLs flow through the product record (Phase 1 populates product; Image Phase 2 PATCHes image fields; Phase 4 queries product and renders `product.media.mainMedia.image.url`).
+
+## Required environment
+
+- `WIX_CLIENT_ID` in `.env.local` (populated by `npx @wix/cli env pull` in Setup)
+- `siteId` known (from `wix.config.json`, extracted in Setup)
+- MCP prefix discovered (Setup Step 0)
+
+## References
+
+- `references/stores/PRODUCT_CATALOG_DATA.md` — Phase 1 (products seed; categories are merchant-driven and not seeded)
+- `references/stores/SHARED_WIRING.md` — Phase 3 Components (stores-specific islands + utils)
+- `references/stores/PRODUCT_PAGES.md` — Phase 4 product-pages scope
+- `references/stores/CATEGORY_PAGES.md` — Phase 4 category-pages scope (rail + /category/[slug])
+- `references/stores/HOME_AND_NAV.md` — Phase 4 home page patch + Shop submenu
+- Cart/checkout references are in the ecom pack: `references/ecom/`