@wix/agent-skills 1.6.0 → 1.8.0

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

@@ -5,65 +5,95 @@ description: "Implements Wix Stores vertical — product catalog, categories, ad
 
 # Stores Implementer
 
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, MCP prefix, site.json read pattern, return contract, style conventions, and common failure modes.
+Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, prompt-inlined inputs (read only your `.wix/seeded.json` slice), return contract, style conventions, and common failure modes.
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `seed` | Seed (MCP catalog setup — products only; categories are merchant-driven, not seeded) | `./PRODUCT_CATALOG_DATA.md` |
-| `components` | Components (React islands + SeoTags + back-in-stock util — TSX/Astro only, **no CSS**) | `./SHARED_WIRING.md` |
-| `components-css` | Components (scoped CSS — `components-stores.css` only; runs concurrently with `components`) | `./COMPONENTS_CSS.md` |
-| `pages-categories` | Pages (`/category/[slug]` listing + shared CategoryRail + `utils/categories.ts`) | `./CATEGORY_PAGES.md` |
-| `pages-products` | Pages (products listing + detail + ProductCard; mounts the rail written by `pages-categories`) | `./PRODUCT_PAGES.md` |
-| `pages-home-and-nav` | Pages (home-page contribution + Shop submenu in Navigation) | `./HOME_AND_NAV.md` |
+| `seed` | Seed (REST catalog setup — products only; categories are merchant-driven, not seeded) | `./PRODUCT_CATALOG_DATA.md` |
+| `components` | Components (React islands + SeoTags + back-in-stock util — TSX/Astro only, **no CSS**) | `../astro/stores/SHARED_WIRING.md` |
+| ~~`components-css`~~ | **Do not dispatch.** `src/styles/components-stores.css` is copied from `<SKILL_ROOT>/references/astro/templates/stores/components-stores.css` by the orchestrator's pre-Step-4.5 batch (see BUILD-astro.md § Step 4.5). The template uses direct `var(--token)` CSS, so it works against any designer-published vocabulary without per-run rewrites. `COMPONENTS_CSS.md` documents that CSS for reference — there is no `components-css` subagent to dispatch. | — |
+| `pages-categories` | Pages (`/category/[slug]` listing + shared CategoryRail + `utils/categories.ts`) | `../astro/stores/CATEGORY_PAGES.md` |
+| `pages-products` | Pages (products listing + detail + ProductCard; mounts the rail written by `pages-categories`) | `../astro/stores/PRODUCT_PAGES.md` |
+| `pages-home-and-nav` | Pages (home-page contribution + Shop submenu in Navigation) | `../astro/stores/HOME_AND_NAV.md` |
 
-> **Why `components` is split.** A single agent writing five .tsx/.astro files plus the scoped CSS dominated Phase 3 wall time (228 s on a 3-product run, 320 s on an 8-product run). The CSS file has no runtime coupling to the TSX components — it's referenced only by class name at build time — so it splits cleanly into a sibling agent that runs in the same dispatch batch. Each scope gets a smaller reading set and a smaller write list. See `./COMPONENTS_CSS.md` § "What this scope owns".
+> **Why `components` is TSX/Astro-only.** The scoped CSS (`src/styles/components-stores.css`) has no runtime coupling to the TSX components — it's referenced only by class name at build time — so it ships pre-copied from the template by the orchestrator (see § "CSS ownership" below) rather than being written by an agent. The `components` agent gets a smaller reading set and a smaller write list. See `../astro/stores/COMPONENTS_CSS.md` § "What this scope owns".
 
 ## Files this vertical creates / contributes
 
-See `<SKILL_ROOT>/references/verticals/stores.md` frontmatter (`creates:` and `contributes:` blocks).
+See the § "Templates" list below for the canonical files each scope reads and adapts.
+
+## Seed return
+
+The `seed` scope emits this `data` shape in its return JSON (envelope rules in `../shared/RETURN_CONTRACT.md`). Phase 4 page agents consume `data.products[*].slug` and `data.products[*].variantId` to wire live SDK queries.
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-seed",
+  "scope": "seed",
+  "summary": "Deleted 12 default products; created 3 on-brand products with variants",
+  "data": {
+    "products": [
+      {
+        "id": "2d1bce83-...",
+        "name": "Tero Dining Table",
+        "slug": "tero-dining-table",
+        "variantId": "ffc1caa2-...",
+        "price": 2890,
+        "inventory": 12,
+        "sku": "TAB-TERO-OAK"
+      }
+    ],
+    "deletedCount": 12,
+    "createdCount": 3
+  },
+  "files": [],
+  "errors": []
+}
+```
 
 ## Pre-return file-existence assertion (all page scopes)
 
-Before returning `status: "complete"` from any `pages-*` scope, verify every file listed in your scope's `files:` block (see verticals/stores.md) exists on disk. Silently dropping a file (e.g. `[slug].astro` from `pages-products`) reports `complete` to the orchestrator, but every product link 404s at runtime.
+Before returning `status: "complete"` from any `pages-*` scope, verify every file your scope produces (per the § "Templates" list below) exists on disk. Silently dropping a file (e.g. `[slug].astro` from `pages-products`) reports `complete` to the orchestrator, but every product link 404s at runtime.
 
 If a declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success. The orchestrator's Step 8.0.5 manifest check will also catch this, but an agent-side assertion gives a faster and more precise failure.
 
 ## Templates
 
-Canonical templates live at `<SKILL_ROOT>/templates/stores/`. Your `components` and `pages-*` scopes read these and adapt them — don't invent markup or logic.
+Canonical templates live at `<SKILL_ROOT>/references/astro/templates/stores/`. Your `components` and `pages-*` scopes read these and adapt them — don't invent markup or logic.
 
 Components (`components` scope — TSX/Astro only):
-- `<SKILL_ROOT>/templates/stores/AddToCartButton.tsx`
-- `<SKILL_ROOT>/templates/stores/ProductPurchase.tsx`
-- `<SKILL_ROOT>/templates/stores/BackInStockForm.tsx`
-- `<SKILL_ROOT>/templates/stores/SeoTags.astro`
+- `<SKILL_ROOT>/references/astro/templates/stores/AddToCartButton.tsx`
+- `<SKILL_ROOT>/references/astro/templates/stores/ProductPurchase.tsx`
+- `<SKILL_ROOT>/references/astro/templates/stores/BackInStockForm.tsx`
+- `<SKILL_ROOT>/references/astro/templates/stores/SeoTags.astro`
 
-Components CSS (`components-css` scope — scoped CSS only):
-- `<SKILL_ROOT>/templates/stores/components-stores.css`
+Components CSS (pre-copied by the orchestrator — no agent writes it):
+- `<SKILL_ROOT>/references/astro/templates/stores/components-stores.css`
 
 Pages (`pages-products` scope):
-- `<SKILL_ROOT>/templates/stores/ProductCard.astro`
-- `<SKILL_ROOT>/templates/stores/products/index.astro`
-- `<SKILL_ROOT>/templates/stores/products/[slug].astro`
+- `<SKILL_ROOT>/references/astro/templates/stores/ProductCard.astro`
+- `<SKILL_ROOT>/references/astro/templates/stores/products/index.astro`
+- `<SKILL_ROOT>/references/astro/templates/stores/products/[slug].astro`
 
 Pages (`pages-categories` scope):
-- `<SKILL_ROOT>/templates/stores/CategoryRail.astro`
-- `<SKILL_ROOT>/templates/stores/category/[slug].astro`
+- `<SKILL_ROOT>/references/astro/templates/stores/CategoryRail.astro`
+- `<SKILL_ROOT>/references/astro/templates/stores/category/[slug].astro`
 
 ### Pre-copied by the orchestrator (do NOT write these yourself)
 
 The following utility files are deterministically copied by the orchestrator BEFORE your phase dispatches (`components` for the first, `pages` for the second). They are mechanical SDK wrappers with no brand-specific content; reading or rewriting them as part of your scope wastes tokens and risks drift. Just import the helpers at the listed paths:
 
-- `src/utils/back-in-stock.ts` — pre-copied from `<SKILL_ROOT>/templates/stores/back-in-stock.ts` before `components` dispatches.
-- `src/utils/categories.ts` — pre-copied from `<SKILL_ROOT>/templates/stores/categories.ts` before `pages` dispatches.
+- `src/utils/back-in-stock.ts` — pre-copied from `<SKILL_ROOT>/references/astro/templates/stores/back-in-stock.ts` before `components` dispatches.
+- `src/utils/categories.ts` — pre-copied from `<SKILL_ROOT>/references/astro/templates/stores/categories.ts` before `pages` dispatches.
 
 If you find one of these missing at runtime, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "<missing>"}]` and continue. Do NOT write your own version; the post-phase manifest check will recover by template-copy and the right helper lands on disk.
 
 ## CSS ownership — stores pack
 
-Stores-specific component CSS lives in `src/styles/components-stores.css` (written by the `components-css` scope — see `./COMPONENTS_CSS.md`), NOT in the designer's `global.css`. The classes the pack owns:
+Stores-specific component CSS lives in `src/styles/components-stores.css` (pre-copied from the template by the orchestrator before Step 4.5 — see the `components` scope-routing note above and `../astro/stores/COMPONENTS_CSS.md`), NOT in the designer's `global.css`. The classes the pack owns:
 
 - `.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index` — the product card itself, including the `overflow: hidden` + `border-radius` clipping context. Whoever writes the `border-radius` here also writes any inner padding required to keep child content inside the rounded edges. Without inner padding, a price `<p>` sits flush against the rounded bottom corner and descenders get clipped. Add `padding-bottom: var(--spacing-md)` on the card plus horizontal padding on each text block when you set the radius. See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer".
 - `.product-grid` — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: var(--spacing-xl);` plus the View-Transitions opacity fade for in-flight navigations.
@@ -73,10 +103,10 @@ The designer's `global.css` declares only tokens, the `.btn` family, decorative
 
 ## Back-in-stock subscribe — components + pages wiring split
 
-Back-in-stock is a dashboard-toggleable feature: it ships in every stores build but only lights up when the merchant clicks "Start Collecting Requests" in the Back in Stock dashboard. The implementation is split across the two scopes the same way every other stores feature is:
+Back-in-stock is a dashboard-toggleable feature: it ships in every stores build but only lights up when the merchant clicks "Start Collecting Requests" in the Back in Stock dashboard. The implementation is split across the `components` and `pages-products` scopes the same way every other stores feature is, with its CSS riding along in the pre-copied stylesheet:
 
-- **`components` scope** writes the SSR probe (`src/utils/back-in-stock.ts`) and the React form island (`src/components/BackInStockForm.tsx`). See `./BACK_IN_STOCK.md` for the full rules — especially the two app ids (use `1380b703-…` for back-in-stock, NOT the Stores install id `215238eb-…`) and the bare-fields rule (no `itemUrl`, no `image` on the SDK call).
-- **`components-css` scope** appends the back-in-stock form rules to `src/styles/components-stores.css` as part of writing that file. See `./BACK_IN_STOCK.md` § 3 for the CSS append.
+- **`components` scope** writes the SSR probe (`src/utils/back-in-stock.ts`) and the React form island (`src/components/BackInStockForm.tsx`). See `../astro/stores/BACK_IN_STOCK.md` for the full rules — especially the two app ids (use `1380b703-…` for back-in-stock, NOT the Stores install id `215238eb-…`) and the bare-fields rule (no `itemUrl`, no `image` on the SDK call).
+- **Back-in-stock form CSS** ships in the pre-copied `src/styles/components-stores.css` template — no agent writes it. See `../astro/stores/BACK_IN_STOCK.md` § 3 for the rules it carries.
 - **`pages-products` scope** imports `getBackInStockEnabled` in `[slug].astro`, awaits the probe, and passes `backInStockEnabled` + `priceAmount` to `<ProductPurchase>`. ProductPurchase renders the form in its three OOS branches when the prop is true.
 
 If the merchant hasn't enabled "Start Collecting Requests", the probe returns `false`, the prop stays `false`, and the form never mounts — no rebuild needed when the merchant flips the toggle in the dashboard.
@@ -93,4 +123,4 @@ If the merchant hasn't enabled "Start Collecting Requests", the probe returns `f
 | Use the back-in-stock app id `1380b703-…` when adding items to a category | Use the **Stores install id** `215238eb-22a5-4c36-9e7b-e7c08025e04e` for `appId` on `bulkAddItemsToCategory` items — it's the same id Wix Stores writes to its products |
 | Call `categories.queryCategories(...).limit(N).find()` with no filter | The SDK builder rejects empty filter expressions with `INVALID_FILTER`. Always chain at least `.eq("visible", true)` before `.find()` |
 | Call `categories.listCategoriesForItems(items, ...)` from the SDK | The SDK function ships items via GET querystring and breaks on arrays. Use `POST /categories/v1/categories/list-categories-for-items` directly, or fan out per-category via `listItemsInCategory` |
-| Ship a client-side filter (`data-category-ids` + JS hide) on the product grid | Filter server-side via `/category/[slug]` routes; client-side filtering doesn't scale past ~100 products and breaks SEO. The `<CategoryRail/>` swaps cards via `<ClientRouter />`, not by hiding them |
+| Ship a client-side filter (`data-category-ids` + JS hide) on the product grid | Filter server-side via `/category/[slug]` routes; client-side filtering doesn't scale past ~100 products and breaks SEO. The `<CategoryRail/>` swaps cards via `<ClientRouter />`, not by hiding them |

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

@@ -1,45 +1,48 @@
-# Recipe: Product Catalog Data Setup (Phase 1)
+# Recipe: Product Catalog Data Setup (seed scope)
 
-Replace the default sample products Wix Stores installs with on-brand products via MCP. This file covers the `seed-seed` scope — data seeding only. Frontend wiring lives in the Phase 2 scope references (`SHARED_WIRING.md`, `PRODUCT_PAGES.md`, `CART_CHECKOUT.md`, `HOME_AND_NAV.md`) and should not be read by `seed-seed`.
+Replace the default sample products Wix Stores installs with on-brand products via the Stores REST API (`curl` against `wixapis.com/stores/v3/...` with the standard headers from `../shared/AUTHENTICATION.md`). This file covers the `seed` scope — data seeding only. Frontend wiring lives in the astro scope references (`../astro/stores/SHARED_WIRING.md`, `../astro/stores/PRODUCT_PAGES.md`, `../astro/ecom/CART_PAGES.md`, `../astro/stores/HOME_AND_NAV.md`) and should not be read by `seed`.
 
 > **Critical Rules — Read Before Starting**
 > 1. **V3 only** — all endpoints under `/stores/v3/...` for products.
-> 2. **No improvised endpoints** — if an MCP call returns 404, stop and report. Do not guess alternative URLs. Do not loop on `SearchWixRESTDocumentation` more than twice on the same topic.
-> 3. **Do not seed categories.** Categories are merchant-driven — created in the Wix dashboard, not by this scope. The storefront's rail, Shop submenu, and `/category/[slug]` route are still wired (Phase 4) and light up automatically once the merchant adds at least one visible category with items (≤ 5 min after creation, the helper's TTL).
+> 2. **No improvised endpoints** — if an REST call returns 404, stop and report. Do not guess alternative URLs. Do not loop on `docs-search REST (see DOCS_SEARCH.md)` more than twice on the same topic.
+> 3. **Do not seed categories** — they are merchant-driven. See Step 6 for the full rule and how the storefront still wires up automatically.
 
 > **V3 Catalog:** New Wix sites use Catalog V3. All endpoints below live under `/stores/v3/...`. The V1 product endpoints should not be used — they silently return 0 results on V3 catalogs.
 
 ## Prerequisites
 
-- Wix Stores app must be installed on the site (via MCP after scaffolding, or installed via MCP if missing — see Step 0)
+- Wix Stores app must be installed on the site (installed via the apps-installer REST endpoint after scaffolding — see Step 0)
 
-## Setup: Replace Default Products via MCP
+## Setup: Replace Default Products via REST
 
 > **Conditional:** This section only applies when ALL of these are true:
 > - The Stores app was just installed (default sample products exist)
-> - Wix MCP tools are available (`mcp__wix-mcp-remote__CallWixSiteAPI` exists)
+> - CLI auth works (`npx @wix/cli@latest token --site "$SITE_ID"` returns a token)
 > - Discovery context is available in your prompt (business type, brand name, style)
 >
-> **If MCP tools are not available, skip this entire section.** The 12 default products remain and can be customized later in the Wix dashboard.
+> **If CLI auth is not available, skip this entire section.** The 12 default products remain and can be customized later in the Wix dashboard.
 
-> **API error guard:** If any MCP call in Phase 1 returns a 404 or an unexpected error, do **not** retry the same call with a guessed alternative URL or namespace. Report the failing endpoint, request body, and error verbatim to the user, then stop. Improvised endpoints have caused multi-minute silent stalls in past runs.
+> **API error guard:** If any REST call in this seed scope returns a 404 or an unexpected error, do **not** retry the same call with a guessed alternative URL or namespace. Report the failing endpoint, request body, and error verbatim to the user, then stop.
+
+> **Stores appDefId** for install and `catalogReference.appId`: `215238eb-22a5-4c36-9e7b-e7c08025e04e`. (A different defId — `1380b703-ce81-ff05-f115-39571d94dfcd` — is used for `wixMetadata.appDefId` in the pages scope. Do not swap them.)
+>
+> <!-- REVIEW (appDefId discrepancy): `1380b703-…` is labeled the `wixMetadata.appDefId` here, but `stores/INSTRUCTIONS.md` (back-in-stock split + failure-mode table) calls the same id the back-in-stock app id. One of these labels is wrong — flagged for human review; value left unchanged. -->
 
-> **Stores appDefId** for install and `catalogReference.appId`: `215238eb-22a5-4c36-9e7b-e7c08025e04e`. (A different defId — `1380b703-ce81-ff05-f115-39571d94dfcd` — is used for `wixMetadata.appDefId` in Phase 2. Do not swap them.)
 
 ### Step 0: Ensure Stores App Is Installed
 
 Before querying products, verify the Stores app is installed:
 
-1. **Probe** — `CallWixSiteAPI: POST /stores/v3/products/query` with body `{ "query": { "paging": { "limit": 1 } } }`
+1. **Probe** — `REST: POST https://www.wixapis.com/stores/v3/products/query`
 2. **If the API returns a "REQUIRED_APP_NOT_INSTALLED" error** → install the Wix Stores 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": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "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 the probe query to confirm installation succeeded.
 3. **If the probe succeeds** → proceed to Step 1.
@@ -51,7 +54,7 @@ Replace the 12 generic sample products with 3 on-brand products that match the u
 ### Step 1: Query Default Products
 
 ```
-CallWixSiteAPI: POST /stores/v3/products/query
+REST: POST https://www.wixapis.com/stores/v3/products/query
 body: {
   "query": {
     "paging": { "limit": 50 }
@@ -64,7 +67,7 @@ Collect all product IDs from the response.
 ### Step 2: Bulk Delete Defaults
 
 ```
-CallWixSiteAPI: POST /stores/v3/bulk/products/delete
+REST: POST https://www.wixapis.com/stores/v3/bulk/products/delete
 body: {
   "productIds": ["<id1>", "<id2>", ..., "<id12>"]
 }
@@ -98,7 +101,7 @@ Adapt names, descriptions, and pricing to match the brand's tone and style. Use
 **Product with variants** (e.g., skincare with 30ml/50ml sizes):
 
 ```
-CallWixSiteAPI: POST /stores/v3/bulk/products-with-inventory/create
+REST: POST https://www.wixapis.com/stores/v3/bulk/products-with-inventory/create
 body: {
   "products": [
     {
@@ -183,7 +186,7 @@ Include all products in the same `products` array. Do not include `media` — pr
 ### Step 5: Verify
 
 ```
-CallWixSiteAPI: POST /stores/v3/products/query
+REST: POST https://www.wixapis.com/stores/v3/products/query
 body: {
   "query": { "paging": { "limit": 50 } }
 }
@@ -201,17 +204,17 @@ If the merchant later creates visible categories in the Wix dashboard and assign
 - The `Navigation` Shop submenu lists the categories.
 - `/category/<slug>` becomes a reachable, server-side-filtered listing.
 
-This works because the frontend (`src/utils/categories.ts`, written by the `pages-categories` scope in Phase 4) live-queries the Wix API at SSR time with a 5-min cache — no redeploy or regen is needed.
+This works because the frontend (`src/utils/categories.ts`, pre-copied by the orchestrator before Phase 4 and imported by the `pages-*` scopes) live-queries the Wix API at SSR time with a 5-min cache — no redeploy or regen is needed.
 
 ### Step 7: Return Results
 
-Emit a structured JSON block at the end of your completion message per `../../shared/RETURN_CONTRACT.md`. Do NOT write a sidecar file.
+Emit a structured JSON block at the end of your completion message per `../shared/RETURN_CONTRACT.md`. Do NOT write a sidecar file.
 
 ```json
 {
   "status": "complete",
   "phase": "stores-seed",
-  "scope": "seed-seed",
+  "scope": "seed",
   "summary": "Deleted {N} default products; created {N} on-brand products with variants",
   "data": {
     "products": [
@@ -220,14 +223,14 @@ Emit a structured JSON block at the end of your completion message per `../../sh
         "name": "<name>",
         "slug": "<slug>",
         "variantId": "<uuid>",
-        "price": 0,
-        "inventory": 0,
+        "price": 48.0,
+        "inventory": 50,
         "sku": "<sku>"
       }
     ],
     "categories": [],
-    "deletedCount": 0,
-    "createdCount": 0
+    "deletedCount": 12,
+    "createdCount": 3
   },
   "files": [],
   "errors": []
@@ -238,12 +241,12 @@ Emit a structured JSON block at the end of your completion message per `../../sh
 
 The JSON block MUST be the last content in your message. Parent skill consumes `data.products[*].slug` and `data.products[*].variantId` for the Phase 4 Pages scopes.
 
-### Phase 1 Boundary — Do Not Touch Other Site Data
+### Seed Boundary — Do Not Touch Other Site Data
 
-Phase 1 is complete after Step 7. Do **not** attempt any of the following, even if they seem like reasonable polish:
+The seed scope is complete after Step 7. Do **not** attempt any of the following, even if they seem like reasonable polish:
 
 - Cleaning up "orphan customizations", "All Products" containers, brand records, or any other catalog metadata you didn't create.
-- Creating, renaming, or deleting any category — categories are merchant-driven (see Step 6). The auto-managed "All Products" category (handle `online_stores_all_products`) stays in place; the frontend filters it out by handle.
+- Creating, renaming, or deleting any category — see Step 6 (leave the auto-managed "All Products" category in place).
 - Verifying your work via additional `query` calls beyond the Step 5 verification already performed.
 
-Phase 2+ (frontend wiring) is covered in the scope-specific references (`SHARED_WIRING.md`, `PRODUCT_PAGES.md`, `CATEGORY_PAGES.md`, `CART_CHECKOUT.md`, `HOME_AND_NAV.md`) — do not read them during `seed-seed`.
+Phase 2+ (frontend wiring) is covered in the astro scope references (`../astro/stores/SHARED_WIRING.md`, `../astro/stores/PRODUCT_PAGES.md`, `../astro/stores/CATEGORY_PAGES.md`, `../astro/ecom/CART_PAGES.md`, `../astro/stores/HOME_AND_NAV.md`) — do not read them during `seed`.

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

@@ -1,160 +1,74 @@
 {
   "$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.",
+  "title": "Wix Headless Vertical Frontmatter (Phase 1 — discovery only)",
+  "description": "Validates verticals/<name>.md frontmatter. Phase 1 scope only — later phases (setup, seed, design, pages, build) are owned by @skills/wix-manage plus this skill's own templates and INSTRUCTIONS.md files; per-pack fields (packages, cmsCollections, seed, components, componentsCss, pages, creates, contributes, include) are not part of this skill and not validated here.",
   "type": "object",
-  "required": ["name", "description", "packages"],
-  "additionalProperties": true,
+  "required": ["name", "description"],
+  "additionalProperties": false,
   "properties": {
     "name": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
       "description": "Must match filename stem (e.g., stores.md → 'stores')"
     },
+    "description": { "type": "string" },
     "triggers": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": { "type": "string" },
+      "description": "Prompt patterns that route to this vertical. Empty allowed for transitive-only packs (ecom, gift-cards, cms). The SKILL.md routing table is the actual source of truth for what gets loaded; this is human reference + a fallback signal."
     },
-    "description": { "type": "string" },
     "requires": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": { "type": "string" },
+      "description": "Verticals that must be co-loaded in the same read batch when this pack is loaded. Today: stores → [ecom, gift-cards]; gift-cards → [ecom]."
     },
     "features": {
       "type": "array",
       "items": {
         "type": "object",
         "required": ["name", "description"],
+        "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
           "description": { "type": "string" }
         }
-      }
+      },
+      "description": "Feature blurbs for DISCOVERY-create.md Step 3 Section B."
     },
     "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"],
+        "required": ["name"],
+        "additionalProperties": false,
         "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" } }
-          }
+          "name": { "type": "string" },
+          "appDefId": { "type": "string" }
         }
-      ]
+      },
+      "description": "Zero or one entry per pack. apps[0].name fills the Source column of the Pages table."
     },
-    "pages": {
+    "routes": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["agentLocation", "scope", "references"],
+        "required": ["route"],
+        "additionalProperties": false,
         "properties": {
-          "name": { "type": "string" },
-          "agentLocation": { "type": "string" },
-          "scope": {
+          "route": {
             "type": "string",
-            "pattern": "^pages(-[a-z][a-z0-9-]*)?$",
-            "description": "Must be 'pages' or 'pages-<subscope>'"
+            "description": "URL path (e.g. /cart) OR the literal 'Hosted by Wix' for Wix-hosted endpoints like checkout."
           },
-          "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" }
+          "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)."
+          }
         }
       }
     },
-    "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." }
+    "disabled": {
+      "type": "boolean",
+      "description": "If true, the pack's surfaces (pages, nav links, home blocks) are inactive 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). 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."
+    }
   }
 }