@wix/agent-skills 1.0.0

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

@@ -0,0 +1,164 @@
+# Phase 3 Components — Stores (TSX/Astro)
+
+Launched in **Step 4.5** (after Phase 2 Design System completes, parallel to any running designer page scopes). Writes code that depends on the **design tokens** but NOT on Phase 4 page markup. Finishes before the Phase 4 Pages scopes run in Step 7.
+
+> **CSS lives in a sibling scope.** `src/styles/components-stores.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.
+
+## Scope
+
+Files this agent OWNS (creates fresh, no designer output to read):
+
+- `src/components/SeoTags.astro` — Renders `product.seoData.tags` into `<head>`
+- `src/components/AddToCartButton.tsx` — React island; optimistic add-to-cart
+- `src/components/ProductPurchase.tsx` — React island; option selectors + variant resolution + wraps AddToCartButton
+- `src/components/BackInStockForm.tsx` — React island; back-in-stock subscription form
+
+Files this agent MUST NOT touch:
+- `src/styles/components-stores.css` — owned by the **`components-css`** sibling scope (see `./COMPONENTS_CSS.md`). Reference its class names; do not write the file.
+- `src/utils/wix-image.ts` — **shared utility shipped by the build skill.** Import `resolveWixImageUrl` from `../utils/wix-image`; do NOT write your own copy (would shadow the shared util and drop other verticals' callers). The canonical source lives at `<SKILL_ROOT>/shared-utilities/wix-image.ts`; it's copied into projects by `seed-utilities.sh` during Setup.
+- `src/components/CartView.tsx`, `src/components/CartBadge.tsx`, `src/utils/analytics.ts`, `src/styles/components-ecom.css` — owned by ecom
+- Any `.astro` page — those are designed and later rewritten by other scopes
+- `src/styles/global.css` — owned by designer foundation
+- `src/layouts/Layout.astro` — owned by designer foundation (including the `components-stores.css` import line)
+- Any designed component (`ProductCard.astro`, `Navigation.astro`, etc.) — owned by designers
+
+## 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 and do not poll for it. The parent skill serializes your launch behind designer foundation specifically so the contract is already available in your prompt when you start.
+
+Reference the ACTUAL class names from the contract in React components (e.g. `className="add-to-cart-btn"`, not `className="addToCartButton"` or an invented name). See `references/shared/IMPLEMENTER.md` § "Contract class-name adaptation" for the full rule.
+
+## Critical rules
+
+1. **Import `productsV3`, never `products`** — V1 silently returns 0 results on V3 catalogs (used in `ProductPurchase.tsx` type definitions).
+2. **Always include `variantId` in `catalogReference.options`** — even single-variant products have one. Without it, `addToCurrentCart` returns 200 OK but silently adds nothing.
+3. **No HTML comments in `.astro` frontmatter** — frontmatter is TypeScript; use `//` or `/* */`. Build-fails with "Legacy HTML single-line comments are not allowed".
+4. **Use brand-token Tailwind utilities on React islands** (e.g., `bg-bark`, `text-cream`), never default Tailwind colors (`bg-green-50`, `text-red-600`). See IMPLEMENTER.md § "Contract class-name adaptation" for the class-name rule itself.
+5. **Analytics is fire-and-forget** — see `references/shared/IMPLEMENTER.md` § "Fire-and-forget analytics".
+
+## Template files
+
+This scope uses **template files** instead of inline code. For each file below:
+
+1. Read the template from `<Agent location>/templates/<filename>`
+2. Write it to the project at the target path
+3. Adapt CSS class names if the design tokens maps them differently than the defaults
+
+Do NOT modify logic, imports, or component structure.
+
+## Implementation
+
+### 1. `src/styles/components-stores.css` — not owned by this scope
+
+> Owned by the **`components-css`** sibling scope. See `./COMPONENTS_CSS.md`. Reference the contract class names from the design tokens in your TSX/Astro files; the CSS sibling defines the rules.
+
+### 2. `src/utils/analytics.ts` — not owned by this scope
+
+> Import from it (`import { trackEvent } from "../utils/analytics"`) but do not write it. Shipped by the build skill as a seeded shared utility.
+
+### 3. `src/utils/wix-image.ts` — not owned by this scope
+
+> Import `resolveWixImageUrl` from `../utils/wix-image` but do not write it. Shipped by the build skill as a seeded shared utility that already exposes `resolveWixImageUrl(image, width?, height?)`. Writing your own copy shadows and breaks callers in other verticals (blog, cms).
+
+### 4. `src/components/SeoTags.astro`
+
+Use template `templates/SeoTags.astro`.
+
+Renders merchant-edited SEO from the Wix dashboard into `<head>`. Mounted on the product detail page (by `product-pages` scope) via `Layout`'s `head` slot.
+
+`product.seoData` is returned by default from `getProductBySlug` — no `fields` flag needed.
+
+### 5. `src/components/AddToCartButton.tsx`
+
+Use template `templates/AddToCartButton.tsx`.
+
+Optimistic add-to-cart button. Shows "Added ✓" immediately; fires API in background; reverts on failure. Dispatches `cart-updated` events so CartBadge can update badge count instantly.
+
+Uses `@wix/ecom` `currentCart.addToCurrentCart`. `WIX_STORES_APP_ID` is the Stores appDefId constant (`215238eb-22a5-4c36-9e7b-e7c08025e04e`) used in `catalogReference.appId`.
+
+**Modifier support** — accepts pre-flattened `modifierChoices` and `customTextFields` from ProductPurchase and merges them into `catalogReference.options` per the Wix Stores Catalog V3 contract. ProductPurchase owns the flattening; this component just passes them through.
+
+Class from contract: `addToCartButton` → `"add-to-cart-btn"`.
+
+### 6. `src/components/CartBadge.tsx` — not owned by this scope
+
+> Do not write this file. AddToCartButton dispatches `cart-updated` CustomEvents that CartBadge (owned by ecom) listens for.
+
+### 7. `src/components/ProductPurchase.tsx`
+
+Use template `templates/ProductPurchase.tsx`.
+
+Handles variant selection, quantity selector, stock awareness, and wraps `AddToCartButton`. Mounted on product detail pages (by `product-pages` scope) as:
+
+```tsx
+<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} />
+```
+
+**Prop contract — single `product` object.** The template accepts the full productsV3 product and destructures internally. This mirrors `ProductCard.astro`'s `{ product }` contract so both stores components take the same shape (prevents the regression observed in an earlier run where a fallback-written `[slug].astro` passed `product` as a whole when the component expected flat props).
+
+Key behaviors:
+- `hasMeaningfulOptions` — a product has meaningful options only when at least one option has >1 choice. Dummy single-choice options (e.g., "Type: Standard") are treated as no options.
+- Out of stock → renders just the message, no button.
+- No meaningful options → renders quantity + AddToCartButton with default variant ID.
+- Has options → renders pill selectors + quantity + AddToCartButton with resolved variant ID.
+- **Modifiers** — customization choices that do NOT create separate variants. Pills for `modifierRenderType === "TEXT_CHOICES"` / `"SWATCH_CHOICES"`, textarea for `"FREE_TEXT"`. Mandatory modifiers must have a value before add-to-cart is enabled. Selections flatten into `{ options: { [modifier.key]: choice.key }, customTextFields: { [modifier.freeTextSettings.key]: text } }` before being handed to AddToCartButton.
+- **OOS gating** — source of truth is `inventoryByVariant` (from `inventoryItemsV3`). `variantsInfo[].inventoryStatus.inStock` is a stale cached flag and is only used when the live map is empty. See PRODUCT_PAGES.md for the detail-page query that populates `inventoryByVariant`.
+
+Classes from contract (stores pack):
+
+- **Global** (CSS in foundation's `global.css`):
+  - `productPurchase` → `"product-purchase"` (outer wrapper — use on the root `<div>`)
+- **Scoped** (CSS in `components-stores.css`, owned by the `components-css` sibling scope — see `./COMPONENTS_CSS.md`):
+  - `optionGroup` → `"option-group"`
+  - `optionLabel` → `"option-label"`
+  - `optionChoices` → `"option-choices"`
+  - `optionPill` → `"option-pill"` (state modifier `.selected` for active choice)
+  - `quantitySelector` → `"quantity-selector"`
+  - `quantityBtn` → `"quantity-btn"`
+  - `quantityValue` → `"quantity-value"`
+  - `stockStatus` → `"stock-status"`
+
+**Do not invent new class names** — if a new interactive control needs a class, add it to the pack's `contractKeys.scoped` first.
+
+### 8. `src/components/CartView.tsx` — not owned by this scope
+
+> Do not write this file.
+
+## Return format
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-components",
+  "scope": "components",
+  "summary": "Wrote React islands and Astro components from templates (CSS handled by components-css sibling)",
+  "data": {
+    "islands": ["ProductPurchase.tsx", "AddToCartButton.tsx", "BackInStockForm.tsx"],
+    "astroComponents": ["SeoTags.astro"],
+    "globalContractClassesReferenced": ["addToCartButton", "productPurchase"],
+    "scopedContractClassesReferenced": ["optionGroup", "optionLabel", "optionChoices", "optionPill", "stockStatus", "quantitySelector", "quantityBtn", "quantityValue"]
+  },
+  "files": [
+    "src/components/SeoTags.astro",
+    "src/components/AddToCartButton.tsx",
+    "src/components/ProductPurchase.tsx",
+    "src/components/BackInStockForm.tsx"
+  ],
+  "errors": []
+}
+```
+
+## Anti-patterns
+
+| WRONG | CORRECT |
+|-------|---------|
+| Read designer `.astro` files | Not needed — this scope doesn't touch pages |
+| Import `products` from `@wix/stores` | Use `productsV3` |
+| Write `src/utils/wix-image.ts` | Import from it — shared util already exposes `resolveWixImageUrl` |
+| Hardcode `className="btn-primary"` | Use contract class `className="add-to-cart-btn"` |
+| Default Tailwind color utilities on React islands (`bg-green-50`, `bg-blue-500`) | Brand `@theme` utilities (`bg-bark`, `text-cream`) or contract class names |
+| `<!--` HTML comments in `.astro` frontmatter | `//` or `/* */` — frontmatter is TypeScript |
+| Omit `WIX_STORES_APP_ID` constant | Hardcoded `215238eb-22a5-4c36-9e7b-e7c08025e04e` in AddToCartButton for `catalogReference.appId` |
+| Introspect `node_modules/@wix/*` | All symbols are documented here; if missing, call `<prefix>SearchWixSDKDocumentation` |
+| Write `CartView.tsx`, `CartBadge.tsx`, or `analytics.ts` | Not owned by this scope — do not write |
+| Pass flat props to `ProductPurchase` (`productId`, `options`, `variantsInfo`, …) | Pass the whole product: `<ProductPurchase product={product} inventoryByVariant={inventoryByVariant} />` |

package/skills/wix-headless/references/verticals/_schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Wix Headless Vertical Frontmatter",
+  "description": "Validates verticals/<name>.md frontmatter. Runs at session start; malformed vertical aborts the skill.",
+  "type": "object",
+  "required": ["name", "description", "packages"],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Must match filename stem (e.g., stores.md → 'stores')"
+    },
+    "triggers": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "description": { "type": "string" },
+    "requires": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "description"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "apps": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string", "description": "App name (resolved via known-apps.json)" },
+          {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string" },
+              "appDefId": { "type": "string" }
+            }
+          }
+        ]
+      }
+    },
+    "packages": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "routes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["route"],
+        "properties": {
+          "route": { "type": "string", "description": "URL path (e.g. /cart) OR the literal 'Hosted by Wix' for Wix-hosted endpoints like checkout." },
+          "name": { "type": "string", "description": "Optional user-facing page name override for DISCOVERY.md's Section C table. When omitted, the orchestrator derives the name from the path (/ → Home; /thank-you → Thank You). Set this only when path-derivation produces a poor name (e.g. /products/[slug] → 'Product Detail') or when the route has no path (e.g. ecom's Wix-hosted Checkout)." }
+        }
+      }
+    },
+    "cmsCollections": { "type": "array" },
+    "seed": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["agentLocation", "scope", "references"],
+          "properties": {
+            "agentLocation": { "type": "string" },
+            "scope": { "type": "string", "const": "seed" },
+            "description": { "type": "string" },
+            "references": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      ]
+    },
+    "components": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["agentLocation", "scope", "references"],
+          "properties": {
+            "agentLocation": { "type": "string" },
+            "scope": { "type": "string", "const": "components" },
+            "description": { "type": "string" },
+            "references": { "type": "array", "items": { "type": "string" } },
+            "files": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      ]
+    },
+    "componentsCss": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["agentLocation", "scope", "references"],
+          "description": "Optional sibling of `components`. When present, the orchestrator dispatches a second concurrent Phase 3 subagent that owns the pack's scoped CSS file only — independent of TSX/Astro work in the `components` scope. Used by packs whose `components` agent dominated phase wall time (today: stores). Backward compatible — packs without this field keep the single-agent shape.",
+          "properties": {
+            "agentLocation": { "type": "string" },
+            "scope": { "type": "string", "const": "components-css" },
+            "description": { "type": "string" },
+            "references": { "type": "array", "items": { "type": "string" } },
+            "files": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      ]
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["agentLocation", "scope", "references"],
+        "properties": {
+          "name": { "type": "string" },
+          "agentLocation": { "type": "string" },
+          "scope": {
+            "type": "string",
+            "pattern": "^pages(-[a-z][a-z0-9-]*)?$",
+            "description": "Must be 'pages' or 'pages-<subscope>'"
+          },
+          "description": { "type": "string" },
+          "references": { "type": "array", "items": { "type": "string" } },
+          "files": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "creates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "phase"],
+        "properties": {
+          "file": { "type": "string" },
+          "phase": { "type": "string", "enum": ["seed", "components", "pages"] }
+        }
+      }
+    },
+    "contributes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "marker"],
+        "properties": {
+          "file": { "type": "string" },
+          "marker": { "type": "string", "pattern": "^<!--\\s.*\\s-->$" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "include": { "type": "boolean", "description": "Pack-level loading flag. If true, the pack is loaded in every site regardless of triggers/requires (today: only the cms pack uses include:true). Default false — the pack loads only when triggers match the user's prompt or another pack pulls it in via requires." },
+    "disabled": { "type": "boolean", "description": "Pack-level activation flag, ORTHOGONAL to `include`. If true, the pack's surfaces (pages, nav links, home blocks) are disabled by default — they ship as code but do not appear without a separate user action (today: enabling the matching Wix app from the dashboard, which the pack's runtime probe detects). Files still ship via creates: / contributes: so activation is instant once the user opts in. 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 ask for. Today only the gift-cards pack uses disabled:true." }
+  }
+}

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

@@ -0,0 +1,185 @@
+# Vertical Schema
+
+Each file in `references/verticals/` declares one vertical's contribution to the build flow. The skill reads the user's prompt, loads matching verticals, and assembles the phase-based flow from them.
+
+## File format
+
+Markdown with YAML frontmatter. The frontmatter is the machine-readable config. The markdown body is human-readable docs (what the vertical does, gotchas, examples).
+
+## Frontmatter fields
+
+```yaml
+---
+# --- Identity ---
+name: stores                          # unique vertical name, matches the filename stem
+triggers:                             # prompt patterns that route the user to this vertical
+  - "sell"
+  - "ecommerce"
+  - "store"
+  - "shop"
+description: "Full ecommerce: products, cart, checkout, thank-you"
+
+# --- Dependencies ---
+requires: []                          # optional list of vertical names that must be co-loaded
+                                      # e.g. stores requires ["ecom"] for cart/checkout
+
+# --- Plan contribution ---
+features:                             # human-readable feature blurbs for the plan
+  - name: "Product catalog"
+    description: "Browse products with images, prices, and variants."
+  - name: "Cart & checkout"
+    description: "Add to cart, review, check out via Wix's hosted checkout."
+
+# --- Infrastructure ---
+apps:                                 # MCP app installs (0 or more per pack)
+  - name: "Wix Stores"
+    appDefId: "215238eb-22a5-4c36-9e7b-e7c08025e04e"
+packages:                             # npm packages to install
+  - "@wix/stores"
+  - "@wix/ecom"
+  - "@wix/redirects"
+  - "@wix/site"
+
+# --- Routes this vertical contributes (for plan assembly) ---
+# Agent dispatch for rewriting page files lives under the 'pages:' phase entry further down.
+routes:
+  - route: "/products"
+  - route: "/products/[slug]"
+    name: "Product Detail"                     # OPTIONAL: user-facing name override for DISCOVERY's Section C table. When omitted, the orchestrator derives the name from the path (/ → "Home"; /thank-you → "Thank You"). Override only when path-derivation produces a poor name (e.g. /products/[slug] would derive to "Products [slug]") OR when the route has no path (ecom's Wix-hosted Checkout uses route: "Hosted by Wix" + name: "Checkout").
+
+# --- CMS collections this vertical declares (if any) ---
+cmsCollections: []                    # stores adds none; the cms vertical adds About + FAQ
+
+# --- Seed phase: data seeding (MCP-only, no design-token dependency) ---
+seed:
+  agentLocation: "references/stores/"
+  scope: "seed"
+  description: "Delete default sample products, create on-brand products"
+  references: ["references/stores/PRODUCT_CATALOG_DATA.md"]
+
+# --- Components phase: shared React/Astro components (runs after Design System, parallel with other verticals' components) ---
+components:
+  agentLocation: "references/stores/"
+  scope: "components"
+  description: "SDK-wiring code and reusable islands (reads design tokens + site.d.ts)"
+  references: ["references/stores/SHARED_WIRING.md"]
+  files:
+    - "src/utils/wix-image.ts"
+    - "src/utils/analytics.ts"
+    - "src/components/SeoTags.astro"
+    - "src/components/AddToCartButton.tsx"
+    - "src/components/CartBadge.tsx"
+    - "src/components/ProductPurchase.tsx"
+    - "src/components/CartView.tsx"
+
+# --- Pages phase: route files (written ONCE with both visual design and data queries) ---
+pages:
+  - name: "product-pages"
+    agentLocation: "references/stores/"
+    scope: "pages-products"
+    references: ["references/stores/PRODUCT_PAGES.md"]
+    files:
+      - "src/pages/products/index.astro"
+      - "src/pages/products/[slug].astro"
+      - "src/components/ProductCard.astro"
+  - name: "cart-checkout"
+    agentLocation: "references/stores/"
+    scope: "pages-cart-checkout"
+    references: ["references/ecom/CART_PAGES.md"]
+    files:
+      - "src/pages/cart.astro"
+      - "src/pages/thank-you.astro"
+  - name: "home-and-nav"
+    agentLocation: "references/stores/"
+    scope: "pages-home-and-nav"
+    references: ["references/stores/HOME_AND_NAV.md"]
+    files:
+      - "src/pages/index.astro (patch)"
+      - "src/components/Navigation.astro (patch)"
+
+# --- File ownership declarations ---
+# `creates:` lists files this vertical is the sole author of. Schema validator
+#   enforces single-owner (two verticals claiming the same file → fail at session start)
+#   and unresolved-import check (if ANY loaded reference imports ../utils/X, some
+#   vertical must declare it in `creates:` OR it must be a plugin shared utility).
+# `contributes:` lists files this vertical co-edits via named markers. The Design
+#   System phase scaffolds shell files (Navigation.astro, index.astro) with markers;
+#   each vertical inserts at its marker. Replaces the old `homeSection:` concept —
+#   contributes[].description is surfaced in the plan shown to the user.
+# Skill-level shared utilities (wix-image.ts, analytics.ts, ricos.ts) are NEVER listed here —
+#   they ship via <SKILL_ROOT>/shared-utilities/ and are copied into projects by
+#   <SKILL_ROOT>/scripts/seed-utilities.sh during Setup.
+creates:
+  - { file: src/components/AddToCartButton.tsx, phase: components }
+  - { file: src/pages/products/index.astro,     phase: pages }
+
+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"
+
+# --- Loading + activation (orthogonal pack-level flags) ---
+include: false                        # if true, the pack loads in every site regardless of triggers/requires (today: only `cms` sets include:true). Default false → loads on trigger match or via another pack's requires.
+disabled: false                       # if true, the pack ships its code but its surfaces (pages, nav, home blocks) are inactive by default — they light up only when the user takes a separate action (today: enabling the matching Wix app from the dashboard, detected by a runtime probe). 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 ask for. Today only `gift-cards` sets disabled:true. Default false.
+---
+```
+
+## Field reference
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `name` | string | yes | Matches filename stem (e.g., `stores.md` → `name: stores`) |
+| `triggers` | string[] | yes unless `include: true` | Case-insensitive substrings matched against user prompt |
+| `description` | string | yes | Short label for the plan |
+| `features` | object[] | yes | Feature blurbs for the plan's "Features" section |
+| `apps` | object[] | no | MCP app installs; `{name, appDefId}` pairs |
+| `packages` | string[] | yes | npm packages |
+| `routes` | object[] | no | `{route, name?}` — routes the pack ships. Optional `name` overrides the path-derived page name in DISCOVERY's Section C. |
+| `cmsCollections` | object[] | no | Collections this vertical adds |
+| `seed` | object | no | Seed-phase agent config; omit if the vertical has no seeding |
+| `components` | object | no | Components-phase agent config; omit if none |
+| `pages` | object[] | no | Pages-phase agent dispatch (one entry per page-rewrite sub-scope) |
+| `creates` | object[] | no | `{file, phase}` — files this vertical is sole author of. Schema validator enforces single-owner + unresolved-import check. |
+| `contributes` | object[] | no | `{file, marker, description}` — files this vertical co-edits via named markers. |
+| `include` | bool | no | If true, the pack loads in every site regardless of triggers/requires (today: only `cms`). Controls **loading**. |
+| `disabled` | bool | no | If true, the pack ships its code but its surfaces are inactive by default — they light up only via a separate user action (today: enabling the matching Wix app from the dashboard; the pack's runtime probe detects it). DISCOVERY plan composition skips disabled packs from Sections B + C. Today only `gift-cards`. Controls **activation**. |
+
+### `include` vs `disabled` — orthogonal axes
+
+The two flags answer different questions. Don't conflate them:
+
+- **`include`** — *Is this pack in the loaded set?* Default: load when triggers match or another pack pulls it in via `requires:`. `include: true` overrides that and forces the pack to load in every site. Used by `cms` (every site needs About/FAQ).
+- **`disabled`** — *Do this pack's surfaces appear without further user action?* Default: yes — the moment the pack is loaded, its routes and contributions are live. `disabled: true` says no — the code ships, but a separate runtime check (today: a dashboard-app probe) decides whether to render. Used by `gift-cards` (the surface only appears once the user enables the Wix Gift Card app from the dashboard).
+
+A pack can be `include: true, disabled: true` (always loaded but never auto-active) or any other combination — they don't conflict.
+
+## How the skill uses the vertical
+
+1. **Discovery step**: scan loaded verticals for `features`, `routes`, `cmsCollections` → assemble plan markdown.
+2. **Setup phase**: collect `apps`, `packages` → one MCP call per app, one `npm install` with merged package list.
+3. **Seed phase**: for each vertical with a `seed` block, dispatch `seed.agent + scope`.
+4. **Design System phase**: Design System agent writes global styling — `@theme` token contract + a small set of always-required global semantic classes (compound patterns, interactive states, JS targets). Layout/spacing/typography flows through tokens-as-utilities at call sites; see `references/shared/STYLING.md`.
+5. **Components phase**: for each vertical with a `components` block, dispatch `components.agent + scope` (parallel).
+6. **Pages phase**: for each vertical, launch one agent per `pages[*]` entry (parallel).
+
+## Adding a new vertical
+
+1. Create `<name>.md` in this directory with frontmatter per the schema above.
+2. Create `references/<name>/` with `INSTRUCTIONS.md` and `references/`.
+3. No changes needed to `SKILL.md` or other verticals.
+
+The skill discovers verticals by listing this directory. No registration step.
+
+## Validation (informal)
+
+The skill should sanity-check vertical frontmatter at load time:
+- `name` matches filename stem
+- `packages` non-empty (empty would mean nothing to install)
+- If `seed` is declared, `seed.agentLocation` exists on disk
+- If `components` or `pages` declared, their agent locations exist on disk
+- All declared `apps`, `routes`, `creates`, `contributes` paths are valid and don't collide with another loaded vertical's owned paths
+
+If validation fails, fail loud — surface the error to the user. A malformed vertical breaking the whole flow is better than silently dropping it.

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

@@ -0,0 +1,125 @@
+---
+name: blog
+triggers: ["blog", "publish articles", "write posts", "content site", "editorial", "journal", "newsletter"]
+description: "Blog — post listing, post detail with rich content, RSS feed, sitemap"
+
+features:
+  - name: "Blog"
+    description: "Publish posts with a listing page, individual post pages with rich content rendering, and an RSS feed."
+  - name: "RSS and sitemap"
+    description: "Auto-generated RSS feed and XML sitemap for search engine discovery."
+
+apps:
+  - name: "Wix Blog"
+    appDefId: "14bcded7-0066-7c35-14d7-466cb3f09103"
+
+packages:
+  - "@wix/blog"
+  - "@wix/ricos"
+  - "@astrojs/rss"
+  - "@astrojs/sitemap"
+
+routes:
+  - route: "/blog"
+  - route: "/blog/[slug]"
+    name: "Blog Post"   # path-derivation would produce "Blog [slug]" — override with the user-facing label
+  - route: "/rss.xml"
+
+cmsCollections: []
+
+seed:
+  agentLocation: "references/blog/"
+  scope: "seed"
+  description: "Ensure Blog app is installed, seed 3 on-brand blog posts via MCP with rich Ricos content"
+  references: ["references/blog/BLOG_CONTENT.md"]
+
+components:
+  agentLocation: "references/blog/"
+  scope: "components"
+  description: "Blog service module (queryBlogPosts, getPostBySlug), RicosViewer React wrapper, site constants, astro.config sitemap integration"
+  references: ["references/blog/BLOG_SETUP.md"]
+  files:
+    - "src/lib/blog.ts"
+    - "src/components/RicosViewer.tsx"
+    - "src/consts.ts"
+    - "astro.config.mjs (patch — add site property and sitemap integration)"
+
+pages:
+  - name: "blog-pages"
+    agentLocation: "references/blog/"
+    scope: "pages"
+    description: "Wire blog listing + post detail pages to @wix/blog SDK, add RSS feed endpoint, BlogPost layout, SEO head, date formatting, patch home page latest-posts section"
+    references: ["references/blog/BLOG_PAGES.md"]
+    files:
+      - "src/pages/blog/index.astro"
+      - "src/pages/blog/[...slug].astro"
+      - "src/pages/rss.xml.js"
+      - "src/layouts/BlogPost.astro"
+      - "src/components/BaseHead.astro"
+      - "src/components/FormattedDate.astro"
+      - "src/pages/index.astro (patch — latest-posts section only)"
+
+creates:
+  - { file: src/lib/blog.ts,                  phase: components }
+  - { file: src/components/RicosViewer.tsx,   phase: components }
+  - { file: src/consts.ts,                    phase: components }
+  - { file: src/pages/blog/index.astro,       phase: pages }
+  - { file: src/pages/blog/[...slug].astro,   phase: pages }
+  - { file: src/pages/rss.xml.js,             phase: pages }
+  - { file: src/layouts/BlogPost.astro,       phase: pages }
+  - { file: src/components/BaseHead.astro,    phase: pages }
+  - { file: src/components/FormattedDate.astro, phase: pages }
+
+contributes:
+  - file: astro.config.mjs
+    marker: "<!-- config:sitemap -->"
+    description: "site property + @astrojs/sitemap integration"
+  - file: src/pages/index.astro
+    marker: "<!-- home:blog -->"
+    description: "Latest 3 posts grid (cover images, titles, dates, excerpts) from queryBlogPosts(3)"
+  - file: src/components/Navigation.astro
+    marker: "<!-- nav:links -->"
+    description: "Blog menu link → /blog"
+
+include: false
+disabled: false
+---
+
+# Blog Pack
+
+Blog vertical for content-driven sites. Loaded when the user's prompt mentions blogging, publishing, or editorial content.
+
+## 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) | blog.ts, RicosViewer.tsx, consts.ts, astro.config.mjs | Styling contract |
+| `blog-pages` | Phase 4 — Step 7 (bg) | blog/index.astro, blog/[...slug].astro, rss.xml.js, BlogPost.astro, BaseHead.astro, FormattedDate.astro, index.astro (patch) | Phase 2 Design System + Phase 1 Seed post data |
+
+Phase 3 Components runs in the background from Step 4.5 through Phase 4. Phase 4 blog-pages dispatches in Step 7 after Phase 3 + Phase 1 Seed complete — it needs the React islands written by Phase 3 and the seeded post slugs from Phase 1.
+
+RSS feed generation (`rss.xml.js`) is included in the blog-pages scope rather than a separate scope — it's ~15 lines, has no design dependency, and doesn't justify its own agent dispatch.
+
+## Known failure modes (propagate to agent prompts)
+
+| Wrong | Right |
+|-------|-------|
+| `import { items } from "@wix/data"` for blog queries | `import { posts } from "@wix/blog"` — use the Blog SDK |
+| `<article set:html={post.content} />` | `<RicosViewer client:only="react" content={post.richContent} />` — content is Ricos format |
+| Skip `wixMetadata` export on `[...slug].astro` | Required for Wix page routing and SEO |
+| `media.wixMedia.image` as raw URL | `media.getImageUrl(item.media.wixMedia.image).url` — must resolve |
+| Query posts without `RICH_CONTENT` fieldset | Always request `RICH_CONTENT` or `post.richContent` is undefined |
+| `const { tag } = await tags.getTag(id)` | `const tag = await tags.getTag(id)` — returns directly (unlike `getCategory()`) |
+| Scoped `<style>` for RicosViewer overrides | `<style is:global>` — React islands don't inherit scoped Astro styles |
+| Skip `.ricos-content` color overrides | Ricos CSS hardcodes `color: rgb(0, 0, 0)` — invisible on dark themes without overrides |
+
+## Images
+
+Cover images for blog posts are generated by the shared image agent (`image-phase-2-entity` scope), not by blog agents. The image agent PATCHes cover images onto post records after Phase 1 Seed creates them. Phase 4 agents query posts and render `post.media` — the image URL flows through the post record.
+
+## References
+
+- `references/blog/BLOG_CONTENT.md` — Phase 1: MCP post seeding
+- `references/blog/BLOG_SETUP.md` — Phase 3 Components: service module, RicosViewer, config
+- `references/blog/BLOG_PAGES.md` — Phase 2 blog-pages: listing, detail, RSS, layout, SEO